maestro-flow 0.3.42 → 0.3.44

package/.claude/commands/quality-retrospective.md

@@ -1,6 +1,6 @@
 ---
 name: quality-retrospective
-description: Phase retrospective with insight routing to specs and lessons
+description: Phase retrospective with insight routing to specs and knowhow
 argument-hint: "[phase|N..M] [--lens technical|process|quality|decision] [--all] [--no-route] [--compare N] [-y]"
 allowed-tools:
   - Read
@@ -13,7 +13,7 @@ allowed-tools:
   - AskUserQuestion
 ---
 <purpose>
-Post-execution multi-perspective retrospective (复盘) for completed phases. Consumes existing execution artifacts (verification.json, review.json, issues.jsonl, plan.json, .summaries/, uat.md, state.json) and runs four parallel lenses — technical, process, quality, decision — to distill reusable insights. Routes each insight into the appropriate store: spec stub for reusable patterns, memory tip for process notes, issue for recurring gaps. Auto-scans for unreviewed completed phases and reports the backlog. Every insight is also persisted to `.workflow/learning/lessons.jsonl` for cross-phase queryability.
+Post-execution multi-perspective retrospective (复盘) for completed phases. Consumes existing execution artifacts (verification.json, review.json, issues.jsonl, plan.json, .summaries/, uat.md, state.json) and runs four parallel lenses — technical, process, quality, decision — to distill reusable insights. Routes each insight into the appropriate store: spec stub for reusable patterns, memory tip for process notes, issue for recurring gaps. Auto-scans for unreviewed completed phases and reports the backlog. Every insight is also persisted to `.workflow/knowhow/specs/learnings.md` as `<spec-entry>` blocks for cross-phase queryability.
 </purpose>
 
 <required_reading>
@@ -70,9 +70,8 @@ Follow `~/.maestro/workflows/retrospective.md` Stages 1–8 in order. Key invari
 - [ ] Spec entries (if any) appended as `<spec-entry>` to matching `.workflow/specs/{category-file}.md`
 - [ ] Issue rows (if any) match canonical issues.jsonl schema (status "open", full issue_history, all required fields)
 - [ ] Note tips (if any) created via `Skill({ skill: "manage-learn", args: "tip ..." })`
-- [ ] `lessons.jsonl` appended with one row per insight regardless of routing target
-- [ ] `learning-index.json` updated and parseable
+- [ ] `specs/learnings.md` appended with one `<spec-entry>` per insight regardless of routing target
 - [ ] No existing phase artifacts modified (verification.json, review.json, plan.json untouched)
 - [ ] Confirmation banner displays routing counts and next-step suggestions
-- [ ] Next step: `/manage-status` to review state, or `/manage-issue list --source retrospective` to triage created issues, or `/manage-learn list` to browse the lessons library
+- [ ] Next step: `/manage-status` to review state, or `/manage-issue list --source retrospective` to triage created issues, or `/manage-learn list` to browse the knowhow library
 </success_criteria>

package/.claude/commands/quality-review.md

@@ -54,6 +54,14 @@ Extract conclusions from related artifacts that may affect this review. Pass as
 2. **Wiki constraints**: Run `maestro wiki search "architecture constraint" --json 2>/dev/null`. If results found, pass as `wiki_context` to reviewer agents for evaluating code against documented decisions.
 3. Both are optional — proceed without if unavailable.
 
+### Role Knowledge
+1. Browse accumulated knowledge for this role:
+   `maestro wiki list --role review`
+2. Analyze the index, identify entries relevant to the current task
+3. Load selected documents:
+   `maestro wiki load <id1> [id2] [id3...]`
+4. Review loaded knowledge before proceeding
+
 **Output**: `REVIEW_DIR = .workflow/scratch/{YYYYMMDD}-review-P{N}-{slug}/` (P{N} = phase number, enables directory-level identification as state.json fallback)
 </context>
 

package/.claude/commands/spec-add.md

@@ -1,7 +1,7 @@
 ---
 name: spec-add
-description: Add spec entry by category
-argument-hint: "[--scope project|global|team|personal] <category> <content>"
+description: Add spec entry by category with role tagging
+argument-hint: "[--scope project|global|team|personal] [--roles <csv>] <category> <content>"
 allowed-tools:
   - Read
   - Write
@@ -13,6 +13,7 @@ allowed-tools:
 Add a knowledge entry to the specs system using `<spec-entry>` closed-tag format.
 Each category maps 1:1 to a single target file — no dual-write.
 Supports 4 scopes: project (default), global, team, personal.
+Entries use `roles` attribute to declare which agent roles should load them.
 </purpose>
 
 <required_reading>
@@ -20,9 +21,29 @@ Supports 4 scopes: project (default), global, team, personal.
 </required_reading>
 
 <context>
-$ARGUMENTS -- expects `[--scope <scope>] [--uid <uid>] <category> <content>`
+$ARGUMENTS -- expects `[--scope <scope>] [--uid <uid>] [--roles <csv>] <category> <content>`
+
+**Options:**
+- `--roles <csv>` — Comma-separated roles (implement, plan, test, review, analyze, explore). Determines which agents load this entry via `spec load --role`.
+- `--ref <path>` — Create as index entry referencing a knowhow document. If the path exists, only creates the spec index entry. If path doesn't exist, also creates the knowhow file.
+- `--knowhow-type <type>` — Knowhow document type when creating with --ref (asset, blueprint, document, template, recipe, reference, decision)
 
 Scope-to-directory mapping, category-to-file mapping, and entry format defined in workflow specs-add.md.
+
+**Examples:**
+```bash
+# Tool spec with roles (stored in tools.md)
+/spec-add tools "Integration Test Flow" "## Steps\n1. Setup\n2. Run" --roles "implement,test" --keywords "testing,api"
+
+# Tool spec with ref to detailed knowhow
+/spec-add tools "OAuth PKCE Flow" "完整 PKCE 集成流程" --roles "implement" --ref knowhow/RCP-oauth-pkce.md
+
+# Standard spec with role
+/spec-add coding "Named exports" "Always use named exports" --roles "implement"
+
+# Legacy style (no --roles, backward compat)
+/spec-add arch "OAuth PKCE 集成" "完整流程设计" --ref knowhow/AST-oauth-flow.md
+```
 </context>
 
 <execution>
@@ -34,7 +55,7 @@ Follow '~/.maestro/workflows/specs-add.md' completely.
 |------|----------|-------------|-------|
 | E001 | fatal | Category and content are both required | parse_input |
 | E002 | fatal | Specs directory not initialized -- run `maestro spec init --scope <scope>` | validate_entry |
-| E003 | fatal | Invalid category -- must be one of: coding, arch, quality, debug, test, review, learning | parse_input |
+| E003 | fatal | Invalid category -- must be one of: coding, arch, quality, debug, test, review, learning, tools | parse_input |
 | E004 | fatal | Invalid scope -- must be one of: project, global, team, personal | parse_input |
 | E005 | fatal | Personal scope requires uid -- use `--uid` or run `maestro collab join` first | parse_input |
 </error_codes>

package/.claude/commands/spec-load.md

@@ -1,7 +1,7 @@
 ---
 name: spec-load
 description: Load specs and lessons for current context
-argument-hint: "[--category <type>] [--keyword <word>] [--with-lessons]"
+argument-hint: "[--role <role>] [--keyword <word>]"
 allowed-tools:
   - Read
   - Bash
@@ -9,8 +9,8 @@ allowed-tools:
   - Grep
 ---
 <purpose>
-Load and display relevant spec files for the current working context.
-Supports filtering by category (file-level) and keyword (entry-level via `<spec-entry>` tags).
+Load relevant specs filtered by role (primary), category (file-level), and/or keyword (entry-level).
+Role-based loading: loads the role's primary doc in full + matching entries from other files.
 </purpose>
 
 <required_reading>
@@ -20,14 +20,34 @@ Supports filtering by category (file-level) and keyword (entry-level via `<spec-
 <context>
 $ARGUMENTS -- optional flags and keyword
 
-Category-to-file mapping (1:1) and flag details defined in workflow specs-load.md.
+**Flags:**
+- `--role <role>` — Load by role: primary role doc (full) + cross-file entries with matching roles attr. Roles: implement, plan, test, review, analyze, explore, brainstorm, research.
+- `--keyword <word>` — Filter by keyword within entries
+
+**File → Primary Role mapping:**
+| File | Role |
+|------|------|
+| coding-conventions.md | implement |
+| architecture-constraints.md | plan |
+| test-conventions.md | test |
+| review-standards.md | review |
+| debug-notes.md | analyze |
+| quality-rules.md | review |
+| learnings.md | implement |
+| tools.md | _(per-entry roles)_ |
 
 **Examples:**
 ```
+/spec-load --role implement             # coding全文 + 跨文件implement条目
+/spec-load --role review                # review-standards + quality-rules + 跨文件review条目
+/spec-load --role implement --keyword auth
 /spec-load --keyword auth
-/spec-load --category coding --keyword naming
-/spec-load --category arch
 ```
+
+**Ref entries:**
+When loading entries with `ref` attribute, only the summary is shown with a load command:
+  → Detail: maestro wiki load <knowhow-id>
+Use the load command to read the full referenced document.
 </context>
 
 <execution>

package/.claude/commands/spec-setup.md

@@ -11,7 +11,7 @@ allowed-tools:
 ---
 <purpose>
 Initialize the project-level specs directory by scanning the codebase for conventions, patterns, and tech stack.
-Core files (coding, arch, learning) are always created. Optional files (quality, debug, test, review) are created only when relevant signals are detected.
+Core files (coding, arch, knowhow) are always created. Optional files (quality, debug, test, review) are created only when relevant signals are detected.
 All output lands in `.workflow/specs/`.
 </purpose>
 
@@ -44,7 +44,7 @@ Follow '~/.maestro/workflows/specs-setup.md' completely.
 
 <success_criteria>
 - [ ] `.workflow/specs/` directory created
-- [ ] Core files always created: `coding-conventions.md`, `architecture-constraints.md`, `learnings.md`
+- [ ] Core files always created: `coding-conventions.md`, `architecture-constraints.md`, `knowhow.md`
 - [ ] Optional files created when detected: `quality-rules.md` (linter/CI), `test-conventions.md` (test framework), `debug-notes.md` (on demand), `review-standards.md` (on demand)
 - [ ] Report displayed with summary and next steps
 </success_criteria>

package/.claude/commands/wiki-connect.md

@@ -56,7 +56,7 @@ Follow '~/.maestro/workflows/wiki-connect.md' completely (Stages 1-6).
 - [ ] If --fix: entries updated with new `related` links
 - [ ] If --fix: new health score computed and delta reported
 - [ ] Report written to `wiki-connections-{date}.md`
-- [ ] Graph insights appended to `lessons.jsonl`
+- [ ] Graph insights appended to `specs/learnings.md` as `<spec-entry>` blocks
 - [ ] No unintended entry modifications (only `related` field changed)
 - [ ] Summary displayed with next-step routing
 </success_criteria>

package/.claude/commands/wiki-digest.md

@@ -48,7 +48,7 @@ Follow '~/.maestro/workflows/wiki-digest.md' completely (Stages 1-8).
 | E001 | error | No wiki entries found (empty index) | Initialize wiki content first |
 | E002 | error | Topic search returned 0 results | Broaden topic or check wiki content |
 | W001 | warning | Too few entries (<5) for meaningful theme clustering | Digest produced but themes may be trivial |
-| W002 | warning | lessons.jsonl not found — skipping cross-reference | Proceed without lesson context |
+| W002 | warning | specs/learnings.md not found — skipping cross-reference | Proceed without knowhow context |
 | W003 | warning | Some entry bodies failed to load — partial summaries | Note incomplete entries in digest |
 </error_codes>
 
@@ -57,13 +57,12 @@ Follow '~/.maestro/workflows/wiki-digest.md' completely (Stages 1-8).
 - [ ] Baseline health score recorded
 - [ ] Entries clustered into 3-5 semantic themes
 - [ ] Per-theme analysis: summary, key entries, gaps, health
-- [ ] Cross-reference with lessons.jsonl completed
+- [ ] Cross-reference with specs/learnings.md completed
 - [ ] Coverage heatmap generated (type × theme matrix)
 - [ ] Knowledge gaps identified with suggested actions
 - [ ] If `--create-issues`: gap issues created in `issues.jsonl` (deduped)
-- [ ] Digest written to `digest-{slug}-{date}.md`
-- [ ] Meta-insights appended to `lessons.jsonl`
-- [ ] `learning-index.json` updated
-- [ ] No files modified outside `.workflow/learning/` and `.workflow/issues/` (issues only when `--create-issues`)
+- [ ] Digest written to `KNW-digest-{slug}-{date}.md`
+- [ ] Meta-insights appended to `specs/learnings.md` as `<spec-entry>` blocks
+- [ ] No files modified outside `.workflow/knowhow/` and `.workflow/issues/` (issues only when `--create-issues`)
 - [ ] Summary displayed with key findings and next-step routing
 </success_criteria>

package/.claude/skills/codify-to-knowhow/SKILL.md

@@ -0,0 +1,167 @@
+---
+name: codify-to-knowhow
+description: Manifest-driven knowledge asset generator — converts any structured package into maestro knowhow + spec entries with ref linking. Triggers on "codify-to-knowhow", "style to knowhow", "知识固化".
+allowed-tools: Read, Write, Edit, Bash, Glob, Grep, TodoWrite
+auto-continue: true
+---
+
+# Codify to Knowhow
+
+通用 manifest 驱动的知识资产生成器。读取 `knowhow-manifest.json`，按声明创建 knowhow 文件和 spec 条目，通过 ref 建立索引-详文桥梁。
+
+**适用场景**: 任何工作流产出需要固化为知识资产时使用。上游 skill（如 `maestro-ui-codify`）负责生成 manifest，本 skill 负责执行知识写入。
+
+## Architecture Overview
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│  Codify to Knowhow (SKILL.md) — Manifest-Driven            │
+│  → Read manifest → Create knowhow → Create specs → Verify  │
+└──────────────────────────┬──────────────────────────────────┘
+                           │
+    ┌──────────┬───────────┼───────────┬──────────┐
+    ↓          ↓           ↓           ↓          │
+┌────────┐ ┌────────┐ ┌────────┐ ┌────────┐      │
+│Phase 1 │ │Phase 2 │ │Phase 3 │ │Phase 4 │      │
+│ Load   │ │Generate│ │Generate│ │ Index  │      │
+│Manifest│ │Knowhow │ │ Specs  │ │ Verify │      │
+└───┬────┘ └───┬────┘ └───┬────┘ └───┬────┘      │
+    │          │          │          │             │
+ manifest   AST-/DCS-  spec-entry  verified       │
+ parsed     files       + ref       assets        │
+```
+
+## Key Design Principles
+
+1. **Manifest 驱动**: 所有行为由 `knowhow-manifest.json` 声明，不含硬编码领域知识
+2. **幂等执行**: 每个写入前按 slug 检查已存在资产，存在则跳过
+3. **ref 桥梁**: spec-entry 通过 `ref` 引用 knowhow 详文
+4. **闭合标签**: 所有条目使用 `<spec-entry>`/`<knowhow-entry>` 闭合标签
+5. **上游生成 manifest**: 本 skill 不做知识提取，只做知识写入
+
+## Manifest Format
+
+`knowhow-manifest.json` 由上游 skill 生成，放在 package 目录中：
+
+```json
+{
+  "slug": "my-style-v1",
+  "domain": "ui-design",
+  "roles": ["implement", "review"],
+  "packagePath": ".workflow/reference_style/my-style-v1",
+
+  "knowhow": [
+    {
+      "prefix": "AST",
+      "fileSlug": "tokens",
+      "title": "Design Tokens",
+      "category": "asset",
+      "assetType": "design-tokens",
+      "codePaths": ["src/styles/"],
+      "tags": ["design-tokens", "colors"],
+      "entries": [
+        {
+          "category": "pattern",
+          "keywords": "colors,tokens",
+          "title": "Color System",
+          "body": "## Colors\n\n..."
+        }
+      ]
+    }
+  ],
+
+  "specs": [
+    {
+      "category": "coding",
+      "keywords": "colors,design-tokens",
+      "title": "颜色编码约定",
+      "ref": "knowhow/AST-my-style-v1-tokens.md",
+      "body": "主色使用 var(--color-primary)..."
+    }
+  ]
+}
+```
+
+## Execution Flow
+
+```
+Input: <package-path> (must contain knowhow-manifest.json)
+
+Phase 1: Load and Validate Manifest
+   └─ Ref: phases/01-load-manifest.md
+      ├─ Validate package path and manifest existence
+      ├─ Parse knowhow-manifest.json
+      └─ Output: manifest object
+
+Phase 2: Generate Knowhow Assets
+   └─ Ref: phases/02-generate-knowhow.md
+      ├─ Idempotency check per file
+      ├─ Write knowhow files per manifest.knowhow[]
+      └─ Output: knowhowPaths[]
+
+Phase 3: Generate Spec Entries
+   └─ Ref: phases/03-generate-specs.md
+      ├─ Idempotency check per entry
+      ├─ Write spec entries per manifest.specs[]
+      └─ Output: specEntryCount
+
+Phase 4: Index and Verify
+   └─ Ref: phases/04-index-verify.md
+      └─ Output: verification report
+```
+
+**Phase Reference Documents**:
+
+| Phase | Document | Purpose |
+|-------|----------|---------|
+| 1 | [phases/01-load-manifest.md](phases/01-load-manifest.md) | Load and validate manifest |
+| 2 | [phases/02-generate-knowhow.md](phases/02-generate-knowhow.md) | Create knowhow files |
+| 3 | [phases/03-generate-specs.md](phases/03-generate-specs.md) | Create spec entries with ref |
+| 4 | [phases/04-index-verify.md](phases/04-index-verify.md) | Verify assets and index |
+
+## Core Rules
+
+1. **Manifest 必需**: 无 manifest 则报错退出
+2. **幂等写入**: 同 slug 文件存在则跳过
+3. **闭合标签**: 所有 entry 使用闭合标签格式
+4. **Auto-Continue**: Phase 完成后自动执行下一 Phase
+5. **不提取知识**: 本 skill 只写入，知识提取由上游完成
+
+## Data Flow
+
+```
+Input (packagePath)
+    ↓
+Phase 1 → manifest: { slug, knowhow[], specs[] }
+    ↓
+Phase 2 → knowhowPaths: string[], knowhowIds: string[]
+    ↓
+Phase 3 → specEntryCount: number
+    ↓
+Phase 4 → verificationResult
+    ↓
+Completion report
+```
+
+## TodoWrite Pattern
+
+```json
+[
+  {"content": "Phase 1: 加载 Manifest", "status": "in_progress"},
+  {"content": "Phase 2: 生成 Knowhow 资产", "status": "pending"},
+  {"content": "Phase 3: 生成 Spec 条目", "status": "pending"},
+  {"content": "Phase 4: 索引验证", "status": "pending"}
+]
+```
+
+## Error Handling
+
+- **Manifest 不存在**: 报告错误，提示上游 skill 需先生成 manifest
+- **Manifest 格式错误**: 报告缺失字段
+- **幂等冲突**: 跳过已存在资产，报告跳过数量
+- **CLI 失败**: 回退到 Write tool 直接写文件
+
+## Related Commands
+
+**上游**: `maestro-ui-codify`, `learn-decompose`, 或任何生成 manifest 的 skill
+**后续**: `maestro wiki list --role implement`, `maestro spec load --keyword <slug>`

package/.claude/skills/codify-to-knowhow/phases/01-load-manifest.md

@@ -0,0 +1,101 @@
+# Phase 1: Load and Validate Manifest
+
+读取和验证 `knowhow-manifest.json`。
+
+## Objective
+
+- 验证 package path 存在
+- 验证 `knowhow-manifest.json` 存在并可解析
+- 提取 manifest 结构供后续 phase 使用
+
+## Execution
+
+### Step 1.1: Validate Package Path
+
+```bash
+package_path="${PACKAGE_PATH}"
+
+# 验证目录存在
+test -d "$package_path" || { echo "ERROR: Package path not found: $package_path"; exit 1; }
+
+# 验证 manifest 存在
+manifest_file="${package_path}/knowhow-manifest.json"
+test -f "$manifest_file" || { echo "ERROR: knowhow-manifest.json not found in $package_path"; exit 1; }
+
+echo "Package: $package_path"
+echo "Manifest: $manifest_file"
+```
+
+### Step 1.2: Read and Parse Manifest
+
+```javascript
+Read("${package_path}/knowhow-manifest.json")
+```
+
+**必需字段验证**:
+
+| 字段 | 必需 | 说明 |
+|------|------|------|
+| `slug` | 是 | 包名 slug，用于文件命名 |
+| `roles` | 是 | 角色标注数组 |
+| `knowhow` | 是 | knowhow 资产声明数组（可为空） |
+| `specs` | 是 | spec 条目声明数组（可为空） |
+| `domain` | 否 | 领域标识（如 ui-design, api, data） |
+| `packagePath` | 否 | 原始包路径（元数据） |
+
+**knowhow[] 每项必需字段**:
+
+| 字段 | 说明 |
+|------|------|
+| `prefix` | 文件前缀: AST, DCS, BLP, TIP, RCP, REF 等 |
+| `fileSlug` | 文件名后缀（如 "tokens" → AST-{slug}-tokens.md） |
+| `title` | 文档标题 |
+| `category` | knowhow 类别: asset, decision, blueprint, tip, recipe, reference |
+| `tags` | 标签数组 |
+| `body` | Markdown 正文内容 |
+
+**可选字段**: `assetType`, `codePaths`, `entries[]`（`<knowhow-entry>` 子条目）
+
+**specs[] 每项必需字段**:
+
+| 字段 | 说明 |
+|------|------|
+| `category` | spec 类别: coding, arch, quality, debug, test, review, learning |
+| `title` | 条目标题 |
+| `keywords` | 关键词（逗号分隔字符串） |
+| `body` | 条目正文 |
+
+**可选字段**: `ref`（引用 knowhow 文件路径）
+
+### Step 1.3: Validate and Summarize
+
+```javascript
+const manifest = JSON.parse(manifestContent);
+
+// 必需字段检查
+const required = ['slug', 'roles', 'knowhow', 'specs'];
+const missing = required.filter(f => !manifest[f]);
+if (missing.length > 0) {
+  REPORT("ERROR: Missing required fields: " + missing.join(', '));
+  EXIT(1);
+}
+
+// 摘要
+REPORT(`Manifest loaded:
+  Slug: ${manifest.slug}
+  Domain: ${manifest.domain || 'generic'}
+  Roles: ${manifest.roles.join(', ')}
+  Knowhow assets: ${manifest.knowhow.length}
+  Spec entries: ${manifest.specs.length}
+`);
+```
+
+## Output
+
+- **Variable**: `manifest` — 解析后的 manifest 对象
+- **Variable**: `slug` — `manifest.slug`
+- **TodoWrite**: Mark Phase 1 completed, Phase 2 in_progress
+
+## Next Phase
+
+Return to orchestrator, then auto-continue to [Phase 2: Generate Knowhow](02-generate-knowhow.md).

package/.claude/skills/codify-to-knowhow/phases/02-generate-knowhow.md

@@ -0,0 +1,97 @@
+# Phase 2: Generate Knowhow Assets
+
+按 `manifest.knowhow[]` 声明创建 knowhow 文件。
+
+## Objective
+
+- 遍历 `manifest.knowhow[]` 数组
+- 每个条目生成对应的 knowhow 文件
+- 幂等：同名文件存在则跳过
+
+## Execution
+
+### Step 2.1: Ensure Directory
+
+```bash
+mkdir -p .workflow/knowhow
+```
+
+### Step 2.2: Iterate and Write
+
+对 `manifest.knowhow[]` 中的每一项执行：
+
+```javascript
+for (const asset of manifest.knowhow) {
+  const filename = `${asset.prefix}-${manifest.slug}-${asset.fileSlug}.md`;
+  const filepath = `.workflow/knowhow/${filename}`;
+
+  // 幂等检查
+  if (fileExists(filepath)) {
+    REPORT(`SKIP: ${filename} (already exists)`);
+    continue;
+  }
+
+  // 构建 frontmatter
+  let frontmatter = `---
+title: ${asset.title}
+type: ${asset.category}`;
+
+  if (asset.assetType) {
+    frontmatter += `\nassetType: ${asset.assetType}`;
+  }
+
+  frontmatter += `\nroles: [${manifest.roles.join(', ')}]`;
+
+  if (asset.codePaths && asset.codePaths.length > 0) {
+    frontmatter += `\ncodePaths:`;
+    for (const cp of asset.codePaths) {
+      frontmatter += `\n  - ${cp}`;
+    }
+  }
+
+  frontmatter += `\ntags: [${asset.tags.join(', ')}]`;
+  frontmatter += `\n---`;
+
+  // 构建 body
+  let body = asset.body || '';
+
+  // 如果有 entries[]，生成 <knowhow-entry> 闭合标签
+  if (asset.entries && asset.entries.length > 0) {
+    const today = new Date().toISOString().split('T')[0];
+    for (let i = 0; i < asset.entries.length; i++) {
+      const entry = asset.entries[i];
+      const entryId = `${asset.prefix}-${manifest.slug}-${String(i + 1).padStart(3, '0')}`;
+      body += `\n\n<knowhow-entry keywords="${entry.category},${entry.keywords}" date="${today}" id="${entryId}" roles="${manifest.roles.join(',')}" source="codify-to-knowhow">
+
+### ${entry.title}
+
+${entry.body}
+
+</knowhow-entry>`;
+    }
+  }
+
+  const content = `${frontmatter}\n\n${body}`;
+  Write(filepath, content);
+  REPORT(`CREATED: ${filename}`);
+  knowhowPaths.push(filepath);
+}
+```
+
+### Step 2.3: Collect Results
+
+```javascript
+const knowhowPaths = []; // 已创建的文件路径
+const skippedCount = manifest.knowhow.length - knowhowPaths.length;
+
+REPORT(`Knowhow assets: ${knowhowPaths.length} created, ${skippedCount} skipped`);
+```
+
+## Output
+
+- **Variable**: `knowhowPaths` — 已创建的文件路径列表
+- **TodoWrite**: Mark Phase 2 completed, Phase 3 in_progress
+
+## Next Phase
+
+Return to orchestrator, then auto-continue to [Phase 3: Generate Specs](03-generate-specs.md).

package/.claude/skills/codify-to-knowhow/phases/03-generate-specs.md

@@ -0,0 +1,92 @@
+# Phase 3: Generate Spec Entries
+
+按 `manifest.specs[]` 声明写入 spec 条目。
+
+## Objective
+
+- 遍历 `manifest.specs[]` 数组
+- 每个条目追加到对应的 spec 文件
+- 幂等：同 title 的条目已存在则跳过
+- 使用 `<spec-entry>` 闭合标签格式
+
+## Execution
+
+### Step 3.1: Idempotency Check
+
+对每个 spec 条目，检查是否已存在同 title 的 entry：
+
+```bash
+# 按 keyword 搜索
+maestro spec load --keyword "${manifest.slug}" --json 2>/dev/null | head -5
+```
+
+### Step 3.2: Iterate and Write
+
+对 `manifest.specs[]` 中的每一项执行：
+
+```javascript
+const today = new Date().toISOString().split('T')[0];
+let specEntryCount = 0;
+
+for (const spec of manifest.specs) {
+  // spec.category 决定目标文件
+  const categoryFileMap = {
+    coding: 'coding-conventions.md',
+    arch: 'architecture-constraints.md',
+    quality: 'quality-rules.md',
+    debug: 'debug-notes.md',
+    test: 'test-conventions.md',
+    review: 'review-standards.md',
+    learning: 'learnings.md'
+  };
+
+  const targetFile = `.workflow/specs/${categoryFileMap[spec.category]}`;
+
+  // 幂等检查：grep title 是否已存在
+  const titleExists = Bash(`grep -q "${spec.title}" "${targetFile}" 2>/dev/null && echo "exists" || echo "new"`);
+
+  if (titleExists.trim() === 'exists') {
+    REPORT(`SKIP spec: "${spec.title}" (already exists in ${spec.category})`);
+    continue;
+  }
+
+  // 构建 spec-entry 闭合标签
+  let refAttr = '';
+  if (spec.ref) {
+    refAttr = `\n  ref="${spec.ref}"`;
+  }
+
+  const entryBlock = `
+
+<spec-entry category="${spec.category}" keywords="${spec.keywords}" date="${today}"${refAttr}>
+
+### ${spec.title}
+
+${spec.body}
+
+</spec-entry>`;
+
+  // 追加到目标文件
+  // 优先使用 maestro spec add CLI
+  const cliResult = Bash(`maestro spec add ${spec.category} "${spec.title}" "${spec.body}" --keywords "${spec.keywords}" 2>/dev/null`);
+
+  if (cliResult.exitCode !== 0) {
+    // 回退：直接追加到文件
+    Edit(targetFile, { append: entryBlock });
+  }
+
+  specEntryCount++;
+  REPORT(`CREATED spec: "${spec.title}" → ${spec.category}`);
+}
+
+REPORT(`Spec entries: ${specEntryCount} created`);
+```
+
+## Output
+
+- **Variable**: `specEntryCount` — 创建的 spec 条目数量
+- **TodoWrite**: Mark Phase 3 completed, Phase 4 in_progress
+
+## Next Phase
+
+Return to orchestrator, then auto-continue to [Phase 4: Index and Verify](04-index-verify.md).