EngramGraph: Skill for Claude Code

/plan — 從 Spec 自動生成 plan.json

用法

/plan <spec-file.md>              # Spec 模式（自有格式 / SpecKit）
/plan <openspec-change-dir/>      # OpenSpec 模式
/plan "需求描述文字"               # 需求模式
/plan                             # 互動模式（自動偵測）

---

執行流程

Step 1: 輸入辨識與格式偵測

根據引數類型判斷使用模式：

引數是 .md 檔案：

1. 讀取檔案內容
2. 偵測格式：
   • 含 ## Requirements 且 ## Technical Design → 自有格式（SPEC-NNN-*.md）
   • 含 ## Summary 且 ## Detailed Design → SpecKit 格式
   • 其他 .md → 嘗試解析為通用 Spec（按自有格式處理，缺少的欄位由 AI 補充）

引數是目錄：

1. 檢查是否含 proposal.md + tasks.md → OpenSpec 格式
2. 否則報錯：「此目錄不符合 OpenSpec 結構」

引數是字串描述（非檔案路徑）： → 需求模式

無引數： → 互動模式

1. 偵測 openspec/ 目錄存在？ → 列出 changes 讓使用者選擇
2. 偵測 specs/*.md 存在？ → 列出可用 Spec 讓使用者選擇
3. 都沒有 → 進入需求模式問答

---

Step 2: 專案 Context 收集

讀取目標專案的關鍵資訊：

1. CLAUDE.md / AGENTS.md — 語言、框架、測試工具、開發規範
2. package.json / pyproject.toml — 可用 scripts（build, test, lint）

從 Context 推斷：

• 主要語言（TypeScript / Python / 其他）
• 預設 verify_command（如 pnpm build && pnpm test、pytest -x）
• 預設 lint_command（如 pnpm lint、ruff check .）

---

Step 3: Spec 解析

依偵測到的格式，解析 Spec 內容：

自有格式（SPEC-NNN-*.md）

提取以下區段：

• Summary / Motivation → 理解背景與需求動機
• Requirements (REQ-NNN) → 功能需求列表
• Acceptance Criteria (AC-N) → Given/When/Then 驗收條件
• Technical Design → Phase 分層、每個 Phase 的實作項目
• Test Plan → 測試清單
• Risks → 風險評估

OpenSpec（change 目錄）

讀取以下檔案：

• proposal.md → Why（動機）、What Changes（變更項目）、Impact
• tasks.md → - [ ] checklist 項目
• design.md（若存在）→ 技術決策
• specs/*/spec.md（若存在）→ Requirements（SHALL/MUST 語句）、Scenarios

SpecKit（SPEC-ID.md）

提取以下區段：

• Summary / Motivation → 背景
• Detailed Design → 技術實作步驟
• Acceptance Criteria → checkbox 驗收條件
• Dependencies → 外部依賴
• Risks → 風險

---

Step 4: Task 切分

依格式套用不同映射規則：

自有格式映射規則

Spec 區段	plan.json 欄位	映射規則
Technical Design > Phase	一組 tasks	每個 Phase 的每個實作項目 = 1 個 task
Phase 實作項目描述	task.spec	合併：項目描述 + 相關 REQ + 技術細節
Acceptance Criteria (AC-N)	task.acceptance_criteria	分配到最相關的 task
Summary / Motivation	task.user_intent	萃取與 task 最相關的意圖
Test Plan	task.verify_command	推斷測試指令