LIFEAI/rdc:build

⚠️ OUTPUT CONTRACT (READ FIRST): guides/output-contract.md Checklist-only output. No tool-call narration. No raw MCP/JSON/log dumps. One checklist upfront, updated in place, shown again at end with a 1-line verdict.

Sandbox contract: This skill honors RDC_TEST=1 per guides/agent-bootstrap.md § RDC_TEST Sandbox Contract. Destructive external calls short-circuit under the flag.

rdc:build — Typed Agent Dispatch Engine

When to Use

• Plan is approved and ready to execute
• Project lead says "build it", "go", "execute", "do not stop"
• An epic exists with child tasks ready for implementation
• Called by rdc:overnight as part of the automated build loop

Arguments

• rdc:build <epic-id> — build from a specific Supabase epic
• rdc:build <topic> — find the epic by label/title match
• rdc:build (no args) — show open epics and ask which to build (interactive only)
• rdc:build <epic-id> --unattended — silent mode for overnight builds

Agent Types & Guide Files

Every dispatched agent MUST read two files before starting — in this order:

1. {PROJECT_ROOT}/.rdc/guides/agent-bootstrap.md — credentials, git rules, completion report format (fallback: .rdc/guides/agent-bootstrap.md relative to cwd if {PROJECT_ROOT} is not substituted)
2. {PROJECT_ROOT}/.rdc/guides/engineering-behavior.md — assumptions, minimal changes, surgical scope, verification evidence (fallback: .rdc/guides/engineering-behavior.md relative to cwd if {PROJECT_ROOT} is not substituted)
3. {PROJECT_ROOT}/.rdc/guides/<type>.md — role-specific guide (fallback: .rdc/guides/<type>.md relative to cwd if {PROJECT_ROOT} is not substituted)

Include both lines in every agent prompt:

"Read {PROJECT_ROOT}/.rdc/guides/agent-bootstrap.md first (fallback: .rdc/guides/agent-bootstrap.md), then {PROJECT_ROOT}/.rdc/guides/engineering-behavior.md (fallback: .rdc/guides/engineering-behavior.md), then {PROJECT_ROOT}/.rdc/guides/<type>.md (fallback: .rdc/guides/<type>.md) before starting."

| Agent Type | Guide File | When to dispatch | |-----------|-----------|-----------------| | frontend | .rdc/guides/frontend.md | React components, pages, UI, Tailwind, animation | | backend | .rdc/guides/backend.md | API routes, server components, database queries, auth | | data | .rdc/guides/data.md | Migrations, schema changes, RPC functions | | design | .rdc/guides/design.md | Visual design, brand palettes, OG images, token work | | infra | .rdc/guides/infrastructure.md | CI/CD, deployment, DNS, SSL | | content | .rdc/guides/content.md | Marketing copy, messaging, tone | | cs2 | .rdc/guides/cs2.md | CS 2.0 paradigm work (generic) | | hail | .rdc/guides/cs2.md + packages/hail/CLAUDE.md | Grammar, DSL compiler, evolution | | pal | .rdc/guides/cs2.md + packages/pal/CLAUDE.md | Sessions, moment windows, graph memory | | bpmn | .rdc/guides/cs2.md + docs/systems/<domain>/flowable-bpmn-architecture.md | BPMN flows, governance | | virtue | .rdc/guides/cs2.md + packages/virtue-engine/CLAUDE.md | Virtue weights, coherence, certification | | viz | .rdc/guides/frontend.md + .rdc/guides/design.md | Custom viz components, charts, diagrams |

How to classify a task → agent type

Read the task title and description, then:

• Mentions React, component, page, UI, Tailwind → frontend
• Mentions API route, server, database query, auth → backend
• Mentions migration, schema, table, RPC → data
• Mentions brand, palette, typography, OG image → design
• Mentions deploy, infrastructure, CI, DNS → infra
• Mentions copy, messaging, email template → content
• Mentions grammar, DSL, compiler → hail
• Mentions session, moment, memory graph → pal
• Mentions BPMN, flow, governance → bpmn
• Mentions virtue, coherence, certification → virtue
• Mentions visualization, chart, diagram, SVG → viz
• Multiple types? Dispatch multiple agents, each with its guide.

Procedure

1. Load the epic and run pre-flight gate:

   SELECT get_work_items_by_epic('<epic-id>', 'todo');
   

   Session lock — claim the epic immediately (before any agent dispatch):

   After loading the epic, check its status:

   • If status = 'in_progress' → ABORT with:

     SKIP: epic <id> is already in_progress — claimed by another session. Pick a different epic.
     

     Do NOT proceed. Do NOT dispatch any agents.
   • If status = 'todo' or status = 'blocked' → immediately claim it:

     SELECT update_work_item_status('<epic-id>'::uuid, 'in_progress',
       '["Claimed by build session — dispatching agents"]'::jsonb
     );
     

     This is an atomic Supabase write. A concurrent session that loads the same epic after this point will see in_progress and abort. Do this before any classification, planning, or agent dispatch.

   Pre-flight gate — run after claiming:

   | Condition | Action | |-----------|--------| | No child tasks returned | → Invoke rdc:plan on this epic. Do NOT proceed with build. | | Tasks exist but all have empty description fields | → Invoke rdc:plan on this epic. Tasks without descriptions cannot be safely dispatched. | | Plan doc missing ## Checklist Decomposition Matrix | → Invoke rdc:plan on this epic. Do NOT dispatch agents. | | Plan doc missing ## Checklist Quality Gate with verdict: PASS | → Invoke rdc:plan on this epic. Do NOT dispatch agents. | | Any implementation task lacks decomp-* checklist items | → Invoke rdc:plan on this epic. Coarse checklists cannot be safely dispatched. | | Any decomp-* item lacks route/file, action, expected result, or evidence artifact | → Invoke rdc:plan on this epic. Do NOT dispatch agents. | | Tasks exist and have descriptions | → Continue with build. |

   Re-planning is not a failure — it is correct behavior. The build skill is the last gate before agent dispatch; catching an under-specified epic here is cheaper than a wasted agent run.

   How to re-plan:

   • Interactive: tell the user — "Epic has no tasks / tasks lack descriptions — invoking rdc:plan first." Then invoke rdc:plan <epic-id>.
   • Unattended: invoke rdc:plan <epic-id> --unattended inline, wait for it to complete, then reload tasks and re-run this gate once. If tasks still missing after re-plan, escalate via advisor.

   Interactive (no args): show open epics, ask which to build.

2. CHECK FOR EXISTING WORK (mandatory — never skip):

   -- Check if prototypes exist from earlier sessions
   SELECT name, component, source_path, status, notes
   FROM prototype_registry
   WHERE status IN ('prototype', 'converting')
   ORDER BY created_at DESC;
   
   -- Check for design decisions on this topic
   SELECT topic, context_type, summary, source
   FROM design_context
   WHERE topic ILIKE '%<epic-topic>%'
   ORDER BY created_at DESC;
   

   If a prototype exists: ADAPT IT. Do not build from scratch. Tell the agent: "Read <source_path> first and convert it to the production contract."

   If design decisions exist: follow them. Include the summary in the agent prompt.

3. Load the plan (mandatory): check .rdc/plans/ for matching topic (fallback: .rdc/plans/).

3b. Checklist decomposition quality gate (mandatory before code):

rdc:build is the final gate before implementation. It MUST reject any plan or work item that is too coarse for an agent to execute and verify independently.

Required plan sections:

• ## Checklist Decomposition Matrix
• ## Checklist Quality Gate
• verdict: PASS

Required task checklist shape:

• Every implementation work item has at least one decomp-* checklist row and one test-* checklist row.
• Every decomp-* row names a concrete route or file path.
• Every decomp-* row names one user/agent action.
• Every decomp-* row names one expected UI/API/DB result.
• Every decomp-* row names one verification artifact: test name, route probe, Playwright screenshot, SQL query, API response, type-check, migration proof, or CLI transcript.

Atomicity rubric:

• One observable behavior per decomp-* row.
• The row can pass or fail without reading hidden intent from the plan narrative.
• The row is small enough for a worker to implement, tick, and cite evidence for directly.
• Vague rows such as "theme management works", "UI implemented", "verified", "all screens", or "integration complete" are failures.

Minimum decomposition heuristics:

• UI route: at least empty/loading/loaded/error or the documented reason a state does not apply.
• CRUD surface: at least list, create, edit, detail, duplicate/delete/archive where applicable, and validation failure.
• API route: at least successful read/write, validation failure, and unauthorized/forbidden or documented auth bypass.
• DB/migration task: at least schema object, relationship/guard, policy/permission, seed/fixture or backfill, and smoke query.
• Editor/sidebar/CLI workflow: at least start, attach/open, enqueue action, observe result, timeout/error, and live refresh where applicable.

If the gate fails:

• Interactive: show the failing rows and invoke rdc:plan <epic-id> to repair the matrix before dispatch.
• Unattended: invoke rdc:plan <epic-id> --unattended, reload tasks, and run this gate once more.
• If the second gate fails, abort the build and return the failure list. Do not dispatch implementation agents.

Plan verifier escalation: A separate verifier agent is optional, not default. Dispatch one only when the plan touches 5+ UI routes, 3+ data/API boundaries, auth/security, production deployment, or when this rubric fails twice. The verifier reads the plan and work-item checklists only; it does not write code.

4. Read CLAUDE.md files for all affected packages.

5. Classify each task → assign agent type from the table above.

5b. Write or refresh the checklist into every work item before dispatching: For each task, append the exact decomp-* and test-* checklist rows to its notes BEFORE setting to in_progress: sql SELECT update_work_item_status('<id>'::uuid, 'in_progress', '["CHECKLIST: [ ] decomp-ui-route-state: <route/file> | action=<action> | expect=<result> | evidence=<artifact>, [ ] test-smoke-route: <route probe>, [ ] committed"]'::jsonb ); The agent must complete every item on this checklist and return it checked off in AGENT_COMPLETE. A checklist with unchecked items = incomplete work. Do not proceed to next wave with unchecked items.

6. Group tasks into waves — parallelize tasks with no file overlap:

   • Wave 1: independent tasks (different packages/files)
   • Wave 2: tasks that depend on Wave 1 outputs
   • Wave 3: integration tasks

7. For each wave — dispatch typed agents in parallel:

   ⛔ Agent Dispatch Non-Negotiable Defaults

   Every Agent() call MUST include these parameters — no exceptions:

   model: <chosen per the routing table below>
   max_turns: 70
   isolation: "worktree"
   

   Agent model routing — pick per task, not per wave. The supervisor session model does NOT cascade to agents; you must set model explicitly on every dispatch.

   | Task character | Model | When to pick it | |---|---|---| | Updates, edits, mechanical refactors, small fixes, content tweaks, config patches, doc/copy edits, straightforward API wiring | claude-sonnet-4-6 | Default for frontend.md/content.md/infrastructure.md work whose checklist is mostly "change X to Y" or "wire up endpoint Z". Budget-safe for parallel dispatch. | | Harder coding tasks — non-trivial algorithm, migration with backfill, schema reshape, multi-file refactor with subtle invariants, performance-sensitive code, anything where correctness is the bar | claude-opus-4-6 | Default for backend.md/data.md work and any frontend.md task that involves state machines, race conditions, or cross-package contracts. | | Design or innovative thought — new component design, brand/UX work, CS 2.0 paradigm work (HAIL/Quad Pixel/AEMG/Virtue), grammar evolution, architecture-first design, anything where the shape of the solution is the deliverable rather than the implementation | claude-opus-4-8 | Default for design.md/cs2.md work. Also use for backend.md/data.md tasks tagged with architecture or design-decision in work item labels. |

   How to choose when the task straddles categories:

   • If the task's checklist contains the word "design", "decide", "propose", "evaluate alternatives", "novel", or any CS 2.0 primitive → Opus 4.8.
   • If the task touches packages/cs2*, packages/hail, packages/quad-pixel, packages/virtue-engine, packages/aemg, packages/planetary-ontology, or packages/being-state-processor → Opus 4.8 (CS 2.0 paradigm requires innovative thought, not transcription).
   • If the task is a Supabase migration that drops/renames/reshapes anything, or a refactor across ≥5 files → Opus 4.6.
   • Otherwise → Sonnet 4.6.

   State the choice in the wave plan. Before dispatching a wave, the supervisor must log one line per agent in the form [wave-N agent-K] role=<role> task=<id> model=<chosen> reason=<one phrase>. This keeps routing decisions reviewable in the transcript and lets rdc:report summarize the fleet mix.

   Cost guardrail. If a single wave would dispatch more than 3 Opus 4.8 agents in parallel, downshift the lowest-priority Opus-4.8 tasks to Opus 4.6 unless their work items are tagged priority=urgent. Opus 4.8 fast-mode is cheap individually but still ~5× a Sonnet agent at scale. Without max_turns: 70, agents hit the default turn cap mid-task and stop. isolation: "worktree" gives each agent its own git worktree and branch — eliminates push race conditions and index lock contention when multiple agents commit in parallel. The supervisor merges worktree branches after each wave (Step 9).

   Forked agents vs. standalone agents

   When the supervisor has already read the plan (via a prior Read tool call in the same session), dispatch forked agents with short prompts. Forked agents inherit the full conversation context — including every file the supervisor has read — so you do NOT need to copy plan sections, file specs, or architecture details into the prompt. The agent already sees them.

   Short forked prompt template:

   You are a frontend agent building <WP name>. Work item: <uuid>.
   Scope: <one sentence>. Files: <list>. Verification: tsc --noEmit.
   Set item to review when done, return AGENT_COMPLETE with verification evidence.
   Read .rdc/guides/agent-bootstrap.md + .rdc/guides/engineering-behavior.md + .rdc/guides/frontend.md before starting.
   

   When the supervisor has NOT read the plan (e.g. dispatching from a fresh rdc:build call with only an epic ID), the agent has no plan context — write a full briefing prompt with all specs.

   ---

   Required agent prompt contents

   • Set work item to in_progress before dispatching
   • Each agent prompt MUST include:
     • "Read {PROJECT_ROOT}/.rdc/guides/agent-bootstrap.md first (fallback: .rdc/guides/agent-bootstrap.md), then {PROJECT_ROOT}/.rdc/guides/<type>.md (fallback: .rdc/guides/<type>.md) before starting."
     • "Read {PROJECT_ROOT}/.rdc/guides/engineering-behavior.md (fallback: .rdc/guides/engineering-behavior.md) before editing; follow it for assumptions, minimal changes, surgical scope, evidence, and escalation."
     • Specific files to create/modify (or omit if forked agent inherits plan context)
     • Exact deliverables and commit message
     • "NEVER run pnpm build/test. NEVER modify files outside your scope."
     • "You are running in an isolated git worktree. Commit your work normally. Do NOT push to origin — the supervisor merges your branch after the wave completes."
     • "When done, set your work item to 'review' (NOT 'done') and return AGENT_COMPLETE with a verification field. The validator closes work items — you do not."
     • "COMPLETION PROOF REQUIRED in AGENT_COMPLETE: list every file written, the exact commit hash, and paste the vitest/tsc output. A report without this evidence will be rejected."
     • "If you find that a file or feature already exists: you MUST still verify it satisfies the full task spec before marking review. Finding a file is not completion. Run verification, check every requirement, and report what you found vs. what was required."
     • The decomposition items from the work item's checklist (all decomp-* prefixed items). Include them verbatim in the prompt and instruct the agent:

       DECOMPOSITION CHECKLIST — you MUST implement/verify each row and tick it immediately via update_checklist_item(..., p_actor_session_id := '<your-session-id>', p_actor_role := 'agent'):
       - decomp-ui-xxx: <route/file> | action=<action> | expect=<result> | evidence=<artifact>
       - decomp-api-xxx: <route/file> | action=<action> | expect=<result> | evidence=<artifact>
       Tick each item as soon as that specific behavior is implemented and proven. Do NOT batch.
       

     • The test plan items from the work item's checklist (all test-* prefixed items). Include them verbatim in the prompt and instruct the agent:

       TEST PLAN — you MUST implement/verify each of these and tick them off via update_checklist_item(..., p_actor_session_id := '<your-session-id>', p_actor_role := 'agent'):
       - test-assert-xxx: <description> → write a vitest test that proves this
       - test-smoke-xxx: <description> → run the command and confirm the result
       - test-visual-xxx: <description> → note: delegate to UI audit (you cannot verify this yourself)
       - test-contract-xxx: <description> → verify the export/type/shape exists
       Tick each item as you complete it. Do NOT batch — tick immediately after each verification.
       

   • Use run_in_background: true for parallel execution
   • NEVER let agents overlap on the same files

8. Post-wave test gate (mandatory): After all agents in a wave complete, before proceeding:

   # For each package modified in this wave:
   cd packages/<name> && npx vitest run 2>&1 | tail -20
   

   • All tests must pass before proceeding to next wave
   • If tests fail: fix before proceeding
   • NEVER use pnpm build or pnpm turbo test — vitest only per package
   • New code must have tests: if a modified package shows 0 new test files, flag it

9. After all wave agents complete — merge worktrees and push:

   Each completed agent returns a worktree branch (e.g. claude/agent-frontend-abc123). Merge them all to develop before running the test gate:

   # For each worktree branch returned by agents in this wave:
   git merge --no-ff <worktree-branch> -m "merge(<agent-type>): <task-title>"
   

   • Resolve any conflicts before proceeding — do not skip
   • Worker agents set items to review — do NOT close to done yet
   • After all branches merged, push once:

     if [ "$RDC_TEST" != "1" ]; then
       git push origin develop
     else
       echo "[RDC_TEST] skipping git push"
     fi
     

   • Then run the post-wave test gate (Step 8) on the merged state
   • Then run the code-review gate (Step 9b) before the next wave dispatches
   • Continue to next wave

   If an agent fails (returns no worktree branch):

   • Interactive: diagnose before retrying
   • Unattended: retry once; on second failure escalate via advisor

     BUILD_STATUS: { wave, tasks_done, tasks_failed, commits, escalated: true }
     

9b. Mandatory per-wave code-review gate (runs after merge + test gate, BEFORE next wave dispatches):

⛔ **NO wave may dispatch until the previous wave's code-review pass clears.** Memory `feedback_code_review_per_wave.md` — Davesend 2026-05-24 incident.

Dispatch ONE `pr-review-toolkit:code-reviewer` agent with the wave's merged diff:

```
Agent({
  subagent_type: "pr-review-toolkit:code-reviewer",
  description: "Wave <N> code review",
  prompt: "Review the diff `git diff <wave-base-sha>..HEAD` on develop.
           Focus on: bugs, logic errors, security vulnerabilities, project-convention adherence
           (.claude/rules/*, CLAUDE.md). Apply confidence-based filtering — high-confidence
           findings only. Report severity per finding: critical | high | medium | low.
           Return CODE_REVIEW_COMPLETE with: { critical_count, high_count, medium_count,
           low_count, findings: [{severity, file:line, issue, suggested_fix}] }."
})
```

**Severity gate (default — high+ blocks):**
- `critical` or `high` findings → reopen affected work items to `todo` with finding text in notes; fix in a new wave before continuing
- `medium` or `low` findings → append to each work item's `implementation_report.flags`; do NOT reopen; validator sees them
- Zero findings → log `CODE_REVIEW: CLEAN` and proceed to next wave

Under `RDC_TEST=1`: echo `[RDC_TEST] skipping code-review dispatch` and proceed.

10. Mandatory validator gate (runs after ALL waves complete — before any work item closes):

⛔ **NO work item may be set to `done` without the validator passing it.**

Dispatch ONE validator agent with the complete list of `review` work items and the full git diff.
⚠️ The validator does NOT use `isolation: "worktree"` — it must read the fully merged develop branch. Omit the isolation parameter for this dispatch only.

```
"Read {PROJECT_ROOT}/.rdc/guides/agent-bootstrap.md then {PROJECT_ROOT}/.rdc/guides/verify.md.
 Read {PROJECT_ROOT}/.rdc/guides/engineering-behavior.md before validating scope, deviations, and evidence.
 Validate these work items: [list of IDs and titles].
 Apps touched: [list].
 Git diff since build start: [attach or reference].
 You are the ONLY agent that closes work items to done.
 Follow verify.md procedure exactly: tsc → vitest → dev server route probes → record result per item."
```

The validator:
- Runs `npx tsc --noEmit` for every touched app/package
- Starts the dev server and probes every modified route (expects HTTP 200, not 500)
- Runs vitest for every touched package
- **Verifies checklist decomposition quality per work item before functional validation:**
  - Every implementation work item has at least one `decomp-*` item and one `test-*` item
  - Every `decomp-*` item includes route/file, action, expected result, and evidence artifact
  - Any unchecked `decomp-*` item with `required: true` = work item CANNOT be set to `done`
  - Any coarse or non-falsifiable `decomp-*` item = reopen to `todo` with the specific failure
- **Verifies test plan completion per work item:**
  - For each `test-assert-*` checklist item: confirm a corresponding vitest test exists and passes
  - For each `test-smoke-*` checklist item: run the command and confirm exit code / HTTP status
  - For each `test-visual-*` checklist item: note as "delegated to UI audit" (validator cannot verify visuals)
  - For each `test-contract-*` checklist item: verify the export/type/shape exists in the built code
  - Any unchecked `test-*` item with `required: true` = work item CANNOT be set to `done` (DB enforces this)
- Sets passing items to `done`, failing items back to `todo` with failure detail
- Returns `VALIDATOR_COMPLETE` report with test plan status per item

**If the validator finds failures:** fix them in a new wave, then re-run the validator. Do not skip.
**File existence alone is NOT verification.** A route returning 500 is a failure regardless of tsc passing.
**Unchecked test plan items are a hard gate** — `update_work_item_status('done', ..., p_actor_role := 'validator')` will raise an exception if any `required: true` checklist item is unchecked, missing agent-session tick evidence, or re-ticked by a supervisor/validator.

11. After verification passes: - All wave commits are already on develop and pushed (Step 9 pushes after each wave merge). - Update epic version: bump_epic_version() - Report summary with verification evidence quoted

Agent TDD Requirements

When dispatching agents, include in every prompt:

TDD REQUIREMENT: Write tests FIRST for new functions/modules.
Run: npx vitest run packages/<name> to verify red → implement → verify green.
NEVER run pnpm build or pnpm turbo. Use npx vitest run only.

Rules

• Branch: development branch only (auto-commit, no confirmation needed)
• NEVER let two agents edit the same file
• NEVER run pnpm build (crashes system) — code only
• Every agent reads its guide file — no exceptions
• Update Supabase work items IN REAL TIME — not batch at end
• Push after each wave, not just at the end
• Unattended: NEVER pause — continue automatically
• Unattended: max 2 retries per task before escalating to advisor
• Every Agent() dispatch: model: <routed> + max_turns: 70 + isolation: "worktree" — non-negotiable. Model is chosen per task per the routing table in Step 7: Sonnet 4.6 for updates/edits, Opus 4.6 for harder coding, Opus 4.8 for design/innovative thought (CS 2.0, brand/UX, architecture). Supervisor logs model=<chosen> reason=<phrase> per agent. Exception: validator agent in Step 10 omits isolation; validator model stays claude-sonnet-4-6 (verification, not generation).
• Finding an existing file is NOT task completion — verify it satisfies the spec

Capture lessons (exit step)

Before the final verdict line, follow .rdc/guides/lessons-learned-spec.md § Capture procedure. If this run taught something non-obvious — a first root-cause theory that turned out wrong, the documented/standard path not working, a missing gate or check that cost a round, or a surprising tool/infra behavior — write one .rdc/lessons/<YYYY-MM-DD>-build-<short-slug>.md per lesson using the schema in that spec. Set scope (simple | architectural) and status (open, or applied if you shipped the fix in this same run, with the commit linked). Commit the lesson file(s) on develop alongside the run's other commits, and note "N lessons captured" in your verdict/summary. A run that taught nothing writes nothing — absence is the default.