Work Start

/work-start "" [WD-nn | next | all | --parallel [N]] [--nested]

Bridges a work definition from a work group into the implementation pipeline. Creates a .feature/ directory and hands off to planning, testing, and implementation. For specification-only work (producing specs, ADRs, or interface contracts), use /work-plan instead.

Arguments:

• <group-slug> — the work group to draw from
• WD-nn — start a specific work definition (e.g., WD-01)
• next — auto-select the highest-value READY work definition
• all — sequentially run every SPECIFIED WD (one subagent per WD, waits for each to finish before starting the next). See "Sequential all mode" below. Use this for context-economy on multi-WD groups — the parent stays small while each subagent gets a fresh context.
• --parallel [N] — start every SPECIFIED WD concurrently (optionally cap at N concurrent sub-agents). See "Parallel mode" section below.

If no WD argument is provided, defaults to next.

Subagent contract — MANDATORY for every dispatch. Every WD this skill dispatches (in all, --parallel, or single-WD modes) MUST be given this preamble at the top of its prompt:

Subagent contract: Honor rules/completeness-contract.md (load-bearing — no silent deferrals; trigger phrases = escalation signals, not completion modes). If you cannot complete assigned scope, escalate via AskUserQuestion with user-validatable proof. A return claiming COMPLETE alongside deferred items is a contract violation.

When WD sub-agents return, /work-start MUST run the return-validation script BEFORE accepting COMPLETE:

mkdir -p /tmp/vallorcine
return_file=/tmp/vallorcine/work-start-return-"<group-slug>"-"<wd-id>".txt
printf '%s\n' "$FULL_RETURN_TEXT" > "$return_file"
bash .claude/scripts/validate-subagent-return.sh "$return_file" --require-ac-coverage 2>/tmp/vallorcine/validator-stderr.txt
rc=$?

• rc=0 → proceed with COMPLETE.
• rc=1 → trigger phrase detected. Block COMPLETE. Use AskUserQuestion with the question "WD- claimed COMPLETE but the return contains deferral trigger phrases. Approve as-is, re-dispatch with expanded scope, or stop?" and the validator's stderr as context. Options:
  • "Approve as-is" — user authorizes deferred items, mark COMPLETE
  • "Re-dispatch with expanded scope" — send back with deferred items added to scope
  • "Stop" — pause and inspect manually
• rc=2 → tooling error. Log to stderr, treat as rc=0 (don't block on infrastructure failures).

Choosing between all and --parallel:

Both delegate to the same single-WD /work-start flow, so quality at arbitration boundaries is identical — both modes set automation_mode: autonomous for the dispatched sub-agents (escalations surface, routine choices auto-default).

Step 1 — Validate work group

Check .work/<group-slug>/ exists. If not:

Work group '<group-slug>' not found.

Available groups:

List directories in .work/ (excluding _archive, _refs). Stop.

Step 2 — Run readiness resolver

bash .claude/scripts/work-resolve.sh "<group-slug>"

Parse the output to determine the readiness state of all WDs.

Display opening header:

───────────────────────────────────────────────
🚀 WORK START · <group-slug>
───────────────────────────────────────────────

Step 3 — Select work definition

If all is the argument:

Skip the single-WD selection logic and go to the Sequential all mode section below. The rest of Step 3's single-WD paths (WD-nn / next) do not apply.

If --parallel flag is present:

Skip the single-WD selection logic and go to the Parallel mode section below. The rest of Step 3's single-WD paths (WD-nn / next) do not apply.

If specific WD (e.g., WD-01):

Check the WD's status in the resolver output.

If SPECIFIED: proceed to Step 4.

If BLOCKED: check the blocker detail from the resolver output.

• If blocked by wd: deps (predecessor WDs not complete): report which WDs must complete first. Do not offer to start — the ordering exists for a reason.

  WD-<nn> (<title>) is BLOCKED by predecessor work definitions:
    <list blockers from resolver>
  
  Complete these first, or use /work-start "<group-slug>" next to auto-select
  a WD that is ready.
  

  Stop.
• If blocked by unmet artifact deps (spec/adr/kb): this WD needs specification.

  WD-<nn> (<title>) needs specification before implementation.
  Run /work-plan "<group-slug>" WD-<nn> first.
  

  Use AskUserQuestion with options:
  • "Run /work-plan first"
  • "Start anyway (skip specification)"
  • "Stop"

If READY or SPECIFYING: the WD has not been through /work-plan yet.

WD-<nn> (<title>) needs specification before implementation.
Run /work-plan "<group-slug>" WD-<nn> first.

Use AskUserQuestion with options:

• "Run /work-plan first" (description: "Specify this WD to produce its required artifacts")
• "Start anyway (skip specification)" (description: "Proceed without specs — not recommended")
• "Stop"

If "Run /work-plan first": invoke /work-plan "<group-slug>" WD-<nn>. If "Start anyway": proceed to Step 4 with a warning logged.

If IMPLEMENTING: check if a feature directory already exists for this WD:

WD-<nn> is already being implemented.
Feature directory: .feature/<group>--<wd-slug>/

Resume with: /feature-resume "<group>--<wd-slug>"

Stop.

If COMPLETE:

WD-<nn> is already COMPLETE. Nothing to do.

Stop.

If "next" (or no WD specified):

From the SPECIFIED WDs, select the one with the most downstream dependents (i.e., the WD whose completion would unblock the most other WDs). This maximizes unblocking value.

If multiple WDs tie on unblocking value, prefer the one with fewer artifact dependencies (simpler work first).

If no WDs are SPECIFIED:

No work definitions are SPECIFIED in '<group-slug>'.

Status:
  <ready>  ready (needs /work-plan first)
  <specifying> specifying
  <implementing> implementing
  <complete> complete

Run /work-plan "<group-slug>" to specify a ready WD first.

Stop.

Display the selected WD:

Selected: WD-<nn> — <title>
  Domains: <domains>
  Deps: <dep count> (all satisfied)
  Unblocks: <list of WDs this will unblock, or "none">

Use AskUserQuestion with options:

• "Start WD-"
• "Pick a different WD"
• "Stop"

Step 4 — Create feature directory

Generate a feature slug from the work group and WD:

<group-slug>--<wd-id-lowercase>

Example: auth-migration--wd-01

Create .feature/<slug>/ directory.

4a — Generate brief.md

Read the WD file (.work/<group-slug>/WD-<nn>.md). Build brief.md from:

# Feature Brief: <WD title>

**Source:** Work group '<group-slug>', WD-<nn>
**Generated:** <YYYY-MM-DD>

## Description
<WD Summary section content>

## Acceptance Criteria
<WD Acceptance Criteria section content>

## Constraints
<WD Implementation Notes section content>

## Artifact Dependencies (from work group)
<List each artifact_dep with its current state>

## Produced Artifacts (expected outputs)
<List each produces entry>

## Work Group Context
<Run work-context.sh --group "<group-slug>" and include relevant excerpt>

4b — Verify implementation readiness

If the WD's artifact_deps include unresolved items (the WD was started with "Start anyway" in Step 3), display a warning:

  Warning: This WD has unresolved artifact dependencies.
  Consider running /work-plan "<group-slug>" WD-<nn> first to produce
  the required specifications.

Proceed regardless — the user explicitly chose to start.

4c — Write status.md

Write .feature/<slug>/status.md with the standard format plus work group metadata:

work_group: <group-slug>
work_definition: WD-<nn>
pipeline_mode: implementation

Set stage = planning, substage = loading-context.

If --nested was passed (this single-WD invocation is being driven by /work-start all, /work-start --parallel, or /work-run — i.e., this whole /work-start is itself running inside a dispatched sub-agent), add these additional fields:

nested_in_dispatch: true
execution_strategy: cost

Why: the dispatched-sub-agent context cannot itself dispatch nested Agent tool calls — /feature-coordinate (which /feature-plan would otherwise invoke for balanced/speed strategies) needs Agent dispatch for its work-unit parallel batches. Inside an already- dispatched sub-agent, that nested dispatch fails at runtime. The orchestrator already provides parallelism at the WD level (multiple sub-agents running concurrently); within each WD, sequential execution is correct.

/feature-plan honors nested_in_dispatch: true by forcing execution_strategy: cost and routing directly to /feature-test --unit WU-1 (or sequential single-WU flow) rather than invoking /feature-coordinate. /feature-coordinate has a defensive guard in its Step 0 that errors out if invoked with this flag set.

Stage Completion table — implementation stages only:

4d — Claim the WD (SPECIFIED → IMPLEMENTING)

Use work-claim.sh for the status transition. It does an atomic compare-and-swap under flock so two parallel sessions racing to start implementation on the same WD cannot both succeed — the second one gets a CONFLICT and bails out.

if ! bash .claude/scripts/work-claim.sh "<group-slug>" "WD-<nn>" SPECIFIED IMPLEMENTING; then
  echo ""
  echo "Another session has already started this WD. Run:"
  echo "  /work-resume \"<group-slug>\""
  echo "to see what to do next (likely: /feature-resume \"<group>--<wd-slug>\")."
  exit 1
fi

# Refresh the manifest table and readiness JSON cache so other skills
# and parallel sessions see the new state without waiting for the next
# /work-status call.
bash .claude/scripts/work-resolve.sh "<group-slug>" >/dev/null

The manifest table is automatically synced by work-resolve.sh — do not update it manually.

Step 5 — Hand off to pipeline

Feature directory created: .feature/<slug>/
Pipeline mode: implementation (specifications already exist)

Proceeding directly to work planning — specs and ADRs will be loaded
from the resolved context.

Invoke /feature-plan "<slug>".

Sequential all mode

When invoked with all, /work-start runs every SPECIFIED work definition in the group one at a time, dispatching a separate sub-agent that executes the existing single-WD /work-start flow for each. The coordinator (this skill, in the user's conversation) carries only the dispatch state and one-line summaries of completed runs — the heavy 200K-per-WD planning + testing + implementation context lives inside each sub-agent and is gone when it returns.

This is the structural automation of the /clear + /work-resume + /work-start WD-N rhythm: same per-WD context economy, same dependency-respecting selection, no /clear or /work-resume typed by the user during the run.

When to use all vs --parallel

Both run every SPECIFIED WD in the group. The trade-off is wall-clock vs. resource isolation, NOT quality of arbitration — both modes delegate to the same single-WD /work-start flow which uses the same mode-gating in pipeline skills.

all (sequential):

• Context economy is the priority — multi-WD groups that would otherwise accumulate context across skill switches.
• No spec/test resource contention by construction — one sub-agent at a time.
• One arbitration session per WD — the user only sees prompts for the WD currently in flight.

--parallel:

• Wall-clock speed is the priority AND the WDs are runtime-isolated.
• N× token cost is acceptable.
• Concurrent sub-agents may serialize on shared writes (manifest, KB) — see Parallel mode caveats.

Both modes use automation_mode: autonomous and execution_strategy: cost for the dispatched sub-agents (set by the single-WD flow at Step 4c via the --nested flag; nested sub-agents cannot dispatch nested Agent calls so /feature-coordinate's parallel batching can't run inside them, and the parallelism is already provided at the WD level by this skill). Routine choices auto-default; escalations surface to the user.

Sequential-all flow

Replace Steps 3–5 with this block when all is the argument.

1. Initial enumeration. Read _readiness.json (refreshed by the resolver call in Step 2) and collect WDs into three sets:

   • specified — WDs whose status is SPECIFIED. Dispatch the full single-WD /work-start pipeline for each.

   • stranded_implementing — WDs whose status is IMPLEMENTING (or the legacy alias IN_PROGRESS) that are NOT being actively run by another session. These are typically WDs whose prior /work-start run claimed them (SPECIFIED → IMPLEMENTING) but didn't finish the pipeline — for example, a crashed sub-agent or a stalled /feature-coordinate dispatch. Route these via /feature-resume "<feature-slug>" (NOT another /work-start, which would re-trigger work-claim.sh and fail on the already- IMPLEMENTING state). The feature slug is <group>--<wd-id>.

     Active vs stranded distinction. A WD is stranded (eligible for re-dispatch) if EITHER:

     • .work/<group>/_dispatch-<wd-id>.json does not exist, OR
     • The marker exists but is in state fail (prior attempt errored), OR
     • The marker is in state begin and its dispatched_at is more than 30 minutes old (assume the dispatcher died).

     A WD is active (skip — another session is running it) if the marker is in state begin and was written within the last 30 minutes. Surface skipped active WDs in the plan display so the user can stop their other session if it's actually dead.

   • needs_planning — WDs whose status is SPECIFYING. These are mid-/spec-author arbitration and need /work-plan "<group-slug>" "<wd-id>" to finish. Surface them as informational; /work-start all does not start planning work.

   If specified and stranded_implementing are BOTH empty, report and stop:

   No work to start in '<group-slug>' — no SPECIFIED or stranded
   IMPLEMENTING WDs.
   <if needs_planning is non-empty:>
   Note: <P> WD(s) need /work-plan "<group-slug>" to finish their
   arbitration (currently SPECIFYING):
     - WD-<nn> — <title>
     - ...
   

2. Show the plan. Compute the initial run order — sort by unblocking value (most downstream dependents first), tie-breaking by fewer artifact dependencies. IMPLEMENTING WDs sort BEFORE SPECIFIED ones (finish in-flight work first). Display:

   ── Sequential start plan ──────────────────────
   Group: <group-slug>
   Stranded IMPLEMENTING WDs to resume: <M>  (via /feature-resume)
   SPECIFIED WDs to start: <N>               (full pipeline)
   <if needs_planning is non-empty:>
   Note: <P> SPECIFYING WD(s) need /work-plan first:
     - WD-<nn> — <title>
   <if any active-skipped WDs:>
   Skipping (another session active): <list of WD-ids>
   <end>
   Initial order (by unblocking value, IMPLEMENTING first):
     1. WD-<nn> [resume] — <title>  (unblocks: <list>)
     2. WD-<nn> [start]  — <title>  (unblocks: <list>)
     3. ...
   Note: a WD's completion may unblock a sibling that's currently
   BLOCKED on a wd: dep — the loop re-enumerates between iterations,
   so the run may include WDs not in this initial list.
   ───────────────────────────────────────────────
   

   Use AskUserQuestion to confirm:

   • "Run sequentially" (Recommended)
   • "Cap at 3" (or another cap)
   • "Stop"

3. Iterate until no eligible WD remains. Loop:

   a. Re-enumerate. Run bash .claude/scripts/work-resolve.sh "<group-slug>" >/dev/null then re-read _readiness.json. Re- enumerating is mandatory — completing a WD in iteration N may satisfy a wd: or spec dep that promotes a sibling from BLOCKED to SPECIFIED in iteration N+1.

   b. Pick the next. From the combined stranded_implementing ∪ specified sets, pick the WD with the highest unblocking value (same heuristic as Step 2; IMPLEMENTING WDs sort before SPECIFIED ones). Skip WDs the run has already dispatched (track in a dispatched set keyed by WD id). Also re-evaluate the "active vs stranded" check (Step 1) on each iteration — markers can flip from begin to ack/fail between iterations. If no eligible WD remains, exit the loop.

   c. Honor the cap. If the user chose a cap in Step 2 and the dispatched count has reached it, exit the loop.

   d. Dispatch ONE sub-agent. Route based on the WD's current status — same coordinator, different inner skill:

   • SPECIFIED → sub-agent invokes single-WD /work-start "<group>" <wd-id> --nested (handles feature dir creation, claim, full pipeline).
   • IMPLEMENTING (stranded) → sub-agent invokes /feature-resume "<group>--<wd-id>" (picks up the existing feature directory from where the prior pipeline stopped; no claim needed — WD is already IMPLEMENTING).

   Do NOT hand-roll feature creation + claim + pipeline dispatch logic in this coordinator. Each inner skill handles its respective flow correctly.

   Before the Agent call, write a dispatch marker so a lost-payload or rejected-dispatch failure does not leave the coordinator's task list silently out of sync with reality:

   bash .claude/scripts/work-dispatch.sh begin "<group-slug>" "<wd-id>"
   

   This creates .work/<group-slug>/_dispatch-<wd-id>.json with ack: false. Step 3f flips it to ack: true once the result is parsed (or marks failure_reason when parsing fails). The marker is what /work-resume uses to detect stuck dispatches and surface them as recovery candidates. For resume-mode dispatches, the marker overwrites any stale pre-existing marker — the new one supersedes.

   Then invoke the sub-agent. Use ONE of the two prompts below based on the WD's status.

   Prompt A — SPECIFIED WD (fresh start):

   You are the sequential pipeline runner for <group-slug> /
   <wd-id>.
   
   Invoke /work-start "<group-slug>" <wd-id> --nested. The single-WD
   flow will create the feature directory with nested_in_dispatch:
   true + execution_strategy: cost in status.md (because nested
   dispatch can't invoke /feature-coordinate — see /work-start's
   4c section), claim the WD via work-claim.sh (SPECIFIED →
   IMPLEMENTING), and hand off to /feature-plan → /feature-test →
   /feature-implement → /feature-refactor → /feature-pr.
   
   Treat automation_mode as autonomous. Do not pause between
   pipeline stages. If a stage hits a TECHNICAL escalation (test
   conflict, missing tests, refactor escalation), record it in the
   feature's cycle-log.md and continue with remaining stages where
   possible — this is auto-handled and reported in your summary.
   
   If a stage hits a USER-REQUIRED escalation (design ambiguity,
   missing context the kit can't supply, irreconcilable spec
   conflict, an impossible requirement), follow the user-required
   escalation contract from /work-start: write
   .feature/<feature-slug>/escalation.json with the schema in the
   "User-required escalation contract" section, append a
   `user-escalation — <category>: <question>` entry to cycle-log.md,
   set status.md substage to `awaiting-user-input`, then halt the
   WD and return ESCALATION_AT_<stage> as below.
   
   Distinguish these return modes in your final return:
   
   - If the /work-start invocation reports a `[claim] CONFLICT:`
     message from work-claim.sh (another terminal advanced the WD
     between the coordinator's enumeration and this dispatch),
     return:
       "<group-slug>--<wd-id>: SKIPPED — claim conflict"
   
   - If you wrote escalation.json per the contract, return:
       "<group-slug>--<wd-id>: ESCALATION_AT_<stage> — <category>: <question>"
   
   - Any other failure (feature directory creation, status.md
     write error, pipeline escalation, unexpected exception) is an
     ERROR — return:
       "<group-slug>--<wd-id>: ERROR — <one-line detail>"
   
   Successful runs return:
     "<group-slug>--<wd-id>: <COMPLETE | STOPPED_AT_<stage>> — <detail>"
   
   Return exactly ONE line and nothing else after. The coordinator
   parses this string.
   

   Prompt B — IMPLEMENTING WD (stranded resume):

   You are the sequential resume runner for <group-slug> /
   <wd-id>. The WD is already IMPLEMENTING — a prior /work-start
   dispatch claimed it and started the pipeline, but did not run
   it to completion (typically because of a crashed sub-agent or
   a stalled inner-dispatch step). The feature directory exists
   at .feature/<group-slug>--<wd-id>/ with status.md reflecting
   the stage where the prior run stopped.
   
   Invoke /feature-resume "<group-slug>--<wd-id>". It will read
   status.md, identify the stage to resume from, and continue the
   pipeline through /feature-pr. Do NOT re-invoke /work-start —
   work-claim.sh would reject the transition (already IMPLEMENTING).
   
   Treat automation_mode as autonomous. TECHNICAL escalations are
   auto-handled (record in cycle-log, continue). USER-REQUIRED
   escalations follow the contract: write
   .feature/<group-slug>--<wd-id>/escalation.json, append a
   user-escalation entry to cycle-log.md, set status.md substage
   to awaiting-user-input, then return ESCALATION_AT_<stage>.
   
   Return exactly ONE line matching the same classifier shape as
   Prompt A:
     "<group-slug>--<wd-id>: COMPLETE — <detail>"
     "<group-slug>--<wd-id>: ESCALATION_AT_<stage> — <category>: <question>"
     "<group-slug>--<wd-id>: STOPPED_AT_<stage> — <detail>"
     "<group-slug>--<wd-id>: ERROR — <one-line detail>"
   
   Nothing else after.
   

   e. Wait for the sub-agent to return. The Agent tool blocks until the child emits its final assistant message.

   f. Classify the return and update the marker. The Agent tool returns one of five shapes. Treat each distinctly — silent assumptions corrupt the task list. Match ESCALATION_AT_ before STOPPED_AT_ since both share the <STATUS>_AT_<stage> shape.

   • Escalation return matching <group-slug>--<wd-id>: ESCALATION_AT_<stage> — <category>: <question>. The sub-agent halted awaiting user input and has written .feature/<group>--<wd>/escalation.json with the structured question (see "User-required escalation contract"). Mark with the category as the reason so the future orchestrator can route:

     bash .claude/scripts/work-dispatch.sh fail "<group-slug>" "<wd-id>" "escalation:<category>"
     

     Use fail (not ack) because the WD is not complete — it is paused awaiting user input. Append to a dedicated escalations list separate from the clean-return aggregate.

   • Clean return matching <group-slug>--<wd-id>: <STATUS> — <detail> (where STATUS is one of COMPLETE, STOPPED_AT_<stage>, ERROR, SKIPPED). Acknowledge:

     bash .claude/scripts/work-dispatch.sh ack "<group-slug>" "<wd-id>" "<exact return line>"
     

     Append to the aggregate results list.

   • Payload lost — the Agent return literally equals [Tool result missing due to internal error] or otherwise contains no parseable result. The sub-agent may have run, partially run, or never started; the result is gone. Mark:

     bash .claude/scripts/work-dispatch.sh fail "<group-slug>" "<wd-id>" "payload-lost"
     

     Surface to the user via AskUserQuestion: "Pause for /work-resume <group-slug> recovery" / "Continue with the next WD (recovery later)" / "Stop the run". Do NOT advance the coordinator's TaskTool entry to completed — leave it in_progress so the user sees that it needs attention. The marker is the durable record; recovery is /work-resume.

   • User stopped — the Agent return contains The user doesn't want to proceed with this tool use. The tool use was rejected. The sub-agent never started. Mark:

     bash .claude/scripts/work-dispatch.sh fail "<group-slug>" "<wd-id>" "user-stopped"
     

     Surface to the user via AskUserQuestion: "Re-dispatch this WD" / "Continue with the next WD" / "Stop the run". Re-dispatching is safe because the sub-agent never claimed; /work-start will see the WD still SPECIFIED (or IMPLEMENTING if a previous attempt got further) and the marker will be overwritten on the next begin.

   • Parse failed — the return is a string but does not match the expected shape. Mark:

     bash .claude/scripts/work-dispatch.sh fail "<group-slug>" "<wd-id>" "parse-failed: <first 80 chars of return>"
     

     Surface the same recovery prompt as payload-lost. The marker records the unparseable tail so /work-resume can show it.

   Append to the aggregate. Display incrementally:

   [<n>/<eligible>] <group-slug>--<wd-id>: <STATUS> — <detail>
   

   For payload-lost / user-stopped / parse-failed lines, show:

   [<n>/<eligible>] <group-slug>--<wd-id>: DISPATCH FAILURE (<reason>) — recoverable via /work-resume
   

   g. Stop conditions. Continue unless:

   • The sub-agent returned ERROR or STOPPED_AT_<stage> AND the user opts to halt (AskUserQuestion: "Continue with remaining" / "Stop and inspect").
   • The dispatch hit payload-lost / user-stopped / parse-failed AND the user picked "Pause" / "Stop" in 3f.
   • SKIPPED returns are silent — log and continue (the coordinator intentionally tolerates conflicts as parallel-session signals).

4. Final aggregate. When the loop exits:

   ── Sequential run complete · <group-slug> ─────
   Dispatched: <N>
   Complete: <n>
   Stopped mid-pipeline: <list with stage>
   Errored: <list with detail>
   Skipped (claim conflict / no longer eligible): <list>
   ───────────────────────────────────────────────
   
   Next steps:
     <if any stopped/errored:> /feature-resume "<group>--<wd-id>" — inspect each
     <if any new SPECIFIED post-run:> /work-start "<group-slug>" all — run the next batch
     <if all complete:> the group is fully implemented; consider /feature-retro on each feature
   

Concurrency caveats

Sequential all avoids parallel-mode hazards by construction — one WD's pipeline finishes before the next starts. Two failure modes remain, both handled gracefully:

• Another terminal racing the same WD. work-claim.sh (called inside the dispatched single-WD flow at Step 4d) rejects the claim with CONFLICT and exits 1. The sub-agent returns SKIPPED — claim conflict and the coordinator continues to the next WD. No corruption, no stuck loop.
• Status drift mid-run. A WD that was SPECIFIED at Step 3a may be IMPLEMENTING by Step 3b (another terminal got there). The re-enumeration at the top of every iteration catches this — the ineligible WD is filtered out before dispatch.

Parallel mode

When invoked with --parallel [N], /work-start dispatches every SPECIFIED work definition in the group as a concurrent sub-agent. Each sub-agent runs the full feature pipeline (/feature-plan → /feature-test → /feature-implement → /feature-refactor) in an isolated context.

When to use parallel mode

Parallel mode is a velocity multiplier when the group has multiple WDs that are READY to implement and have no runtime cross-dependencies (e.g., they land in separate modules or produce non-overlapping artifacts). A wave of five SPECIFIED WDs in a group can complete in roughly the time of one WD instead of five sequential runs.

When NOT to use parallel mode

• WDs share runtime state (test DB, ports, cache). Parallel test execution will fight for resources. Sequential is safer.
• WDs produce overlapping specs or KB entries. Concurrent writes to the same spec file or KB entry corrupt the registry.
• The user wants to review each step. Parallel mode is fire-and-wait; individual WD progress is visible in each sub-agent's .feature/<slug>/status.md but there is no global pause point between stages.

Parallel-mode flow

Replace Steps 3–5 with this block when --parallel is set.

1. Enumerate startable WDs. Parse the work-resolve.sh output table and collect every WD whose Status is SPECIFIED. If zero, report and stop:

   No SPECIFIED work definitions in '<group-slug>' — run /work-plan
   first to specify READY WDs, or check work-status for blockers.
   

2. Cap concurrency. If the user supplied --parallel N, take the first N SPECIFIED WDs (prefer those with more downstream dependents — same "unblocking value" heuristic as next mode). If N is omitted, dispatch all of them.

3. Show the plan. Display:

   ── Parallel start plan ─────────────────────────
   Group: <group-slug>
   SPECIFIED WDs: <N>
   Will dispatch concurrently: <dispatched count>
   
     WD-<nn> — <title>  (domains: <domains>, unblocks: <list>)
     WD-<nn> — ...
   ───────────────────────────────────────────────
   

   Use AskUserQuestion to confirm — parallel mode spawns multiple long-running pipelines at once and the user should be explicit:

   • "Dispatch all in parallel"
   • "Cap at 2" (or a lower number)
   • "Stop — I'll start them manually"

4. Create feature directories (all WDs, sequential). For each dispatched WD, run Step 4 from the single-WD path in full treating --nested as set (the dispatched sub-agent cannot itself dispatch /feature-coordinate; status.md must carry nested_in_dispatch: true + execution_strategy: cost so /feature-plan routes sequentially): generate brief.md, verify readiness, write status.md with the nested fields per 4c, update the WD's status to IMPLEMENTING. Do this sequentially — these operations touch the .work/ tree and are fast. Fanning out here adds no measurable benefit and risks racing on manifest.md regeneration.

5. Dispatch sub-agents concurrently. First, write a dispatch marker for every WD that's about to be dispatched (so a payload- loss or user-stop on any single sub-agent can be recovered). Run sequentially before the Agent calls:

   for wd_id in <list of WD ids being dispatched>; do
     bash .claude/scripts/work-dispatch.sh begin "<group-slug>" "$wd_id"
   done
   

   Then spawn one sub-agent per WD in a single message with multiple Agent tool calls. Each sub-agent receives this prompt:

   You are the parallel pipeline runner for <feature-slug>.
   The feature directory exists at .feature/<feature-slug>/.
   Status.md is initialized at planning/loading-context and the WD is
   marked IMPLEMENTING.
   
   Invoke /feature-plan "<feature-slug>" and run the full pipeline
   through to /feature-refactor. Do not pause for user confirmation;
   treat automation_mode as autonomous.
   
   TECHNICAL escalations (spec conflict, missing tests, test writer
   escalation) are auto-handled: record in cycle-log.md and continue
   with remaining stages where possible; mention in your summary.
   
   USER-REQUIRED escalations (design ambiguity, missing context the
   kit can't supply, irreconcilable spec conflict, impossible
   requirement) halt the WD. Follow the user-required escalation
   contract from /work-start:
     1. write .feature/<feature-slug>/escalation.json with the schema
        in /work-start's "User-required escalation contract" section
     2. append a `user-escalation — <category>: <question>` entry to
        cycle-log.md
     3. set status.md substage to `awaiting-user-input`
     4. return ESCALATION_AT_<stage> per below
   
   Return a single summary line of one of these forms:
     "<feature-slug>: COMPLETE — <detail>"
     "<feature-slug>: ESCALATION_AT_<stage> — <category>: <question>"
     "<feature-slug>: STOPPED_AT_<stage> — <detail>"
     "<feature-slug>: ERROR — <detail>"
   

6. Aggregate results — classify each return. Use the same five-way classification as Sequential mode Step 3f (escalation / clean / payload-lost / user-stopped / parse-failed). Match ESCALATION_AT_ before STOPPED_AT_ since both share the <STATUS>_AT_<stage> shape. For each sub-agent's return:

   • Escalation (ESCALATION_AT_<stage> — <category>: <question>): bash .claude/scripts/work-dispatch.sh fail "<group>" "<wd-id>" "escalation:<category>" (use fail not ack — WD is paused awaiting user input)
   • Clean: bash .claude/scripts/work-dispatch.sh ack "<group>" "<wd-id>" "<line>"
   • Payload lost: bash .claude/scripts/work-dispatch.sh fail "<group>" "<wd-id>" "payload-lost"
   • User stopped: bash .claude/scripts/work-dispatch.sh fail "<group>" "<wd-id>" "user-stopped"
   • Parse failed: bash .claude/scripts/work-dispatch.sh fail "<group>" "<wd-id>" "parse-failed: <first 80 chars>"

   Then summarize:

   ── Parallel run complete · <group-slug> ───────
   Dispatched: <N>
   Complete: <n>/<N>
   Escalations awaiting user input: <n>
     WD-<nn> (<category>) — "<question>"
          .feature/<group>--WD-<nn>/escalation.json
   Stopped mid-pipeline: <list with stage>
   Errored: <list with detail>
   Dispatch failures (payload-lost / user-stopped / parse-failed):
     <list with WD-id and reason>
   ───────────────────────────────────────────────
   

   For escalations, the user's next action is to open the listed escalation.json file(s), resolve the design point (edit the spec, add an ADR, supply context), then re-dispatch via /work-resume "<group-slug>". For stopped or errored WDs, the user's next action is usually /feature-resume "<feature-slug>". For dispatch failures, the next action is /work-resume "<group-slug>" — it scans the dispatch markers and surfaces each stuck WD with the right recovery path (re-dispatch, inspect, or accept the partial result).

Concurrency caveats (documented, user-accepted)

• Shared KB / ADR writes. If two WDs' /feature-retro phases both want to write a new adversarial-finding KB entry about the same pattern, both writes succeed but one silently clobbers. Mitigation: run /curate after a parallel batch; it detects duplicate KB entries in the cross-reference analysis.
• Shared spec writes. If two WDs produce specs in overlapping domains, both /spec-write calls may serialize through the same manifest file. The manifest update uses atomic jq + tmp + mv, so the last writer wins on the manifest — but individual spec files are per-WD and don't conflict.
• Test runner contention. Parallel test suites can race on shared resources (test DB, network ports, temp files). This is a project-level concern. If the project's tests are isolated per WD, parallel is safe; if not, either cap at 1 or don't use parallel.
• Token / cost budget. N parallel pipelines burn roughly N× the tokens and dollars of a single run. Budget accordingly.

User-required escalation contract

Two kinds of escalation happen during autonomous pipeline runs. They need to be distinguished — only one of them halts the WD.

Stage escalation (existing, auto-continued): a pipeline stage hits a technical conflict it can handle within the pipeline — test writer can't write a failing test, refactor stage finds a spec conflict, etc. The kit's existing rules say: record in cycle-log.md and continue with remaining stages. The WD finishes (possibly with STOPPED_AT_) and the user sees the escalation in the post-run summary.

User-required escalation (this contract): the sub-agent cannot proceed without user input. Common categories:

The sub-agent halts the WD and surfaces the question via a structured artifact. The parent (this skill, today; the orchestrator in a future PR) routes the question to the user.

Sub-agent obligations on user-required escalation

When a sub-agent in automation_mode: autonomous encounters a user-required situation:

1. Write .feature/<slug>/escalation.json with this schema (JSON, atomic write via tmp + rename):

   {
     "schema_version": 1,
     "feature_slug": "<group>--<wd>",
     "wd_id": "WD-nn",
     "group_slug": "<group-slug>",
     "raised_at": "<ISO-8601 UTC>",
     "blocking_stage": "feature-plan|feature-test|feature-implement|feature-refactor",
     "category": "design-choice|missing-context|spec-conflict|impossible|other",
     "question": "<one-line summary, suitable for AskUserQuestion prompt>",
     "context": "<longer explanation; may include rationale + what was tried>",
     "context_refs": ["<file:line>", "<spec-id.RN>", "<.decisions/slug>"],
     "options": [
       { "label": "<short>", "description": "<what choosing this means>" }
     ]
   }
   

   context_refs and options are optional. If the sub-agent has no candidate answers, omit options — the user will provide one.

2. Record a user-escalation entry in cycle-log.md:

   - <ISO-8601 UTC> user-escalation — <category>: <question>
   

   This complements escalation.json (which is the structured form) and keeps cycle-log as the single audit timeline.

3. Update status.md substage to awaiting-user-input so /work-resume and /feature-resume recognize the halted state.

4. Return one line of the form:

   <feature-slug>: ESCALATION_AT_<stage> — <category>: <question>
   

   The leading sentinel ESCALATION_AT_ is what the parent classifier matches. The <category>: <question> tail is for the human-readable summary.

Parent classifier (5-way + dispatch-failure modes)

Extend the sequential and parallel mode classifiers from 4 to 5 recognized clean-return shapes. Order matters — match ESCALATION_AT_ before STOPPED_AT_ since both share the <feature>: <STATUS>_AT_<stage> shape.

…(truncated)