@laitszkin/apollo-toolkit 5.0.2 → 5.0.4

package/skills/spec/SKILL.md

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

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

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

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）。