@laitszkin/apollo-toolkit 5.0.3 → 5.0.4

package/CHANGELOG.md

@@ -2,6 +2,20 @@
 
 All notable changes to this repository are documented in this file.
 
+## [v5.0.4] - 2026-06-07
+
+### Added
+
+- **design skill `references/` folder**: Design phase now populates `<spec_dir>/references/` with external method/API reference documents (name, purpose, required parameters), reducing hallucinated external code during implementation.
+- **`apltk codegraph` as dedicated workflow step**: `spec` and `docs-project` skills now run `apltk codegraph survey` before reading requirements, ensuring BDD boundaries align with real code. `design` uses codegraph survey before architecture design.
+- **Brownfield refactoring assessment**: `design` skill now includes explicit T1–T3 refactoring planning for brownfield changes as a standard workflow step.
+- **Worker prompt separation**: `plan` and `qa` skills now store worker prompts in `plan/*.md` and `fix/*.md` files respectively, keeping coordinator prompts focused on strategy. PROMPT.md/FIX.md Reference sections cite all worker prompt paths and code file paths.
+- **Prompt generation guidance consolidated**: Notes on writing quality worker prompts moved from PROMPT.md/FIX.md templates into `plan`/`qa` SKILL.md, aligning with the optimise-skill principle of behavioral guidance in SKILL.md.
+
+### Changed
+
+- **Self-review renamed to Verification**: `design` and `spec` skills now use "Pre-delivery Verification" with explicit completeness and quality checks, plus code traceability validation.
+
 ## [v5.0.3] - 2026-06-06
 
 ### Added

package/package.json

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

package/skills/design/SKILL.md

@@ -12,9 +12,13 @@ During architecture survey, identify and classify refactoring opportunities by m
 ## Acceptance Criteria
 
 - Three web research passes completed and recorded
+- `apltk codegraph` survey run on affected modules, with findings recorded
+- Brownfield assessment completed: T1–T3 refactoring opportunities identified and dispositioned
 - `docs/plans/<YYYY-MM-DD>/<spec_name>/DESIGN.md` produced, covering: architecture design, external dependencies (with API facts and limits), data persistence, invariants, technical trade-offs, design-time refactoring
 - `docs/plans/<YYYY-MM-DD>/<spec_name>/CHECKLIST.md` produced, covering: behavior-to-test mapping, hardening requirements, test level choices
+- `docs/plans/<YYYY-MM-DD>/<spec_name>/references/` populated with external method/API reference documents (name, purpose, required parameters)
 - Architecture Diff produced using the C4 model hierarchy
+- DESIGN.md and CHECKLIST.md References sections cite all designed code file paths (not just project context files)
 - Design-time refactoring classified by module boundary scope (T1–T3) and dispositioned (refactored / scheduled / deferred with rationale)
 
 ## Workflow
@@ -72,9 +76,42 @@ Verify external dependency compatibility with the repo's existing dependencies:
 
 Output: Recommended tech stack + compatibility report
 
-### 3. Design Architecture → DESIGN.md
+### 3. CodeGraph Survey
 
-Based on the research findings, design the architecture. Use `assets/templates/DESIGN.md`.
+Deeply investigate the repo using `apltk codegraph` before designing.
+
+#### 3a. Survey the Project
+
+Run `apltk codegraph survey --json` to get entry points, function clusters, and cross-boundary edges.
+
+Consult `references/codegraph.md` for detailed flags.
+
+#### 3b. List APIs in Affected Areas
+
+Use `apltk codegraph list-apis` to review the full project API directory in the affected modules — function names, file paths, callers. Understand what existing modules and functions the new feature will interact with.
+
+#### 3c. Code Health Assessment
+
+While reading code via codegraph, actively assess code quality:
+- Identify code smells, dead code, legacy patterns, and unnecessary complexity in the affected modules
+- Classify findings using the T1–T3 framework (see `references/code-smells.md` for patterns to recognize)
+- T1 items (module-internal simplification) are safe to refactor immediately — existing tests validate behavioral preservation
+- T2 and T3 items feed into the target architecture design
+
+### 4. Read Spec and Design Architecture → DESIGN.md
+
+Based on web research (Step 2) and codegraph findings (Step 3), design the architecture. Use `assets/templates/DESIGN.md`.
+
+#### 4a. Brownfield Assessment
+
+If this is a brownfield change (modifying existing code), design a refactoring plan:
+- Identify which existing modules need restructuring to accommodate the new feature
+- Classify refactoring by T1–T3 scopes (see `references/code-smells.md`)
+- T1: Safe to refactor inline — existing unit tests validate behavior
+- T2: Schedule in task decomposition — existing integration tests validate
+- T3: Define migration strategy with dedicated test coverage
+
+#### 4b. Fill DESIGN.md
 
 Transfer the research outputs from Steps 2a-2c into the **Research Summary** section of DESIGN.md (feasibility table, reference patterns table, tech stack compatibility table).
 
@@ -87,17 +124,17 @@ Cover the following sections:
 - **System Invariants**: Architectural constraints that must not be violated, plus violation symptoms
 - **Technical Trade-offs**: Each decision with rejected alternatives and lock-in effects
 - **Design-Time Refactoring**: T1–T3 code health findings classified and dispositioned
-- **References**: List important project context files the LLM will need to understand this design (e.g., `CLAUDE.md`, `AGENTS.md`, architecture atlas files). This reduces the LLM's need to search for relevant files when processing the design document.
+- **References**: List designed code file paths, project context files, and related documents
 
 Use `Req 1`, `Req 2` numbering to reference SPEC.md requirements (matching the SPEC.md template's `Requirement 1`, `Requirement 2`).
 
 **Scale awareness** — Not every section applies at full depth. Adapt based on the change's scope:
 
-- **Interaction Design (Section 3)**: If the change is confined to a single module with no new cross-module coupling, mark this section as `None`. Do not fabricate INT-### entries.
-- **External Dependency deep-dives (Section 4.2)**: For simple utility libraries (e.g., date formatting, UUID generation) with no API quotas, authentication, or failure modes, skip the sub-tables. A one-line entry in Section 4.1 overview suffices.
-- **Target vs Baseline (Section 2.3)**: If the change touches multiple dimensions (new modules, removed modules, ownership shifts, deployment changes), expand to multiple rows. A single-dimension change needs only one row.
-- **System Invariants (Section 6)**: If the change does not modify any architectural constraint, explicitly write `None` with brief justification.
-- **Design-Time Refactoring (Section 8)**: If no code health issues were identified during the architecture survey, write `None`. Do not fabricate findings.
+- **Interaction Design**: If the change is confined to a single module with no new cross-module coupling, mark this section as `None`. Do not fabricate INT-### entries.
+- **External Dependency deep-dives**: For simple utility libraries (e.g., date formatting, UUID generation) with no API quotas, authentication, or failure modes, skip the sub-tables. A one-line entry in the overview suffices.
+- **Target vs Baseline**: If the change touches multiple dimensions (new modules, removed modules, ownership shifts, deployment changes), expand to multiple rows. A single-dimension change needs only one row.
+- **System Invariants**: If the change does not modify any architectural constraint, explicitly write `None` with brief justification.
+- **Design-Time Refactoring**: If no code health issues were identified during the architecture survey, write `None`. Do not fabricate findings.
 
 **Design self-challenge** — Before finalizing the design, step back and ask three questions:
 
@@ -105,18 +142,10 @@ Use `Req 1`, `Req 2` numbering to reference SPEC.md requirements (matching the S
 2. **Is this the simplest viable design?** Have I introduced abstractions, indirections, or intermediate layers that are not justified by the current requirements? Prefer the simplest structure that works.
 3. **Are there rejected alternatives?** For every major architectural decision (module split, dependency choice, communication pattern), if you have not considered and explicitly rejected at least one alternative, you may be settling on the first workable solution rather than the best one.
 
-**Design-time refactoring** — While designing the target architecture, also assess code health in the affected modules:
-
-- **T1 (Module-internal simplification)**: Simplify control flow, remove dead code, inline unnecessary wrappers within a single function or file. Existing unit tests validate behavior — refactor directly.
-- **T2 (Module-internal restructuring)**: Extract shared logic, consolidate state, reorganize files within the same module boundary. Existing integration tests validate behavior — include in the design's task decomposition.
-- **T3 (Module boundary adjustment)**: Changes affecting a module's public API, data contract, or cross-module coupling. Requires dedicated test coverage — define test strategy in CHECKLIST.md.
-
-See `references/code-smells.md` for patterns to identify, and the module-specific reference files for detailed guidance per tier.
-
 **Single spec**: Produce one DESIGN.md for one SPEC.md.
 **Batch spec**: Produce **one** unified DESIGN.md covering the scope of all SPEC.md files in the batch.
 
-### 4. Define Verification Strategy → CHECKLIST.md
+### 5. Define Verification Strategy → CHECKLIST.md
 
 Use the `test-case-strategy` skill to design the verification strategy.
 Use `assets/templates/CHECKLIST.md`.
@@ -128,7 +157,7 @@ Cover the following sections:
 - **Hardening Requirements**: Regression tests, drift checks, property-based tests, edge cases, authorization checks
 - **E2E / Integration Decisions**: Per flow, choose the appropriate test level with rationale
 - **Design-Time Refactoring (T3)**: If T3 refactoring is planned, define its test coverage requirements here
-- **References**: List important project context files the LLM will need (e.g., `CLAUDE.md`, `AGENTS.md`).
+- **References**: List designed code file paths, project context files, and related documents
 
 **Mandatory test coverage** (applies when the SPEC.md describes changes other than pure documentation or pure test changes):
 
@@ -141,38 +170,24 @@ Risk definitions: **Medium risk** = paths involving I/O, external dependencies,
 **Single spec**: Produce one CHECKLIST.md for one SPEC.md.
 **Batch spec**: Produce **one** unified CHECKLIST.md covering the behavioral requirements of all SPEC.md files in the batch.
 
-### 5. Generate Architecture Diff
+### 6. Generate Architecture Diff
 
 Use the `apltk architecture` CLI tool to generate the Architecture Diff, following the C4 model hierarchy.
 
-#### 5a. Survey the project with `apltk codegraph survey`
-
-**Prerequisite** before any diff work. Survey the project code to establish a code-level baseline for comparison with the atlas.
-
-Run `apltk codegraph survey --json` to get entry points, function clusters, and cross-boundary edges.
-
-Consult `references/codegraph.md` for detailed flags.
-
-#### 5b. Read the Existing Architecture
+#### 6a. Read the Existing Architecture
 
 Read the project's existing architecture files (`resources/project-architecture/atlas/atlas.index.yaml` + the affected feature YAML files).
 Do not read unrelated features or modules — maintain context economy.
 
 If no existing architecture exists, skip the baseline comparison and start defining the boundary from System Context level.
 
-**Code health assessment** — While reading code to measure the baseline, actively assess code quality:
-- Identify code smells, dead code, legacy patterns, and unnecessary complexity in the affected modules
-- Classify findings using the T1–T3 framework (see `references/code-smells.md` for patterns to recognize)
-- T1 items (module-internal simplification) are safe to refactor immediately — existing tests validate behavioral preservation
-- T2 and T3 items feed into the target architecture design in Step 3
-
-#### 5c. Measure Baseline Drift
+#### 6b. Measure Baseline Drift
 
 Compare the existing architecture diagram against the current code to assess its reliability:
 - If the baseline atlas differs significantly from the code (> 20% entries inconsistent), flag the risk in the architecture diff
 - If the baseline atlas is reliable, the diff can be layered directly on top of it
 
-#### 5d. Define the Diff by C4 Level
+#### 6c. Define the Diff by C4 Level
 
 1. **System Context**: Define external actors, system boundaries, cross-system edges
 2. **Container level** (features): Define new or modified features and the edges between them
@@ -181,62 +196,85 @@ Compare the existing architecture diagram against the current code to assess its
 
 C4 level mapping: System Context → system boundary, Container → feature, Component → submodule, Code → function (selective). See `references/definition.md` for full definitions.
 
-#### 5e. Evidence Tracing
+#### 6d. Evidence Tracing
 
 Each component should link to:
 - The requirement number from SPEC.md (requirement → module)
 - The technical decision from research findings (decision → dependency choice)
 
-#### 5f. Generate the Diff and Validate
+#### 6e. Generate the Diff and Validate
 
 Two alternative workflows — use the **Classic flow** when `codegraph` is not installed, or the **CodeGraph-integrated flow** when it is available.
 
 **Classic flow** (manual):
 Generate and validate the architecture diff using `apltk architecture` commands. Confirm validation passes, then produce a visual comparison. See `references/architecture.md` for all CLI flags.
 
-**New flow (CodeGraph-integrated):**
-
-1. **Survey the existing API landscape** — Use `apltk codegraph list-apis` to review the full project API directory (function names, file paths, callers). Understand what existing modules and functions your new feature will interact with.
+**CodeGraph-integrated flow:**
 
-2. **Fill the proposal skeleton** — Based on your design decisions from steps 5b–5e, fill in the `proposal.yaml` file generated by `apltk architecture template`. Define the feature, its submodules, their functions, and cross-feature edges.
+1. **Fill the proposal skeleton** — Based on design decisions from steps 6a–6d, fill in the `proposal.yaml` file generated by `apltk architecture template`. Define the feature, its submodules, their functions, and cross-feature edges.
 
-3. **Apply and verify** — Apply the mutations and verify correctness:
+2. **Apply and verify** — Apply the mutations and verify correctness:
    - `apltk architecture apply` processes all mutations with undo protection
    - `apltk codegraph verify` confirms every symbol and edge reference exists in actual code
 
-4. **Render diff** (optional) — `apltk architecture diff --spec <spec_dir>` for visual confirmation.
+3. **Render diff** (optional) — `apltk architecture diff --spec <spec_dir>` for visual confirmation.
 
 See `references/architecture.md` for exact CLI flags and mutation commands.
 
 **Single spec**: Produce one Architecture Diff for one SPEC.md.
 **Batch spec**: Produce **one** unified Architecture Diff covering all SPEC.md files in the batch.
 
-### 6. Pre-delivery Self-Review
+### 7. Populate references/ Folder
+
+Under `<spec_dir>/references/` (single spec) or `<batch_dir>/references/` (batch spec), create reference documents for every external method and API used in the design:
+
+#### External Methods
+
+For each external method referenced in the design, document:
+- **Method name**: The method or function name
+- **Purpose**: What it does, why it is needed
+- **Required parameters**: Input parameters with types and descriptions
+- **Source**: Where this method is documented (URL or code path)
+
+#### External APIs
+
+For each external API referenced in the design, document:
+- **API name**: The API or service name
+- **Purpose**: What it does, why it is needed
+- **Required parameters**: Request payload structure, query parameters, headers
+- **Authentication**: How to authenticate (key location, scope)
+- **Rate limits / quotas**: Documented limits
+
+**Why this step exists**: Explicit external method/API reference documentation reduces the chance of hallucinated code during implementation. Workers and coordinators can consult these files instead of guessing API shapes.
+
+### 8. Pre-delivery Verification
 
 Before delivering, run two passes — completeness then quality.
 
-**Completeness checks** (documentation integrity):
+#### Completeness checks (documentation integrity)
 
 - Research results are recorded in DESIGN.md as evidence for technical decisions
 - Every architecture decision has a trade-off record (rejected alternatives + lock-in effects)
 - External dependency API facts are traceable to official documentation
 - CHECKLIST.md completely covers all BDD requirements from SPEC.md
 - Architecture Diff covers the full change scope
-- Design-time refactoring is documented in DESIGN.md Section 8, with T1–T3 findings classified and dispositioned (refactored / scheduled / deferred with rationale)
+- Design-time refactoring is documented in DESIGN.md with T1–T3 findings classified and dispositioned
+- `references/` folder exists with external method and API reference documents
+- DESIGN.md and CHECKLIST.md References sections cite designed code file paths
 
-**Design quality checks** (architectural soundness):
+#### Design quality checks (architectural soundness)
 
 - **Requirement traceability**: Can every BDD behavior from SPEC.md be traced to a module, interaction, data flow, or invariant in this design?
-- **Internal consistency**: Do the modules listed in Section 2 appear as callers or callees in Section 3? Do the dependencies in Section 4 correspond to module responsibilities in Section 2?
+- **Internal consistency**: Do the modules listed in the architecture appear as callers or callees in the interaction design? Do the dependencies correspond to module responsibilities?
 - **Design simplicity**: Is this the simplest design that satisfies all requirements? Could any module, abstraction, or dependency be removed without breaking functionality?
-- **Risk transparency**: Are all feasibility risks, compatibility concerns, or uncertain technical points from Step 2 either addressed in the design or explicitly documented as accepted risks?
-- **Refactoring disposition**: Are all identified code health findings accounted for — either refactored, scheduled in the task plan, or explicitly deferred with rationale? Unaddressed T1/T2 findings represent missed opportunities to reduce technical debt at the cheapest possible time.
+- **Risk transparency**: Are all feasibility risks, compatibility concerns, or uncertain technical points either addressed in the design or explicitly documented as accepted risks?
+- **Refactoring disposition**: Are all identified code health findings accounted for — either refactored, scheduled in the task plan, or explicitly deferred with rationale?
 
 ## Examples
 
-- "SPEC.md defines a real-time messaging feature" → Research WebSocket vs SSE vs Polling → Confirm compatibility → Choose SSE → Design architecture → Produce DESIGN.md + CHECKLIST.md + Architecture Diff → During code survey, identify legacy socket wrapper (T2) → schedule extraction in task plan
-- "SPEC.md requires CSV export, repo has no CSV library" → Research Node.js CSV libraries (json2csv vs csv-writer vs papaparse) → Confirm compatibility → Choose the lightest option → Design export flow architecture
-- "Batch spec: docs/plans/2026-05-29/auth-redesign/ with 3 SPEC.md files (login, permissions, 2FA)" → Read all 3 SPEC.md files → Unified research → Produce **one** DESIGN.md + CHECKLIST.md + Architecture Diff → Identify dead auth middleware during survey (T1) → remove and verify with existing tests
+- "SPEC.md defines a real-time messaging feature" → Research WebSocket vs SSE vs Polling → CodeGraph survey to find existing socket infrastructure → Confirm compatibility → Choose SSE → Design architecture → Produce DESIGN.md + CHECKLIST.md + Architecture Diff → During code survey, identify legacy socket wrapper (T2) → schedule extraction in task plan → Populate references/ with external API docs
+- "SPEC.md requires CSV export, repo has no CSV library" → Research Node.js CSV libraries (json2csv vs csv-writer vs papaparse) → CodeGraph survey to understand export module boundaries → Confirm compatibility → Choose the lightest option → Design export flow architecture → Document CSV library API in references/
+- "Batch spec: docs/plans/2026-05-29/auth-redesign/ with 3 SPEC.md files (login, permissions, 2FA)" → Read all 3 SPEC.md files → Unified research → CodeGraph survey of auth modules → Unified DESIGN.md + CHECKLIST.md + Architecture Diff → Brownfield assessment: identify dead auth middleware during survey (T1) → remove and verify with existing tests → Populate references/ with auth API docs
 
 ## References
 

package/skills/design/assets/templates/CHECKLIST.md

@@ -42,5 +42,6 @@ Map each BDD requirement from SPEC.md to one or more tests:
 
 ## References
 
+- **Designed code file paths**: [List code file paths that this design touches or references — e.g., `src/auth/login.ts`, `src/api/routes.ts`]
 - **Project context files**: [List important project files the LLM will need — e.g., `CLAUDE.md`, `AGENTS.md`, `resources/project-architecture/**`]
 - **Related documents**: [Links to related SPEC.md, DESIGN.md, or external documentation]

package/skills/design/assets/templates/DESIGN.md

@@ -156,5 +156,6 @@ If none, write **None**.
 
 ## 9. References
 
+- **Designed code file paths**: [List code file paths that this design touches or references — e.g., `src/auth/login.ts`, `src/api/routes.ts`]
 - **Project context files**: [List important project files the LLM will need — e.g., `CLAUDE.md`, `AGENTS.md`, `resources/project-architecture/**`]
 - **Related documents**: [Links to related SPEC.md, other design docs, or external documentation]

package/skills/docs-project/SKILL.md

@@ -13,6 +13,8 @@ description: >-
 
 ## 驗收條件
 
+- 使用 `apltk codegraph` 完成 repo 深度調查，產出模組邊界與 API 目錄分析
+- 使用 subagents 閱讀關鍵程式碼片段，確保文檔記述可驗證
 - repo 的所有細節被仔細閱讀，並轉化為標準化的 `docs/features/`、`docs/architecture/`、`docs/principles/` 文檔
 - 每條文檔記述皆有可追溯的來源證據（檔案路徑 + 行號區間）；無法證明的內容標記為 `[INFERRED]`
 - `AGENTS.md` / `CLAUDE.md` 已被同步更新
@@ -20,21 +22,36 @@ description: >-
 
 ## 工作流程
 
-### 1. 建立對 repo 的基線認知
+### 1. 使用 CodeGraph 深入調查 Repo
 
-閱讀項目現有文檔，建立對 repo 的基線認知，制定後續閱讀策略。
+在開始文檔工作前，先用 `apltk codegraph` 建立對 repo 的深度理解。
 
-### 2. 比對 repo 及項目文檔
+1. 執行 `apltk codegraph survey --json` 取得專案的 entry points、function clusters、cross-boundary edges
+2. 使用 `apltk codegraph list-apis` 檢視完整 API 目錄（函式名稱、檔案路徑、呼叫者）
+3. 對關鍵模組使用 `apltk codegraph explore` 深入了解內部結構
+
+將調查結果記錄為結構化摘要，供後續文檔撰寫使用。
+
+### 2. 建立對 Repo 的基線認知
+
+閱讀項目現有文檔，並結合 CodeGraph 調查結果，建立對 repo 的基線認知，制定後續閱讀策略。
+
+### 3. 比對 Repo 及項目文檔
 
 按照上一步建立的閱讀策略，通過並行調度 subagents 全面搜索整個 repo，驗證並確保現有項目文檔的描述正確、無遺漏。
 
-### 3. 制定文檔更新策略
+使用 subagents 深入閱讀關鍵程式碼片段：
+- 每個 subagent 負責一個模組或檔案群組
+- Subagent 閱讀原始碼後回報：模組職責、關鍵函式、資料流程、外部整合點
+- 將 subagent 發現與現有文檔比對，標記差異
+
+### 4. 制定文檔更新策略
 
 根據上一步發現的文檔遺漏或脫節之處，制定文檔更新策略。
 閱讀模板文檔；使用模板規定的格式重寫所有項目文檔。
 移除舊有說明文檔（必要文檔如 `CHANGELOG.md`、`CONTRIBUTION.md` 除外）。
 
-### 4. 後續維護指引
+### 5. 後續維護指引
 
 完成初始文檔後，在 `docs/README.md` 中記錄以下維護指引：
 
@@ -44,4 +61,4 @@ description: >-
 - **定期 drift detection**（建議）：定期（每月或每季）比對文檔與實際程式碼，確認無重大偏離。發現 drift 時只修補受影響章節，不全面重寫。
 
 ## 參考資料
-- `assets/templates/standardized-docs-template.md` - 三類文檔的目標結構、分類規則與清理檢查表。
+- `assets/templates/standardized-docs-template.md` - 三類文檔的目標結構、分類規則與清理檢查表。

package/skills/fix/SKILL.md

@@ -59,7 +59,7 @@ Report to the user:
 
 ## Examples
 
-- FIX.md defines Batch 1 with 2 parallel fixes → Coordinator extracts FIX-01 and FIX-03 worker prompts from Section 6 → Dispatches 2 workers → Waits → Digests results → Runs gate verification → Proceeds to Batch 2
+- FIX.md defines Batch 1 with 2 parallel fixes → Coordinator reads FIX-01 and FIX-03 worker prompts from `fix/` files listed in Section 6 (Worker Prompt Index) → Dispatches 2 workers → Waits → Digests results → Runs gate verification → Proceeds to Batch 2
 - Worker FIX-02 reports failure → Coordinator retries the worker with more specific guidance → Second attempt still fails → Pauses, preserves FIX-01's success, notifies the user
 - All batches complete → Regression tests pass → Commit → Cross-check REPORT.md → Report
 

package/skills/implement/SKILL.md

@@ -56,7 +56,7 @@ Report to the user:
 
 ## Examples
 
-- PROMPT.md defines Batch 1 with 2 parallel tasks → Coordinator extracts T1.1 and T1.2 worker prompts from Section 6 → Dispatches 2 workers → Waits for both → Digests results → Runs gate verification → Proceeds to Batch 2
+- PROMPT.md defines Batch 1 with 2 parallel tasks → Coordinator reads T1.1 and T1.2 worker prompts from `plan/` files listed in Section 6 (Worker Prompt Index) → Dispatches 2 workers → Waits for both → Digests results → Runs gate verification → Proceeds to Batch 2
 - Worker T2.1 reports failure → Coordinator retries the worker with more specific guidance → Second attempt still fails → Pauses, preserves T2.2's success, notifies the user
 - Merge conflict detected when combining worker results → Coordinator resolves the conflict markers → Re-runs batch gate verification → Proceeds
 

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,7 +95,9 @@ 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:
 
@@ -102,11 +111,11 @@ Each worker prompt must include:
 ## 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**: 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
+**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
 
@@ -146,13 +155,13 @@ Use `assets/templates/PROMPT.md`. Fill each section according to the table below
 | 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. References | Important project context files (CLAUDE.md, AGENTS.md, architecture atlas, codegraph index) — reduces LLM search overhead |
-| 6. Task Units | Step 3 (task decomposition) + Step 4 (dependency analysis) |
-| 7. Worker Prompt Library | Step 6 — one entry per dispatchable task |
-| 8. Batch Schedule | Step 7 (batch schedule) |
-| 9. Verification Checkpoints | CHECKLIST.md: behavior-to-test mapping (CL-###), hardening requirements, test execution commands |
-| 10. Error Recovery | Fixed template — populate spec-specific test commands from CHECKLIST.md |
-| 11. Boundaries | Fixed template + spec-specific rules (including worktree cleanup after each batch) |
+| 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) |
 
 ### 11. Pre-delivery Self-Review
 
@@ -160,31 +169,34 @@ Before delivering PROMPT.md, verify all of the following.
 
 **Worker prompt quality:**
 
-- Every worker prompt in Section 7 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:**
 
-- Every BDD requirement from SPEC.md is addressed by at least one task in Section 6. 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 5. 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 9.
+- Every hardening requirement from CHECKLIST.md appears in Section 8.
 
 **Structural consistency:**
 
-- Each task's Depends on field in Section 6 matches the batch ordering in Section 8. No task scheduled in a batch before its dependencies are met.
-- Every task listed in Section 8 (Batch Schedule) has a worker prompt in Section 7 — unless it is explicitly marked as coordinator-handled.
-- No orphaned tasks (a task listed in Section 6 that never appears in any batch), no missing dependencies (a Depends on field referencing a task ID that does not exist).
+- 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.
 
-### 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

@@ -15,7 +15,7 @@
 ### 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 6)
 - 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
@@ -74,14 +74,7 @@
 
 ---
 
-## 5. References
-
-- **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]
-
----
-
-## 6. Task Units
+## 5. Task Units
 
 [Each task is an atomic work unit. Task ID format: `T{batch}.{sequence}`.]
 
@@ -91,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]`
@@ -107,53 +92,20 @@
 
 ---
 
-## 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.]
+## 6. Worker Prompt Index
 
-### T{batch}.{sequence}: [Task name]
+[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.]
 
-```
-## 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]
-
-## 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]
-
-## 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.]
 
 ---
 
-## 8. Batch Schedule
+## 7. 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.]
 
@@ -190,7 +142,7 @@ On completion, report:
 
 ---
 
-## 9. Verification Checkpoints
+## 8. Verification Checkpoints
 
 ### Per-batch
 
@@ -213,7 +165,7 @@ On completion, report:
 
 ---
 
-## 10. Error Recovery
+## 9. Error Recovery
 
 | Scenario | Response |
 |---|---|
@@ -225,12 +177,12 @@ On completion, report:
 
 ---
 
-## 11. Boundaries
+## 10. Boundaries
 
 ### ALWAYS
 
 - Run gate verification immediately after every batch
-- Extract worker prompts verbatim from Section 7 — 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.
@@ -252,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:
 
@@ -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,24 +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. References | Important project context files (CLAUDE.md, AGENTS.md, architecture atlas, codegraph index) — reduces LLM search overhead |
+| 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. Produce FIX.md
+### 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.
+
+### 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. [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]
+[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.]
 
-## 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
-- 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] |
 
 ---
 
@@ -313,6 +224,10 @@ If there are no entries here, see Section 5 for each fix's regression test desig
 
 ## 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]
 
@@ -323,7 +238,7 @@ If there are no entries here, see Section 5 for each fix's regression test desig
 ### 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

package/skills/spec/SKILL.md

@@ -17,33 +17,46 @@ Execution methodology (task breakdown, coordination routing) belongs to the `pla
 
 - SPEC.md follows the template format strictly
 - SPEC.md includes: clear business goal, scope (In/Out), BDD behaviors, error and edge cases, clarification questions
+- SPEC.md References section cites key code file paths affected by the requirements
 - High-uncertainty requirements are marked with Uncertainty Level and reflected in Clarification Questions
-- For non-greenfield repos: subagent repo research is complete, and every requirement's boundary is calibrated against the actual code
-- Single spec generated at `docs/plans/<YYYY-MM-DD>/<spec_name>/SPEC.md` or batch spec generated at `docs/plans/<YYYY-MM-DD>/<batch-name>/<spec_name>/SPEC.md`.
+- For non-greenfield repos: `apltk codegraph` survey completed, subagent repo research complete, and every requirement's boundary calibrated against the actual code
+- Single spec generated at `docs/plans/<YYYY-MM-DD>/<spec_name>/SPEC.md` or batch spec generated at `docs/plans/<YYYY-MM-DD>/<batch-name>/<spec_name>/SPEC.md`
 
 ## Workflow
 
-### 1. Understand Requirements and Research the Repo
+### 1. Survey the Repo with CodeGraph
 
-Analyze the user's requirements from the PROPOSAL.md.
+Before reading requirements, use `apltk codegraph` to deeply understand the repo.
+
+**Greenfield repo (no existing code)**: Skip this step. Proceed to Step 2.
+
+**Non-greenfield repo**:
+
+1. Run `apltk codegraph survey --json` to get entry points, function clusters, and cross-boundary edges across the project
+2. Use `apltk codegraph list-apis` to review API directory — function names, file paths, callers — in modules potentially affected by the requirements
+3. Use `apltk codegraph explore` or `apltk codegraph search` to dig into specific areas of interest
 
-**Greenfield repo (no existing code)**: Skip repo research. Proceed to Step 2.
+Consult `references/codegraph.md` for detailed flags.
+
+**Purpose of this step**: Establish code-level understanding of module boundaries, existing APIs, and data structures BEFORE reading requirements. This ensures every BDD requirement is scoped correctly against real code.
+
+### 2. Read PROPOSAL.md and Understand Requirements
+
+Analyze the user's requirements from the PROPOSAL.md.
 
-**Non-greenfield repo**: Research the repo to ensure SPEC.md aligns with actual code.
+**Bridge from Step 1**: Compare codegraph findings against PROPOSAL.md. If the actual code contradicts or constrains what PROPOSAL.md describes, note these calibrations explicitly — they represent the core value the spec skill adds over simple template filling.
 
-Research method:
-- Dispatch multiple subagents in parallel to deeply investigate:
-  - Affected modules and their responsibility boundaries
-  - Existing data structures and persistence patterns
-  - Existing API contracts and call relationships
-  - Existing features that overlap or conflict with the requirements
-- Document findings for the next step
+For complex repos, dispatch multiple subagents in parallel to deeply investigate:
+- Affected modules and their responsibility boundaries
+- Existing data structures and persistence patterns
+- Existing API contracts and call relationships
+- Existing features that overlap or conflict with the requirements
 
-**Bridge to Step 2**: Compare research findings against PROPOSAL.md. If the actual code contradicts or constrains what PROPOSAL.md describes, adjust the requirement boundaries accordingly. Note these calibrations explicitly — they represent the core value the spec skill adds over simple template filling.
+Document findings for the next step.
 
-### 2. Refine, Combine, Split Requirements into BDD
+### 3. Refine, Combine, Split Requirements into BDD
 
-Transform requirements into clearly-bounded BDD business requirements (GIVEN/WHEN/THEN). Use your research findings from Step 1 to correctly scope each requirement.
+Transform requirements into clearly-bounded BDD business requirements (GIVEN/WHEN/THEN). Use your codegraph findings from Step 1 and research from Step 2 to correctly scope each requirement.
 
 Process:
 - **Refine**: Convert vague descriptions into precise BDD behavior statements
@@ -78,7 +91,7 @@ Define:
 
 If a requirement remains unclear after research and it affects scope definition, record it and wait for the user's answer before proceeding.
 
-### 3. Generate SPEC.md
+### 4. Generate SPEC.md
 
 Generate SPEC.md using the template at `assets/templates/SPEC.md`.
 
@@ -91,12 +104,12 @@ Generate SPEC.md using the template at `assets/templates/SPEC.md`.
 
 2. Fill in each section of the generated template:
    - **Goal** → One sentence from the PROPOSAL.md's Problem Statement and your research context. State the business goal, not the implementation.
-   - **Scope (In/Out)** → Directly from Step 2. Be precise: ambiguous boundaries cause scope creep.
-   - **Functional Behaviors** → One BDD block per requirement from Step 2.
+   - **Scope (In/Out)** → Directly from Step 3. Be precise: ambiguous boundaries cause scope creep.
+   - **Functional Behaviors** → One BDD block per requirement from Step 3.
    - **Uncertainty Level** → Per requirement, mark Known or Exploratory.
-   - **Error and Edge Cases** → List specific cases. Free-form list; no fixed categories needed in the template (the five categories from Step 2 guide your thinking, not the output format).
+   - **Error and Edge Cases** → List specific cases. Free-form list; no fixed categories needed in the template (the five categories from Step 3 guide your thinking, not the output format).
    - **Clarification Questions** → List questions for the user. Must be populated when any requirement is Exploratory. Omit only if all requirements are fully clear.
-   - **References** → List important project context files the LLM will need (e.g., `CLAUDE.md`, `AGENTS.md`, `resources/project-architecture/**`), plus official docs and related code files for traceability.
+   - **References** → Cite key code file paths affected by the requirements, plus project context files and official docs. The code file paths serve as traceability anchors linking requirements to actual code.
 
    **BDD writing guidelines**:
    - **GIVEN** states the precondition and actor role
@@ -108,22 +121,24 @@ Generate SPEC.md using the template at `assets/templates/SPEC.md`.
 
 3. If creating a batch spec, repeat the template-filling process for each group of requirements, producing one SPEC.md per group.
 
-### 4. Pre-delivery Self-Review
+### 5. Pre-delivery Verification
 
 Before delivering, verify all of the following. Fix any issues found before proceeding.
 
 - **BDD verifiability**: Every requirement has a clear verification condition — THEN is observable and specific, not vague or qualitative
 - **Scope clarity**: In Scope and Out of Scope are unambiguous and do not overlap
-- **Error case completeness**: All five categories from Step 2 are substantively covered (individual cases, not category names)
+- **Error case completeness**: All five categories from Step 3 are substantively covered (individual cases, not category names)
 - **Uncertainty reflected**: High-uncertainty requirements are marked Exploratory AND mentioned in Clarification Questions
 - **Internal consistency**: No contradictions or overlaps between requirements
+- **Code traceability**: References section cites specific code file paths that each requirement maps to
+- **CodeGraph data used**: Boundary scoping decisions reference codegraph findings (what exists vs what needs to be built)
 
 Only deliver SPEC.md to the user after passing self-review.
 
 ## Examples
 
-- "Build a web-based Texas Hold'em game" → Research existing code → 4 BDD items (deal, bet, judge, chips). ≤5, single SPEC.md.
-- "Rewrite the user system: register, login, permissions, password reset, 2FA, session management" → Research existing auth code → 6 BDD items. >5, batch spec: Auth spec (register, login, password reset — 3 items) and Security spec (permissions, 2FA, sessions — 3 items).
+- "Build a web-based Texas Hold'em game" → CodeGraph survey to check for existing game engine → 4 BDD items (deal, bet, judge, chips). ≤5, single SPEC.md. → References cite game engine code paths
+- "Rewrite the user system: register, login, permissions, password reset, 2FA, session management" → CodeGraph survey of existing auth modules → 6 BDD items. >5, batch spec: Auth spec (register, login, password reset — 3 items) and Security spec (permissions, 2FA, sessions — 3 items). → References cite auth module code paths
 
 ## References
 

package/skills/spec/assets/templates/SPEC.md

@@ -44,7 +44,9 @@
 
 ## References
 
+- **Key code file paths** (affected by this spec):
+  - [File path — e.g., `src/auth/login.ts`]
 - Official docs:
   - [Link or document]
-- Related code files:
-  - [File path]
+- Related project context files:
+  - [File path — e.g., `CLAUDE.md`, `AGENTS.md`]