docs/architecture.md

AIOS Cockpit Architecture

Role

AIOS Cockpit is the homogeneous surface over the existing agentic system. It is not a new planning brain and not a new execution engine.

Sources

• Focus and operating constraints: samuel-os-v2
• Routing: KomandoZentral
• Harness profiles and run records: Zentrale
• Prompt memory: PromptGarage
• Evaluation evidence: harness experiment databases and HarnessEcosystem
• Safety/coaching: Sidecar-V8 and its plan repo

MVP Flow

1. Read today's focus and active priorities.
2. Show integration-source projects separately from active/parked projects.
3. Route a concrete task through KomandoZentral.
4. Generate a canonical handoff for Codex/OpenCode/Claude.
5. Show latest run/eval/prompt signals as evidence.

V2 additions

• Project detail pages expose README/PLAN context without editing source repos.
• Run detail pages expose Zentrale run artifacts.
• Handoffs are saved under handoffs/ with frontmatter metadata.
• CodexMaxHarnessHowTo is mounted as a first-class local runbook.

V3 workbench

The primary UI is /workbench, a three-column agent terminal:

• Left rail: project selector, task queue, source-of-truth shortcuts.
• Center: active task, routing, handoff, run preview actions.
• Right pane: today's focus, project context, runbook, latest runs.

V3 writes only cockpit-owned artifacts:

• workspace/tasks/*.json
• workspace/runs/*.json
• workspace/runs/*-instructions.md
• handoffs/*.md

The run preview uses Zentrale's existing opencode-prompt --dry-run path. It does not execute a source-mutating agent command in V3.

Non-goals

• No database in v0.1.
• No autonomous execution from the UI.
• No migration of all old projects.
• No second routing engine.