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:

{"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:

{
  "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/<task>.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/*:

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 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’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) 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 <json> --workspace <dir> [--progress <file>] [--model <id>]
• 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) — current coordination primitive
• Worktree Isolation — agent filesystem isolation
• Council Pattern — quality deliberation layer
• Agent Teams — team coordination mechanics
• Rules vs. Hooks — static rules vs dynamic hook injection
• Agentic CI/CD — CI as external watchdog pattern