@event4u/agent-config 1.31.0 → 1.32.0

package/.agent-src/skills/feature-planning/SKILL.md

@@ -67,7 +67,7 @@ Explore → Plan → Refine → Roadmap → Implement
 ### Full workflow (complex features, 7 phases)
 
 Use the full workflow for features that span multiple files, require architecture decisions,
-or have unclear requirements. Trigger with `/feature-dev`.
+or have unclear requirements. Trigger with `/feature:dev`.
 
 ```
 Discovery → Exploration → Questions → Architecture → Implementation → Review → Summary
@@ -100,7 +100,7 @@ Discovery → Exploration → Questions → Architecture → Implementation →
 - **Wait for answers before proceeding.**
 
 #### Phase 4: Architecture Design
-- Design 2-3 impl approaches with different tradeoffs:
+- Design 2-3 implementation approaches with different tradeoffs:
   - **Minimal changes** — smallest change, maximum reuse.
   - **Clean architecture** — maintainability, elegant abstractions.
   - **Pragmatic balance** — speed + quality.
@@ -114,7 +114,7 @@ Discovery → Exploration → Questions → Architecture → Implementation →
 - Track progress via task list or roadmap.
 
 #### Phase 6: Quality Review
-- Review the impl for:
+- Review the implementation for:
   - Simplicity, DRY, elegance.
   - Bugs and correctness.
   - Convention adherence.
@@ -136,9 +136,45 @@ Maintain a running **decision log** throughout the planning process. For each de
 Include the decision log in the feature plan file under a `## Decisions` section.
 This ensures future developers (and agents) understand the reasoning, not just the outcome.
 
+## Bite-sized task granularity (structural roadmaps only)
+
+When a feature plan's generated roadmap declares `complexity: structural` in its frontmatter, every task bullet must be self-contained and 2–5 minutes of work. Lightweight roadmaps (the default) skip this section — coarse-grained tasks ("Add login endpoint", "Update tests") are correct when the work is well-scoped and low-risk.
+
+Structural roadmap tasks must include:
+
+1. **Exact file path** — `app/Modules/Auth/Services/LoginService.php`, never *"the login service"*.
+2. **Complete code** — every method body, import, and signature ready to paste; no `// existing code` ellipses, no `…`.
+3. **Exact command** — `php artisan migrate --path=database/migrations/2026_05_09_create_logins.php`, never *"run the migration"*.
+4. **Expected output** — what success looks like (`Migrated: 2026_05_09_create_logins`) and the exit code.
+5. **No placeholders** — angle-bracket placeholders, `TODO`, `FIXME`, `tbd`, and `???` are blockers; resolve before the task ships.
+
+The complexity flag lives in the roadmap's YAML frontmatter:
+
+```yaml
+---
+complexity: structural   # triggers bite-sized granularity
+# or
+complexity: lightweight  # default — skips bite-sized granularity
+---
+```
+
+Source: adapted from `obra/superpowers` `writing-plans/SKILL.md` § Task Structure + § No Placeholders (v5.1.0); complexity-gating is our addition (Council Round 1, Q4 — mitigates UX pushback for senior engineers on well-scoped work).
+
+## Self-review (3-scan checklist)
+
+Before presenting any plan, run these three scans in order. Each is a fast pass — not a deep review. Failures block presentation; fix and re-scan.
+
+1. **Spec coverage** — every requirement, AC bullet, or constraint from the input has a corresponding section / AC / scope item in the plan. Walk the input top-to-bottom; tick each requirement against the plan; missing items become open questions or new AC.
+2. **Placeholder / TODO scan** — grep the draft for `<placeholder>`, `TODO`, `FIXME`, `tbd`, `???`, `XXX`. Either resolve them now or surface them in the *Open questions* section. No placeholder ships unflagged.
+3. **Type / shape consistency** — proposed data structures, API shapes, file paths, and module names match existing codebase patterns. Cite at least one existing file per new structure as the convention anchor.
+
+This scan is **separate from** adversarial-review (below). Self-review catches mechanical gaps (missing AC, leftover placeholders, mis-shaped types); adversarial-review challenges the plan's reasoning.
+
+Source: adapted from `obra/superpowers` `writing-plans/SKILL.md` § Self-Review (v5.1.0).
+
 ## Adversarial self-review
 
-After completing a plan, run the **`adversarial-review`** skill before presenting it.
+After the 3-scan self-review passes, run the **`adversarial-review`** skill before presenting.
 Focus on the "Feature plans / Architecture" attack questions. See that skill for the full process.
 
 ## Feature plan format
@@ -183,7 +219,7 @@ module's `agents/` directory:
 Before creating a feature plan, always:
 1. **Search the codebase** for related code, existing patterns, and affected areas.
 2. **Read module docs** if the feature touches a specific module.
-3. **Check existing features** in `agents/features/` for overlap or deps.
+3. **Check existing features** in `agents/features/` for overlap or dependencies.
 
 ### Be collaborative
 
@@ -194,7 +230,7 @@ Before creating a feature plan, always:
 
 ### Keep it navigational
 
-Feature plans are decision documents, not impl guides.
+Feature plans are decision documents, not implementation guides.
 Implementation details belong in roadmaps.
 
 ## Output format
@@ -221,6 +257,6 @@ Implementation details belong in roadmaps.
 
 - Do NOT create feature plans without user input — always collaborate.
 - Do NOT skip codebase research — always check what exists.
-- Do NOT put impl steps in the feature plan — that's the roadmap's job.
+- Do NOT put implementation steps in the feature plan — that's the roadmap's job.
 - Do NOT commit or push without permission.
 - Do NOT duplicate information from `AGENTS.md` or module docs.

package/.agent-src/skills/judge-test-coverage/SKILL.md

@@ -147,6 +147,10 @@ as a follow-up for the implementer — the judge does not execute tools.
   model-pairing rules (`subagents.judge_model` one tier above implementer).
 - [`test-driven-development`](../test-driven-development/SKILL.md) —
   the write-the-test-first workflow that prevents most findings this judge makes.
+- [`testing-anti-patterns`](../testing-anti-patterns/SKILL.md) and its
+  sibling [`process-anti-patterns.md`](../testing-anti-patterns/process-anti-patterns.md) —
+  prevention layer this judge backs up; rationalization-table row numbers
+  are valid review citations.
 - Sibling judges: [`judge-bug-hunter`](../judge-bug-hunter/SKILL.md),
   [`judge-security-auditor`](../judge-security-auditor/SKILL.md),
   [`judge-code-quality`](../judge-code-quality/SKILL.md) — dispatched

package/.agent-src/skills/pest-testing/SKILL.md

@@ -22,6 +22,13 @@ Use this skill for all Laravel testing tasks, especially when working with:
 
 This skill extends `php-coder`, `laravel`, and `eloquent`.
 
+For prevention layers that fire **before** writing a test — TDD
+discipline, mock-isolation gates, and the 12 process rationalizations
+("I'll add the test after", "patch first, test later") — see
+[`test-driven-development`](../test-driven-development/SKILL.md),
+[`testing-anti-patterns`](../testing-anti-patterns/SKILL.md), and
+[`process-anti-patterns.md`](../testing-anti-patterns/process-anti-patterns.md).
+
 ## Procedure: Write Pest tests
 
 1. **Read the base skills first** — apply `php-coder`, `laravel`, and `eloquent` where relevant.
@@ -53,9 +60,9 @@ For bug fixes and new features, prefer test-driven development:
 
 ### Why test-first matters
 
-Tests written **after** impl pass immediately. Passing immediately proves nothing:
+Tests written **after** implementation pass immediately. Passing immediately proves nothing:
 - The test might test the wrong thing.
-- The test might test impl, not behavior.
+- The test might test implementation, not behavior.
 - You never saw it catch the bug — so you don't know if it would.
 
 ### Bug fix TDD
@@ -120,7 +127,7 @@ The test proves the fix works AND prevents regression.
 - For JSON APIs, assert:
     - exact relevant fields
     - error structure when applicable
-    - DB state after the request
+    - database state after the request
 - Do not only assert `200` — verify meaningful behavior.
 
 ## Validation tests
@@ -258,7 +265,7 @@ When reviewing or auditing existing tests, check for these anti-patterns:
 
 - Do not test private methods directly.
 - Do not over-mock Laravel internals.
-- Do not assert impl details when behavior assertions are enough.
+- Do not assert implementation details when behavior assertions are enough.
 - Do not write brittle tests tied to formatting or irrelevant response noise.
 - Do not create giant tests that cover many behaviors at once.
 - Do not skip authorization or validation coverage for important endpoints.
@@ -285,7 +292,7 @@ When generating Pest tests:
 - Don't use `readonly` or `final` on Pest test helper classes — it breaks mocking.
 - Don't add `use` statements for global classes (`Exception`, `DateTimeImmutable`) in Pest files — they're auto-imported.
 - The model forgets `$this->travel(5)->seconds()` for time-dependent tests — never rely on `now()` differing between lines.
-- Parallel tests share the DB — don't assume column values are null unless you explicitly set them.
+- Parallel tests share the database — don't assume column values are null unless you explicitly set them.
 
 ## Do NOT
 
@@ -297,7 +304,7 @@ When generating Pest tests:
 When generating new tests, focus on:
 - **Business logic**: calculations, status transitions, validation rules, data transformations
 - **Edge cases**: null, empty string, zero, negative numbers, boundary values, max length
-- **Error paths**: invalid input, missing deps, exception handling
+- **Error paths**: invalid input, missing dependencies, exception handling
 - **Different code branches**: if/else, early returns, fallback behavior
 
 What NOT to test:

package/.agent-src/skills/quality-tools/SKILL.md

@@ -34,6 +34,10 @@ If both PHP and JS/TS files changed → run **both** pipelines.
 - `verify-before-complete` rule — timing: run quality tools ONCE at the end, not after each edit
 - `php-coding` rule → PHPStan section — inline ignores, PHPDoc rules
 - `verify-before-complete` rule — must run quality checks before claiming work is done
+- [`testing-anti-patterns`](../testing-anti-patterns/SKILL.md) and
+  [`process-anti-patterns.md`](../testing-anti-patterns/process-anti-patterns.md) —
+  test-side rationalizations these tools cannot catch (e.g. "CI is red,
+  patch first, test later").
 
 ---
 

package/.agent-src/skills/refine-prompt/SKILL.md

@@ -126,6 +126,16 @@ The rubric (5 dimensions × 0–2, sum / 10) and band thresholds
 (`high ≥ 0.8`, `medium 0.5–0.79`, `low < 0.5`) are owned by
 `confidence.py`. Do not re-derive them in prose.
 
+### 6. Self-review (3-scan checklist)
+
+Before emitting the envelope, run these three scans. Each is a fast pass; failure blocks emission.
+
+1. **Spec coverage** — every concrete signal from step 2 (constraints) and step 3 (assumptions) is reflected somewhere in the AC list. Walk the constraint list top-to-bottom; each must anchor at least one AC bullet or appear in the *Assumptions* block.
+2. **Placeholder / TODO scan** — the rendered envelope contains no `<placeholder>`, `TODO`, `FIXME`, `tbd`, `???`, `XXX` strings. The literal angle-bracket placeholders in the template (`<one sentence …>`, `<bullet>`) must be replaced with concrete text before emission.
+3. **Type / shape consistency** — every named file, module, route, or command in the AC matches the project's existing conventions. If the prompt names `auth.service.ts` but the codebase uses `AuthService.php`, surface the mismatch in *Assumptions* rather than adopting the prompt's spelling.
+
+Source: adapted from `obra/superpowers` `writing-plans/SKILL.md` § Self-Review (v5.1.0).
+
 ## Band-action mapping
 
 The `refine` dispatcher step in `directives/backend/refine.py` reads

package/.agent-src/skills/refine-ticket/SKILL.md

@@ -250,6 +250,18 @@ open questions surfaced>
 The "Refined ticket" section is wrapped in a **copyable Markdown box**
 so the user can grab it verbatim.
 
+## Self-review (3-scan checklist)
+
+Run these three scans on the rendered output before the close-prompt. Each is a fast pass; failure blocks emission and forces a fix.
+
+1. **Spec coverage** — every AC bullet and constraint from the original ticket (and every parent-AC line surfaced via `fold_parent_context`) is reflected in the rewritten ticket, the Top-5 risks, or the *Open questions* section. Nothing from the input vanishes silently.
+2. **Placeholder / TODO scan** — no `<placeholder>`, `TODO`, `FIXME`, `tbd`, `???`, `XXX` strings remain. The angle-bracket placeholders in the template (`<rewritten title>`, `<risk>`, `<one paragraph>`) must be replaced with concrete prose before the close-prompt fires.
+3. **Type / shape consistency** — every module, file, route, or domain term cited in the rewritten ticket and Top-5 risks matches `repo_context.context_docs` and `recent_branches` vocabulary. Invented terms are flagged in *Open questions* or replaced with the project's actual term.
+
+Self-review is mechanical (gaps, leftovers, naming drift); persona voices and orchestration outputs handle reasoning critique. Both run; neither replaces the other.
+
+Source: adapted from `obra/superpowers` `writing-plans/SKILL.md` § Self-Review (v5.1.0).
+
 ## Close-prompt (mandatory final step)
 
 **Probe write access first (Phase F6).** Before rendering, do a

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.