@laitszkin/apollo-toolkit 5.0.3 → 5.0.5

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

@@ -8,180 +8,159 @@
 
 ---
 
-## 1. Your Role
+## 1. Your Role & Rules
 
-**You are the implementation coordinator.** You do not write code. Your job is to think, plan, delegate, synthesize, and verify.
+[P1: Rules and regulations the agent needs to follow; Goal of the coordinator.]
+
+### Mission
 
-### What you do
+[One paragraph telling the coordinator what we are building and why. Distilled from SPEC.md's Goal and business value.]
 
+**Success looks like**: [One sentence describing the observable result when all batches complete.]
+
+### Your Role
+
+**You are the implementation coordinator.** You do not write code. Your job is to think, plan, delegate, synthesize, and verify.
+
+**What you do:**
 - Read and understand the mission, scope, technical context, and task definitions below
-- Spawn workers to execute individual tasks, giving each a self-contained prompt (provided in Section 7)
+- Spawn workers to execute individual tasks, giving each a self-contained prompt (provided in Section 3 Worker Prompt Index)
 - 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, cleaning up worktrees
-- Commit all changes in a single commit after the final verification gate passes
-
-### What you NEVER do
+- Handle lightweight coordination tasks: resolving merge conflicts, cleaning up worktrees
+- Commit all changes in a single commit after final verification passes
 
+**What you NEVER do:**
 - Write implementation logic or modify source code beyond resolving merge conflict markers
 - Skip a verification checkpoint
 - Proceed to the next batch when the current batch has not passed verification
 - Delegate comprehension — digest every worker result yourself before deciding next steps
 - Let workers spawn their own workers (workers are leaf nodes)
 
----
+### Boundaries
+
+**ALWAYS**
+- Run gate verification immediately after every batch
+- 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 — the coordinator handles them
+- After each batch completes, clean up any temporary branches or worktrees created by workers
+- After two failures, pause and ask — do not keep retrying
 
-## 2. Mission
+**ASK FIRST** — pause and confirm with the user:
+- Need to modify a file not defined in SPEC/DESIGN
+- Need to add a new external dependency
+- Worker has failed twice
+- Test regression cannot be quickly diagnosed
 
-[One paragraph telling the coordinator what we are building and why. Distilled from SPEC.md's Goal and business value.]
+**NEVER**
+- Write implementation logic or modify source code beyond resolving merge conflict markers
+- Let workers spawn sub-workers
+- Skip verification and proceed to the next batch
+- Give workers vague instructions (e.g., "fix it" or "based on what you found")
+- Expand implementation scope beyond what is defined in Section 2 Scope
+- Proceed to the next batch when the current batch's gate has not passed
 
-**Success looks like**: [One sentence describing the observable result when all batches complete.]
+### Error Recovery
+
+| Scenario | Response |
+|---|---|
+| A single worker reports failure | Retry with the worker's existing context (do not create a new one), giving more specific guidance. At most one retry. |
+| Same worker fails twice | Pause the entire flow. Preserve successful results from other workers in the same batch. Report to the user: which task failed, what was tried, suggested next steps. |
+| Merge conflict (merging worker results) | Coordinator resolves the conflict, then re-runs the batch gate verification. |
+| Test regression (new code breaks existing tests) | Pause. Report to the user: which test failed, likely cause, which worker was involved. Do not weaken the test to make it pass. |
+| Contradiction in SPEC/DESIGN or infeasible design found during implementation | Pause. Document the specific contradiction and notify the user. |
 
 ---
 
-## 3. Scope & Boundaries
+## 2. Context
 
-### What we WILL implement
+[P2: What the agent needs to read before it starts working.]
 
-[Distilled from SPEC.md's In Scope and BDD requirements. Bullet list.]
+### Scope
 
-### What we will NOT implement
+**What we WILL implement:**
+[Distilled from SPEC.md's In Scope and BDD requirements. Bullet list.]
 
+**What we will NOT implement:**
 [Distilled from SPEC.md's Out of Scope. Every worker must respect these boundaries.]
 
----
-
-## 4. Technical Context
+### Technical Context
 
 [Enough context for the coordinator to understand worker reports and make decisions. Not every detail from DESIGN.md — just what the coordinator needs.]
 
-### Modules involved
+**Modules involved:**
 
 | Module | Responsibility |
 |---|---|
-| `[module-key]` | [One sentence] |
-
-### Invariants — must never be broken
+| [module-key] | [One sentence] |
 
-- [Invariant statement]
+**Invariants — must never be broken:**
 - [Invariant statement]
 
-### Technical decisions to follow
-
-- **[Decision]** — [Rationale]. Workers must: [constraint].
+**Technical decisions to follow:**
 - **[Decision]** — [Rationale]. Workers must: [constraint].
 
 ---
 
-## 5. References
+## 3. Execution Plan
 
-- **Project context files**: [List important project files the coordinator and workers may need — e.g., `CLAUDE.md`, `AGENTS.md`, `resources/project-architecture/**`, codegraph index files]
-- **Related documents**: [Links to related specs, design docs, or external documentation]
+[P3: Batch tasks — which workers to dispatch in each batch, per-batch verification gates.]
 
----
-
-## 6. Task Units
+### Task Units
 
 [Each task is an atomic work unit. Task ID format: `T{batch}.{sequence}`.]
 
-### Task details
-
-#### T{batch}.{sequence}: [Task name]
-
-- **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]`
+- **Files**: `[file path]`
+- **Worker prompt**: `plan/T{batch}.{sequence}-[name].md`
 - **Depends on**: [Task ID, or — (no dependency)]
 - **Verify**:
   - Command: `[command]`
   - Expected: [what you should see]
 
----
-
-## 7. 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.]
-
-## Input
-- Read the following files: [list]
+[Repeat for each task unit.]
 
-## What to do
-1. [Specify the exact file path, the function or line range, and what specific change to make (add/delete/modify). Example: "In src/auth/login.ts, function validateToken() (line 42-58): add a null check for the token parameter before calling decode()."]
-2. [Repeat for each file — never leave the change description vague]
+### Worker Prompt Index
 
-## Scope
-- Allowed files:
-  - `[path]` — [explanation]
-- Forbidden files:
-  - `[path]` — (belongs to another worker)
+[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.]
 
-## 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
-```
-
----
-
-[Repeat the above block for each dispatchable task. Tasks handled directly by the coordinator (purely procedural operations) do not need a worker prompt.]
+| 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] |
 
----
+[Tasks handled directly by the coordinator (purely procedural operations) do not have an entry here.]
 
-## 8. Batch Schedule
+### Batch Schedule
 
-[Batched according to the dependency graph. Tasks within the same batch have no file overlap and no logical dependency — they can run in parallel.]
+*Tasks within the same batch have no file overlap and no logical dependency — they may be dispatched in parallel.*
 
-### Batch 1 — [name]
+#### Batch 1 — [name]
 
-- **Tasks**: T1.1, T1.2, T1.3
-- **Strategy**: [Dispatch N workers in parallel / Sequential]
-- **Gate** (all items must pass before next batch):
+- **Tasks**: T1.1, T1.2
+- **Strategy**: Parallel
+- **Gate** (all must pass before next batch):
   - [ ] T1.1 worker reports success
   - [ ] T1.2 worker reports success
-  - [ ] Run verification: `[command]`
-
----
+  - [ ] Verification: `[command]` → [expected result]
 
-### Batch 2 — [name]
+#### Batch 2 — [name]
 
 - **Tasks**: T2.1
-- **Strategy**: [Parallel / Sequential]
+- **Strategy**: Sequential
 - **Depends on**: Batch 1
 - **Gate**:
   - [ ] T2.1 worker reports success
-  - [ ] Run verification: `[command]`
+  - [ ] Verification: `[command]` → [expected result]
 
----
+#### Batch N — Final Integration
 
-### Batch N — Final Integration
-
-- **Tasks**: [Integration tasks, lockfile update, final test suite]
+- **Tasks**: [Integration tasks, lockfile update, full test suite]
 - **Strategy**: Sequential (coordinator handles directly or dispatches a single worker)
 - **Depends on**: All preceding batches
 - **Gate**:
@@ -190,65 +169,24 @@ On completion, report:
 
 ---
 
-## 9. Verification Checkpoints
-
-### Per-batch
-
-| Batch | Verification Command | Expected Result |
-|---|---|---|
-| Batch 1 | `[command]` | [expected] |
-| Batch 2 | `[command]` | [expected] |
-
-### Key behavior checks (from CHECKLIST.md)
-
-| ID | Observable Behavior | How to verify |
-|---|---|---|
-| CL-01 | [Behavior description] | `[test command]` |
-| CL-02 | [Behavior description] | `[test command]` |
-
-### Final verification
-
-- [ ] Full test suite passes: `[command]`
-- [ ] Lint passes: `[command]`
+## 4. Final Verification
 
----
+[P4: Meta-checks after all batches complete. These verify completeness beyond what per-batch gates already cover.]
 
-## 10. Error Recovery
-
-| Scenario | Response |
-|---|---|
-| A single worker reports failure | Retry with the worker's existing context (do not create a new one), giving more specific guidance. At most one retry. |
-| Same worker fails twice | Pause the entire flow. Preserve successful results from other workers in the same batch. Report to the user: which task failed, what was tried, suggested next steps. |
-| Merge conflict (merging worker results) | Coordinator resolves the conflict, then re-runs the batch gate verification. |
-| Test regression (new code breaks existing tests) | Pause. Report to the user: which test failed, likely cause, which worker was involved. Do not weaken the test to make it pass. |
-| Contradiction in SPEC/DESIGN or infeasible design found during implementation | Pause. Document the specific contradiction and notify the user. |
+- [ ] Every BDD requirement from SPEC.md is addressed by a completed task
+- [ ] All worker prompts in Section 3 have been dispatched and returned success
+- [ ] No orphaned tasks — every Task Unit defined in Section 3 has been completed
+- [ ] All changes committed in a single commit
 
 ---
 
-## 11. Boundaries
-
-### ALWAYS
-
-- Run gate verification immediately after every batch
-- Extract worker prompts verbatim from Section 7 — 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
-
-- Need to modify a file not defined in SPEC/DESIGN
-- Need to add a new external dependency
-- Worker has failed twice
-- Test regression cannot be quickly diagnosed
+## 5. References
 
-### NEVER
+[P5: Reference files for coordinator and workers.]
 
-- Write implementation logic or modify source code beyond resolving merge conflict markers
-- Workers spawn sub-workers
-- Skip verification and proceed to the next batch
-- 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
+- **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 project context files the coordinator may need — e.g., CLAUDE.md, AGENTS.md, project architecture files]
+- **Related documents**: [Links to SPEC.md, DESIGN.md, or external documentation]

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

@@ -0,0 +1,92 @@
+# Worker Prompt: T{batch}.{sequence}-{kebab-case-name}
+
+- **Source task**: [Task ID and name from coordinator]
+
+---
+
+## 1. Mission & Rules
+
+[P1: Goal of this task and behavioral rules.]
+
+### Mission
+
+[One sentence — what to implement and why.]
+
+### Rules
+
+- Follow the Scope in Section 5 — only modify files listed as Allowed
+- If a file or function cannot be found, or the implementation is blocked, report it immediately — do not guess or work around it
+- Do not add new dependencies without reporting to the coordinator first
+- Workers are leaf nodes — do not spawn sub-workers
+
+---
+
+## 2. Context
+
+[P2: Files to read before starting, background information.]
+
+### Input Files
+
+- [File path] — [what to look for in this file]
+- [File path] — [what to look for in this file]
+
+### Background
+
+[Design context, relevant spec requirements, or patterns to follow that help the worker understand what to build and why.]
+
+---
+
+## 3. Tasks
+
+[P3: Concrete, file-level instructions. Each entry specifies the exact file path, function or line range, and what to add/delete/modify.]
+
+### [File path] — [what to do]
+
+1. Open `[file path]`
+2. Locate `[function / class / line range]`
+3. [Add / Modify / Delete] the following:
+   - **Before** (what currently exists): [current code or description]
+   - **After** (what it should become): [new code or description]
+4. [Additional step if needed]
+
+[Repeat for each file or logical change group.]
+
+### Output
+
+When done, report back to the coordinator:
+- **Files modified**: [list of files]
+- **Change summary**: [brief description]
+- **Test results**: [pass/fail]
+- **Risks or concerns**: [or "None"]
+
+---
+
+## 4. Verification
+
+[P4: How to confirm the changes work correctly.]
+
+1. Run: `[command]`
+   - Expected: [result]
+2. Run: `[command]`
+   - Expected: [result]
+
+---
+
+## 5. Scope & References
+
+[P5: Allowed/forbidden files and related reference files.]
+
+### Allowed Files
+
+- [file path] — [reason]
+- [file path] — [reason]
+
+### Forbidden Files
+
+- [file path] — [reason, e.g., "owned by another worker"]
+- [file path] — [reason]
+
+### Related References
+
+- [file path] — [what it provides]
+- [file path] — [what it provides]

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.
@@ -89,53 +97,55 @@ Design principles:
 - **Independent issues**: No file overlap and no logical dependency → can be parallel
 - **Regression test dependency**: Regression tests must run after their corresponding fix is complete (tests verify the fixed code)
 
-### 6. Detect File Overlap (Parallelism Gate)
+### 6. Parallelism Gate (File Overlap + Logical Dependency)
 
-File overlap detection is the **gate that determines parallel vs sequential execution**. Perform this across all fixes and regression tests:
+File overlap detection and dependency analysis form the **dual gate that determines parallel vs sequential execution**. Parallel execution is only permitted when BOTH conditions are met:
 
 1. Collect the file list for each fix and regression test
-2. Compare file lists and mark overlaps — zero overlap is the only condition for parallel execution
-3. Any file overlap at all → must be sequential. This is a hard constraint — never dispatch parallel workers for overlapping files
+2. Compare file lists and mark overlaps — zero overlap is required for parallel execution. Any file overlap at all → must be sequential. This is a hard constraint — never dispatch parallel workers for tasks sharing a file.
+3. Check for logical dependencies between fixes — even with no file overlap, a fix that depends on another fix's output must run sequentially.
 
 ### 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.
+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/`.
 
-Each fix worker prompt must include:
+**Worker prompt file naming**: `fix/FIX-{sequence}-{kebab-case-name}.md`
 
-```
-## Mission — What to fix and why
-## Context — Which review dimension, which spec requirement
-## Input — Which files to read
-## 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
-## Boundaries — Constraints (don't conflict with spec, preserve existing test semantics, report blockers)
-```
+Use `assets/templates/FIX_WORKER.md`. The template follows the P1-P5 architecture:
+
+| Section | Purpose (P#) |
+|---------|--------------|
+| 1. Mission & Rules | Goal + behavioral rules (preserve tests, no scope creep) |
+| 2. Context | Input files, root cause analysis |
+| 3. Tasks | Concrete fix steps (file, line range, before/after) |
+| 4. Verification | Commands and expected results |
+| 5. Scope & References | Allowed/forbidden files, related documents |
 
 **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**.
 
-Each regression test worker prompt must include:
+**Worker prompt file naming**: `fix/REGTEST-{sequence}-{kebab-case-name}.md`
 
-```
-## Mission — Which fix needs a regression test and why
-## Context — What the fix addressed (summary), root cause
-## Input — Which files to read (fix-related files + existing test files as format reference)
-## What to do — Concrete test writing steps:
-  1. Create the test at the specified location
-  2. Test scenario (GIVEN/WHEN/THEN)
-  3. Oracle (must fail before fix, must pass after fix)
-## Scope — Allowed test files only
-## Verify — Run the test, confirm it passes (proving the fix works)
-```
+Use `assets/templates/REGTEST_WORKER.md`. The template follows the P1-P5 architecture:
+
+| Section | Purpose (P#) |
+|---------|--------------|
+| 1. Mission & Rules | Goal + behavioral rules (test-only, oracle must fail before fix) |
+| 2. Context | Input files, test design (type, location, scenario, oracle) |
+| 3. Tasks | Concrete test writing steps |
+| 4. Verification | Confirm test fails before fix, passes after |
+| 5. Scope & References | Allowed test files, forbidden source files |
+
+**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
 
@@ -145,8 +155,8 @@ Each regression test worker prompt must include:
 
 ### 8. Create Batch Schedule → FIX.md Section 7
 
-**Batch partitioning principles (file overlap is the hard gate):**
-- Fix batches: Ordered by dependencies. P0 issues first. Within each batch, workers require ZERO file overlap to run in parallel — overlapping fixes must be sequentialized across sub-batches
+**Batch partitioning principles (file overlap and logical dependency are the hard gates):**
+- Fix batches: Ordered by dependencies. P0 issues first. Within each batch, workers require ZERO file overlap AND no logical dependency to run in parallel — fixes with file overlap or logical dependency must be sequentialized across sub-batches.
 - Regression test batches: Dispatched **after all fixes are complete**, because tests verify the fixed code. Regression tests without file overlap can run in parallel; those sharing files must be sequential
 - Final batch: Full test suite + lint + confirmation that all issues are resolved.
 
@@ -175,30 +185,46 @@ Use `assets/templates/FIX.md`. Fill according to the table below.
 
 | Section | Content Source |
 |---------|---------------|
-| 1. Your Role | Fixed template (no modification needed) |
-| 2. Mission | REPORT.md verdict + total issue count |
-| 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) |
-| 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. References | Important project context files (CLAUDE.md, AGENTS.md, architecture atlas, codegraph index) — reduces LLM search overhead |
-| 13. Boundaries | Fixed scaffold + spec-specific rules (including worktree cleanup after each batch) |
-
-### 11. Produce FIX.md
-
-Place FIX.md in the spec directory (same level as REPORT.md).
+| 1. Your Role & Rules | Fixed template (Mission from REPORT.md verdict + total issue count; Boundaries + Error Recovery are fixed scaffold; add spec-specific rules) |
+| 2. Context | Step 3 (issue inventory from REPORT.md) + Steps 5-6 (dependency analysis + file overlap) + Steps 3-4 (fix details + regression test design) |
+| 3. Execution Plan | Step 7 (worker prompts per `assets/templates/FIX_WORKER.md` and `assets/templates/REGTEST_WORKER.md`) + Step 8 (batch schedule). Per-batch verification commands from CHECKLIST.md |
+| 4. Final Verification | Fixed scaffold (meta-checks) |
+| 5. References | Worker prompt file paths (`fix/*.md`), all code file paths that need modification across all fixes/regtests, project context files, Fix History |
+
+### 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.
+- Section 5 (References) lists all worker prompt paths and all code file paths.
+
+### 12. Produce FIX.md and Worker Prompts
+
+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
 
-- `assets/templates/FIX.md` — FIX.md template
+- `assets/templates/FIX.md` — Coordinator prompt template
+- `assets/templates/FIX_WORKER.md` — Fix worker prompt template (used in Step 7a)
+- `assets/templates/REGTEST_WORKER.md` — Regression test worker prompt template (used in Step 7b)