@event4u/agent-config 1.31.0 → 1.33.0

package/.agent-src/skills/subagent-orchestration/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: subagent-orchestration
-description: "Use when orchestrating implementer/judge subagents — six modes (do-and-judge, do-in-steps, do-in-parallel, do-competitively, judge-with-debate, do-in-worktrees) — models from .agent-settings.yml."
+description: "Use when orchestrating implementer/judge subagents — seven modes (do-and-judge ±two-stage, do-in-steps/parallel/worktrees, do-competitively, judge-with-debate) — models from .agent-settings.yml."
 source: package
 ---
 
@@ -44,7 +44,7 @@ judge is a fresh pair of eyes. If `.agent-settings.yml` resolves to
 identical implementer and judge models, surface the mismatch before
 running — do not silently continue.
 
-## The six modes
+## The seven modes
 
 Each mode has a decision row: when to use, when not, and the expected
 model pairing. Defaults come from
@@ -60,7 +60,34 @@ back to the user.
 |---|---|---|
 | Single-change task with non-trivial risk | Tiny fix, or spike/exploration | implementer = session; judge = one tier up |
 
-### 2. do-in-steps
+### 2. do-and-judge-two-stage
+
+Implementer produces a diff; **two judges run sequentially** — first a
+spec-compliance reviewer (does the diff satisfy the stated spec /
+acceptance criteria?), then a code-quality reviewer (is the diff well-
+written for the codebase it lands in?). The orchestrator only proceeds
+to stage two if stage one returns `DONE` or `DONE_WITH_CONCERNS`. A
+stage-one `BLOCKED` shortcuts the loop — there is no point quality-
+reviewing a diff that does not satisfy the spec.
+
+| When to use | When not | Model pairing |
+|---|---|---|
+| Spec is contested or AC are detailed; diff size makes one judge prone to missing one axis (correctness vs craft) | Spec is one sentence, or the diff is one line (collapse to mode 1) | implementer = session; spec-judge = one tier up; quality-judge = same tier as spec-judge, fresh context |
+
+**Why two stages, not one judge with both rubrics:** combining the
+rubrics in one prompt reliably regresses one of them — the judge "spends
+attention" on whichever rubric appears last. Splitting the prompts
+forces each judge to commit fully to its rubric.
+
+**Stage-routing rule:**
+- Stage-1 returns `DONE` → run stage-2.
+- Stage-1 returns `DONE_WITH_CONCERNS` → run stage-2; concerns carry
+  forward to the final envelope.
+- Stage-1 returns `NEEDS_CONTEXT` → pause; stage-2 does not run.
+- Stage-1 returns `BLOCKED` → final verdict is `BLOCKED`; stage-2
+  does not run (saves cost).
+
+### 3. do-in-steps
 
 Plan is split into N steps; judge runs **between** steps. A step that
 fails judgment is revised before the next step starts. Used for
@@ -70,7 +97,7 @@ multi-file changes where a mid-plan mistake would cascade.
 |---|---|---|
 | Multi-step plan with ordered dependencies | Single-step change, or when steps are independent (use `do-in-parallel`) | implementer = session; judge = one tier up |
 
-### 3. do-in-parallel
+### 4. do-in-parallel
 
 Independent slices run concurrently. No judge per slice — judge runs
 once on the aggregated result. Parallelism capped by
@@ -80,7 +107,7 @@ once on the aggregated result. Parallelism capped by
 |---|---|---|
 | Independent slices (different files, non-overlapping) | Any slice touches shared state | implementer = session; judge = one tier up, run once |
 
-### 4. do-competitively
+### 5. do-competitively
 
 Multiple implementers produce candidate diffs for the **same** slice.
 Judge picks the winner and rejects the losers. Expensive — use only
@@ -90,7 +117,7 @@ when the solution space is genuinely broad.
 |---|---|---|
 | Broad solution space (algorithm choice, API shape) | Well-defined problem with one good answer | implementers = same tier (≥2 instances); judge = one tier up |
 
-### 5. judge-with-debate
+### 6. judge-with-debate
 
 Two judges each produce a verdict; a meta-judge reconciles
 disagreements. Used for high-stakes changes (security, data
@@ -100,7 +127,7 @@ migration, public API) where a single judge is too easy to fool.
 |---|---|---|
 | Security, data integrity, public API change | Routine internal refactor | judges = same tier (2x); meta-judge = one tier up |
 
-### 6. do-in-worktrees
+### 7. do-in-worktrees
 
 Cross-wing or cross-skill chain executed across isolated git
 worktrees — each handoff in the chain runs in its own worktree, so
@@ -130,7 +157,44 @@ end produces a single integration PR.
 **Anti-pattern:** do not use for fast iteration loops where each
 step is under ~30 minutes. The branch-creation, context-switch, and
 worktree-cleanup cost dominates. Stick with mode 1 (do-and-judge)
-or mode 2 (do-in-steps) for those.
+or mode 3 (do-in-steps) for those.
+
+## Status taxonomy — every subagent return uses one envelope
+
+Every implementer or judge return must conform to
+[`schemas/subagent-status.json`](schemas/subagent-status.json). Four
+statuses, no free-form alternatives:
+
+| Status | Meaning | Required keys (beyond `status`, `summary`) |
+|---|---|---|
+| `DONE` | Work shipped, all gates green. | `evidence[]` |
+| `DONE_WITH_CONCERNS` | Work shipped but caller must act on concerns. | `evidence[]`, `concerns[]` |
+| `NEEDS_CONTEXT` | Paused; caller can unblock by answering. | `blocking_question` |
+| `BLOCKED` | No path forward exists. | `blocking_reason` |
+
+**Why a fixed taxonomy:** orchestrators (`/do-and-judge`, `/do-in-steps`)
+route on status. Free-form "kind of done" returns force the orchestrator
+to interpret prose, which silently regresses the two-revision ceiling and
+the judge-rejected-do-not-apply rule. The schema makes routing mechanical.
+
+**Tests:** `tests/test_subagent_status_schema.py` exercises all four
+statuses plus rejection cases (missing required keys, unknown status,
+extra fields, conditional-key violations).
+
+**Distinguishing `NEEDS_CONTEXT` from `BLOCKED`:** `NEEDS_CONTEXT` means
+*"you, the caller, can fix this by telling me X"*. `BLOCKED` means
+*"no input from you unblocks this — escalate or rescope"*. If a subagent
+is unsure, it picks `BLOCKED` and the caller can downgrade.
+
+## Dispatch prompts — externalized
+
+Each mode's literal dispatch template lives under
+[`prompts/{mode}.md`](prompts/README.md). The orchestrator loads the
+matching prompt at dispatch time and substitutes `{{placeholders}}`.
+Edits to a prompt do not bloat this skill against the 400-line sunset
+trigger; `tests/test_subagent_prompt_loading.py` confirms each of the
+seven modes resolves to a loadable prompt that cites all four taxonomy
+statuses.
 
 ## Procedure
 
@@ -158,9 +222,10 @@ same context, **stop** and report. Do not improvise.
 
 ### 3. Pick the mode
 
-Match task shape to one of the five modes. When two modes could fit,
-prefer the cheaper one (`do-and-judge` < `do-in-steps` < `do-in-parallel`
-< `do-competitively` < `judge-with-debate`).
+Match task shape to one of the seven modes. When two modes could fit,
+prefer the cheaper one (`do-and-judge` < `do-and-judge-two-stage` <
+`do-in-steps` < `do-in-parallel` < `do-competitively` <
+`judge-with-debate` < `do-in-worktrees`).
 
 ### 4. Dispatch
 
@@ -195,7 +260,7 @@ the judge verdict.
 
 ## Output format
 
-1. **Mode chosen** — one of the five, with the one-line reason
+1. **Mode chosen** — one of the seven, with the one-line reason
 2. **Model pairing** — implementer model / judge model (resolved)
 3. **Verdict** — applied / revised / handed back
 4. **Evidence** — diff summary, test output, or judge transcript

package/.agent-src/skills/subagent-orchestration/prompts/README.md

@@ -0,0 +1,29 @@
+# Subagent dispatch prompts
+
+One file per mode in [`SKILL.md`](../SKILL.md) § *The seven modes*. Each
+prompt is the **literal template** the orchestrator hands to the
+subagent on dispatch — externalized so prompt edits do not bloat the
+skill above the 400-line sunset trigger.
+
+| Mode | File |
+|---|---|
+| do-and-judge | [`do-and-judge.md`](do-and-judge.md) |
+| do-and-judge-two-stage | [`do-and-judge-two-stage.md`](do-and-judge-two-stage.md) |
+| do-in-steps | [`do-in-steps.md`](do-in-steps.md) |
+| do-in-parallel | [`do-in-parallel.md`](do-in-parallel.md) |
+| do-competitively | [`do-competitively.md`](do-competitively.md) |
+| judge-with-debate | [`judge-with-debate.md`](judge-with-debate.md) |
+| do-in-worktrees | [`do-in-worktrees.md`](do-in-worktrees.md) |
+
+## Contract
+
+Every prompt cites the status taxonomy in
+[`../schemas/subagent-status.json`](../schemas/subagent-status.json) and
+ends with the **return-envelope** instruction so the subagent's reply
+validates against `tests/test_subagent_status_schema.py`.
+
+## Loading
+
+`tests/test_subagent_prompt_loading.py` asserts that every mode named
+in `SKILL.md` § *The seven modes* has a loadable prompt file under this
+directory and that each prompt mentions all four status enum values.

package/.agent-src/skills/subagent-orchestration/prompts/do-and-judge-two-stage.md

@@ -0,0 +1,121 @@
+# Prompt — do-and-judge-two-stage
+
+Mode reference: [`../SKILL.md`](../SKILL.md) § *2. do-and-judge-two-stage*.
+
+## Implementer prompt
+
+```
+You are the implementer in a do-and-judge-two-stage loop. Two judges
+will review your diff in sequence: first SPEC COMPLIANCE, then CODE
+QUALITY. Spec failure shortcuts the loop — quality is not reviewed if
+spec is wrong.
+
+TASK: {{task_description}}
+ACCEPTANCE CRITERIA: {{acceptance_criteria}}
+CONTEXT FILES: {{file_paths}}
+
+CONSTRAINTS:
+- Hit every AC literally; do not "interpret" them away.
+- Do not silently expand scope; AC are the contract.
+- Write tests that map 1:1 to the AC so the spec-judge can verify.
+
+ON COMPLETION, return ONE envelope per schemas/subagent-status.json:
+  - DONE                — every AC satisfied, tests pass; evidence[]
+                          maps each AC to the test that exercises it.
+  - DONE_WITH_CONCERNS  — every AC satisfied but a trade-off needs
+                          flagging in concerns[].
+  - NEEDS_CONTEXT       — an AC is ambiguous; blocking_question must
+                          name the AC and the interpretation gap.
+  - BLOCKED             — an AC cannot be satisfied as stated;
+                          blocking_reason explains why.
+```
+
+## Stage-1 prompt — SPEC COMPLIANCE judge
+
+```
+You are the SPEC COMPLIANCE judge. Stage 1 of two. Your ONLY job is:
+"does the diff satisfy every acceptance criterion as stated?" Do NOT
+review style, naming, or craft — that is stage 2's job.
+
+ACCEPTANCE CRITERIA: {{acceptance_criteria}}
+DIFF: {{diff}}
+TEST OUTPUT: {{test_output}}
+IMPLEMENTER ENVELOPE: {{envelope}}
+
+PER-AC SCAN — for each AC, return:
+  - SATISFIED — cite the diff hunk + test that proves it.
+  - PARTIAL   — cite what is missing and why it falls short.
+  - MISSING   — AC has no corresponding implementation.
+
+VERDICT (one envelope, schemas/subagent-status.json):
+  - DONE                — every AC SATISFIED; evidence[] is the per-AC
+                          scan above.
+  - DONE_WITH_CONCERNS  — every AC SATISFIED but a stretch
+                          interpretation needs flagging (rare at this
+                          stage).
+  - NEEDS_CONTEXT       — an AC is ambiguous AND the implementer's
+                          interpretation is plausible; orchestrator
+                          must clarify.
+  - BLOCKED             — one or more AC PARTIAL or MISSING. Stage 2
+                          will NOT run; implementer revises first.
+
+NEVER comment on naming, structure, or style. Stay in your lane —
+that is the value of the two-stage split.
+```
+
+## Stage-2 prompt — CODE QUALITY judge (only if stage 1 passes)
+
+```
+You are the CODE QUALITY judge. Stage 2 of two. Stage 1 already
+confirmed the diff satisfies the spec. Your ONLY job is craft: is
+the diff well-written for THIS codebase?
+
+DIFF: {{diff}}
+NEIGHBORING FILES: {{neighboring_files}}
+PROJECT CONVENTIONS: {{conventions_summary}}
+STAGE-1 CONCERNS (carry-forward): {{stage_1_concerns}}
+
+QUALITY DIMENSIONS — cite each in evidence[]:
+1. Naming consistency with neighbors.
+2. Structure / responsibility boundary.
+3. Error handling matches project style.
+4. Test shape matches project conventions (Pest / pytest / etc.).
+5. Diff size — could the same intent ship smaller?
+
+VERDICT (one envelope, schemas/subagent-status.json):
+  - DONE                — quality is on par with the codebase;
+                          evidence[] cites the five dimensions.
+  - DONE_WITH_CONCERNS  — apply the diff, but concerns[] lists the
+                          craft issues caller must address (carry
+                          forward stage-1 concerns too).
+  - NEEDS_CONTEXT       — convention is unclear; orchestrator must
+                          name the canonical pattern.
+  - BLOCKED             — diff is correct per stage 1 but quality is
+                          unacceptable; implementer must revise.
+
+NEVER re-litigate the spec. Stage 1 already settled correctness —
+your job is craft.
+```
+
+## Stage routing — orchestrator logic
+
+Stage-1 status determines whether stage 2 runs:
+
+| Stage-1 status | Run stage 2? | Final envelope |
+|---|---|---|
+| `DONE` | Yes | Stage-2 envelope |
+| `DONE_WITH_CONCERNS` | Yes | Stage-2 envelope; merge concerns[] from both |
+| `NEEDS_CONTEXT` | No | Stage-1 envelope; pause |
+| `BLOCKED` | No | Stage-1 envelope; implementer revises |
+
+The orchestrator never collapses both stages into one prompt — that
+defeats the purpose of the split (see SKILL.md § "Why two stages, not
+one judge with both rubrics").
+
+## Cost-discipline rule
+
+Two-stage = up to **3 subagent calls** per cycle (implementer + two
+judges) versus 2 for plain `do-and-judge`. Use only when AC are
+detailed enough that a single judge would predictably miss one of
+correctness or craft. For one-line fixes or single-AC tasks, mode 1
+(`do-and-judge`) is the right answer.

package/.agent-src/skills/subagent-orchestration/prompts/do-and-judge.md

@@ -0,0 +1,60 @@
+# Prompt — do-and-judge
+
+Mode reference: [`../SKILL.md`](../SKILL.md) § *1. do-and-judge*.
+
+## Implementer prompt
+
+```
+You are the implementer in a do-and-judge loop. Hard ceiling: two
+revision cycles before hand-back to the user.
+
+TASK: {{task_description}}
+
+CONTEXT FILES: {{file_paths}}
+
+CONSTRAINTS:
+- Do not modify files outside the cited paths without surfacing why.
+- Do not skip tests; if the task does not include a test, write one.
+- Prefer the smallest diff that satisfies the task.
+
+ON COMPLETION, return ONE envelope conforming to
+schemas/subagent-status.json. Pick exactly one status:
+  - DONE                — work shipped, all gates green; include evidence[].
+  - DONE_WITH_CONCERNS  — shipped but caller must read concerns[];
+                          include evidence[] AND concerns[].
+  - NEEDS_CONTEXT       — paused; the orchestrator can unblock by
+                          answering blocking_question.
+  - BLOCKED             — no path forward; include blocking_reason.
+
+NEVER invent a fifth status. Free-form "kind of done" prose is rejected
+by the schema validator.
+```
+
+## Judge prompt
+
+```
+You are the judge reviewing the implementer's diff. The implementer
+returned the envelope below. Validate against the task and constraints.
+
+TASK: {{task_description}}
+DIFF: {{diff}}
+IMPLEMENTER ENVELOPE: {{envelope}}
+
+VERDICT (return ONE envelope per schemas/subagent-status.json):
+  - DONE                — apply this diff; cite evidence in evidence[].
+  - DONE_WITH_CONCERNS  — apply but caller must address concerns[].
+  - NEEDS_CONTEXT       — orchestrator must clarify blocking_question
+                          before re-dispatching the implementer.
+  - BLOCKED             — diff is wrong; explain in blocking_reason.
+                          Do NOT silently rewrite — that is the
+                          implementer's job on the revision pass.
+
+NEVER apply a diff you would have written differently if your concerns
+were not addressed. Use DONE_WITH_CONCERNS for that case.
+```
+
+## Revision-loop rule
+
+After two revision cycles, the orchestrator stops and hands back to the
+user with the most recent envelope. The judge does not become the
+implementer.

package/.agent-src/skills/subagent-orchestration/prompts/do-competitively.md

@@ -0,0 +1,65 @@
+# Prompt — do-competitively
+
+Mode reference: [`../SKILL.md`](../SKILL.md) § *4. do-competitively*.
+
+## Implementer prompt (per candidate)
+
+```
+You are CANDIDATE {{candidate_id}} of {{n_candidates}} competing on the
+SAME slice. Other implementers are solving the identical problem in
+parallel; the judge will pick exactly one winner.
+
+TASK: {{task_description}}
+CONTEXT FILES: {{file_paths}}
+
+CONSTRAINTS:
+- Do NOT optimize for "what the judge wants to see" — solve the task.
+- Do NOT copy from other candidates; you do not have access to them.
+- Make a real choice: name the algorithm, the API shape, the trade-off.
+  Generic safe answers lose to specific decisive ones.
+
+ON COMPLETION, return ONE envelope per schemas/subagent-status.json:
+  - DONE                — your candidate is complete and tests pass;
+                          evidence[] cites the test output.
+  - DONE_WITH_CONCERNS  — complete but flag the trade-off you made so
+                          the judge can score it.
+  - NEEDS_CONTEXT       — task ambiguity blocks all candidates; if so,
+                          all candidates should converge on the same
+                          blocking_question.
+  - BLOCKED             — task is malformed; explain in blocking_reason.
+```
+
+## Judge prompt (winner selection)
+
+```
+You are the judge picking ONE winner from {{n_candidates}} competing
+diffs for the SAME slice. Losers are rejected, not merged.
+
+CANDIDATE ENVELOPES: {{envelopes_array}}
+CANDIDATE DIFFS: {{diffs_array}}
+TASK: {{task_description}}
+
+SCORING DIMENSIONS (cite each in evidence[]):
+1. Correctness — does it pass tests AND solve the task?
+2. Trade-off clarity — is the choice named and defended?
+3. Maintenance cost — what does the codebase look like in 6 months?
+4. Diff size — smaller wins ties.
+
+VERDICT (one envelope, schemas/subagent-status.json):
+  - DONE                — winner picked; evidence[] cites the four
+                          scoring dimensions and names the winner.
+  - DONE_WITH_CONCERNS  — winner picked but the chosen trade-off has
+                          carry-over costs (concerns[]).
+  - NEEDS_CONTEXT       — all candidates need the same clarification.
+  - BLOCKED             — no candidate is acceptable; rerun with new
+                          implementers or change the task.
+
+NEVER pick a winner because it was the cheapest model. NEVER merge
+two candidates — that is do-in-parallel, not do-competitively.
+```
+
+## Cost-discipline rule
+
+`do-competitively` is N+1 subagent calls per slice. The orchestrator
+confirms budget with the user before dispatch. The losing diffs are
+discarded — that cost is the price of the trade-off survey.

package/.agent-src/skills/subagent-orchestration/prompts/do-in-parallel.md

@@ -0,0 +1,62 @@
+# Prompt — do-in-parallel
+
+Mode reference: [`../SKILL.md`](../SKILL.md) § *3. do-in-parallel*.
+
+## Implementer prompt (per slice)
+
+```
+You are the implementer for SLICE {{slice_id}} in a parallel-dispatch
+run. {{n_slices}} slices run concurrently. Slices are guaranteed
+independent — different files, no shared state.
+
+SLICE: {{slice_description}}
+CONTEXT FILES (this slice only): {{file_paths}}
+SHARED-STATE BAN: {{shared_paths_to_avoid}}
+
+CONSTRAINTS:
+- Do NOT touch any file outside the cited paths. The orchestrator
+  verified independence — violating it causes a merge race.
+- Do NOT communicate with other slices. They are doing their own work.
+- Write tests scoped to your slice; do not assert on slice-cross
+  behavior.
+
+ON COMPLETION, return ONE envelope per schemas/subagent-status.json:
+  - DONE                — slice shipped clean; evidence[] required.
+  - DONE_WITH_CONCERNS  — shipped but mark concerns[] for the
+                          aggregating judge to surface.
+  - NEEDS_CONTEXT       — paused; orchestrator must answer
+                          blocking_question. Other slices keep running.
+  - BLOCKED             — slice cannot complete in isolation; explain
+                          in blocking_reason. Other slices keep running;
+                          aggregating judge handles partial outcome.
+```
+
+## Judge prompt (run once on aggregate)
+
+```
+You are the judge running ONCE over the merged output of N parallel
+slices. Per-slice judges were skipped to keep cost linear.
+
+SLICE ENVELOPES: {{envelopes_array}}
+AGGREGATED DIFF: {{merged_diff}}
+TEST OUTPUT (full suite): {{test_output}}
+
+VERDICT (one envelope, schemas/subagent-status.json):
+  - DONE                — every slice DONE or DONE_WITH_CONCERNS that
+                          you accept; evidence[] cites the merge being
+                          test-green.
+  - DONE_WITH_CONCERNS  — accept the aggregate, but consolidated
+                          concerns[] from all slices need caller action.
+  - NEEDS_CONTEXT       — one or more slices need clarification before
+                          the aggregate can land; cite which.
+  - BLOCKED             — aggregate is broken; cite the slice(s) that
+                          must be re-run.
+
+INDEPENDENCE-VIOLATION CHECK: scan for files touched by more than one
+slice. If found, return BLOCKED — the dispatch was unsafe.
+```
+
+## Failure-isolation rule
+
+A slice returning BLOCKED does not abort the other slices. The
+aggregating judge decides whether the partial result lands.

package/.agent-src/skills/subagent-orchestration/prompts/do-in-steps.md

@@ -0,0 +1,62 @@
+# Prompt — do-in-steps
+
+Mode reference: [`../SKILL.md`](../SKILL.md) § *2. do-in-steps*.
+
+## Implementer prompt (per step)
+
+```
+You are the implementer for STEP {{step_number}} of {{total_steps}} in a
+sequential plan. Earlier steps that PASSED judgment are committed; their
+diffs are read-only context.
+
+PLAN: {{plan_summary}}
+THIS STEP: {{step_description}}
+PRIOR STEP DIFFS (read-only): {{prior_diffs}}
+CONTEXT FILES: {{file_paths}}
+
+CONSTRAINTS:
+- Do NOT modify code from prior steps; their tests must still pass.
+- Do NOT preempt later steps; one step at a time.
+- Write the test for THIS step before the production code.
+
+ON COMPLETION, return ONE envelope per schemas/subagent-status.json:
+  - DONE                — step complete, gate green; cite evidence[].
+  - DONE_WITH_CONCERNS  — step complete but flag carry-over concerns
+                          for later steps.
+  - NEEDS_CONTEXT       — paused; blocking_question must be answered
+                          before this step can complete.
+  - BLOCKED             — step cannot complete on the current plan;
+                          blocking_reason explains why. The orchestrator
+                          may revise the plan and re-dispatch.
+```
+
+## Judge prompt (between steps)
+
+```
+You are the judge reviewing STEP {{step_number}} before STEP
+{{step_number_plus_one}} starts. A failing step here cascades into the
+next, so verdicts are stricter than a one-shot do-and-judge.
+
+STEP DIFF: {{diff}}
+STEP TESTS: {{test_output}}
+PRIOR STEPS: {{prior_step_summaries}}
+NEXT STEP DESCRIPTION: {{next_step_description}}
+
+VERDICT — return ONE envelope per schemas/subagent-status.json:
+  - DONE                — proceed to next step; evidence[] required.
+  - DONE_WITH_CONCERNS  — proceed, but next step's prompt MUST surface
+                          the concerns[] so the implementer compensates.
+  - NEEDS_CONTEXT       — pause; orchestrator answers blocking_question
+                          before next step.
+  - BLOCKED             — do not start next step; this step is wrong.
+
+DOWNSTREAM IMPACT CHECK: name one way this diff could break the next
+step. If you cannot, return DONE. If you can but the implementer
+already mitigated, DONE. Otherwise DONE_WITH_CONCERNS.
+```
+
+## Cascade rule
+
+A step that returns BLOCKED stops the chain. The orchestrator does not
+"jump ahead" or re-order — it surfaces the BLOCKED envelope to the user
+and waits.

package/.agent-src/skills/subagent-orchestration/prompts/do-in-worktrees.md

@@ -0,0 +1,70 @@
+# Prompt — do-in-worktrees
+
+Mode reference: [`../SKILL.md`](../SKILL.md) § *6. do-in-worktrees*.
+Worktree creation/destruction lives in [`../../using-git-worktrees/SKILL.md`](../../using-git-worktrees/SKILL.md).
+
+## Implementer prompt (per worktree step)
+
+```
+You are the implementer for STEP {{step_id}} in a cross-wing chain.
+You are running INSIDE a fresh git worktree at {{worktree_path}} on
+branch {{branch_name}}. Prior step's open files / branch state cannot
+leak into this worktree — that is the whole point.
+
+STEP TYPED INPUT (from prior step's ## Output): {{typed_input}}
+STEP DESCRIPTION: {{step_description}}
+EXPECTED ## Output (next step's ## Input): {{expected_output_shape}}
+
+CONSTRAINTS:
+- Stay inside the worktree path. Do NOT cd to the parent repo.
+- Do NOT touch branches other than {{branch_name}}.
+- Produce the expected ## Output shape literally — the next worktree's
+  implementer consumes it as ## Input.
+- Run the chain-end test for THIS step before signaling completion.
+
+ON COMPLETION, return ONE envelope per schemas/subagent-status.json:
+  - DONE                — step output produced and validated; evidence[]
+                          cites the typed-output file path.
+  - DONE_WITH_CONCERNS  — output produced but flag carry-over for next
+                          worktree; concerns[] surfaces in next step's
+                          dispatch.
+  - NEEDS_CONTEXT       — paused; chain pauses until orchestrator
+                          answers blocking_question. Other worktrees
+                          are NOT running concurrently in this mode.
+  - BLOCKED             — step cannot complete; chain halts. The
+                          orchestrator decides whether to drop the
+                          worktree or rescope.
+```
+
+## Chain-end judge prompt (run once after final worktree)
+
+```
+You are the chain-end judge. The chain produced N typed outputs, one
+per worktree. Validate the final integration PR against the chain's
+goal.
+
+CHAIN STEPS: {{step_summaries_array}}
+TYPED OUTPUTS: {{outputs_array}}
+INTEGRATION PR DIFF: {{integration_diff}}
+
+VERDICT (one envelope, schemas/subagent-status.json):
+  - DONE                — chain landed cleanly; evidence[] cites each
+                          step's typed output and the integration test
+                          run.
+  - DONE_WITH_CONCERNS  — chain landed but consolidated concerns[]
+                          across steps need follow-up.
+  - NEEDS_CONTEXT       — integration is unclear; cite which step(s)
+                          need clarification.
+  - BLOCKED             — integration is broken; cite the worktree(s)
+                          that must be redone. Do NOT silently rewrite.
+
+WORKTREE-LEAK CHECK: scan the integration diff for branch names or
+files belonging to a different worktree's step. If found, BLOCKED —
+isolation was violated.
+```
+
+## Sequential-not-parallel rule
+
+`do-in-worktrees` runs steps sequentially across isolated worktrees.
+Parallel concurrent worktrees are `do-in-parallel` with explicit
+isolation, not this mode.