> ## Documentation Index > Fetch the complete documentation index at: https://vietbui.mintlify.site/llms.txt > Use this file to discover all available pages before exploring further. # Control Plane Expansion Plan — Gap Analysis and Phase 0.5 Roadmap > Synthesizes gap analysis, tool landscape research, and concrete Phase 0.5 implementation steps for expanding the current agent setup toward a full Agentic En… # Control Plane Expansion Plan Synthesizes gap analysis, tool landscape research, and concrete Phase 0.5 implementation steps for expanding the current agent setup toward a full Agentic Engineering Control Plane. Source concept: 4-layer control plane architecture (execution/coordination/quality/experience layers) ## Current Setup Inventory What already exists: | Component | How Implemented | | ----------------------------- | ---------------------------------------------- | | Execution | `claude --bg`, `claude agents` TUI (v2.1.144+) | | Task state machine | `.agents/inbox/`, `claimed/`, `done/` dirs | | Task model | YAML frontmatter in `.agents/*.md` files | | Atomic claim (single-machine) | POSIX `mv` from inbox → claimed | | Quality gate | Hooks: biome, lint-autofix, pre-commit | | Context compression | `CLAUDE_AUTOCOMPACT_PCT_OVERRIDE=50` | | Council primitive | `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1` | | Agent isolation | `isolation: "worktree"` on Agent tool | ## Phase 1 Gap Analysis | Requirement | Coverage | Gap | | ---------------------------- | ------------------------------ | ------------------------------------- | | Kanban v1 | Partial — dirs exist | No board view / status skill | | Task schema | YES — YAML frontmatter | No validation layer | | Agent registry v1 | Partial — TUI shows sessions | No persistent `.agents/registry.json` | | Single-provider quality gate | YES — hooks | No approval UI or policy file | | Human approval v1 | **Missing** | Entire workflow absent | | Observability v1 | Partial — session output only | No centralized append-only log | | Multi-machine coordination | **Missing** | POSIX `mv` fails across machines | | Council quality gate | Partial — AGENT\_TEAMS env set | No council evaluator agents wired | Gaps cluster into two areas: * **Visibility**: kanban board, registry, event log * **Control**: approval workflow, council quality gate ## Tool Landscape — Buy vs Build ### Buy | Need | Tool | Rationale | | ---------------------- | ----------------------- | ------------------------------------------------------------------------------- | | Code review | CodeRabbit | 2M+ repos *(claimed, unverified)*, PR comments out of box, not worth building | | Eval framework | PromptFoo or Braintrust | CLI-first gates (PromptFoo) vs production dashboards (Braintrust) | | Observability | Langfuse | Open source, self-hostable, LLM-aware trace model | | Kanban UI | GitHub Projects | Free, already integrated with repo, no infra | | Workflow orchestration | LangGraph (if needed) | Production v1.0, battle-tested *(claimed, unverified)*; only needed at Phase 2+ | ### Build | Component | Why build | | -------------------------- | ------------------------------------------------ | | `/kanban-status` skill | Trivial board renderer — 1 skill file | | Agent registry + event log | JSON files — nothing to install | | Approval workflow skill | Agentic decision logic — domain-specific | | Council aggregation | Glue between parallel evaluators + majority vote | | Model tier routing | Already partially in model-routing.md rules | ## Phase 0.5 — Implementation Steps ### Step 1: Event Log Create `.agents/events.jsonl` — append-only, one JSON object per line: ```json theme={null} {"ts": "2026-05-19T10:00:00Z", "event": "task_claimed", "task": "TASK-001", "agent": "session-abc"} {"ts": "2026-05-19T10:45:00Z", "event": "task_complete", "task": "TASK-001", "result": "pass"} ``` Wire to Stop hook: emit `session_end` event with files changed, exit status. ### Step 2: Agent Registry Create `.agents/registry.json`: ```json theme={null} { "agents": [ {"id": "session-abc", "task": "TASK-001", "status": "running", "started_at": "...", "machine": "hostname"} ] } ``` Orchestrator writes on spawn; Stop hook writes on completion. ### Step 3: `/kanban-status` Skill Skill reads `.agents/inbox/`, `claimed/`, `done/`, `registry.json` and renders: ``` INBOX CLAIMED DONE ──────────── ──────────── ──────────── TASK-003 TASK-001 @abc TASK-002 ✓ TASK-004 TASK-005 @def ``` ### Step 4: Approval Workflow Skill Invoked before any agent auto-commit. Renders diff, blocks on stdin approval: ``` Agent: session-abc Task: TASK-001 Files: src/auth/middleware.ts (+42 -8) Approve? [y/n/diff]: ``` On approval: writes approval token to `.agents/approvals/.approved`. Agent's commit hook checks for token before proceeding. ### Step 5: Stop Hook Quality Summary Append to Stop hook: emit structured summary to stdout and to `.agents/events.jsonl`: ``` Session: session-abc | Task: TASK-001 Files changed: 3 | Tests run: 47 passed, 0 failed Status: COMPLETE ``` ## Phase 2 Preview — Multi-Machine Coordination POSIX `mv` for atomic claim only works on single machine (same filesystem). Multi-machine atomic claim: **git branch creation race on `refs/tasks/*`**: ```bash theme={null} git push origin HEAD:refs/tasks/TASK-001 # succeeds for first claimer # fails for others: "remote: error: cannot lock ref" ``` This is atomic across machines without a shared filesystem. No external coordination service needed. Task inbox becomes git branch per task. Orchestrator pulls `refs/tasks/*`, picks unclaimed (no corresponding `refs/tasks-claimed/*`), races to claim. ## Phase 3 Preview — Council Quality Gate Already have: `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1` as council engine primitive. Pattern: spawn 3 Haiku evaluators in parallel (acceptance criteria, code quality, style), collect PASS/FAIL + reasoning, majority vote, write signal file. See [Council Pattern](/concepts/council-pattern) for full 3-stage structure and cost model (\~15K tokens vs \~1K single-model). ## Critical Path Phase 0 → 0.5: **5 concrete deliverables, no new infra** — all implemented as SKILL.md files and JSON files. Phase 0.5 → 1: Buy Langfuse + GitHub Projects. Build approval UI. Schema validation layer. Phase 1 → 2: Git-based inbox migration. Multi-machine agent orchestrator. Phase 2 → 3: Wire council evaluators into Stop hook quality check. ## 2026-06 Update: Bootstrap Path New source synthesis sharpens the next build order: 1. **Cockpit action registry** — borrow [Agent-Native](/entities/agent-native)'s shared action/state philosophy. Define a local action vocabulary for tasks, sessions, approvals, artifacts, evidence, review packages, runners, and machines. Do not replace Commandr with Agent-Native's shared SQL runtime. 2. **agent-control skills** — adapt Builder.io's SKILL.md packaging pattern for reusable workflows: commandr-task, evidence-package, review-package, pentest-finding, runner-adapter, approval-policy, bus-debugger. 3. **commandr-omp-runner** — integrate [omp (oh-my-pi)](/entities/omp) as the first serious L2 worker after local shell/Claude/OpenCode. Start with a wrapper, then add omp custom tools for bus-native progress and approvals. Recommended immediate artifacts: | Artifact | Status | Purpose | | ----------------------- | ------------------- | ------------------------------------------------------------------------------------------ | | `COCKPIT-ACTIONS.md` | 📋 Pending | Design contract for UI/agent shared action vocabulary | | `agent-control-skills/` | 📋 Pending | Portable SKILL.md workflow library | | `commandr-omp-runner` | Scaffold/smoke only | L2 runner wrapper target; RPC host tools needed for real bus-native progress and approvals | Layer placement remains unchanged: skills are L1/L4, omp is L2, Commandr is L3, DiffViewer/Tauri is L5. ### commandr-omp-runner — Scaffold/Smoke Status Created scaffold: `commandr-omp-runner/setup.sh` + `runner.sh` + `README.md` * **Bootstrap** (`setup.sh`): installs omp, copies hooks/tools to agent dirs * **Runner** (`runner.sh`): runner-agnostic interface — task packet in, NDJSON out, progress events to file/stderr * **Interface**: `--task --workspace [--progress ] [--model ]` * **Exit**: 0 = success, 1 = failure * **Plugin**: pi-headroom documented as opt-in (not auto-installed) ### RPC Mode Discovery Research on `omp --mode rpc` reveals a better path than custom TypeScript plugins for bus integration: | Integration Approach | Effort | Language Lock-in | Bidirectional | | ----------------------------------- | ---------- | --------------------------------- | ------------- | | Custom TS plugins (Level 3) | High | TypeScript only | Limited | | **RPC host tools (Level 2+)** | **Medium** | **None — any JSON-lines process** | **Full** | | Subprocess + parse stdout (Level 1) | Low | None | One-way | **RPC host tools** let Commandr register `commandr_progress`, `commandr_request_approval`, etc. as host-side tools. The agent calls them via standard tool calling; the host (our runner) handles the bus side effects. No TypeScript required — the host can be Python, Rust, Go, or bash. **Recommended evolution:** * Phase 1 (current): `--mode json`, one-shot scaffold/smoke path * Phase 2: `--mode rpc`, register host tools for bus-native progress/approvals/artifacts * Phase 3: `--mode rpc-ui`, handle `extension_ui_request` for approval flows See Omp Snapcompact Rpc for full protocol analysis. ### snapcompact vs pi-headroom `snapcompact` (omp's native compaction) already truncates tool results to 2000 chars with head/tail preservation during archival compression. This is **conversation-level** (old turns → PNG frames). `pi-headroom` is **turn-level** (current turn tool outputs). They are complementary, not redundant. **pi-headroom status:** Keep as opt-in stopgap. Document that it handles bash output, search results, and eval kernel output — things not already truncated by omp's native read tool. Next: Level 2 via RPC host tools. Schema designed in `commandr-omp-runner/HOST-TOOLS.md`: * `commandr_progress` — milestone logging to events.jsonl * `commandr_emit_artifact` — artifact declaration (workspace + events.jsonl) * `commandr_request_approval` — policy-enforced approval (log-only at Level 1, blocking at Level 2) * `commandr_complete` / `commandr_fail` — task finalization * Policy table: bash rm/sudo/docker, write to .env/ssh, git push * Runner-agnostic: any L2 runner can implement the same schema ## Related Pages * [Shared Task Queue (Cross-Worktree)](/concepts/shared-task-queue) — current coordination primitive * [Worktree Isolation](/concepts/worktree-isolation) — agent filesystem isolation * [Council Pattern](/concepts/council-pattern) — quality deliberation layer * [Agent Teams](/concepts/agent-teams) — team coordination mechanics * [Rules vs. Hooks](/concepts/rules-vs-hooks) — static rules vs dynamic hook injection * [Agentic CI/CD](/concepts/agentic-cicd) — CI as external watchdog pattern