@laitszkin/apollo-toolkit 5.0.2 → 5.0.3

package/CHANGELOG.md

@@ -2,6 +2,17 @@
 
 All notable changes to this repository are documented in this file.
 
+## [v5.0.3] - 2026-06-06
+
+### Added
+
+- **codegraph integration across skills**: `init-project-html`, `update-project-html`, and `design` now run `apltk codegraph survey` as a prerequisite before architecture work. `commit` and `version-release` run `apltk codegraph sync` to keep the code graph index in sync after code changes.
+- **References section in deliverable templates**: All planner deliverables (SPEC.md, DESIGN.md, CHECKLIST.md, PROMPT.md, REPORT.md, FIX.md) now include a References section populated with important project context files, reducing LLM search overhead.
+- **Branch-aware version release**: `version-release` now detects non-default branches and follows a merge workflow (commit → merge to default → release → sync back).
+- **maintain-project-constraints**: Generated CLAUDE.md/AGENTS.md now include `apltk codegraph` CLI commands and require codegraph investigation before starting work.
+- **Worker prompt specificity**: `plan` and `qa` skill worker prompts now require exact file paths, function/line ranges, and specific change descriptions to reduce worker drift.
+- **Worktree cleanup rule**: `plan` and `qa` PROMPT.md/FIX.md templates include an ALWAYS rule to clean up temporary worktrees after each batch.
+
 ## [v5.0.2] - 2026-06-06
 
 ### Fixed

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@laitszkin/apollo-toolkit",
-  "version": "5.0.2",
+  "version": "5.0.3",
   "description": "Apollo Toolkit npm installer for managed skill copying across Codex, OpenClaw, and Trae.",
   "license": "MIT",
   "author": "LaiTszKin",
@@ -59,4 +59,4 @@
     "@types/node": "^25.9.1",
     "typescript": "^6.0.3"
   }
-}
+}

package/skills/commit/SKILL.md

@@ -34,7 +34,12 @@ description: 提交指引與提交前的必要品控閘門。將變更提交到
 
 若存在代碼變更，使用 `update-project-html` 檢查並更新項目架構圖。
 
-### 5. 提交及推送變更
+### 5. 同步代碼圖索引
+
+若存在代碼變更，執行 `apltk codegraph sync` 確保代碼圖與實際代碼同步。
+若 `CLAUDE.md` 或 `AGENTS.md` 缺少 `apltk codegraph` 的引用，必須添加。
+
+### 6. 提交及推送變更
 
 依使用者的 staging 邊界建立 commit。
 提交訊息須遵循 `references/commit-messages.md`。

package/skills/design/SKILL.md

@@ -87,6 +87,7 @@ 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.
 
 Use `Req 1`, `Req 2` numbering to reference SPEC.md requirements (matching the SPEC.md template's `Requirement 1`, `Requirement 2`).
 
@@ -127,6 +128,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`).
 
 **Mandatory test coverage** (applies when the SPEC.md describes changes other than pure documentation or pure test changes):
 
@@ -143,7 +145,15 @@ Risk definitions: **Medium risk** = paths involving I/O, external dependencies,
 
 Use the `apltk architecture` CLI tool to generate the Architecture Diff, following the C4 model hierarchy.
 
-#### 5a. Read the Existing Architecture
+#### 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
 
 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.
@@ -156,13 +166,13 @@ If no existing architecture exists, skip the baseline comparison and start defin
 - 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
 
-#### 5b. Measure Baseline Drift
+#### 5c. 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
 
-#### 5c. Define the Diff by C4 Level
+#### 5d. 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
@@ -171,13 +181,13 @@ 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.
 
-#### 5d. Evidence Tracing
+#### 5e. Evidence Tracing
 
 Each component should link to:
 - The requirement number from SPEC.md (requirement → module)
 - The technical decision from research findings (decision → dependency choice)
 
-#### 5e. Generate the Diff and Validate
+#### 5f. 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.
 
@@ -188,7 +198,7 @@ Generate and validate the architecture diff using `apltk architecture` commands.
 
 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.
 
-2. **Fill the proposal skeleton** — Based on your design decisions from steps 5a–5d, fill in the `proposal.yaml` file generated by `apltk architecture template`. Define the feature, its submodules, their functions, and cross-feature edges.
+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.
 
 3. **Apply and verify** — Apply the mutations and verify correctness:
    - `apltk architecture apply` processes all mutations with undo protection
@@ -233,6 +243,7 @@ Before delivering, run two passes — completeness then quality.
 - `assets/templates/DESIGN.md` — DESIGN.md template
 - `assets/templates/CHECKLIST.md` — CHECKLIST.md template
 - `references/architecture.md` — `apltk architecture` CLI reference (all mutation commands)
+- `references/codegraph.md` — `apltk codegraph` CLI reference (consult for subcommand flags)
 - `references/definition.md` — C4 model level definitions
 - `references/code-smells.md` — Common code smell patterns to spot during architecture survey
 - `references/module-internal-simplification.md` — T1: module-internal simplification patterns

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

@@ -37,3 +37,10 @@ Map each BDD requirement from SPEC.md to one or more tests:
 | Flow / Risk | Test Level | Rationale |
 |---|---|---|
 | [Flow description] | [E2E / Integration / Existing coverage / N/A] | [why] |
+
+---
+
+## References
+
+- **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

@@ -151,3 +151,10 @@ Code health findings identified during architecture survey, classified by module
 | […] | […] | […] | […] | […] |
 
 If none, write **None**.
+
+---
+
+## 9. References
+
+- **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/design/references/codegraph.md

@@ -0,0 +1,41 @@
+# apltk codegraph — Code Intelligence CLI Reference
+
+## Purpose
+Parse source code into a knowledge graph of symbols (functions, classes) and relationships (call edges), backed by a local SQLite database with FTS5 full-text search. Powered by @colbymchenry/codegraph (tree-sitter-backed code knowledge graph engine).
+
+## Usage
+```
+apltk codegraph <subcommand> [options]
+```
+
+## Subcommands
+
+### Lifecycle
+
+| Subcommand | Description | Key Flags |
+|------------|-------------|-----------|
+| `init` | Initialize CodeGraph for the project | `--index` (run initial indexing immediately), `--json` |
+| `sync` | Sync index with current file state (incremental) | `--json` |
+| `status` | Show index statistics (files, nodes, edges, languages) | `--json` |
+
+### Discovery
+
+| Subcommand | Description | Key Flags |
+|------------|-------------|-----------|
+| `search <query>` | Search code graph for symbols via FTS5 | `--limit N` (default 20, max 100), `--json` |
+| `explore <query>` | Deep-dive on a symbol — callers, callees, source | `--feature <name>`, `--json` |
+| `survey [dir]` | Scan directory, suggest submodule groupings and edges | `--feature <name>`, `--json` |
+| `list-apis [path]` | List public APIs in project or sub-path | `--all` (include internal symbols), `--json` |
+
+### Validation
+
+| Subcommand | Description | Key Flags |
+|------------|-------------|-----------|
+| `verify --spec <dir>` | Verify a spec overlay against actual code | `--json` |
+
+## Common Workflows
+
+- **Before atlas work**: `apltk codegraph init --index` (first time), then `apltk codegraph survey --json`
+- **After code changes**: `apltk codegraph sync` to keep index current
+- **Understanding a symbol**: `apltk codegraph explore <name>` to see callers and callees
+- **Searching code**: `apltk codegraph search <query> --json --limit 30`

package/skills/init-project-html/SKILL.md

@@ -51,24 +51,20 @@ At load time, check the project state to select the correct mode:
 
 Applicable modes: design (full initialization), record (quick recording)
 
-### 1. Survey the project with `apltk codegraph survey`
+### 1. Analyze the project with `apltk codegraph`
 
-Before diving into the code, establish a high-level understanding:
-- Which external actors interact with the system (users, third-party services, other systems)
-- What high-level capabilities the system provides
+**Prerequisite** before any architecture work. The code graph provides the source-code evidence that powers the atlas.
 
-Then read `sample-demo/` to understand the expected output format and abstraction level.
+1. Initialize: `apltk codegraph init --index` (run once per project to build the symbol index).
+2. Survey: `apltk codegraph survey --json` for a structured report with file/function counts, entry points, and suggested submodule groupings.
 
-Next, run `apltk codegraph survey` to get a structured survey report:
-- List of all files in the project directory with function counts
-- Entry points (public functions called from external files)
-- Suggested submodule groupings and cross-boundary edges
-- Supports `--json` output for programmatic consumption by the LLM
-
-Based on the survey report, decide how to partition features (C4 Container level):
-- Group closely interconnected function clusters into the same feature's submodules
+Based on the survey, partition features (C4 Container level):
+- Group interconnected function clusters into the same feature's submodules
 - Identify feature boundaries and cross-feature call relationships
-- Record the directory path and entry points for each feature
+
+Then read `sample-demo/` to understand the expected output format and abstraction level before writing the atlas.
+
+Consult `references/codegraph.md` for detailed flags.
 
 ### 2. Write the atlas with `apltk architecture apply`
 
@@ -107,7 +103,8 @@ If time or context constraints prevent full traceability, record the scanned sco
 
 ## References
 
-- `references/architecture.md` — Full parameter reference for the apltk architecture tool (consult when CLI flag details are needed).
+- `references/codegraph.md` — `apltk codegraph` CLI reference (consult for subcommand flags).
+- `references/architecture.md` — Full parameter reference for the `apltk architecture` tool (consult when CLI flag details are needed).
 - `references/TEMPLATE_SPEC.md` — Atlas field reference, enum values, and CLI shape cheat sheet.
 - `references/definition.md` — Detailed definitions of feature and submodule.
 - `assets/architecture-page.template.html` — HTML template.

package/skills/init-project-html/references/codegraph.md

@@ -0,0 +1,41 @@
+# apltk codegraph — Code Intelligence CLI Reference
+
+## Purpose
+Parse source code into a knowledge graph of symbols (functions, classes) and relationships (call edges), backed by a local SQLite database with FTS5 full-text search. Powered by @colbymchenry/codegraph (tree-sitter-backed code knowledge graph engine).
+
+## Usage
+```
+apltk codegraph <subcommand> [options]
+```
+
+## Subcommands
+
+### Lifecycle
+
+| Subcommand | Description | Key Flags |
+|------------|-------------|-----------|
+| `init` | Initialize CodeGraph for the project | `--index` (run initial indexing immediately), `--json` |
+| `sync` | Sync index with current file state (incremental) | `--json` |
+| `status` | Show index statistics (files, nodes, edges, languages) | `--json` |
+
+### Discovery
+
+| Subcommand | Description | Key Flags |
+|------------|-------------|-----------|
+| `search <query>` | Search code graph for symbols via FTS5 | `--limit N` (default 20, max 100), `--json` |
+| `explore <query>` | Deep-dive on a symbol — callers, callees, source | `--feature <name>`, `--json` |
+| `survey [dir]` | Scan directory, suggest submodule groupings and edges | `--feature <name>`, `--json` |
+| `list-apis [path]` | List public APIs in project or sub-path | `--all` (include internal symbols), `--json` |
+
+### Validation
+
+| Subcommand | Description | Key Flags |
+|------------|-------------|-----------|
+| `verify --spec <dir>` | Verify a spec overlay against actual code | `--json` |
+
+## Common Workflows
+
+- **Before atlas work**: `apltk codegraph init --index` (first time), then `apltk codegraph survey --json`
+- **After code changes**: `apltk codegraph sync` to keep index current
+- **Understanding a symbol**: `apltk codegraph explore <name>` to see callers and callees
+- **Searching code**: `apltk codegraph search <query> --json --limit 30`

package/skills/maintain-project-constraints/SKILL.md

@@ -41,6 +41,16 @@ description: 基於 repo 最新程式碼與文檔，更新 CLAUDE.md 和 AGENTS.
 
 > 兩份檔案皆應維持在 100 行以內。若超過此限制，優先精煉而非擴充。
 
+#### 加入 `apltk codegraph` 相關命令
+
+在兩份文檔的 `Common Development Commands` 區塊中，加入：
+
+- `apltk codegraph <subcommand> [options]` — CodeGraph code intelligence CLI（init/sync/status/search/explore/survey/list-apis/verify）。由 tree-sitter 驅動的代碼知識圖譜引擎。
+
+#### 加入代碼調查要求
+
+在兩份文檔中，明確要求 agent 在開始實作前，應先通過 `apltk codegraph` 進行代碼調查（如 `apltk codegraph survey`、`apltk codegraph explore`），確保變更基於對現有代碼的真實理解。此規則可放在 `Common Development Commands` 區塊的開頭作為前置條件說明，或放在 Prohibitions 區塊附近作為開發慣例。
+
 ## 參考資料
 
 - `references/constraint-file-reference.md`：三區塊契約、撰寫規則、AGENTS.md vs CLAUDE.md 區分指引、核對清單與輸出模板。

package/skills/maintain-project-constraints/references/constraint-file-reference.md

@@ -37,6 +37,8 @@ CLAUDE.md 可在這三個區塊之後額外加入 Claude Code 特有設定區塊
 - 只收錄能被當前倉庫驗證的命令。
 - 優先從 `package.json`、`Makefile`、`bin/`、`scripts/`、CI 設定或其他真實入口提取。
 - 每條命令附上一句簡短用途說明，避免捏造不存在的工作流。
+- 若專案已安裝 `apltk codegraph`，必須在 Commands 區塊中包含該 CLI 的完整子命令列表（init/sync/status/search/explore/survey/list-apis/verify）。
+- 在 Commands 區塊開頭或附近加入前置條件：要求 agent 在開始實作前，先通過 `apltk codegraph survey`（或 `explore`）進行代碼調查，確保變更基於對現有代碼的真實理解。
 
 ### `Project Business Goals`
 

package/skills/plan/SKILL.md

@@ -95,7 +95,7 @@ Each worker prompt must include:
 ```
 ## Mission — What to do and why
 ## Input — Which files to read
-## What to do — Concrete steps (describe "what" to do, not "which tool" to use)
+## What to do — Concrete steps, each specifying the exact file path, the function or line range, and what specific change to make (add/delete/modify). Never leave the change description vague.
 ## Scope — Allowed and forbidden files
 ## Output — What to report on completion (file list, change summary, test results, risks)
 ## Verify — Verification commands and expected results
@@ -104,7 +104,7 @@ Each worker prompt must include:
 
 **Writing principles:**
 - **Self-contained**: Workers do not see the coordinator's context. The prompt must include everything necessary
-- **Concrete**: Embed file paths, function names, line numbers. Do not write "fix it" or "based on your findings"
+- **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
 
@@ -146,12 +146,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. Task Units | Step 3 (task decomposition) + Step 4 (dependency analysis) |
-| 6. Worker Prompt Library | Step 6 — one entry per dispatchable task |
-| 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 |
+| 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) |
 
 ### 11. Pre-delivery Self-Review
 
@@ -159,21 +160,21 @@ Before delivering PROMPT.md, verify all of the following.
 
 **Worker prompt quality:**
 
-- Every worker prompt in Section 6 is self-contained. Scan for phrases like "based on your findings", "fix it appropriately", "as discussed above" — these leak shared context assumptions. If found, rewrite the prompt to include the necessary information inline.
+- Every worker prompt in 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 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").
 
 **Coverage completeness:**
 
-- Every BDD requirement from SPEC.md is addressed by at least one task in Section 5. If a requirement has no task, add one or document why it is already satisfied by existing code.
+- Every BDD requirement from SPEC.md is addressed by at least one task in Section 6. If a requirement has no task, add one or document why it is already satisfied by existing code.
 - Every module from DESIGN.md has a corresponding task or is explicitly noted as unchanged.
-- Every hardening requirement from CHECKLIST.md appears in Section 8.
+- Every hardening requirement from CHECKLIST.md appears in Section 9.
 
 **Structural consistency:**
 
-- Each task's Depends on field in Section 5 matches the batch ordering in Section 7. No task scheduled in a batch before its dependencies are met.
-- Every task listed in Section 7 (Batch Schedule) has a worker prompt in Section 6 — unless it is explicitly marked as coordinator-handled.
-- 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).
+- 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).
 
 ### 12. Produce PROMPT.md
 

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

@@ -15,11 +15,11 @@
 ### What you do
 
 - Read and understand the mission, scope, technical context, and task definitions below
-- Spawn workers to execute individual tasks, giving each a self-contained prompt (provided in Section 6)
+- Spawn workers to execute individual tasks, giving each a self-contained prompt (provided in Section 7)
 - Wait for all workers in a batch to complete, then digest their results
 - Run verification commands at each checkpoint
 - Decide whether to proceed to the next batch, retry a failed worker, or halt
-- Handle lightweight coordination tasks: resolving merge conflicts, updating lockfiles
+- Handle lightweight coordination tasks: resolving merge conflicts, updating lockfiles, cleaning up worktrees
 - Commit all changes in a single commit after the final verification gate passes
 
 ### What you NEVER do
@@ -74,7 +74,14 @@
 
 ---
 
-## 5. Task Units
+## 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
 
 [Each task is an atomic work unit. Task ID format: `T{batch}.{sequence}`.]
 
@@ -100,7 +107,7 @@
 
 ---
 
-## 6. Worker Prompt Library
+## 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.]
 
@@ -114,8 +121,8 @@
 - Read the following files: [list]
 
 ## What to do
-1. [Concrete step — describe "what" to do, not "which tool" to use]
-2. [Include specific file paths, function names, line numbers]
+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:
@@ -146,7 +153,7 @@ On completion, report:
 
 ---
 
-## 7. Batch Schedule
+## 8. 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.]
 
@@ -183,7 +190,7 @@ On completion, report:
 
 ---
 
-## 8. Verification Checkpoints
+## 9. Verification Checkpoints
 
 ### Per-batch
 
@@ -206,7 +213,7 @@ On completion, report:
 
 ---
 
-## 9. Error Recovery
+## 10. Error Recovery
 
 | Scenario | Response |
 |---|---|
@@ -218,15 +225,16 @@ On completion, report:
 
 ---
 
-## 10. Boundaries
+## 11. Boundaries
 
 ### ALWAYS
 
 - Run gate verification immediately after every batch
-- Extract worker prompts verbatim from Section 6 — do not rewrite them
+- Extract worker prompts verbatim from Section 7 — do not rewrite them
 - After a worker reports, digest the results before deciding next steps
 - Follow the File Ownership implied by task assignments — do not let two workers modify the same file
 - **Resolve merge conflicts yourself** — when combining worker results, the coordinator handles conflict resolution. This is coordination, not implementation.
+- **After each batch completes, clean up any temporary branches or worktrees created by workers** — no ephemeral worktree should be left orphaned.
 - After two failures, pause and ask — do not keep retrying
 
 ### ASK FIRST — pause and confirm with the user

package/skills/qa/SKILL.md

@@ -109,7 +109,7 @@ Each fix worker prompt must include:
 ## Mission — What to fix and why
 ## Context — Which review dimension, which spec requirement
 ## Input — Which files to read
-## What to do — Concrete fix steps (describe "what" to do, not "which tool" to use)
+## What to do — Concrete fix steps, each specifying the exact file path, the function or line range, and what specific change to make (add/delete/modify). Never leave the change description vague.
 ## Scope — Allowed and forbidden files
 ## Output — What to report on completion
 ## Verify — Verification commands and expected results
@@ -186,7 +186,8 @@ Use `assets/templates/FIX.md`. Fill according to the table below.
 | 9. Verification Checkpoints | Fixed scaffold, customized with spec-specific commands |
 | 10. Error Recovery | Fixed scaffold (natural language) |
 | 11. Fix History | Fixed scaffold (history entries only, no instructions) |
-| 12. Boundaries | Fixed scaffold + spec-specific rules |
+| 12. References | Important project context files (CLAUDE.md, AGENTS.md, architecture atlas, codegraph index) — reduces LLM search overhead |
+| 13. Boundaries | Fixed scaffold + spec-specific rules (including worktree cleanup after each batch) |
 
 ### 11. Produce FIX.md
 

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

@@ -120,8 +120,8 @@
 - Read the following files: [list]
 
 ## What to do
-1. [Concrete fix steps — describe "what" to do, not "which tool" to use]
-2. [Include specific file paths, function names, line numbers, modification approach]
+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:
@@ -311,7 +311,14 @@ If there are no entries here, see Section 5 for each fix's regression test desig
 
 ---
 
-## 12. Boundaries
+## 12. References
+
+- **Project context files**: [List important project files the fix coordinator and workers may need — e.g., `CLAUDE.md`, `AGENTS.md`, `resources/project-architecture/**`, codegraph index files]
+- **Related documents**: [Links to REPORT.md, SPEC.md, DESIGN.md, or external documentation]
+
+---
+
+## 13. Boundaries
 
 ### ALWAYS
 
@@ -322,6 +329,7 @@ If there are no entries here, see Section 5 for each fix's regression test desig
 - Regression tests must not start before all fix batches pass
 - Resolve merge conflicts yourself — the coordinator handles them. This is coordination, not implementation.
 - **For fixes marked as Complex**: ensure the worker performs systematic debugging (reading related code, tracing execution paths) before applying the fix. Do not let the worker guess the fix.
+- **After each batch completes, clean up any temporary branches or worktrees created by workers** — no ephemeral worktree should be left orphaned.
 
 ### ASK FIRST — pause and confirm with the user
 

package/skills/review/SKILL.md

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

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

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

package/skills/spec/SKILL.md

@@ -96,7 +96,7 @@ Generate SPEC.md using the template at `assets/templates/SPEC.md`.
    - **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).
    - **Clarification Questions** → List questions for the user. Must be populated when any requirement is Exploratory. Omit only if all requirements are fully clear.
-   - **References** → Link to official docs and related code files for traceability.
+   - **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.
 
    **BDD writing guidelines**:
    - **GIVEN** states the precondition and actor role

package/skills/update-project-html/SKILL.md

@@ -17,14 +17,24 @@ Keep the architecture diagram continuously aligned with the actual codebase.
 
 ## Workflow
 
-### 1. Review the current atlas
+### 1. Analyze current code with `apltk codegraph survey`
+
+**Prerequisite** before measuring drift. The code graph provides the structural baseline for comparison with the atlas.
+
+Run `apltk codegraph survey --json` to get a structured view of the current codebase:
+- Entry points, function clusters, and suggested submodule groupings
+- Cross-boundary edges for identifying architectural relationships
+
+Consult `references/codegraph.md` for detailed flags.
+
+### 2. Review the current atlas
 
 Read the existing architecture diagram.
 Capture the relationship between features and submodules.
 
 > Read only `atlas.index.yaml` + the YAML files of affected features. Do not read unrelated features or unchanged modules to preserve context economy.
 
-### 2. Measure architecture drift
+### 3. Measure architecture drift
 
 Before deciding the update scope, compare the atlas against the current code:
 
@@ -36,7 +46,7 @@ Determine the update strategy based on drift severity:
 - **Low drift (< 20%)**: Update only the features affected by the diff
 - **High drift (≥ 20%)**: Flag as significant divergence, notify the user and recommend a full re-initialization via `init-project-html`
 
-### 3. Filter diff noise
+### 4. Filter diff noise
 
 Analyze the diff scope and filter non-architectural changes:
 
@@ -45,11 +55,11 @@ Analyze the diff scope and filter non-architectural changes:
 
 Map the filtered diff hunks to the affected features.
 
-### 4. Cross-reference code with the current atlas
+### 5. Cross-reference code with the current atlas
 
 Dispatch subagents in parallel to cross-reference the code against the architecture diagram and verify whether the atlas has errors or omissions.
 
-### 5. Update the atlas via `apltk` CLI
+### 6. Update the atlas via `apltk` CLI
 
 Use `apltk architecture` commands to update the architecture diagram:
 
@@ -67,7 +77,7 @@ apltk architecture function add --feature <slug> --submodule <slug> --name <fn>
 
 After completing the update, re-measure drift to confirm it has been reduced to an acceptable range.
 
-### 6. Self-review
+### 7. Self-review
 
 Confirm the following before finishing:
 
@@ -79,5 +89,6 @@ Confirm the following before finishing:
 
 ## References
 
-- `references/architecture.md` — Full parameter reference for the apltk architecture tool (consult when CLI flag details are needed).
+- `references/codegraph.md` — `apltk codegraph` CLI reference (consult for subcommand flags).
+- `references/architecture.md` — Full parameter reference for the `apltk architecture` tool (consult when CLI flag details are needed).
 - `references/definition.md` — Detailed definitions of feature and submodule.

package/skills/update-project-html/references/codegraph.md

@@ -0,0 +1,41 @@
+# apltk codegraph — Code Intelligence CLI Reference
+
+## Purpose
+Parse source code into a knowledge graph of symbols (functions, classes) and relationships (call edges), backed by a local SQLite database with FTS5 full-text search. Powered by @colbymchenry/codegraph (tree-sitter-backed code knowledge graph engine).
+
+## Usage
+```
+apltk codegraph <subcommand> [options]
+```
+
+## Subcommands
+
+### Lifecycle
+
+| Subcommand | Description | Key Flags |
+|------------|-------------|-----------|
+| `init` | Initialize CodeGraph for the project | `--index` (run initial indexing immediately), `--json` |
+| `sync` | Sync index with current file state (incremental) | `--json` |
+| `status` | Show index statistics (files, nodes, edges, languages) | `--json` |
+
+### Discovery
+
+| Subcommand | Description | Key Flags |
+|------------|-------------|-----------|
+| `search <query>` | Search code graph for symbols via FTS5 | `--limit N` (default 20, max 100), `--json` |
+| `explore <query>` | Deep-dive on a symbol — callers, callees, source | `--feature <name>`, `--json` |
+| `survey [dir]` | Scan directory, suggest submodule groupings and edges | `--feature <name>`, `--json` |
+| `list-apis [path]` | List public APIs in project or sub-path | `--all` (include internal symbols), `--json` |
+
+### Validation
+
+| Subcommand | Description | Key Flags |
+|------------|-------------|-----------|
+| `verify --spec <dir>` | Verify a spec overlay against actual code | `--json` |
+
+## Common Workflows
+
+- **Before atlas work**: `apltk codegraph init --index` (first time), then `apltk codegraph survey --json`
+- **After code changes**: `apltk codegraph sync` to keep index current
+- **Understanding a symbol**: `apltk codegraph explore <name>` to see callers and callees
+- **Searching code**: `apltk codegraph search <query> --json --limit 30`

package/skills/version-release/SKILL.md

@@ -11,20 +11,37 @@ description: 協助完成自動化版本發佈。同步文檔、更新版本號
 
 - `CHANGELOG.md`, `docs/` 下所有項目文檔已經被同步到最新狀態
 - GitHub release 與 version tag 已被建立
+- 代碼圖索引（codegraph）與實際代碼同步
+- 若不在 default 分支，已完成分支合併流程
 
 ## 工作流程
 
-### 1. 檢查並確認 repo 狀態
+### 1. 確定發佈分支
 
-檢查 repo 狀態。
-若有未提交變更，使用 `commit` 技能暫存並提交。推送到 remote。
+檢查當前 git 分支是否為 default 分支（main 或 master）：
+- 若在 **default 分支**：直接進入步驟 2-5
+- 若在 **非 default 分支**：按照以下流程完成版本發佈
 
-### 2. 更新項目文檔狀態
+#### 非 default 分支發佈流程
+
+1. 使用 `commit` 技能提交所有待處理變更。推送到 remote。
+2. 切換到 default 分支。將工作分支合併到 default 分支。
+3. 在 default 分支上，按步驟 2-4 完成發佈。
+4. 發佈完成後，切回原始的 working branch。
+5. 與 remote default branch 同步（`git merge --ff-only origin/<default>`）。
+6. 推送已同步的工作分支。
+
+### 2. 同步代碼圖索引
+
+若有代碼變更，執行 `apltk codegraph sync` 確保代碼圖與實際代碼同步。
+若 `CLAUDE.md` 或 `AGENTS.md` 缺少 `apltk codegraph` 的引用，必須添加。
+
+### 3. 更新項目文檔狀態
 
 通過並行調度 subagents 完成變更的逐行深度閱讀，檢查文檔是否存在錯誤或遺漏。
 若有，使用 `docs-project`、`maintain-project-constraints` 將文檔同步到最新。
 
-### 3. 發佈版本
+### 4. 發佈版本
 
 確認所有文檔已更新。
 更新 repo 的版本文件（如 pyproject.toml）。