@laitszkin/apollo-toolkit 4.0.11 → 4.1.0

package/skills/design/SKILL.md

@@ -167,6 +167,10 @@ Each component should link to:
 
 #### 5e. 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):
+
 ```bash
 apltk architecture --spec <spec_dir> render
 apltk architecture --spec <spec_dir> validate
@@ -178,6 +182,35 @@ Confirm validation passes, then use the diff command to produce a visual compari
 apltk architecture diff
 ```
 
+**New flow (CodeGraph-integrated):**
+
+1. **Survey the existing API landscape**:
+   ```bash
+   apltk codegraph list-apis --all
+   ```
+   This returns the full project API directory (function names, file paths, callers) as a reference for integration points. Use this data to understand what existing modules, services, 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.
+
+3. **Apply batch mutations**:
+   ```bash
+   apltk architecture apply <spec_dir>/architecture_diff/atlas/proposal.yaml --spec <spec_dir>
+   ```
+   This processes all mutations in one call with undo protection.
+
+4. **Verify correctness**:
+   ```bash
+   apltk codegraph verify --spec <spec_dir>
+   ```
+   This confirms every symbol and edge reference in the spec overlay exists in the actual code.
+
+5. **Render and validate** (optional, for visual confirmation):
+   ```bash
+   apltk architecture diff --spec <spec_dir>
+   ```
+
 **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.
 

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

@@ -52,7 +52,7 @@ At load time, check the project state to select the correct mode:
 
 適用模式：design（完整初始化）、record（快速記錄）
 
-### 1. 閱讀並理解代碼庫 — 先建立 System Context
+### 1. 使用 codegraph survey 取得專案結構
 
 在深入程式碼前，先建立系統的宏觀認知：
 - 系統與哪些外部 actor 互動（使用者、第三方服務、其他系統）
@@ -60,18 +60,18 @@ At load time, check the project state to select the correct mode:
 
 然後閱讀 `sample-demo/` 了解預期的輸出格式與抽象層級。
 
-按照功能模塊定義，全面檢索代碼庫。
-將其拆分為單個或多個功能模塊（對應 C4 Container 層級）。
-接著，識別功能模塊下的子模塊（對應 C4 Component 層級），並進行深度閱讀。
+接著使用 `apltk codegraph survey` 取得專案的結構化調查報告：
+- 專案目錄下的所有檔案清單與函式數量
+- Entry points（被外部檔案呼叫的公開函式）
+- 建議的 submodule 分組與跨邊界 edge
+- 支援 `--json` 輸出供 LLM 程式化消費
 
-並行調度 subagents，並為每一個功能模塊分配一個 subagent 進行深度閱讀，要求 subagents 完整列出：
-- 該功能模塊與其他功能模塊之間是否存在交互；如有，如何交互。
-- 該功能模塊內部存在哪些子模塊，這些子模塊之間如何交互並實現功能模塊的功能。
-- 該功能模塊及下屬子模塊的資料流、錯誤處理。
+根據 survey 報告，決定功能模塊的劃分（對應 C4 Container 層級）：
+- 將高度互相呼叫的函式群歸類為同一功能模塊的子模塊
+- 識別功能模塊之間的邊界與跨模塊呼叫關係
+- 記錄每個功能模塊對應的目錄路徑與 entry point
 
-> 每個 subagent 回報的每個宣告都應附上對應的程式碼檔案路徑與行號，作為證據追溯的基礎。
-
-### 2. 使用 `apltk` cli 工具協助生成架構圖
+### 2. 使用 `apltk architecture apply` 批次寫入 atlas
 
 依照 C4 層級逐步產生：
 在操作 CLI 前先閱讀 `references/architecture.md` 了解所有參數與 mutation 系列的使用方式。
@@ -81,6 +81,7 @@ At load time, check the project state to select the correct mode:
 3. **Component 層級**：定義子模塊（submodule）及其內部元素（function、variable、dataflow、error）
 4. **Code 層級**（選擇性）：對關鍵路徑補充函式層級細節
 
+使用 `apltk architecture apply <proposal.yaml>` 進行批次 atlas 寫入（取代逐一手動 mutation）。
 將前一步獲取的代碼庫知識透過 CLI 工具轉化為清晰的架構圖。
 完成後驗證架構圖格式正確且可渲染。
 

package/tsconfig.json

@@ -21,6 +21,7 @@
     { "path": "packages/tool-utils" },
     { "path": "packages/cli" },
     { "path": "packages/tools/architecture" },
+    { "path": "packages/tools/codegraph" },
     { "path": "packages/tools/eval" },
     { "path": "packages/tools/create-review-report" },
     { "path": "packages/tools/create-specs" },