Capture natural-language requests, spelling drift, format hints, and project context in a durable task record that becomes the source of truth for later decisions.
Command by Rudraix
Phase 1 Build Blueprint
A premium operator blueprint for structured execution, real-time transparency, multimodal output delivery, and safe local-first control.
Phase 1 is the complete product foundation for Command: a conversation-first execution system that understands intent, creates structured plans, streams live work, asks for approval when needed, handles projects locally, supports multimodal outputs, tracks assets, explains its decisions, and stays ready for queueing, recovery, provider connectivity, and premium operator control from day one.
Phase 1 Scope Map
This expanded blueprint already covers the full operator foundation
Phase 1 now spans execution control, workspace intelligence, multimodal delivery, operational transparency, and safety engineering inside one unified product foundation.
Foundation
Execution Blueprint
Control Plane
Backend Readiness
Operator UX
Workspace Intelligence
Delivery
Multimodal Outputs
Trust
Safety + Control
Open the live operator product
Launch Command
Move directly from the blueprint into Command and test the current workspace, live workstream, assets, and local project experience.
Core Goal
Phase 1 must establish the full operator-grade foundation, not a narrow proof of concept
Phase 1 now defines the complete Command foundation: intent understanding, live workstream transparency, approvals, diff visibility, multimodal output handling, asset organization, local-first project control, recovery posture, provider readiness, and a premium human-readable workspace that can grow without architectural regret.
Produce understanding snapshots and execution briefs that convert ambiguous asks into explicit, reviewable system intent.
Translate understanding into a visible sequence of steps, dependencies, checkpoints, and expected outcomes before the system mutates a project or generates an asset.
Show a live workstream with readable titles, explanations, file awareness, command context, and status progression instead of raw terminal spam.
Introduce approval requests for risky or ambiguous actions so the operator can allow, deny, refine, or set low-risk preferences without losing context.
Expose file reads, edits, diffs, and revert boundaries in a way that makes technical work understandable even when the user is not thinking like an engineer.
Handle apps, websites, images, audio, video, PDFs, documents, presentations, and spreadsheets through a common output pipeline rather than fragmented one-off flows.
Every created result needs a visible preview, a download path, an open action, and enough metadata to feel trustworthy immediately.
Outputs remain linked to prompt, thread, project, timestamp, and version lineage so users can always answer what created a result and when.
Project operations respect real local folders, local file editing, safe diffs, preview behavior, and honest disappearance when a folder is gone.
Command explains what it is doing, why it is doing it, and what a command or file change means without forcing users to decode jargon.
Live UI updates come from actual backend events, with fallback and ambient language used only to keep the experience readable during quiet windows.
The system foundation already accounts for queued requests, background continuity, longer-lived runs, and operator-safe task switching.
Execution is designed with revert points, retry policies, validation gates, and no-fake-success behavior even when every recovery branch is not fully live yet.
External providers, memory, preference persistence, auth boundaries, and enterprise-quality UI are all first-class citizens in the blueprint.
Tech Stack
A broader but still disciplined platform stack for the full Phase 1 foundation
The stack remains credible and implementation-minded, but it now reflects a real operator product: orchestration, workspace UI, live events, asset handling, provider readiness, and durable state all belong in the same Phase 1 platform story.
- Python 3.11+
- FastAPI
- SQLAlchemy and Pydantic contracts
- PostgreSQL-compatible DB with SQLite-friendly local fallback
- Realtime event mapping through WebSocket / SSE
- Execution, planning, verification, delivery, asset, approval, rollback, memory, and provider services
- Queue and background-run readiness
- Next.js App Router
- Tailwind + semantic theme system
- Landing, Command workspace, assets, roadmap, and task detail surfaces
- Live workstream, approval dialog, diff viewer, output preview, and local project editing surfaces
- Realtime socket/SSE client, action mapping, and fallback narration engine
- Redis-compatible transport and caching layer where needed
- Persistent output assets and version records
- Secret-backed provider configuration and OAuth readiness
- Rollback snapshots and user preference persistence
- Docker + Cloud Run + Cloud SQL + Memorystore
- Artifact Registry, Cloud Build, and local parity paths
Project Structure
A broader system layout that still keeps the codebase understandable
The structure grows with the real product surface: realtime events, workstream shaping, approvals, assets, providers, memory, rollback, and workspace behavior all remain explicit instead of hiding behind vague utility layers.
backend/
app/
main.py
api/v1/
tasks.py
workspaces.py
outputs.py
approvals.py
providers.py
core/
db/
models/
task.py
task_run.py
output_asset.py
approval_request.py
rollback_point.py
user_preference.py
provider_connection.py
workspace_metadata.py
schemas/
realtime/
services/
orchestration/
content/
intent/
verification/
delivery/
queue/
rollback/
memory/
providers/
workstream/
utils/
Dockerfile
requirements.txt
frontend/
app/
page.tsx
command/page.tsx
assets/page.tsx
roadmap/page.tsx
task/[id]/page.tsx
agent/[workspaceId]/page.tsx
components/
AgentShell.tsx
WorkspaceShell.tsx
ExecutionOverlayDialog.tsx
ApprovalDialog.tsx
RightDiffPanel.tsx
OutputPreviewGallery.tsx
AssetsShell.tsx
ProjectFileEditor.tsx
lib/
api.ts
agent/realtime.ts
roadmap.ts
public/
phase-1.html
phase-2.html
phase-3.html
phase-4.html
phase-5.html
Backend Requirements
The backend is the authoritative execution, transparency, and asset foundation for Phase 1
It owns lifecycle state, planning artifacts, approvals, event streaming, provider readiness, output records, rollback posture, preference continuity, and the delivery semantics the frontend depends on for trust.
Composable application foundation
/healthendpoint for readiness and diagnostics/api/v1/*routing for task, workspace, output, approval, and provider APIs- WebSocket and/or SSE support for live workstream delivery
- CORS enabled for local frontend development and preview surfaces
- Router boundaries that keep execution, auth, assets, and workspaces predictable
Durable workflow and product state
Core model vocabulary:
Task
TaskRun
UnderstandingSnapshot
ExecutionBrief
Plan
PlanStep
EventLog
FileChange
CommandRun
VerificationReport
DeliveryReport
OutputAsset
OutputVersion
ApprovalRequest
RollbackPoint
UserPreference
ProviderConnection
WorkspaceMetadata
- UUID primary keys, timestamps, and structured JSON payloads where appropriate
- Clean relationships across task, run, output, approval, rollback, and workspace entities
- Truthful persistence for traceability instead of transient UI-only state
Stable schemas for a richer operator product
TaskCreate / TaskResponse
ExecutionBriefSchema
UnderstandingSnapshotSchema
PlanSchema
TaskRunSchema
OutputAssetSchema
ApprovalRequestSchema
RollbackPointSchema
WorkspaceSchema
ProviderConnectionSchema
Every schema should support the premium UI, not just the backend. The contract has to explain enough for workstream, previews, assets, approvals, and project surfaces to remain coherent.
Blueprint-level API coverage
POST/api/v1/tasks
POST/api/v1/tasks/{task_id}/analyze
POST/api/v1/tasks/{task_id}/plan
POST/api/v1/tasks/{task_id}/execute
POST/api/v1/tasks/{task_id}/approve-understanding
GET/api/v1/task-runs/{task_run_id}/stream
GET/api/v1/task-runs/{task_run_id}/events
GET/api/v1/task-runs/{task_run_id}/verification
GET/api/v1/task-runs/{task_run_id}/delivery
GET/api/v1/assets
POST/api/v1/workspaces/import
POST/api/v1/providers/connect
Planning, execution, verification, and delivery belong in services
task_service
intent_engine_service
understanding_service
planner_service
execution_service
verification_service
delivery_service
asset_service
approval_service
realtime_event_service
queue_service
rollback_service
memory_service
provider_adapter_service
- Routes stay thin and orchestration stays testable
- Workstream language is shaped intentionally, not improvised in controllers
- Execution, asset, and recovery behaviors remain independently evolvable
Real operational transparency with honest event semantics
Live UI updates must come from actual backend activity and persisted event logs rather than optimistic fake progress lines.
task.created
task.understood
approval.requested
step.started
file.read
file.edited
command.started
asset.generated
verification.completed
task.completed
Blueprint support for overlapping demand and background continuity
- Queued, running, waiting-for-approval, completed, failed, and recoverable states
- Background-job continuity without breaking the current operator session
- Task switcher and multi-run visibility readiness in the state model
- Clear ownership of active resources so simultaneous work does not become chaotic
Trust engineering, not optimistic promises
- Rollback points before risky file or environment changes
- Diff records and revert eligibility tied to actual file operations
- Workspace-safe restore boundaries that the UI can explain honestly
- No claim of reversibility when the system cannot actually restore state
Operator continuity without invisible behavior drift
- User preference storage for format defaults, tone selection, and approval shortcuts
- Session memory for low-risk repeated clarifications
- Provider connection state and safe preference recall
- Explicit boundaries so memory improves UX without becoming confusing hidden state
Outputs are first-class product records
- Persistent output assets with versions, timestamps, and MIME-aware metadata
- Preview URLs, download paths, source prompt linkage, and thread/project lineage
- Asset categories for apps, images, videos, audio, PDFs, documents, presentations, and spreadsheets
- Import-back-into-Command behavior for iterative creation loops
Credible local and deployable runtime configuration
DATABASE_URLPrimary durable workflow and asset store
REDIS_URLEvent transport, queueing, or cache support where needed
STORAGE_ROOTLocal output and workspace file root
PROVIDER_KEYSImage, document, video, and external provider credentials
OAUTH_CONFIGProvider and identity integration readiness
APP_ENV / LOG_LEVELOperational mode and observability behavior
Local parity and cloud readiness from the beginning
- Dockerized backend with Cloud Run
PORTsupport - Cloud SQL and managed database compatibility
- Memorystore or Redis-compatible runtime path for queues or realtime support
- Secret Manager, Artifact Registry, and build pipeline readiness
- Local startup flow that mirrors production semantics as closely as practical
Frontend Operator Workspace
The frontend is a premium execution surface, not a thin test harness
Phase 1 already includes the full operator-facing product grammar: landing entry, conversation-first workspace, live actions, diff visibility, output previews, asset management, local project behavior, and roadmap intelligence surfaces.
A premium entry surface captures messy user asks, mode hints, expertise context, and optional uploads without overwhelming the operator.
Command entry
Large prompt surface with clear context, mode selection, and workspace import cues.
Describe what you want. Command will infer the workflow.
AppImagePDFProject
The main operator area is a three-panel execution environment: left memory and assets, center thread and workstream, right diff inspection.
Library / assets / projectsleft
Conversation-first execution
Understanding, approvals, workstream, outputs, and next actions stay centered in one thread.
Diff viewerright
Users can browse created outputs by category, inspect previews, download results, and reopen local projects without losing traceability.
Assets
Images, PDFs, docs, videos, audio, apps, and project outputs stay organized by category.
Preview + download + import to Commandready
Local folder awaresafe
Approval dialogs, readable diff review, explanation surfaces, and output result cards all belong to the same calm operator experience.
Approval
Allow, deny, or refine a risky action without losing the active task context.
Output preview
Generated result card with preview, download, version, and source traceability.
Workspace Intelligence
The workspace behaves like a calm, explainable human operator
This is where Command differentiates itself: the product does not just run tasks, it shows thought, progress, context, and next actions in a way that keeps the user oriented and in control.
The workspace is conversation-first, not dashboard-first. Work happens in the thread, live actions appear where attention already is, approvals stay contextual, diffs remain readable, and the system explains commands, file changes, and reasoning in human language before the operator has to ask.
User prompt, understanding, plan, live actions, approvals, outputs, and follow-up steps all belong to one continuous narrative.
Run, preview, open, download, explain, revert, continue, and import actions appear at the moment they are useful instead of being buried in controls.
Command proactively explains why it is running a command, why a file is changing, and what it expects the result to be.
Execution updates should feel alive and technical without collapsing into unreadable raw logs or fake optimism.
The user can allow, deny, refine, pause, or inspect the system without tearing apart the execution context already in motion.
The UI must feel enterprise-grade and reassuring even while it is performing technical work at speed.
Multimodal Output System
Phase 1 already includes the foundation for creation, preview, delivery, and traceability
Outputs are not side effects. They are primary product objects with previews, downloads, versions, categories, and prompt lineage built into the same operator system.
- Apps and websites
- Images, video, and audio
- PDFs, documents, presentations, and spreadsheets
- Shared output schema regardless of modality
- Preview-first result cards
- Direct download and open actions
- Version records when a result is regenerated
- Import-to-Command workflow for iterative creation
- Source prompt and thread linkage
- Project or workspace context where relevant
- Timestamped creation records
- Asset category and file-type-aware presentation
A premium result card should immediately tell the user what was created, how to preview it, how to download it, and where it lives in the asset system.
Output: Product brief.pdf
Snapshot preview, file type, created time, source prompt, and version badge.
PreviewDownload
Open assetImport to Command
The asset library turns output history into a usable system: browse by type, inspect snapshots, reopen results, and keep the operator oriented over time.
Images / PDFs / Docs / Apps
Polished category filters with counts and status-aware cards.
Version awaretraceable
Download / save / remove / importready
Real-Time Operational Transparency
Live workstream visibility is one of the core differentiators of Phase 1
Command should feel alive because it is streaming real work, not because it is performing noisy theater. The operator must see what is happening, why it is happening, and what state the system is in.
The workstream layer follows a strict rule set: real backend events always win, fallback messages only appear when the real stream goes quiet, ambient language appears sparingly to keep the experience readable, and the system must never invent file names, commands, or completion states it does not actually have.
Readable action rows
Each work item needs a title, explanation, phase, status, and optional file or command context so the operator can scan progress quickly.
Backend events become UI language
Actual events should map into human-readable rows without losing the underlying technical meaning of the action.
Friendly, professional, or mixed voice
Progress language can adapt to tone settings, but it must remain precise and grounded in real action state.
Only when the real stream is quiet
Fallback lines keep the experience from going dead during silent windows, but they must never fake commands, files, or success.
Used sparingly to keep the system human
Low-frequency ambient lines can make the product feel alive without turning it into cartoon narration or spam.
Run state remains visible even when work moves on
Queued and active tasks need transparent status even if the operator is viewing another area of the product.
Reading brand brief.mdrunning
Running npm run buildqueued
Generating landing page assetsprocessing
Why this action
This build verifies whether the generated site compiles before Command marks the run as successful.
The system should keep the operator informed and entertained in a measured way, but the underlying truth of the execution state must always stay intact.
- Real events always replace fallback messages
- Command and file names only appear when actually known
- No early completion messages
- No fake “all good” states after recoverable failure
Safety + Control
Trust engineering is part of the Phase 1 blueprint, not an add-on
Command should feel powerful because it is well-bounded. Approvals, rollback posture, validation, provider safety, and local-first correctness all belong to the first serious system foundation.
Ask when needed, not constantly
Approval requests should appear when the system crosses meaningful risk or ambiguity boundaries, with clear allow, deny, and refine options.
Readable file change visibility
When files change, Command exposes a human-readable diff surface rather than hiding mutations behind generic success messages.
Revert readiness with honest limits
Rollback and revert cues must reflect real restore boundaries instead of aspirational claims.
Safe recovery behavior
Transient failures should trigger bounded retries, clearer explanations, and recoverable paths before the run is declared failed.
Real folders, honest state
Project operations must respect actual local folder availability, edit real files, and never imply persistence where none exists.
Secure auth and connection boundaries
Provider tokens, auth flows, and external execution surfaces should be explicit, revocable, and appropriately permissioned.
No fake success behavior
Command must verify output and runtime outcomes before claiming a run completed successfully.
Human control stays available
The operator can always stop, deny, or redirect a path without the product becoming unstable.
Safety in Phase 1 means the system stays transparent, bounded, and honest under load. It never hides actions, never invents success, never claims rollback without backing, and never lets provider complexity or local project risk silently degrade trust.
Mock Intelligence
Structured intelligence that already behaves like the final product architecture
The intelligence layer can still use simulation where necessary, but the surrounding system must already feel honest, structured, and compatible with the full production blueprint.
The intelligence layer is not just a placeholder text generator. It returns structured intent understanding, planning artifacts, event-shaping hints, explanation copy, approval summaries, and workstream narration that match the eventual production contracts. Where behavior is simulated, the system should say so through the architecture, not through weak UX or fake completion claims.
Command returns explicit execution briefs and understanding snapshots rather than a vague blob of assistant prose.
Even simulated planning creates ordered steps, scope boundaries, and expected outcomes the UI can render and the operator can trust.
Execution language is shaped for clarity so users feel the system is thinking in public, not hiding behind logs.
Approval copy summarizes what Command understood, what it wants to do next, and why that decision matters.
Intelligence outputs shape live event titles, explanations, and phase assignments without breaking truthfulness.
Safe simulation remains acceptable when a capability is not fully live, but the system still preserves production-shaped data, UI, and operator expectations.
What Command understood
Create a premium B2B landing page with a deployable local preview and matching brand assets.
Plan step 1: inspect contextready
Plan step 2: generate layoutready
Plan step 3: validate previewready
The intelligence layer generates operator-grade explanations so every major command or file change can be justified in plain language on demand.
- What Command is doing
- Why this action matters
- What it expects to confirm next
- What changed in the plan after new information arrives
Rules to Prevent Breakage
Guardrails that protect the broader Phase 1 system from design and architecture drift
These are trust and product rules as much as engineering rules. They preserve clarity, honesty, local-first correctness, and premium operator experience.
Service boundaries should stay explicit, but the product must not dissolve into tiny disconnected modules that are difficult to reason about.
Execution transparency must stay calm and readable instead of becoming a cluttered operations console.
Command must never imply that it completed, recovered, reverted, or validated work that it cannot actually prove.
File edits, commands, approvals, and provider interactions must remain visible enough to earn trust.
Provider support is part of the blueprint, but it must not destabilize the core execution and workspace foundations.
Restore and verification surfaces must reflect real system capability, not aspirational product copy.
Projects, folders, previews, and saved outputs must behave honestly on the user’s machine.
Ambient or fallback messaging can keep the product alive, but it can never fabricate commands, files, or certainty.
Even under technical load, the system must remain polished, readable, and structured like a serious product rather than an internal tool.
Final Output
What a real expanded Phase 1 handoff must include
The handoff now covers the entire serious product foundation: backend control plane, frontend operator experience, realtime visibility, asset handling, local project readiness, safety posture, and deployment quality.
1
Backend control planeTask, run, approval, output, rollback, provider, and event services implemented in a stable FastAPI foundation.
2
Structured task lifecycleUnderstanding, planning, execution, verification, and delivery artifacts are persisted and inspectable.
3
Realtime event streamLive backend events and workstream mapping support transparent execution UI.
4
Command workspace UILanding entry, three-panel workspace, execution overlay, and premium operator shell all behave coherently.
5
Approvals and diff reviewApproval surfaces, readable diffs, and revert-aware interaction patterns are included in the product surface.
6
Multimodal output foundationApps, media, and documents move through one previewable, downloadable, traceable output system.
7
Asset libraryCreated outputs are stored, categorized, version-aware, and reusable through a dedicated library surface.
8
Local-first project readinessProjects, folders, diffs, and local preview behavior are treated as real filesystem concerns.
9
Provider readinessExternal generation and connection surfaces are designed with real config, auth, and safety boundaries.
10
Rollback and recovery postureSnapshot, revert, retry, and self-healing semantics exist at the architectural and UI contract level.
11
Memory and preference readinessUser preference and session memory structures are ready to reduce friction without creating opaque behavior.
12
Deployable product foundationLocal development, containerization, cloud deployment, and roadmap-grade documentation all ship together.
Success Criteria
Definition of done for the expanded Phase 1 system blueprint
Success is no longer measured only by whether a narrow task loop exists. It is measured by whether Command already behaves like a serious, transparent, premium execution product with credible foundations.
1
Task creation is durableNew requests are stored with clear identifiers, status, and contextual metadata.
2
Understanding is structuredThe system produces readable intent artifacts before acting.
3
Planning is visibleOrdered plan steps and expected outcomes are available to the UI and the operator.
4
Execution stays safeRuns proceed through bounded lifecycle states with honest approval and validation behavior.
5
Live workstream feels realRealtime activity updates keep the user informed without fake commands, fake files, or noisy spam.
6
Approvals are contextualRequests for confirmation appear when they matter and remain readable and actionable.
7
Diffs are visible and usableFile changes can be reviewed, explained, and reversed through premium product surfaces.
8
Outputs are visibly generatedCreated apps, media, and documents appear with previews instead of disappearing into backend state.
9
Outputs are downloadableEvery asset that matters can be opened, downloaded, and re-imported into later work.
10
Asset traceability is intactPrompt, thread, project, version, and timestamp lineage remain attached to created outputs.
11
Local-first project behavior worksProjects open, preview, edit, and disappear honestly based on real local folder state.
12
Provider readiness is credibleProvider connection and secret boundaries are present and product-ready even when integrations vary by environment.
13
Explanation quality feels humanCommand can explain commands, file changes, actions, and next steps in language that reduces confusion.
14
Rollback and retry posture existsThe blueprint supports revert boundaries, safe recovery, and no-fake-success validation semantics.
15
Queue and background readiness are built inThe system model already supports longer-lived work, queued requests, and safer execution continuity.
16
The UX feels premium and deployableThe end result reads like a serious Rudraix product foundation, not a thin internal prototype.