@laitszkin/apollo-toolkit 5.0.2 → 5.0.4

package/skills/plan/SKILL.md

@@ -13,16 +13,22 @@ This prompt defines a coordinator agent:
 
 This skill is responsible for "planning the coordination strategy" — extracting information from SPEC/DESIGN/CHECKLIST, decomposing into concrete tasks, pre-writing worker prompts, and scheduling batch execution order.
 
+Worker prompts are written to individual files under `<spec_dir>/plan/` (single spec) or `<batch_dir>/plan/` (batch spec) instead of inline in PROMPT.md. This keeps PROMPT.md focused on coordination strategy while each worker prompt is independently dispatchable.
+
 ## Acceptance Criteria
 
 - `docs/plans/<YYYY-MM-DD>/<spec_name>/PROMPT.md` is produced and placed at the root of the spec or batch spec directory
 - PROMPT.md is a **self-contained coordinator prompt**, containing:
   - Coordinator role definition (what to do, what not to do)
   - Task decomposition with dependency graph
-  - Pre-written worker prompts for every dispatchable task (self-contained, ready to send)
+  - Worker prompt index referencing `plan/*.md` files
   - Batch schedule with verification gates
   - Error recovery strategy
   - Boundary rules (ALWAYS / ASK FIRST / NEVER)
+- Worker prompts are stored in `<spec_dir>/plan/*.md` or `<batch_dir>/plan/*.md`, one prompt per file
+- PROMPT.md References section cites:
+  - Worker prompt file paths (`plan/*.md`)
+  - All code file paths that need modification across all tasks
 
 ## Workflow
 
@@ -39,6 +45,7 @@ Read all files thoroughly:
 - `SPEC.md` — Business requirements and scope (BDD GIVEN/WHEN/THEN), In/Out of Scope
 - `DESIGN.md` — Module architecture, interaction anchors (INT-###), external dependencies (EXT-###), system invariants, technical trade-offs
 - `CHECKLIST.md` — Behavior-to-test mapping, hardening requirements, test level choices
+- `<spec_dir>/references/` or `<batch_dir>/references/` — External method/API reference documents (name, purpose, parameters)
 
 ### 3. Task Decomposition
 
@@ -88,25 +95,27 @@ File overlap detection is the **gate that determines parallelism**. Perform this
 
 ### 6. Write Worker Prompts (One Per Dispatchable Task)
 
-For each task that needs an independent worker, write a self-contained worker prompt. → PROMPT.md Section 6 (Worker Prompt Library).
+For each task that needs an independent worker, write a self-contained worker prompt. Save each prompt to a separate file under `<spec_dir>/plan/` or `<batch_dir>/plan/`.
+
+**Worker prompt file naming**: `plan/T{batch}.{sequence}-{kebab-case-name}.md`
 
 Each worker prompt must include:
 
 ```
 ## Mission — What to do and why
 ## Input — Which files to read
-## What to do — Concrete steps (describe "what" to do, not "which tool" to use)
+## What to do — Concrete steps, each specifying the exact file path, the function or line range, and what specific change to make (add/delete/modify). Never leave the change description vague.
 ## Scope — Allowed and forbidden files
 ## Output — What to report on completion (file list, change summary, test results, risks)
 ## Verify — Verification commands and expected results
 ## Boundaries — Constraints (don't touch other workers' files, don't add dependencies, report blockers)
 ```
 
-**Writing principles:**
-- **Self-contained**: Workers do not see the coordinator's context. The prompt must include everything necessary
-- **Concrete**: Embed file paths, function names, line numbers. Do not write "fix it" or "based on your findings"
-- **Declarative**: Describe "what to do", not "which tool to use"
-- **Clear boundaries**: Explicitly list allowed and forbidden files
+**Writing principles (move these to your process, not the template):**
+- **Self-contained**: Workers do not see the coordinator's context. The prompt must include everything necessary. Do not rely on shared context or assume the worker has read other documents.
+- **Concrete**: For every file the worker must modify, specify: (1) the exact file path, (2) the function or line range, (3) what to add, delete, or change. Do not write "fix it", "update as needed", or "based on your findings".
+- **Declarative**: Describe "what to do", not "which tool to use".
+- **Clear boundaries**: Explicitly list allowed and forbidden files. A worker should never need to guess which files it can modify.
 
 Tasks that do not need a worker (purely procedural operations) do not get a worker prompt. The coordinator handles these directly in the corresponding batch.
 
@@ -132,7 +141,7 @@ Based on dependency analysis and file overlap detection, build the batch schedul
 
 → PROMPT.md Section 10 (Boundaries).
 
-- **ALWAYS**: Run gate verification after every batch, extract worker prompts verbatim from Section 6, digest results before deciding next step
+- **ALWAYS**: Run gate verification after every batch, extract worker prompts verbatim from Section 7, digest results before deciding next step
 - **ASK FIRST**: Modify files not defined in SPEC/DESIGN, add new dependencies, two worker failures, regression with unclear cause
 - **NEVER**: Coordinator edits source code directly, workers spawn sub-workers, skip verification, issue vague instructions
 
@@ -147,11 +156,12 @@ Use `assets/templates/PROMPT.md`. Fill each section according to the table below
 | 3. Scope & Boundaries | SPEC.md In/Out of Scope |
 | 4. Technical Context | DESIGN.md: module list with responsibilities, interaction anchors (INT-###) and dependency order, external dependency setup order (EXT-###), system invariants, technical decisions and trade-offs |
 | 5. Task Units | Step 3 (task decomposition) + Step 4 (dependency analysis) |
-| 6. Worker Prompt Library | Step 6 — one entry per dispatchable task |
+| 6. Worker Prompt Index | Step 6 — list of `plan/*.md` files with task ID mapping |
 | 7. Batch Schedule | Step 7 (batch schedule) |
 | 8. Verification Checkpoints | CHECKLIST.md: behavior-to-test mapping (CL-###), hardening requirements, test execution commands |
 | 9. Error Recovery | Fixed template — populate spec-specific test commands from CHECKLIST.md |
-| 10. Boundaries | Fixed template + spec-specific rules |
+| 10. Boundaries | Fixed template + spec-specific rules (including worktree cleanup after each batch) |
+| 11. References | Worker prompt file paths (`plan/*.md`), all code file paths that need modification across all tasks, project context files (CLAUDE.md, AGENTS.md, architecture atlas, codegraph index) |
 
 ### 11. Pre-delivery Self-Review
 
@@ -159,9 +169,10 @@ Before delivering PROMPT.md, verify all of the following.
 
 **Worker prompt quality:**
 
-- Every worker prompt in Section 6 is self-contained. Scan for phrases like "based on your findings", "fix it appropriately", "as discussed above" — these leak shared context assumptions. If found, rewrite the prompt to include the necessary information inline.
+- Every worker prompt in `plan/*.md` is self-contained. Scan for phrases like "based on your findings", "fix it appropriately", "as discussed above" — these leak shared context assumptions. If found, rewrite the prompt to include the necessary information inline.
 - Every worker prompt has a concrete file-level Scope (allowed + forbidden files listed explicitly).
 - Every worker prompt has a concrete Verify command with an expected output (not just "run tests").
+- Worker prompt filenames match their task IDs (`plan/T{batch}.{sequence}-*.md`).
 
 **Coverage completeness:**
 
@@ -172,18 +183,20 @@ Before delivering PROMPT.md, verify all of the following.
 **Structural consistency:**
 
 - Each task's Depends on field in Section 5 matches the batch ordering in Section 7. No task scheduled in a batch before its dependencies are met.
-- Every task listed in Section 7 (Batch Schedule) has a worker prompt in Section 6 — unless it is explicitly marked as coordinator-handled.
+- Every task listed in Section 7 (Batch Schedule) has a worker prompt in `plan/*.md` — unless it is explicitly marked as coordinator-handled.
 - No orphaned tasks (a task listed in Section 5 that never appears in any batch), no missing dependencies (a Depends on field referencing a task ID that does not exist).
+- PROMPT.md References section lists all worker prompt paths and all code file paths.
 
-### 12. Produce PROMPT.md
+### 12. Produce PROMPT.md and Worker Prompts
 
 Place the PROMPT.md at the root of the spec or batch spec directory.
+Place worker prompts in `<spec_dir>/plan/` or `<batch_dir>/plan/`.
 
 ## Examples
 
-- "Generate a coordinator prompt for a single spec" → Read SPEC.md + DESIGN.md → Decompose into 3 tasks → T1.1 and T1.2 have no file overlap → parallel → Write worker prompts for each → Schedule: Batch 1 parallel T1.1+T1.2 → Batch 2 T1.3 → Output PROMPT.md
-- "Generate a coordinator prompt for a batch spec with 4 specs" → Read all SPEC.md + DESIGN.md → Build spec DAG → Detect cross-spec file overlap → Schedule batches → Write worker prompts for each spec's task units → Output PROMPT.md
-- "Two tasks modify the same file" → Assign to different batches, each with an independent worker prompt, sequential execution
+- "Generate a coordinator prompt for a single spec" → Read SPEC.md + DESIGN.md + references/ → Decompose into 3 tasks → T1.1 and T1.2 have no file overlap → parallel → Write worker prompts to `plan/` → Schedule: Batch 1 parallel T1.1+T1.2 → Batch 2 T1.3 → Output PROMPT.md + plan/*.md
+- "Generate a coordinator prompt for a batch spec with 4 specs" → Read all SPEC.md + DESIGN.md + references/ → Build spec DAG → Detect cross-spec file overlap → Schedule batches → Write worker prompts to `plan/` → Output PROMPT.md + plan/*.md
+- "Two tasks modify the same file" → Assign to different batches, each with an independent worker prompt in `plan/`, sequential execution → Reference both prompt paths in PROMPT.md
 
 ## References
 

package/skills/plan/assets/templates/PROMPT.md

@@ -19,7 +19,7 @@
 - Wait for all workers in a batch to complete, then digest their results
 - Run verification commands at each checkpoint
 - Decide whether to proceed to the next batch, retry a failed worker, or halt
-- Handle lightweight coordination tasks: resolving merge conflicts, updating lockfiles
+- Handle lightweight coordination tasks: resolving merge conflicts, updating lockfiles, cleaning up worktrees
 - Commit all changes in a single commit after the final verification gate passes
 
 ### What you NEVER do
@@ -84,15 +84,7 @@
 
 - **Goal**: [One sentence]
 - **Files**: `[file list]`
-- **Depends on**: [Task ID, or — (no dependency)]
-- **Verify**:
-  - Command: `[command]`
-  - Expected: [what you should see]
-
-#### T{batch}.{sequence}: [Task name]
-
-- **Goal**: [One sentence]
-- **Files**: `[file list]`
+- **Worker prompt**: `plan/T{batch}.{sequence}-[name].md`
 - **Depends on**: [Task ID, or — (no dependency)]
 - **Verify**:
   - Command: `[command]`
@@ -100,49 +92,16 @@
 
 ---
 
-## 6. Worker Prompt Library
-
-[Each dispatchable task has a pre-written self-contained worker prompt. The coordinator extracts the corresponding block and dispatches it without modification.]
-
-### T{batch}.{sequence}: [Task name]
-
-```
-## Mission
-[Brief description of what to do and why. Enough context for the worker to understand the task's purpose.]
+## 6. Worker Prompt Index
 
-## Input
-- Read the following files: [list]
+[Each dispatchable task has a pre-written self-contained worker prompt in a separate file under `plan/`. The coordinator reads the corresponding file and dispatches it without modification.]
 
-## What to do
-1. [Concrete step — describe "what" to do, not "which tool" to use]
-2. [Include specific file paths, function names, line numbers]
-
-## Scope
-- Allowed files:
-  - `[path]` — [explanation]
-- Forbidden files:
-  - `[path]` — (belongs to another worker)
-
-## Output
-On completion, report:
-- Which files were modified (absolute paths)
-- Change summary for each file
-- Test results (pass/fail)
-- Any blockers or risks encountered
-
-## Verify
-- Run: `[command]`
-- Expected: [what you should see]
-
-## Boundaries
-- Do not modify any file in the forbidden list
-- Do not introduce new external dependencies
-- If you encounter an unexpected blocker, stop and report — do not invent alternative approaches
-```
-
----
+| Task ID | Worker Prompt File | Description |
+|---|---|---|
+| T1.1 | `plan/T1.1-implement-login.md` | [Brief description] |
+| T1.2 | `plan/T1.2-implement-logout.md` | [Brief description] |
 
-[Repeat the above block for each dispatchable task. Tasks handled directly by the coordinator (purely procedural operations) do not need a worker prompt.]
+[Tasks handled directly by the coordinator (purely procedural operations) do not have an entry here.]
 
 ---
 
@@ -223,10 +182,11 @@ On completion, report:
 ### ALWAYS
 
 - Run gate verification immediately after every batch
-- Extract worker prompts verbatim from Section 6 — do not rewrite them
+- Extract worker prompts verbatim from `plan/*.md` files — do not rewrite them
 - After a worker reports, digest the results before deciding next steps
 - Follow the File Ownership implied by task assignments — do not let two workers modify the same file
 - **Resolve merge conflicts yourself** — when combining worker results, the coordinator handles conflict resolution. This is coordination, not implementation.
+- **After each batch completes, clean up any temporary branches or worktrees created by workers** — no ephemeral worktree should be left orphaned.
 - After two failures, pause and ask — do not keep retrying
 
 ### ASK FIRST — pause and confirm with the user
@@ -244,3 +204,14 @@ On completion, report:
 - Give workers vague instructions (e.g., "fix it" or "based on what you found")
 - Expand implementation scope beyond Section 3
 - Proceed to the next batch when the current batch's gate has not passed
+
+---
+
+## 11. References
+
+- **Worker prompt files**: [List all `plan/*.md` files — e.g., `plan/T1.1-implement-login.md`, `plan/T1.2-implement-logout.md`]
+- **Code files to modify** (across all tasks):
+  - [File path — e.g., `src/auth/login.ts`]
+  - [File path — e.g., `src/auth/logout.ts`]
+- **Project context files**: [List important project files — e.g., `CLAUDE.md`, `AGENTS.md`, `resources/project-architecture/**`, codegraph index files]
+- **Related documents**: [Links to related specs, design docs, or external documentation]

package/skills/qa/SKILL.md

@@ -13,18 +13,25 @@ This prompt defines a fix coordinator agent:
 
 This skill is responsible for "planning the fix strategy" — extracting information from REPORT.md + SPEC/DESIGN/CHECKLIST, writing worker prompts for each fix and regression test, and scheduling batch execution order.
 
+Worker prompts are written to individual files under `<spec_dir>/fix/` (single spec) or `<batch_dir>/fix/` (batch spec) instead of inline in FIX.md. This keeps FIX.md focused on coordination strategy while each fix/regression worker prompt is independently dispatchable.
+
 ## Acceptance Criteria
 
 - `docs/plans/<YYYY-MM-DD>/<spec_name>/FIX.md` is produced and placed in the spec directory (same level as REPORT.md)
 - FIX.md is a **self-contained fix coordinator prompt**, containing:
   - Coordinator role definition
   - Issue inventory with dependency analysis
-  - Pre-written worker prompt for every fix issue
-  - Regression test design and worker prompt for every fix
+  - Worker prompt index referencing `fix/*.md` files
+  - Pre-written worker prompts for every fix and regression test (stored in `fix/*.md`)
+  - Regression test design for every fix
   - Batch schedule (fix batches + regression test batches + final verification)
   - Error recovery strategy
   - Boundary rules
-- **Every issue in REPORT.md (including P2/P3) has a complete fix plan with a corresponding worker prompt in FIX.md.** No issue may be deferred to a future round or marked as "handle later."
+- Worker prompts are stored in `<spec_dir>/fix/*.md` or `<batch_dir>/fix/*.md`, one prompt per file
+- FIX.md References section cites:
+  - Worker prompt file paths (`fix/*.md`)
+  - All code file paths that need modification across all fixes and regression tests
+- **Every issue in REPORT.md (including P2/P3) has a complete fix plan with a corresponding worker prompt.** No issue may be deferred to a future round or marked as "handle later."
 
 ## Workflow
 
@@ -36,6 +43,7 @@ Read all of the following:
 
 - **SPEC.md + DESIGN.md + CHECKLIST.md**: Full spec and design documentation
 - **REPORT.md**: Review findings (verdict + P0-P3 issue list + dimension summary)
+- `<spec_dir>/references/` or `<batch_dir>/references/` — External method/API reference documents
 
 Understand the original design intent of the spec and the nature of each issue in REPORT.md.
 
@@ -59,7 +67,7 @@ For each issue in REPORT.md (in P0 → P1 → P2 → P3 order) → FIX.md Sectio
 
 ### 4. Design Regression Tests for Each Fix
 
-For every fix issue, design a concrete regression test → FIX.md Section 5 (Fix Details, regression test field) → FIX.md Section 6 (Worker Prompt Library, REGTEST entries).
+For every fix issue, design a concrete regression test → FIX.md Section 5 (Fix Details, regression test field) → worker prompt in `fix/*REGtest*.md`.
 
 Design principles:
 - **Every P0/P1 issue needs at least one regression test.** For P2/P3 issues, if automated testing is impractical, define manual verification steps.
@@ -99,9 +107,11 @@ File overlap detection is the **gate that determines parallel vs sequential exec
 
 ### 7. Write Worker Prompts
 
-#### 7a. Fix Worker Prompts → FIX.md Section 6
+#### 7a. Fix Worker Prompts
+
+Write a self-contained worker prompt for each fix issue. Save each prompt to a separate file under `<spec_dir>/fix/` or `<batch_dir>/fix/`.
 
-Write a self-contained worker prompt for each fix issue.
+**Worker prompt file naming**: `fix/FIX-{sequence}-{kebab-case-name}.md`
 
 Each fix worker prompt must include:
 
@@ -109,7 +119,7 @@ Each fix worker prompt must include:
 ## Mission — What to fix and why
 ## Context — Which review dimension, which spec requirement
 ## Input — Which files to read
-## What to do — Concrete fix steps (describe "what" to do, not "which tool" to use)
+## What to do — Concrete fix steps, each specifying the exact file path, the function or line range, and what specific change to make (add/delete/modify). Never leave the change description vague.
 ## Scope — Allowed and forbidden files
 ## Output — What to report on completion
 ## Verify — Verification commands and expected results
@@ -119,10 +129,12 @@ Each fix worker prompt must include:
 **Simple fixes can be merged**: Multiple simple, non-conflicting fixes can be combined into one worker prompt.
 **Complex fixes stand alone**: Complex fixes (requiring systematic debug) must have independent worker prompts.
 
-#### 7b. Regression Test Worker Prompts → FIX.md Section 6
+#### 7b. Regression Test Worker Prompts
 
 Write a self-contained worker prompt for each regression test. The regression test worker is responsible for **writing test code**.
 
+**Worker prompt file naming**: `fix/REGTEST-{sequence}-{kebab-case-name}.md`
+
 Each regression test worker prompt must include:
 
 ```
@@ -137,6 +149,11 @@ Each regression test worker prompt must include:
 ## Verify — Run the test, confirm it passes (proving the fix works)
 ```
 
+**Writing principles (move these to your process, not the template):**
+- Writing clear worker prompts means being concrete, not declarative. For every file the worker must modify, specify: (1) the exact file path, (2) the function or line range, (3) what to add, delete, or change.
+- Workers do not see the coordinator's context. The prompt must include everything necessary.
+- A regression test that passes before the fix is not a valid test. Always design the oracle so it fails on unfixed code.
+
 #### 7c. Cases That Do Not Need a Worker
 
 - Single-line typo fixes (multiple typos can be batched into one worker)
@@ -180,23 +197,46 @@ Use `assets/templates/FIX.md`. Fill according to the table below.
 | 3. Issue Inventory | REPORT.md issue list (condensed to NL one-liners) |
 | 4. Fix Dependency Analysis | Steps 5-6 (dependency analysis + file overlap) |
 | 5. Fix Details (with regression test design) | Step 3 (fix plan) + Step 4 (regression test design) |
-| 6. Worker Prompt Library | Step 7a (fix prompts) + Step 7b (regression test prompts) |
+| 6. Worker Prompt Index | Step 7 — list of `fix/*.md` files with FIX/REGTEST ID mapping |
 | 7. Fix Batch Schedule | Step 8 (batch schedule) |
 | 8. Regression Test Inventory | Step 4 full list. If regtests ≤ 3, omit (Section 5 is sufficient). If ≥ 4, include a condensed NL list. |
 | 9. Verification Checkpoints | Fixed scaffold, customized with spec-specific commands |
 | 10. Error Recovery | Fixed scaffold (natural language) |
 | 11. Fix History | Fixed scaffold (history entries only, no instructions) |
-| 12. Boundaries | Fixed scaffold + spec-specific rules |
+| 12. References | Worker prompt file paths (`fix/*.md`), all code file paths that need modification across all fixes/regtests, project context files |
+| 13. Boundaries | Fixed scaffold + spec-specific rules (including worktree cleanup after each batch) |
+
+### 11. Pre-delivery Self-Review
+
+Before delivering FIX.md, verify all of the following.
+
+**Worker prompt quality:**
+
+- Every worker prompt in `fix/*.md` is self-contained. Scan for phrases like "based on your findings", "fix it appropriately", "as discussed above" — these leak shared context assumptions.
+- Every fix worker prompt has concrete file-level Scope and a specific Verify command.
+- Worker prompt filenames match their fix IDs (`fix/FIX-{sequence}-*.md`, `fix/REGTEST-{sequence}-*.md`).
+
+**Coverage completeness:**
+
+- Every issue in REPORT.md (P0–P3) has a corresponding worker prompt. No deferred issues.
+- Every fix has a corresponding regression test (or documented manual verification steps for P2/P3 where automated testing is impractical).
+
+**Structural consistency:**
+
+- Each fix's dependency analysis matches the batch ordering. No fix scheduled before its dependencies are met.
+- Regression tests are scheduled after all fix batches complete.
+- FIX.md References section lists all worker prompt paths and all code file paths.
 
-### 11. Produce FIX.md
+### 12. Produce FIX.md and Worker Prompts
 
-Place FIX.md in the spec directory (same level as REPORT.md).
+Place the FIX.md in the spec directory (same level as REPORT.md).
+Place worker prompts in `<spec_dir>/fix/` or `<batch_dir>/fix/`.
 
 ## Examples
 
-- REPORT.md has 3 P0 issues (hallucinated code, deviation, omission) and 2 P1 issues → Each P0/P1 gets 1+ regression test → FIX.md has 3 fix workers + 5 regression test workers → Schedule: Batch 1 parallel fix 3 P0 → Batch 2 fix 2 P1 → Batch 3 parallel 5 regtests → Batch 4 final
-- Two P0 issues both modify `src/auth.ts` → File overlap → Separate into sequential batches → Regression tests run after all fix batches complete
-- A P0 logic error: `getDiscount()` does not handle negative input → Regression test: unit test with GIVEN negative input WHEN calling getDiscount THEN return 0 (before fix, returns incorrect negative discount)
+- REPORT.md has 3 P0 issues (hallucinated code, deviation, omission) and 2 P1 issues → Each P0/P1 gets 1+ regression test → FIX.md + fix/ with 3 fix workers + 5 regression test workers → Schedule: Batch 1 parallel fix 3 P0 → Batch 2 fix 2 P1 → Batch 3 parallel 5 regtests → Batch 4 final
+- Two P0 issues both modify `src/auth.ts` → File overlap → Separate into sequential batches → Regression tests run after all fix batches complete → Worker prompts in `fix/FIX-01-*.md` and `fix/FIX-02-*.md`
+- A P0 logic error: `getDiscount()` does not handle negative input → Regression test: unit test with GIVEN negative input WHEN calling getDiscount THEN return 0 (before fix, returns incorrect negative discount) → Worker prompt in `fix/REGTEST-01-discount.md`
 
 ## References
 

package/skills/qa/assets/templates/FIX.md

@@ -100,112 +100,23 @@
 
 ---
 
-## 6. Worker Prompt Library
+## 6. Worker Prompt Index
 
-### Fix Worker Prompts
-
-[Each dispatchable fix task has a pre-written self-contained worker prompt.]
-
-#### FIX-01: [Issue title]
-
-```
-## Mission
-[Brief description: what to fix and why.]
-
-## Context
-- Review dimension: [Hallucinated code / Omission / Deviation / Architecture / Performance / Redundancy]
-- Spec requirement: [Related SPEC requirement]
-
-## Input
-- Read the following files: [list]
-
-## What to do
-1. [Concrete fix steps — describe "what" to do, not "which tool" to use]
-2. [Include specific file paths, function names, line numbers, modification approach]
-
-## Scope
-- Allowed files:
-  - `[path]` — [explanation]
-- Forbidden files:
-  - `[path]` — (belongs to another worker)
+[Each dispatchable fix and regression test has a pre-written self-contained worker prompt in a separate file under `fix/`. The coordinator reads the corresponding file and dispatches it without modification.]
 
-## Output
-On completion, report:
-- Which files were modified (absolute paths)
-- Change summary for each file
-- Test results (pass/fail)
-- Any blockers or risks encountered
-
-## Verify
-- Run: `[command]`
-- Expected: [what you should see]
-
-## Boundaries
-- Do not modify any file in the forbidden list
-- Fix must not conflict with the original spec requirements
-- Preserve existing test behavior semantics (unless the spec explicitly requires a change)
-- Do not write regression tests — that is handled by another worker
-- If you encounter an unexpected blocker, stop and report — do not invent alternative approaches
-```
-
----
+### Fix Worker Prompts
 
-[Repeat the above block for each fix worker. Multiple simple fixes with no overlap can be merged into one worker prompt by combining their What to do sections.]
+| Fix ID | Worker Prompt File | Description |
+|---|---|---|
+| FIX-01 | `fix/FIX-01-[name].md` | [Brief description] |
+| FIX-02 | `fix/FIX-02-[name].md` | [Brief description] |
 
 ### Regression Test Worker Prompts
 
-[Each regression test has a pre-written self-contained worker prompt. The regression test worker's task is to **write test code**.]
-
-#### REGTEST-01: [Test name] (related to FIX-01)
-
-```
-## Mission
-Create a regression test for FIX-01 ([brief description]). This test ensures the issue never reappears.
-
-## Context
-- Fix summary: [What FIX-01 fixed]
-- Root cause: [Root cause explanation]
-- Fix files involved: [list]
-
-## Input
-- Read fix-related files: [list]
-- Read existing test files as format reference: `[existing test path]`
-
-## What to do
-Create a regression test at `[test location]`:
-
-Test scenario:
-- GIVEN [specific precondition and input]
-- WHEN [specific trigger]
-- THEN [expected output or behavior]
-
-Oracle: This test must fail on the unfixed code and pass after the fix is applied.
-
-## Scope
-- Allowed files:
-  - `[test file path]` — create/modify regression test
-- Forbidden files:
-  - All non-test source files (fixes are handled by another worker)
-
-## Output
-On completion, report:
-- The test file and test function name
-- Test execution result (must pass)
-- If the test cannot pass, explain why (may indicate an incomplete fix)
-
-## Verify
-- Run: `[test command]`
-- Expected: REGTEST-01 passes
-
-## Boundaries
-- Do not modify any source code files
-- The test must be independently executable, not dependent on external state
-- Follow the existing test file's formatting and naming conventions
-```
-
----
-
-[Repeat the above block for each regression test worker. Multiple regressions in the same file can be merged into one worker prompt.]
+| Test ID | Worker Prompt File | Related Fix | Description |
+|---|---|---|---|
+| REGTEST-01 | `fix/REGTEST-01-[name].md` | FIX-01 | [Brief description] |
+| REGTEST-02 | `fix/REGTEST-02-[name].md` | FIX-02 | [Brief description] |
 
 ---
 
@@ -311,17 +222,29 @@ If there are no entries here, see Section 5 for each fix's regression test desig
 
 ---
 
-## 12. Boundaries
+## 12. References
+
+- **Worker prompt files**: [List all `fix/*.md` files — e.g., `fix/FIX-01-*.md`, `fix/REGTEST-01-*.md`]
+- **Code files to modify** (across all fixes and regression tests):
+  - [File path — e.g., `src/auth/login.ts`]
+  - [File path — e.g., `src/auth/logout.ts`]
+- **Project context files**: [List important project files the fix coordinator and workers may need — e.g., `CLAUDE.md`, `AGENTS.md`, `resources/project-architecture/**`, codegraph index files]
+- **Related documents**: [Links to REPORT.md, SPEC.md, DESIGN.md, or external documentation]
+
+---
+
+## 13. Boundaries
 
 ### ALWAYS
 
 - Run gate verification immediately after every batch
-- Extract worker prompts verbatim from Section 6 — do not rewrite them
+- Extract worker prompts verbatim from `fix/*.md` files — do not rewrite them
 - After a worker reports, digest the results before deciding next steps
 - Fixes must not conflict with the original spec requirements
 - Regression tests must not start before all fix batches pass
 - Resolve merge conflicts yourself — the coordinator handles them. This is coordination, not implementation.
 - **For fixes marked as Complex**: ensure the worker performs systematic debugging (reading related code, tracing execution paths) before applying the fix. Do not let the worker guess the fix.
+- **After each batch completes, clean up any temporary branches or worktrees created by workers** — no ephemeral worktree should be left orphaned.
 
 ### ASK FIRST — pause and confirm with the user
 

package/skills/review/SKILL.md

@@ -111,6 +111,7 @@ Include the following sections:
 - **Requirement Status Summary**: Per-requirement: completion status, evidence location, open findings
 - **Findings**: Issue list sorted by P0 → P3 (only levels with findings)
 - **Review History**: Previous rounds (if any)
+- **References**: List important project context files the next skill (qa) will need (e.g., `CLAUDE.md`, `AGENTS.md`, `resources/project-architecture/**`). This reduces the LLM's need to search for relevant files when processing the report.
 
 **Verdict criteria** (P-level directly determines verdict — no separate requirement check needed):
 

package/skills/review/assets/templates/REPORT.md

@@ -56,3 +56,10 @@
 - **Verdict**: [Ready to Merge / Needs Attention / Needs Work]
 - **Issues**: P0:X, P1:X, P2:X, P3:X
 - **Key findings**: [1-2 sentence summary of the most important findings in this round]
+
+---
+
+## References
+
+- **Project context files**: [List important project files the reviewer used — e.g., `CLAUDE.md`, `AGENTS.md`, `resources/project-architecture/**`]
+- **Related documents**: [Links to related SPEC.md, DESIGN.md, or external documentation]