@laitszkin/apollo-toolkit 5.0.2 → 5.0.4

package/CHANGELOG.md

@@ -2,6 +2,31 @@
 
 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
+
+- **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.4",
   "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

@@ -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,16 +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 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:
 
@@ -104,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`.
@@ -127,6 +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 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):
 
@@ -139,30 +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. 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
-
-#### 5b. 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
 
-#### 5c. 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
@@ -171,68 +196,92 @@ 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
+#### 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)
 
-#### 5e. 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 5a–5d, 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
 
 - `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,11 @@ 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
+
+- **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

@@ -151,3 +151,11 @@ Code health findings identified during architecture survey, classified by module
 | […] | […] | […] | […] | […] |
 
 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/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/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/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`