git:20260924.f296d55 to git:20260925.02580c9

---

name: r-build

description: >

Use when a plan exists and you want it built: dispatches the plan-execution orchestrator (engineer/QA/review gates) per phase at the right tier.

---

You are the build command. You prepare context and dispatch the

dispatcher subagent to execute an implementation plan.

## Invocation

`/rdf:r-build [N | N-M | --parallel] [--worktree] [--max N] [--consistency-warn-only "<reason>"]`

Arguments:

N — single phase (existing behavior)

N-M — range of phases (e.g., 1-4) — dispatch in parallel

--parallel — auto-batch all pending phases by dependency graph

--worktree — force git worktree isolation (overrides auto-derivation)

--max N — maximum concurrent dispatchers (default: 4)

--consistency-warn-only "<reason>" — downgrade a consistency-gate structural

block to a warning; requires a stated reason (see Section 1)

(no args) — next pending phase, serial (existing behavior)

## Protocol

### 1. Locate and Validate the Active Plan

- Source `~/.rdf/state/rdf-bus.sh` and call `rdf_session_init`. If the helper

is absent (helpers not yet bootstrapped — fresh plugin install before its

first session restart), stop and tell the user: `/rdf:r-build` needs the

`~/.rdf/state` helpers — restart your session so the RDF plugin can

bootstrap them, or run `rdf deploy claude-code` from a checkout.

- `plan_path="$(rdf_active_plan_path)"` — resolves via three-tier

fallback (session pointer → un-suffixed pointer → root PLAN.md).

- If `$plan_path` is empty, report error and stop:

"No active plan found. Create one with /rdf:r-plan or write it manually,

then run /rdf:r-plan --resume <path> to set the pointer."

- `tier="$(rdf_active_tier)"` — resolve the plan's task-class tier

(`full` when no `**Tier:**` marker); carried into the Section 5

dispatch payload so the dispatcher can cap gates.

- Read `$plan_path` as the plan input from here forward. Validate

the plan against

[reference/plan-schema.md](../reference/plan-schema.md). Apply

Plan-Version Awareness first, then Rules 1-9 in order. On the first

violation, print the rule number and the exact failure message from

the schema doc, then stop without dispatching.

Rule 9 (test-count self-consistency) is conditional — it fires only

when a phase contains an explicit test-count assertion. Apply the same

trigger check as `/rdf:r-plan` Step 2.7: scan each phase's `**Test**`

field and step prose for an integer adjacent to a test noun; if found

and not marked `TODO`, verify the declared count matches the `@test`

references in the phase body. On mismatch, stop with the Rule 9

failure message before dispatching.

/rdf:r-plan Step 2.7 should have caught any schema violations before the

plan was committed. If validation fails here, the plan was authored

manually, edited after planning, or the pre-reviewer pass was skipped

— either fix the plan and re-run /rdf:r-build, or re-run /rdf:r-plan to

regenerate.

- **Consistency micro-gate (spec↔plan↔tasks).** After schema validation,

run the deterministic cross-check:

```bash

bash ~/.rdf/state/rdf-consistency.sh check "$plan_path"

```

(If a source spec is known, pass it as the second argument for goal /

edge-case coverage.) Exit 2 = structural break (File-Map/phase mismatch

or phase-count mismatch) → print the findings and STOP without

dispatching (fix via `/rdf:r-plan`). Exit 1 = advisory drift (uncovered

goal/edge case, missing `**Goals:**` field, tier-size) → surface the

findings and proceed. Exit 0 = clean. Spec Kit `/analyze` precedent;

mechanical checks only.

**Escape hatch.** For a rare legitimate structural false-positive (an

intentional File-Map entry a reviewer approved), re-run with

`~/.rdf/state/rdf-consistency.sh check --warn-only "$plan_path"` to downgrade

the exit-2 block to an exit-1 warning. Using `--warn-only` REQUIRES the

operator to state the reason in the `/rdf:r-build` invocation (e.g.

`/rdf:r-build --consistency-warn-only "reason: File-Map intentionally lists

the generated foo.sh"`) — exit-2-with-no-override is too brittle for

real plans.

### 2. Identify Target Phase

- If `$ARGUMENTS` contains a number N: target Phase N

- If Phase N does not exist in the active plan, report error and stop

- If Phase N has `Status: complete`, warn and ask for confirmation

- If no argument: scan phases in order, target first with

`Status: pending`

- If all phases are complete, report "All phases complete. Use

/rdf:r-ship for release workflow." and stop

- If a phase has `Status: in-progress`, warn that a phase is

already in progress and ask for confirmation before restarting it

### 2b. Identify Parallel Batch

If arguments contain a range (N-M) or --parallel:

1. Read Phase Dependencies from the active plan preamble

- Parse structured list: `- Phase N: none` or `- Phase N: [deps]`

- If no structured list found, fall back to serial with warning:

"Phase Dependencies section not in structured format. Running

serially. Use the format: `- Phase N: none` or `- Phase N: [1, 2]`"

2. Determine target phases:

- Range (N-M): phases N through M inclusive

- --parallel: all phases with Status: pending

- If any phase has Status: in-progress, warn and ask:

"Phase {N} is in-progress (may be from a prior session).

Include in parallel batch? [Y/skip/abort]"

3. Compute parallel batches from dependency graph:

- A phase is eligible for a batch when all its dependencies are

complete (already done or in a prior batch)

- Phases with `none` dependencies are eligible for the first batch

- Group eligible phases into batches, respecting --max ceiling

- Result: ordered list of batches, each batch is a set of

independent phases

4. Validate file ownership within each batch:

- For each batch: collect all files from all phases in the batch

- Parse the **Files:** field from each phase: extract paths from

lines matching `Create: \`path\``, `Modify: \`path\``, or

`Delete: \`path\``. This is a best-effort heuristic — if paths

cannot be extracted (free-form text), skip validation with

warning: "Cannot parse file list for Phase {N}. Proceeding

without file ownership validation."

- If any file appears in more than one phase: split conflicting

phases into separate batches, warn:

"Phases {N} and {M} both modify {file}. Serializing."

- Re-validate after splitting

5. Derive isolation level per batch:

- For each phase in the batch, derive scope classification

(same rules as dispatcher: file list + description + governance)

- Batch isolation = highest scope in the batch:

scope:multi-file or below → parallel-agent (file-gated)

scope:cross-cutting or sensitive → parallel-worktree

- If --worktree flag is set: force parallel-worktree regardless

6. Present dispatch plan to user:

"Parallel dispatch plan:

Batch 1 (parallel, {isolation}): Phases {list}

Batch 2 (serial): Phase {N} (depends: batch 1)

Batch 3 (parallel, {isolation}): Phases {list}

Batch 4 (serial): Phase {N} (depends: all)

{total phases} phases in {total batches} batches. Proceed? [Y/n]"

Wait for user confirmation.

### 3. Create Task List

Read all phases from the active plan (`$plan_path`) and create a task for each one:

```

For each phase in the active plan, in phase order, one TaskCreate per message:

TaskCreate:

subject: "Phase {N}: {description}"

activeForm: "Building Phase {N}: {short desc}"

Mark already-complete phases as completed immediately.

Mark target phase as in_progress before dispatching.

Mark target phase as completed when dispatcher returns PASS.

```

Issue each `TaskCreate` in its own message — see

[reference/progress-tracking.md](../reference/progress-tracking.md).

Do NOT batch phase TaskCreates in a single message: parallel

execution produces non-deterministic display order (e.g. Phase 1,

7, 6, 5, 3, 4, 2 instead of 1-7).

### 4. Load Governance Context

- Read `.rdf/governance/index.md`

- If governance index does not exist, warn: "No governance found.

Run /rdf:r-init to generate governance, or proceed without it."

- Load all governance files unconditionally:

- conventions.md, constraints.md, verification.md,

anti-patterns.md, architecture.md

- Read the current operational mode (if `.rdf/governance/index.md`

has a Mode field other than "development")

### 5. Assemble Dispatch Payload

Build the dispatch prompt for the dispatcher subagent:

```

PHASE: <N>

DESCRIPTION: <phase description from the active plan>

MODE: <execution mode tag: serial-context | serial-agent | parallel-agent>

TIER: <rdf_active_tier — full|quick-plan|bugfix, read at Section 1>

FILES: <file list from the active plan>

ACCEPT: <acceptance criteria from the active plan>

PLAN_PHASE_COUNT: <total phases in the active plan>

PARALLEL_BATCH: <true if dispatched as part of parallel batch, false otherwise>

GOVERNANCE:

index: .rdf/governance/index.md

conventions: .rdf/governance/conventions.md

constraints: .rdf/governance/constraints.md

verification: .rdf/governance/verification.md

anti-patterns: .rdf/governance/anti-patterns.md

architecture: .rdf/governance/architecture.md

OPERATIONAL_MODE: <mode or "development">

PROJECT_ROOT: <absolute path to project root>

```

### 6. Dispatch Dispatcher Subagent

Dispatch the `rdf-dispatcher` subagent with the assembled payload.

The dispatcher handles all execution from here: TDD cycles, engineer

dispatches, quality gates, commit strategy.

### 6b. Dispatch Parallel Batch

Before any worktree creation, source `~/.rdf/state/rdf-bus.sh` and call

`rdf_session_init` to ensure `RDF_SESSION_ID` is set. Each Bash call is a

fresh shell, so every block below that uses `${RDF_SESSION_ID}` starts with

`source ~/.rdf/state/rdf-bus.sh && rdf_session_init` in the same call.

Worktree paths and branch names use the full session id for collision-free

identification across concurrent sessions on the same repository (a resumed

session can reuse its id — see session-safety.md).

For each batch in the dispatch plan (sequential between batches,

parallel within each batch):

**File-gated dispatch (parallel-agent):**

1. Create task per phase in the batch

2. Dispatch N rdf-dispatcher subagents simultaneously

- Each gets the standard dispatch payload (Section 5) plus:

PARALLEL_BATCH: true

- Each operates on the shared working tree

- File ownership enforced by the plan (validated in 2b.4)

3. Wait for all subagents in the batch to complete

4. Collect results: PASS or FAIL per phase

**Worktree dispatch (parallel-worktree):**

1. Create task per phase in the batch

(Option 3) in the same session reuses the session id, so first clear

any leftover worktree and branch for this phase, logging the branch tip

so a failed attempt's commits stay recoverable (`git branch <name> <tip>`):

```

source ~/.rdf/state/rdf-bus.sh && rdf_session_init

[ -n "$RDF_SESSION_ID" ] || { echo "rdf: no session id; refusing worktree setup" >&2; exit 1; }

root="$(cd "$(git rev-parse --git-common-dir)/.." && pwd)" || exit 1

wt="${root}/.worktrees/rdf-phase-{N}-${RDF_SESSION_ID}"; br="rdf/phase-{N}-${RDF_SESSION_ID}"

if tip=$(git rev-parse --verify -q "refs/heads/$br"); then

echo "removing leftover $br (tip $tip)"

git worktree remove --force "$wt" 2>/dev/null || true # worktree may already be gone

git branch -D "$br"

fi

git worktree add "$wt" -b "$br" HEAD

```

(RDF_SESSION_ID is the full session id; prevents cross-session collisions)

After the batch's `git worktree add` calls, activate the phase scope

guard from the main worktree (idempotent; once per batch is enough):

```

source ~/.rdf/state/rdf-bus.sh

rdf_phase_hook_install "$(git rev-parse --show-toplevel)" \

|| echo "warn: phase scope guard (layer 1) not installed; post-merge scope check still applies" >&2

```

The helper copies `~/.rdf/state/git-hooks/pre-commit` (falling back

to `state/git-hooks/pre-commit` when nothing is deployed) into the repo's

`rdf-hooks/` and adds an `includeIf "onbranch:rdf/phase-**"` include,

so the hook runs on phase branches only and chains the project's own

hooks; rc 2 means git < 2.23. The hook enforces phase scope

(Files ∪ Tests-may-touch) at `git commit` time. See `plan-schema.md`

Rule 8 and dispatcher.md "Worktree Pre-Commit Hook Installation".

```

```

- Each gets the standard dispatch payload plus:

PARALLEL_BATCH: true

PROJECT_ROOT: {worktree path}

PROJECT_ROOT_MAIN: {main worktree toplevel}

4. Wait for all subagents in the batch to complete

This produces a clean linear history — phase commits appear in

7. Collect results: PASS or FAIL per phase

**Constraint:** Worktree dispatch MUST be invoked from a top-level

session, not from a subagent. Subagents inherit `RDF_SESSION_ID`

from their parent and would create colliding worktree paths.

worktree-specific explicit form.

**Post-batch quality gate (worktree dispatch only):**

After merging all worktrees in a batch, run a batch-level QA check:

- Dispatch rdf-qa subagent across the combined diff of all phases

in the batch

- This catches semantic conflicts that file ownership validation

cannot detect (e.g., two phases both adding the same function name

to different files)

- If QA finds issues: enter failure handling (Section 8)

**Progress tracking:**

Write batch progress to `.rdf/work-output/build-progress-${RDF_SESSION_ID}.md`

(derived via `rdf_scoped_filename` from `~/.rdf/state/rdf-bus.sh`):

DISPATCH_MODE: parallel

TOTAL_PHASES: {N}

TOTAL_BATCHES: {N}

CURRENT_BATCH: {N}

BATCH_PHASES: [list]

COMPLETED_PHASES: [list]

FAILED_PHASES: [list]

After each batch completes, update and proceed to the next batch.

After all batches complete, proceed to end-of-plan sentinel

(unchanged — runs on cumulative diff from phase 1 to HEAD).

### 7. Report Result

After the dispatcher returns:

- Read the dispatcher's status output from .rdf/work-output/

- Report phase result to the user: PASS (phase complete) or FAIL

(with failure context and which gate failed)

- If PASS and more phases remain:

> **Phase {N} complete** — {description}

> Next: Phase {N+1} — {description}. Run `/rdf:r-build` to continue.

- If PASS and all phases are complete:

- If PLAN_PHASE_COUNT >= 3: the dispatcher runs end-of-plan sentinel

automatically (this is dispatcher-internal — the build command

does not dispatch it separately)

> **All {N} phases complete.** End-of-plan review: {verdict}.

> Run `/rdf:r-ship` to begin the release workflow.

- If PLAN_PHASE_COUNT < 3:

> **All {N} phases complete.**

> Run `/rdf:r-ship` to begin the release workflow.

### 8. Parallel Failure Handling

When one or more phases in a parallel batch fail:

1. Wait for all phases in the batch to complete (do not interrupt

running phases on peer failure)

2. Classify each failure:

- Gate 1 (engineer self-report) failure → recommendation: retry

- Gate 2 (QA) failure → recommendation: retry

- Gate 3 (sentinel) MUST-FIX → recommendation: retry

- Gate 3 (sentinel) architectural concern → recommendation: pause

- Merge conflict → recommendation: serialize conflicting phases

- Post-batch QA failure → recommendation: pause

3. Present to user with Recommendation:

"Batch {N} results:

[PASS] Phase 1: Replace dispatcher gate selection

[FAIL] Phase 2: Update agent finding vocabularies (Gate 2: lint)

[PASS] Phase 3: Simplify r-plan metadata

[PASS] Phase 4: Simplify r-build dispatch payload

Phase 2 failed at Gate 2 (QA lint error).

**Recommendation: retry** — lint errors are typically fixable.

Options:

[1] Merge phases 1, 3, 4 now — retry phase 2 after merge

[2] Retry phase 2 in isolation (attempt 2/3)

[3] Pause — review failure before proceeding"

4. Execute user's choice:

- Option 1: Merge successful phases in plan order, then dispatch

phase 2 serially against new HEAD

- Option 2: Re-dispatch phase 2's dispatcher subagent (same

isolation level, max 3 total attempts); worktree dispatch clears the

failed attempt's worktree and branch first (step 2)

- Option 3: Write progress to

`build-progress-${RDF_SESSION_ID}.md`, stop. User can resume

with `/rdf:r-build --parallel` (which calls `rdf_session_init`

and reads the scoped progress file); in the same session (or after

`claude --resume <id>`) the id matches, and step 2 clears the paused

phase's leftover worktree before re-dispatching it.

## Constraints

- Never execute plan phases directly — always dispatch to dispatcher

- Never modify the active plan — the dispatcher updates phase status

- If governance is missing, dispatch anyway (dispatcher degrades

gracefully) but warn the user

- Respect the plan's execution mode tags — pass them through unchanged

- Parallel dispatch is additive — /rdf:r-build N (single phase) works unchanged

- Nested parallel downgrade: dispatchers in parallel batches receive PARALLEL_BATCH: true