@laitszkin/apollo-toolkit 5.0.3 → 5.0.5

package/CHANGELOG.md

@@ -2,6 +2,29 @@
 
 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
+
+- **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.5",
   "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
 
@@ -53,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
 
@@ -78,35 +85,35 @@ 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)
 
-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:
+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:**
-- **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.
 
@@ -114,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)
 
@@ -132,7 +139,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
 
@@ -142,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. 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) |
+| 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
 
@@ -160,32 +161,36 @@ 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 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 9.
+- 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 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 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
+### 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
 
-- `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)