@laitszkin/apollo-toolkit 5.0.4 → 5.0.5

package/CHANGELOG.md

@@ -2,6 +2,15 @@
 
 All notable changes to this repository are documented in this file.
 
+## [v5.0.5] - 2026-06-07
+
+### Changed
+
+- **P1-P5 prompt architecture**: `plan` and `qa` coordinator prompt templates (PROMPT.md, FIX.md) restructured into 5-section architecture: Your Role & Rules → Context → Execution Plan → Final Verification → References. All behavioral rules consolidated into Section 1.
+- **Dual parallelism gate**: Both `plan` and `qa` skills' parallelism conditions updated to require BOTH zero file overlap AND no logical dependency. Previous versions only enforced file overlap as the hard gate.
+- **Independent worker prompt templates**: Worker prompt formats extracted from inline SKILL.md blocks into dedicated template files (`WORKER_PROMPT.md`, `FIX_WORKER.md`, `REGTEST_WORKER.md`), each following the P1-P5 architecture.
+- **References section cleaned**: Hard-coded project file names removed from template placeholders, using generic descriptions with `— e.g.,` pattern consistent with other skills.
+
 ## [v5.0.4] - 2026-06-07
 
 ### Added

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@laitszkin/apollo-toolkit",
-  "version": "5.0.4",
+  "version": "5.0.5",
   "description": "Apollo Toolkit npm installer for managed skill copying across Codex, OpenClaw, and Trae.",
   "license": "MIT",
   "author": "LaiTszKin",

package/skills/plan/SKILL.md

@@ -60,7 +60,7 @@ Decompose the architecture design from DESIGN.md into tasks precise to the file
 
 **Decide whether each task needs an independent worker:**
 - Touches ≥2 files → needs independent worker
-- **No file overlap between tasks → workers may run in parallel.** This is permitted ONLY when file lists have ZERO overlap across all workers within the same batch. Any shared file between tasks means sequential execution — this is a hard constraint to prevent overwrite conflicts.
+- **Workers may run in parallel only when BOTH conditions are met:** (1) file lists have ZERO overlap across all workers within the same batch, AND (2) no logical dependency exists between the tasks. If either condition is violated, the tasks must run sequentially.
 - File overlap or logical dependency between tasks → must run sequentially
 - Purely procedural operations (lockfile update, merge, commit) → no worker needed; coordinator handles directly
 
@@ -85,13 +85,13 @@ Analyze dependencies between specs:
 
 Output: Spec DAG.
 
-### 5. Detect File Overlap (Parallelism Gate)
+### 5. Parallelism Gate (File Overlap + Logical Dependency)
 
-File overlap detection is the **gate that determines parallelism**. Perform this across all task units:
+File overlap detection and dependency analysis form the **dual gate that determines parallelism**. Parallel execution is only permitted when BOTH conditions are met:
 
 1. Collect the file list each task unit is expected to modify
-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 tasks sharing a file
+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 task units — even with no file overlap, tasks that depend on each other's output must run sequentially.
 
 ### 6. Write Worker Prompts (One Per Dispatchable Task)
 
@@ -99,17 +99,15 @@ For each task that needs an independent worker, write a self-contained worker pr
 
 **Worker prompt file naming**: `plan/T{batch}.{sequence}-{kebab-case-name}.md`
 
-Each worker prompt must include:
+Use `assets/templates/WORKER_PROMPT.md`. The template follows the P1-P5 architecture:
 
-```
-## Mission — What to do and why
-## Input — Which files to read
-## 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)
-```
+| Section | Purpose (P#) |
+|---------|--------------|
+| 1. Mission & Rules | Goal + behavioral rules |
+| 2. Context | Files to read, background knowledge |
+| 3. Tasks | Concrete file-level instructions (file, line range, change) |
+| 4. Verification | Commands and expected results |
+| 5. Scope & References | Allowed/forbidden files, related references |
 
 **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.
@@ -123,8 +121,8 @@ Tasks that do not need a worker (purely procedural operations) do not get a work
 
 Based on dependency analysis and file overlap detection, build the batch schedule → PROMPT.md Section 7 (Batch Schedule).
 
-**Batch partitioning principles (file overlap is the hard gate):**
-- Within the same batch: tasks must have ZERO file overlap — only then may they dispatch workers in parallel. File-overlapping tasks must be placed in separate sequential batches regardless of dependency
+**Batch partitioning principles (file overlap and logical dependency are the hard gates):**
+- Within the same batch: tasks must have ZERO file overlap AND no logical dependency — only then may they dispatch workers in parallel. Tasks with file overlap or logical dependency must be placed in separate sequential batches regardless.
 - Between batches: the previous batch must complete and pass its gate before the next batch begins
 - A final integration batch handles housekeeping tasks (lockfile update, final test suite)
 
@@ -151,17 +149,11 @@ Use `assets/templates/PROMPT.md`. Fill each section according to the table below
 
 | Section | Content Source |
 |---------|---------------|
-| 1. Your Role | Fixed template (no modification needed) |
-| 2. Mission | SPEC.md Goal + business value |
-| 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 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 (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) |
+| 1. Your Role & Rules | Fixed template (Mission from SPEC.md Goal + business value; Boundaries + Error Recovery are fixed scaffold; add spec-specific rules) |
+| 2. Context | SPEC.md In/Out of Scope + DESIGN.md: module list with responsibilities, interaction anchors (INT-###) and dependency order, external dependency setup order (EXT-###), system invariants, technical decisions and trade-offs |
+| 3. Execution Plan | Step 3 (task decomposition) + Step 4 (dependency analysis) + Step 6 (worker prompts per `assets/templates/WORKER_PROMPT.md`) + Step 7 (batch schedule). Per-batch verification commands from CHECKLIST.md |
+| 4. Final Verification | Fixed scaffold (meta-checks) |
+| 5. References | Worker prompt file paths (`plan/*.md`), all code file paths that need modification across all tasks, project context files, related documents |
 
 ### 11. Pre-delivery Self-Review
 
@@ -176,16 +168,16 @@ Before delivering PROMPT.md, verify all of the following.
 
 **Coverage completeness:**
 
-- Every BDD requirement from SPEC.md is addressed by at least one task in Section 5. If a requirement has no task, add one or document why it is already satisfied by existing code.
+- Every BDD requirement from SPEC.md is addressed by at least one task in Section 3 (Task Units). If a requirement has no task, add one or document why it is already satisfied by existing code.
 - Every module from DESIGN.md has a corresponding task or is explicitly noted as unchanged.
-- Every hardening requirement from CHECKLIST.md appears in Section 8.
+- Every hardening requirement from CHECKLIST.md appears in Section 4 (Final Verification) or in the Batch Schedule gates.
 
 **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 `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.
+- Each task's Depends on field matches the batch ordering. No task scheduled in a batch before its dependencies are met.
+- Every task listed in Batch Schedule has a worker prompt in `plan/*.md` — unless it is explicitly marked as coordinator-handled.
+- No orphaned tasks (a task listed in Task Units that never appears in any batch), no missing dependencies (a Depends on field referencing a task ID that does not exist).
+- Section 5 (References) lists all worker prompt paths and all code file paths.
 
 ### 12. Produce PROMPT.md and Worker Prompts
 
@@ -200,4 +192,5 @@ Place worker prompts in `<spec_dir>/plan/` or `<batch_dir>/plan/`.
 
 ## References
 
-- `assets/templates/PROMPT.md` — PROMPT.md template
+- `assets/templates/PROMPT.md` — Coordinator prompt template
+- `assets/templates/WORKER_PROMPT.md` — Worker prompt template (used in Step 6)

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

@@ -8,91 +8,124 @@
 
 ---
 
-## 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
+
+[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.]
 
-### What you do
+### 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 6)
+- 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
 
-## 2. Mission
+**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
 
-[One paragraph telling the coordinator what we are building and why. Distilled from SPEC.md's Goal and business value.]
+**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
 
-**Success looks like**: [One sentence describing the observable result when all batches complete.]
+**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
+
+### 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. Task Units
+## 3. Execution Plan
 
-[Each task is an atomic work unit. Task ID format: `T{batch}.{sequence}`.]
+[P3: Batch tasks — which workers to dispatch in each batch, per-batch verification gates.]
 
-### Task details
+### Task Units
+
+[Each task is an atomic work unit. Task ID format: `T{batch}.{sequence}`.]
 
 #### 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]
 
----
+[Repeat for each task unit.]
 
-## 6. Worker Prompt Index
+### Worker Prompt Index
 
 [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.]
 
@@ -103,37 +136,31 @@
 
 [Tasks handled directly by the coordinator (purely procedural operations) do not have an entry here.]
 
----
-
-## 7. 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**:
@@ -142,76 +169,24 @@
 
 ---
 
-## 8. Verification Checkpoints
-
-### Per-batch
-
-| Batch | Verification Command | Expected Result |
-|---|---|---|
-| Batch 1 | `[command]` | [expected] |
-| Batch 2 | `[command]` | [expected] |
-
-### Key behavior checks (from CHECKLIST.md)
+## 4. Final Verification
 
-| ID | Observable Behavior | How to verify |
-|---|---|---|
-| CL-01 | [Behavior description] | `[test command]` |
-| CL-02 | [Behavior description] | `[test command]` |
+[P4: Meta-checks after all batches complete. These verify completeness beyond what per-batch gates already cover.]
 
-### Final verification
-
-- [ ] Full test suite passes: `[command]`
-- [ ] Lint passes: `[command]`
+- [ ] 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
 
 ---
 
-## 9. 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. |
-
----
-
-## 10. 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** — 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
-
-### NEVER
-
-- 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
-
----
+## 5. References
 
-## 11. References
+[P5: Reference files for coordinator and workers.]
 
 - **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]
+- **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

@@ -97,13 +97,13 @@ 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
 
@@ -113,18 +113,15 @@ Write a self-contained worker prompt for each fix issue. Save each prompt to a s
 
 **Worker prompt file naming**: `fix/FIX-{sequence}-{kebab-case-name}.md`
 
-Each fix worker prompt must include:
+Use `assets/templates/FIX_WORKER.md`. The template follows the P1-P5 architecture:
 
-```
-## 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)
-```
+| 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.
@@ -135,19 +132,15 @@ Write a self-contained worker prompt for each regression test. The regression te
 
 **Worker prompt file naming**: `fix/REGTEST-{sequence}-{kebab-case-name}.md`
 
-Each regression test worker prompt must include:
+Use `assets/templates/REGTEST_WORKER.md`. The template follows the P1-P5 architecture:
 
-```
-## 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)
-```
+| 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.
@@ -162,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.
 
@@ -192,19 +185,11 @@ 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 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. 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) |
+| 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
 
@@ -225,7 +210,7 @@ Before delivering FIX.md, verify all of the following.
 
 - 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.
+- Section 5 (References) lists all worker prompt paths and all code file paths.
 
 ### 12. Produce FIX.md and Worker Prompts
 
@@ -240,4 +225,6 @@ Place worker prompts in `<spec_dir>/fix/` or `<batch_dir>/fix/`.
 
 ## 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)

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

@@ -8,14 +8,23 @@
 
 ---
 
-## 1. Your Role
+## 1. Your Role & Rules
 
-**You are the fix coordinator.** You do not write code. Your job is to understand the issues found in code review, delegate each fix and regression test to a worker, and verify that every issue is resolved without introducing regressions.
+[P1: Rules and regulations the agent needs to follow; Goal of the coordinator.]
+
+### Mission
+
+[One paragraph summarizing the scope, total issues, regression test count, and overall execution strategy.]
+
+**Success looks like**: All issues in REPORT.md are fixed, all regression tests pass, full test suite passes, no regressions.
 
-### What you do
+### Your Role
 
+**You are the fix coordinator.** You do not write code. Your job is to understand the issues found in code review, delegate each fix and regression test to a worker, and verify that every issue is resolved without introducing regressions.
+
+**What you do:**
 - Read and understand the issue inventory, dependency analysis, and fix details below
-- Spawn workers to execute individual fixes, giving each a self-contained prompt (provided in Section 6)
+- Spawn workers to execute individual fixes, giving each a self-contained prompt (provided in Section 3 Worker Prompt Index)
 - After all fixes pass verification, spawn workers to implement regression tests
 - Wait for all workers in a batch to complete, then digest their results
 - Run verification commands at each checkpoint
@@ -23,8 +32,7 @@
 - Handle lightweight coordination tasks: resolving merge conflicts, updating lockfiles
 - Commit all changes in a single commit after the final verification gate passes
 
-### What you NEVER do
-
+**What you NEVER do:**
 - Write, edit, or modify any source-code or test file directly
 - Skip a verification checkpoint
 - Proceed to the next batch when the current batch has not passed verification
@@ -33,107 +41,134 @@
 - Start regression tests before all fixes in scope are verified
 - Defer any REPORT.md issue to a future round — every issue has a complete plan here
 
----
+### Boundaries
 
-## 2. Mission
+**ALWAYS**
+- Run gate verification immediately after every batch
+- 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
+- For fixes marked as Complex: ensure the worker performs systematic debugging (reading related code, tracing execution paths) before applying the fix
+- After each batch completes, clean up any temporary branches or worktrees created by workers
 
-[One paragraph summarizing the scope, total issues, regression test count, and overall execution strategy.]
+**ASK FIRST** — pause and confirm with the user:
+- Fix approach conflicts with spec design intent
+- Need to add a new external dependency
+- Worker has failed twice
+- Test regression cannot be quickly diagnosed
 
-**Success looks like**: All issues in REPORT.md are fixed, all regression tests pass, full test suite passes, no regressions.
+**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
+- Modify spec documents (unless the fix reveals a spec error — report it instead)
+- Start regression tests before all fixes are verified
+- Defer any REPORT.md issue to a future round
+
+### Error Recovery
+
+| Scenario | Response |
+|---|---|
+| Fix 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 fix worker fails twice | Pause the entire flow. Preserve successful results from other workers in the same batch. Report to the user. |
+| Regression test worker reports failure (test cannot pass) | Check whether the test code is wrong or the fix is incomplete. If test code is wrong, continue the worker to fix it. If the fix is incomplete, go back to the corresponding fix worker. |
+| Regression test passes on the unfixed code | The test design is invalid — redesign the oracle and dispatch a new worker. |
+| Merge conflicts | Coordinator resolves the conflict, then re-runs the batch gate verification. |
+| Fix or regression test breaks existing tests | Pause. Report which test failed and which worker's change caused it. |
 
 ---
 
-## 3. Issue Inventory
+## 2. Context
 
-- FIX-01 (P0, 簡單, 幻覺代碼): [Brief description] — src/a.ts
-- FIX-02 (P0, 複雜, 實作遺漏): [Brief description] — src/b.ts, src/c.ts
-- FIX-03 (P1, 簡單, 架構瑕疵): [Brief description] — src/d.ts
+[P2: What the agent needs to read before it starts working.]
 
----
+### Issue Inventory
 
-## 4. Fix Dependency Analysis
+- FIX-01 (P0, Simple): [Brief description] — src/a.ts
+- FIX-02 (P0, Complex): [Brief description] — src/b.ts, src/c.ts
+- FIX-03 (P1, Simple): [Brief description] — src/d.ts
 
-### Dependencies
+[All REPORT.md issues (P0–P3) listed here. The "no-defer" rule applies — every issue has a complete fix plan.]
 
+### Fix Dependency Analysis
+
+**Dependencies:**
 - FIX-02 depends on FIX-01 (FIX-01 refactors the interface FIX-02 needs)
 - FIX-03 is independent
 - All REGTESTs depend on their corresponding FIX completing first
 
-### File overlaps
-
+**File overlaps:**
 - FIX-04, FIX-05 both modify `src/e.ts` → must be sequential
-- FIX-01, FIX-03: no overlap → can run in parallel
+- FIX-01, FIX-03: no overlap, no logical dependency → can run in parallel
 
----
-
-## 5. Fix Details (with Regression Test Design)
+### Fix Details (with Regression Test Design)
 
 [Each issue's fix information + corresponding regression test design.]
 
-### FIX-01: [Issue title] (P0)
+#### FIX-01: [Issue title] (P0)
 
 **Root cause**: [Root cause of the issue]
 **Files involved**: `[path]` > `[functionName()]` (L[N]-[N])
 **Fix approach**: [How to modify]
 **Complexity**: Simple
 
-**Regression test:** REGTEST-01 ([Unit test / Integration test / E2E] → `[test/file/path.test.ts]`)
+**Regression test:** REGTEST-01 ([Unit test] → `[test/file/path.test.ts]`)
 - GIVEN [precondition] WHEN [trigger] THEN [expected result]
-- Oracle: This test must fail on the unfixed code and pass after the fix is applied
+- Oracle: Must fail on unfixed code, pass after fix
 
----
+#### FIX-02: [Issue title] (P0)
 
-### FIX-02: [Issue title] (P0)
-
-**Root cause**: [Root cause]
+**Root cause**: [Root cause of the issue]
 **Files involved**: `[path]` > `[functionName()]` (L[N]-[N])
 **Fix approach**: [How to modify]
 **Complexity**: Complex — needs systematic debug
 
 **Regression test:** REGTEST-02 ([Integration test] → `[test/file/path.test.ts]`)
 - GIVEN [precondition] WHEN [trigger] THEN [expected result]
-- Oracle: [pass condition]
+- Oracle: Must fail on unfixed code, pass after fix
+
+[Repeat the above block for each issue. If an issue cannot be automatically tested (e.g., visual-only), note manual verification steps in the regression test field.]
 
 ---
 
-[Repeat the above block for each issue. If an issue cannot be automatically tested (e.g., visual-only), note manual verification steps in the regression test.]
+## 3. Execution Plan
 
----
+[P3: Batch tasks — which workers to dispatch in each batch, per-batch verification gates.]
 
-## 6. Worker Prompt Index
+### Worker Prompt Index
 
 [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.]
 
-### Fix Worker Prompts
+**Fix Worker Prompts:**
 
 | 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
+**Regression Test Worker Prompts:**
 
 | 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] |
 
----
+### Batch Schedule
 
-## 7. Fix Batch Schedule
+*Tasks within the same batch have no file overlap and no logical dependency — they may be dispatched in parallel.*
 
-### Batch 1 — Independent P0 Fixes
+#### Batch 1 — Independent P0 Fixes
 
 - **Issues**: FIX-01, FIX-03
-- **Strategy**: Dispatch 2 workers in parallel
+- **Strategy**: Parallel
 - **Gate**:
   - [ ] FIX-01 worker reports success
   - [ ] FIX-03 worker reports success
-  - [ ] Run verification: `[command]`
-
----
+  - [ ] Verification: `[command]` → [expected result]
 
-### Batch 2 — Dependent Fixes
+#### Batch 2 — Dependent Fixes
 
 - **Issues**: FIX-02 → FIX-04 → FIX-05
 - **Strategy**: Sequential (file overlap or logical dependency)
@@ -142,26 +177,25 @@
   - [ ] FIX-02 worker reports success
   - [ ] FIX-04 worker reports success
   - [ ] FIX-05 worker reports success
-  - [ ] Run verification: `[command]`
+  - [ ] Verification: `[command]` → [expected result]
 
----
-
-### Batch N — Regression Test Implementation
+#### Batch 3 — Regression Test Implementation
 
-- **Tasks**: REGTEST-01, REGTEST-02, REGTEST-03, REGTEST-04, REGTEST-05
-- **Strategy**: Parallel dispatch (no file overlap = full parallel; overlap = sub-batches)
+- **Tasks**: REGTEST-01, REGTEST-02, REGTEST-03
+- **Strategy**: Parallel (no file overlap = full parallel; overlap = sub-batches)
 - **Depends on**: All fix batches completed
 - **Gate**:
   - [ ] All REGTEST workers report success
   - [ ] All new regression tests pass
+  - [ ] Logical check: each REGTEST oracle must be "fails on unfixed code, passes after fix" — if a test also passes on unfixed code, it is not a valid regression test
   - [ ] Existing test suite passes (confirm no regression)
 
----
+> If property-based testing is required by the original CHECKLIST.md, implement it alongside the regression tests listed here. Property-based tests serve as additional hardening for business-logic changes.
 
-### Batch Final — Integration
+#### Batch 4 — Final Integration
 
-- **Tasks**: Final test suite, lint, cross-check REPORT.md
-- **Strategy**: Sequential (coordinator handles directly or dispatches a single worker)
+- **Tasks**: Full test suite, lint, cross-check REPORT.md
+- **Strategy**: Sequential
 - **Depends on**: All preceding batches
 - **Gate**:
   - [ ] Full test suite passes: `[command]`
@@ -170,94 +204,32 @@
 
 ---
 
-## 8. Regression Test Inventory
-
-If property-based testing is required by the original CHECKLIST.md, implement it alongside the regression tests listed here. Property-based tests serve as additional hardening for business-logic changes.
-
-- REGTEST-01 → FIX-01: [Unit] [test/unit/foo.test.ts] — GIVEN X WHEN Y THEN Z
-- REGTEST-02 → FIX-02: [Integration] [test/integration/bar.test.ts] — GIVEN A WHEN B THEN C
-- REGTEST-03 → FIX-03: [Unit] [test/unit/baz.test.ts] — GIVEN P WHEN Q THEN R
-
-If there are no entries here, see Section 5 for each fix's regression test design.
-
----
-
-## 9. Verification Checkpoints
-
-### Checkpoint 1 — After fix batches complete (before regression tests)
-- Run: `[command]`
-- Expected: All existing tests pass, all fixes confirmed
+## 4. Final Verification
 
-### Checkpoint 2 — After regression tests are implemented
-- Run: `[command]`
-- Expected: All new regression tests pass, confirming each fix is effective
-- Logical check: Each REGTEST oracle must be "fails on unfixed code, passes after fix" — if a test also passes on the unfixed code, it is not a valid regression test
+[P4: Meta-checks after all batches complete. These verify completeness beyond what per-batch gates already cover.]
 
-### Checkpoint 3 — Final verification
-- Run full test suite: `[command]`
-- Confirm lint passes
-- Cross-check REPORT.md: every issue resolved
+- [ ] Every issue in REPORT.md (P0–P3) has a completed fix
+- [ ] Every fix has a regression test that passes
+- [ ] All worker prompts in Section 3 have been dispatched and returned success
+- [ ] Full test suite passes with no regressions
+- [ ] All changes committed in a single commit
 
 ---
 
-## 10. Error Recovery
+## 5. References
 
-- **If a fix worker fails**: Retry with the worker's existing context (do not create a new one), giving more specific guidance. At most one retry.
-- **If a fix worker fails twice**: Pause the entire flow. Preserve successful results from other workers in the same batch. Report to the user.
-- **If a regression test worker reports failure (test cannot pass)**: Check whether the test code is wrong or the fix is incomplete. If the test code is wrong, continue the worker to fix it. If the fix is incomplete, go back to the corresponding fix worker.
-- **If a regression test passes on the unfixed code**: The test design is invalid — redesign the oracle and dispatch a new worker.
-- **If merge conflicts occur**: The coordinator resolves the conflict, then re-runs the batch gate verification.
-- **If a fix or regression test breaks existing tests**: Pause. Report which test failed and which worker's change caused it.
-
----
-
-## 11. Fix History
-
-<!--
-### Round N — [YYYY-MM-DD]
-- **Issues fixed**: FIX-01, FIX-02, ... (P0:X, P1:X, P2:X, P3:X)
-- **Outcome**: [All resolved / Partial — X issues remaining]
-- **Key notes**: [1-2 sentence summary of important decisions or residual risks]
--->
-
----
-
-## 12. References
+[P5: Reference files for coordinator and workers.]
 
 - **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 `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
-
-- Fix approach conflicts with spec design intent
-- Need to add a new external dependency
-- Worker has failed twice
-- Test regression cannot be quickly diagnosed
-
-### 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
-- Modify spec documents (unless the fix reveals a spec error — report it instead)
-- Start regression tests before all fixes are verified
-- **Defer any REPORT.md issue to a future round** — every issue has a complete fix plan in this FIX.md
+- **Project context files**: [List project context files the fix coordinator may need — e.g., CLAUDE.md, AGENTS.md, project architecture files]
+- **Related documents**: [Paths to source documents — e.g., the paths to REPORT.md, SPEC.md, and DESIGN.md for this spec]
+- **Fix History**:
+  <!--
+  ### Round N — [YYYY-MM-DD]
+  - **Issues fixed**: FIX-01, FIX-02, ... (P0:X, P1:X, P2:X, P3:X)
+  - **Outcome**: [All resolved / Partial — X issues remaining]
+  - **Key notes**: [1-2 sentence summary of important decisions or residual risks]
+  -->

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

@@ -0,0 +1,96 @@
+# Fix Worker Prompt: FIX-{sequence}-{kebab-case-name}
+
+- **Related issue**: [FIX ID from coordinator — e.g., FIX-01]
+
+---
+
+## 1. Mission & Rules
+
+[P1: Goal of this fix and behavioral rules.]
+
+### Mission
+
+[One sentence — which issue to fix and why.]
+
+### Context
+
+[Which review dimension flagged this issue, which spec requirement it relates to.]
+
+### Rules
+
+- Follow the Scope in Section 5 — only modify files listed as Allowed
+- Preserve existing test semantics — do not weaken, skip, or remove existing tests
+- If the fix approach conflicts with the original spec design intent, pause and report to the coordinator
+- 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, root cause analysis.]
+
+### Input Files
+
+- [File path] — [what to read from it]
+- [File path] — [what to read from it]
+
+### Root Cause
+
+[Brief description of the root cause, determined during QA analysis.]
+
+---
+
+## 3. Tasks
+
+[P3: Concrete fix steps. Each entry specifies the exact file path, function or line range, and what to add/delete/modify.]
+
+### [File path] — [what to fix]
+
+1. Open `[file path]`
+2. Locate `[function / class / line range]`
+3. [Add / Modify / Delete] the following:
+   - **Before** (current code): [current code or description]
+   - **After** (fixed code): [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 fix works 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 fix worker"]
+- [file path] — [reason]
+
+### Related Documents
+
+- [path to SPEC.md, DESIGN.md, or relevant files]

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

@@ -0,0 +1,98 @@
+# Regression Test Worker Prompt: REGTEST-{sequence}-{kebab-case-name}
+
+- **Related fix**: FIX-{sequence} — [fix title]
+
+---
+
+## 1. Mission & Rules
+
+[P1: Goal of this regression test and behavioral rules.]
+
+### Mission
+
+[Which fix needs a regression test and why.]
+
+### Context
+
+[What the fix addressed — summary, root cause.]
+
+### Rules
+
+- Only create or modify test files — never modify source code
+- The test must fail on the unfixed code and pass after the fix is applied — this is the core oracle
+- Follow the existing test patterns and style of the reference test files
+- If the test cannot be designed to fail before the fix, report to the coordinator — do not write a weak test
+- Workers are leaf nodes — do not spawn sub-workers
+
+---
+
+## 2. Context
+
+[P2: Files to read before starting, test design.]
+
+### Input Files
+
+- Fix-related files: [path to the fixed code — understand what was changed]
+- Existing test files (as format reference): [path — follow the same style and patterns]
+
+### Test Design
+
+- **Test ID**: REGTEST-{sequence}
+- **Type**: [Unit / Integration / E2E]
+- **Location**: [file path where the test will be written]
+- **Scenario**: GIVEN [precondition] WHEN [trigger] THEN [expected result]
+- **Oracle**: Must fail on unfixed code, must pass after fix
+
+---
+
+## 3. Tasks
+
+[P3: Concrete steps for writing the regression test.]
+
+1. Create the test at `[test file path]`
+   - Write the test according to the Test Design above
+   - Follow the format and naming conventions of [reference test file]
+2. Run the test on the unfixed code — confirm it fails
+3. [If the fix is already applied: temporarily revert the fix, run the test to confirm failure, then restore the fix]
+4. [Additional steps if needed]
+
+### Output
+
+When done, report back to the coordinator:
+- **Test file**: [path]
+- **Test name**: [test name or description]
+- **Oracle confirmed**: [test fails before fix / test passes after fix]
+- **Risks or concerns**: [or "None"]
+
+---
+
+## 4. Verification
+
+[P4: How to verify the regression test is valid.]
+
+1. Run: `[test command for the specific test]` before the fix is applied
+   - Expected: Test fails (confirming the oracle detects the bug)
+2. Run: `[test command for the specific test]` after the fix is applied
+   - Expected: Test passes (proving the fix resolves the issue)
+3. Run: `[relevant subset of the full test suite]`
+   - Expected: All tests pass (no regression to other tests)
+
+---
+
+## 5. Scope & References
+
+[P5: Allowed/forbidden files and related references.]
+
+### Allowed Files
+
+- [test file path] — write the regression test here
+- [reference test file] — use as format reference
+
+### Forbidden Files
+
+- All source code files (`.ts`, `.js`, `.py`, etc.) — the regression test worker must not modify source code
+
+### Related Documents
+
+- [path to FIX_WORKER prompt for the related fix — understand what was fixed]
+- [path to SPEC.md or DESIGN.md — understand the expected behavior]