> ## 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. # Builder.io Patterns for Commandr + DiffViewer > Builder.io's Agent-Native and Skills repos help our workflow in two concrete ways: # Builder.io Patterns for Commandr + DiffViewer Builder.io's Agent-Native and Skills repos help our workflow in two concrete ways: 1. **Shared action vocabulary** — humans and agents should invoke the same validated actions, whether the trigger is a UI click, tool call, CLI command, MCP call, or runner adapter. 2. **Inspectable visual artifacts** — plans and recaps should become durable review packages, not chat walls. They do **not** replace [Commandr](/entities/commandr) or its `.agents/` bus. Commandr remains L3 source of truth. DiffViewer remains L5 projection and action UI. Builder.io patterns shape the seams between them. ```mermaid theme={null} flowchart LR subgraph Inputs["Action Triggers"] HumanClick["human click"] AgentProposal["agent proposal"] RunnerEvent["runner adapter"] SkillCall["visual-plan / visual-recap skill"] end subgraph Dispatcher["DiffViewer Action Dispatcher"] Schema["schema validation"] Risk["risk classification"] Policy["approval policy"] end subgraph Commandr["Commandr Live SPEC Actions"] Claim["task.claim"] Progress["task.progress"] Complete["task.complete / task.fail"] Annotate["annotation.create"] Approve["approval.approve"] Council["council.run"] end subgraph Local["DiffViewer / Runner Local Projections"] Plan["plan.md"] Recap["review-package.json"] Evidence["screenshots / logs / LSP summaries"] Proposal["approval proposal card"] end Inputs --> Schema --> Risk --> Policy Policy -->|SPEC mutation| Commandr Policy -->|local projection| Local SkillCall --> Plan SkillCall --> Recap RunnerEvent --> Evidence Local -. optional neutral note .-> Progress Commandr -->|source of truth| Recap Local -. never authoritative .-> Commandr ``` *** ## Layer Mapping | Builder.io idea | Our layer | Concrete use | | --------------------------- | ---------------------------------------- | --------------------------------------------------------------------------------------------------------- | | Agent-Native `defineAction` | L5 action registry + L3 command wrappers | Define one action schema for UI clicks and agent proposals. Route lifecycle actions to Commandr commands. | | Shared SQL-backed state | DiffViewer/Tauri local cache only | Use SQLite for fast UI state and audit projection, but rebuild from `.agents/` and artifacts. | | `/visual-plan` | L4/L5 planning artifact | Generate a pre-code plan package with file map, diagrams, open questions, approval checklist. | | `/visual-recap` | L5 review package | Generate end-of-task recap with diffs, screenshots, tests, council verdict, risks. | | `/agent-watchdog` | Review workflow | Audit another runner/session from bus events, sidecars, artifacts, and git diff. | | `/plan-arbiter` | Multi-agent planning gate | Compare competing plans, choose one, write the decision into the task packet or plan artifact. | | `/efficient-frontier` | Model routing | Keep expensive models on judgment; use cheaper runners for scans, edits, logs, and artifact generation. | | `/read-the-damn-docs` | L4 retrieval discipline | Require qmd/context7/raw-source pass before implementing external integrations. | *** ## Commandr Contract Commandr should expose action-like verbs, but every bus mutation must still map to SPEC v0.3 or a future conformance-backed SPEC change. | Action | Current Commandr side effect | Status | | ------------------- | --------------------------------------------------------------------------------------------------------------- | ------------------------- | | `task.claim` | `bin/claim`; move `inbox/` → `claimed/`; append `task_claimed` | Live SPEC | | `task.progress` | `bin/progress`; append neutral `task_progress` | Live SPEC | | `task.complete` | `bin/complete`; move `claimed/` → `done/`; append `task_complete` | Live SPEC | | `task.fail` | Supervisor appends `task_failed`; normal completion with unmet criteria uses `bin/complete fail` | Live SPEC | | `annotation.create` | `bin/annotate-write`; write `.agents/annotations/...`; append `task_annotation` | Live SPEC | | `approval.approve` | Write `.agents/approvals/.approved` | Live SPEC | | `approval.deny` | Write nothing; optional neutral `task_progress` note | Live SPEC behavior | | `council.run` | `bin/council`; write `.agents/council/.json`; append `council_verdict` | Live SPEC | | `approval.request` | DiffViewer/local runner artifact only; no `.pending` file | Non-SPEC local projection | | `artifact.create` | `.diffviewer/artifacts//...` or runner workspace artifact | Non-SPEC local projection | | `review.generate` | DiffViewer creates review package from bus + sidecars + git diff | Non-SPEC local projection | | `runner.start` | Runner adapter creates session/worktree and then uses bus commands | Non-SPEC adapter action | Rule: `approval_requested`, `artifact_created`, `.agents/approvals/*.pending`, `.denied`, and runner workspace paths stay outside SPEC until DiffViewer has a real consumer and Commandr adds conformance checks. *** ## DiffViewer Contract DiffViewer should implement the Builder.io pattern as a local action dispatcher: ```ts theme={null} type CockpitAction = { name: string; schema: unknown; actor: "human" | "agent" | "system"; risk: "low" | "medium" | "high"; requiresApproval: boolean; handler: "commandr" | "diffviewer" | "runner"; auditEvent: "local" | "commandr" | "none"; }; ``` Human clicks and agent proposals enter the same dispatcher. The dispatcher validates input, classifies risk, checks approval policy, then calls the right handler. Agent text never jumps directly to side effects. DiffViewer-owned artifacts should live outside `.agents/`, for example: ```text theme={null} .diffviewer/artifacts// plan.md review-package.json review-package.md screenshots/ lsp-summary.json command-log-summary.json ``` These artifacts are regenerated projections. Losing them should not corrupt task lifecycle. *** ## Visual Plan Package Builder.io `/visual-plan` maps to a pre-implementation package rendered by DiffViewer. Inputs: | Source | Data | | ------------------ | ---------------------------------------------------- | | Commandr packet | Goal, acceptance criteria, files to touch, non-goals | | qmd / llm-wiki | Relevant patterns, prior decisions, docs | | CGC / CodeBoarding | file map, architecture graph, blast radius | | Human annotations | constraints, approvals, steer notes | Output: `.diffviewer/artifacts//plan.md`. Required sections: | Section | Purpose | | ------------------ | ------------------------------------------------------- | | Scope | One sentence on what will change | | File map | Files likely touched and why | | Action plan | Ordered implementation steps | | Risk table | risky files/actions and mitigation | | Verification gates | typecheck, tests, visual, screenshot, council, approval | | Open questions | only blockers, not routine ambiguity | | Approval checklist | what human approves before code starts | Commandr relationship: the plan is **not** the task packet. The packet remains the work contract; the plan is a rendered aid and can be referenced from `task_progress` as a neutral note. *** ## Visual Recap / Review Package Builder.io `/visual-recap` maps directly to DiffViewer's end-of-task review package. Inputs: | Source | Data | | ----------------------------------- | ------------------------------------------------- | | Git diff | changed files, hunks, stats | | `.agents/events.jsonl` | lifecycle, progress, annotations, council verdict | | `.agents/council/.json` | vote reasons and final verdict | | `.agents/approvals/.approved` | approval state | | `.diffviewer/turns/` | per-turn file edits and sidecars | | Runner workspace | logs, screenshots, diagnostics, command summaries | | LSP/CodeBoarding | diagnostics, symbols, architecture impact | Output: `.diffviewer/artifacts//review-package.json` plus a rendered Markdown/MDX view. Minimal JSON shape: ```json theme={null} { "task": "TASK-001", "status": "review", "summary": "One sentence outcome.", "changedFiles": [{ "path": "src/auth.ts", "kind": "edit", "risk": "medium" }], "verification": [{ "name": "tests", "status": "pass", "evidence": "npm test" }], "approvals": { "approved": false, "tokenPath": ".agents/approvals/TASK-001.approved" }, "council": { "verdict": "PASS", "abstentions": 0 }, "artifacts": [{ "type": "screenshot", "path": "screenshots/login.png" }], "residualRisks": ["Manual staging deploy not run"] } ``` DiffViewer can render this as cards: overview, file map, risk, verification, screenshots, logs, approvals, council, residual risks. *** ## Workflow ```text theme={null} 1. Human or agent creates Commandr packet 2. DiffViewer action `review.generatePlan` creates visual plan artifact 3. Human approves direction via annotation or task approval workflow 4. Runner claims task through Commandr 5. Runner emits neutral progress and local artifacts 6. DiffViewer watches `.agents/`, sidecars, and artifact dirs 7. Runner completes/fails task through Commandr 8. DiffViewer action `review.generateRecap` builds visual recap 9. Council runs as advisory quality gate 10. Human approves commit through existing `.approved` token gate ``` This preserves the thin waist: Commandr records lifecycle; DiffViewer records UI/action/audit projections; runners own private execution state. ```mermaid theme={null} flowchart TD A["Task packet created"] --> B["Optional visual plan generated"] B --> C{"Human direction clear?"} C -->|needs clarification| D["annotation.create"] D --> B C -->|yes| E["Runner claims task"] E --> F["Implement / research / test"] F --> G["Neutral task_progress"] F --> H["Sidecar turns + local artifacts"] G --> I["DiffViewer review surface"] H --> I I --> J{"Risk or gap?"} J -->|yes| K["human annotation / steer"] K --> F J -->|no| L["Runner completes task"] L --> M["Council advisory review"] M --> N["Visual recap / review package"] N --> O{"Human approves commit?"} O -->|no| K O -->|yes| P[".agents/approvals/.approved"] P --> Q["Commit gate passes"] ``` *** ## Implementation Slices ### Slice 1: No-SPEC-Change Review Package Build in DiffViewer only. Acceptance criteria: | Requirement | Check | | --------------------------------------------------------- | ----------------------------------------------------------------- | | Reads Commandr bus and git diff | No writes to `.agents/` except existing approval/annotation paths | | Writes `.diffviewer/artifacts//review-package.json` | Regenerable and ignored from git | | Renders a review package card | Includes diff stats, tests, council, approval state | | Emits optional `task_progress` | One-line neutral note only | ### Slice 2: Action Registry Add a local dispatcher in DiffViewer. Acceptance criteria: | Requirement | Check | | ------------------------------------------ | --------------------------------------- | | Every action has schema/risk/handler | No ad-hoc side-effect endpoints | | Agent proposals use same path as UI clicks | Invalid schema returns structured error | | Commandr mutations shell to `bin/` tools | No raw bus file manipulation from UI | ### Slice 3: Builder-Style Skills Package workflows as reusable skills consumed by OpenCode/Claude/Pi/omp. Candidate skills: | Skill | Output | | ---------------- | ------------------------------------------ | | `commandr-task` | claim/progress/complete discipline | | `visual-plan` | plan artifact for DiffViewer | | `visual-recap` | review package artifact | | `agent-watchdog` | audit of another runner/session | | `bus-debugger` | SPEC conformance and stale-state diagnosis | Skill rule: a skill may call Commandr commands or write DiffViewer-local artifacts. It must not invent bus files or parse runner-private state as authority. ### Slice 4: Future SPEC Artifact References Only after Slice 1 proves real UI value, consider a Commandr SPEC v0.4 artifact event. Candidate event shape: ```json theme={null} {"ts":"","event":"artifact_ref","task":"TASK-001","kind":"review-package","path":".diffviewer/artifacts/TASK-001/review-package.json","summary":"Review package generated"} ``` This needs SPEC text, conformance checks, and a migration decision. Until then, artifact references stay local or as human-readable `task_progress` notes. *** ## Non-Goals * Do not replace `.agents/` with Agent-Native SQL state. * Do not add `.agents/approvals/*.pending` or denial files. * Do not emit non-SPEC events from Commandr. * Do not store runner transcripts or LSP caches on the bus. * Do not make DiffViewer authoritative for lifecycle. * Do not adopt Builder.io templates wholesale before the local action/artifact seam works. *** ## Related Pages * Builderio Agent Native — source summary for shared actions and app surfaces. * Builderio Skills — source summary for visual-plan, visual-recap, watchdog, arbiter, efficient-frontier. * [Commandr](/entities/commandr) — L3 bus and SPEC boundary. * [DiffViewer](/entities/diffviewer) — L5 UI and Tauri cockpit direction. * [Desktop AI Agent Control Plane — Architecture Synthesis](/syntheses/desktop-control-plane) — big-picture 5-layer control plane. * [Agent Skills](/concepts/agent-skills) — portable `SKILL.md` packaging pattern. * [Tool Design for Agents](/concepts/tool-design-for-agents) — schemas and recovery-friendly tool contracts.