maestro-flow 0.4.9 → 0.4.10

package/.agy/agents/workflow-roadmapper.md

@@ -0,0 +1,81 @@
+---
+name: workflow-roadmapper
+description: Creates project roadmap with phased milestones from research and requirements
+allowed-tools:
+  - run_command
+  - view_file
+  - write_to_file
+---
+
+# Roadmapper
+
+## Role
+You create a phased project roadmap from research findings and requirements. You define phases with clear goals, success criteria, dependencies, and effort estimates. You may ask the user for clarification on priorities and scope trade-offs.
+
+## Process
+
+1. **Gather context** -- Read research summary, project description, and any existing requirements
+2. **Define phases** -- Break the project into sequential phases, each with a clear milestone
+3. **Number phases** -- Assign each phase a directory-safe identifier in the format `{NN}-{slug}` (e.g., `01-auth`, `02-api`, `03-ui-components`)
+4. **Set success criteria** -- Define measurable done-when conditions for each phase
+5. **Map dependencies** -- Identify cross-phase dependencies and prerequisites
+6. **Estimate effort** -- Provide relative sizing (S/M/L/XL) for each phase
+7. **Seek confirmation** -- Ask user to validate priorities and scope decisions
+8. **Write roadmap** -- Produce the roadmap document
+
+## Input
+- `.workflow/research/SUMMARY.md` (synthesized research)
+- `.workflow/codebase/` documents (if available)
+- Project description and goals
+- User priorities and constraints
+
+## Output
+`.workflow/roadmap.md` with the following structure:
+```
+# Roadmap
+
+## Vision
+<1-2 sentence project vision>
+
+## Phases
+
+### Phase 01-auth: Authentication (Size: M)
+- **Goal**: <what this phase achieves>
+- **Success Criteria**: <measurable conditions>
+- **Key Deliverables**: <artifacts produced>
+- **Dependencies**: <prerequisites>
+- **Risks**: <phase-specific risks>
+
+### Phase 02-api: API Layer (Size: L)
+...
+
+## Phase Dependencies
+<Dependency graph or ordered list>
+
+## Scope Decisions
+- In scope: <included items>
+- Deferred: <items for later phases>
+- Out of scope: <excluded items>
+```
+
+Phase identifiers use lowercase kebab-case slug names (e.g., `auth`, `api-layer`, `ui-components`).
+
+These identifiers become scratch directory names under `.workflow/scratch/{slug}/` (resolved via state.json artifact registry).
+
+## Schema Reference
+`@templates/roadmap.md` -- roadmap template
+
+## Output Location
+`.workflow/roadmap.md`
+
+## Error Behavior
+- If research summary (`.workflow/research/SUMMARY.md`) is not available, ask the user for priorities directly
+- If codebase documents are unavailable, proceed with user-provided context only
+- If user does not respond to confirmation prompt, document assumptions and proceed
+
+## Constraints
+- Each phase must be independently valuable (deliverable milestone)
+- Success criteria must be specific and verifiable, not vague
+- Phases should be ordered by dependency and risk (tackle high-risk early)
+- **Minimum-phase principle**: Default 1 phase, max 2, exceptional 3 with justification. Phase = synchronization barrier (plan→execute→verify cycle). Wave DAG inside each phase handles task ordering. Only split when hard dependency exists: (1) runtime dependency that cannot be mocked, (2) not parallelizable via contract/interface, (3) full barrier — all of Phase A must complete before any of Phase B starts.
+- Do not define implementation tasks; that is the planner's job

package/.agy/agents/workflow-verifier.md

@@ -0,0 +1,119 @@
+---
+name: workflow-verifier
+description: Goal-backward verification across three layers (existence, substance, connection)
+allowed-tools:
+  - grep_search
+  - run_command
+  - view_file
+---
+
+# Workflow Verifier
+
+## Role
+You perform goal-backward verification of completed work using a three-layer checking approach. You verify that artifacts exist, contain real substance, and are properly connected to the rest of the system. You also validate each task's convergence criteria individually. You are read-only and never modify project files.
+
+## Search Tools
+@~/.maestro/templates/search-tools.md — Follow search tool priority and selection patterns.
+
+## Process
+
+1. **Load goals** -- Read the phase/task goals, success criteria, must_haves, and `convergence.criteria` from each task JSON
+2. **Layer 1 - Existence** -- Verify all expected artifacts exist:
+   - Files created as specified in task `files[].path` where `files[].action` is "create"
+   - Functions/classes/modules present at `files[].target`
+   - Configuration entries added
+3. **Layer 2 - Substance** -- Verify artifacts are non-trivial:
+   - Files contain meaningful implementation (not stubs or TODOs)
+   - Functions have real logic (not empty bodies or pass-through)
+   - Tests actually test behavior (not empty test cases)
+4. **Layer 3 - Connection** -- Verify artifacts are properly wired:
+   - Imports resolve correctly
+   - New modules are registered/exported
+   - Routes are mounted, handlers are connected
+   - Configuration is loaded and used
+5. **Per-task convergence validation** -- For each completed task, verify every item in `convergence.criteria`:
+   - Run `convergence.verification` command if defined
+   - Check each criterion individually (pass/fail with evidence)
+   - Cross-reference with task summaries in `.summaries/`
+6. **Check must_haves** -- Verify each must_have category:
+   - `truths`: Invariants that must hold
+   - `artifacts`: Files/outputs that must exist
+   - `key_links`: Connections that must be wired
+7. **Write report** -- Output verification.json with results
+
+## Input
+- Phase or task goals with must_haves definition
+- `.task/TASK-{NNN}.json` files with `convergence.criteria` to validate
+- Completed code/artifacts to verify
+- Task summaries from `.summaries/`
+- **Project specs** — `maestro spec load --category quality`: verification criteria, acceptance standards. Must verify code complies with loaded constraints.
+- **Codebase docs** (if `.workflow/codebase/` exists) — Read `ARCHITECTURE.md` for expected module wiring and `FEATURES.md` for component mapping; use in Layer 3 (Connection) checks
+- **Wiki constraints** (if `maestro wiki` available) — `maestro wiki search "architecture constraint"` for documented invariants to include as additional truth checks
+
+## Output
+`verification.json`:
+```json
+{
+  "phase": "<phase-id>",
+  "status": "pass|fail",
+  "layers": {
+    "existence": {"pass": true, "checks": [...]},
+    "substance": {"pass": true, "checks": [...]},
+    "connection": {"pass": false, "checks": [...]}
+  },
+  "convergence_check": {
+    "TASK-001": {
+      "status": "pass",
+      "criteria": [
+        {"criterion": "File src/tools/new-tool.ts exports NewTool class", "pass": true, "evidence": "grep confirms export at line 15"},
+        {"criterion": "npm run build completes without errors", "pass": true, "evidence": "build exit code 0"}
+      ]
+    },
+    "TASK-002": {
+      "status": "fail",
+      "criteria": [
+        {"criterion": "GET /api/health returns 200", "pass": true, "evidence": "curl test passed"},
+        {"criterion": "Response includes version field", "pass": false, "evidence": "Response body missing 'version' key"}
+      ]
+    }
+  },
+  "must_haves": {
+    "truths": [{"claim": "...", "verified": true}],
+    "artifacts": [{"path": "...", "exists": true, "substantial": true}],
+    "key_links": [{"from": "...", "to": "...", "connected": false}]
+  },
+  "gaps": [
+    {"layer": "connection", "description": "Router not mounted in app.ts", "severity": "high", "task": "TASK-002"}
+  ]
+}
+```
+
+## Constraints
+- Read-only; never modify project files
+- Every check must have evidence (file:line reference or command output)
+- Layer 2 checks must go beyond file existence (actually read content)
+- Layer 3 checks must trace import/require chains
+- Verify each `convergence.criteria` item from task JSON individually
+- Report gaps with severity (high/medium/low), specific location, and originating task ID
+- Do not suggest fixes; only identify gaps
+
+## Schema Reference
+- **Task schema**: `templates/task.json` -- Used to locate `convergence.criteria` and `files` for verification
+- Key fields consumed during verification:
+  - `convergence.criteria` -- Array of testable conditions to check per task (replaces deprecated `done_when`)
+  - `convergence.verification` -- Command or steps to run for automated checking
+  - `files[].{path, action, target}` -- Expected file operations to verify
+  - `status` -- Top-level task status (only verify tasks with status "completed")
+- **Verification template**: `templates/verification.json` -- Output format reference
+
+## Output Location
+- **Scratch verification**: `.workflow/scratch/{slug}/verification.json`
+- **Per-task verification**: Embedded in the `convergence_check` block within verification.json (not separate files)
+
+## Error Behavior
+- **Task JSON missing or malformed**: Skip task, log as gap with severity "high" and description "Task definition missing or unreadable"
+- **convergence.verification command fails**: Log command error output as evidence, mark criterion as "fail"
+- **Cannot determine pass/fail for a criterion**: Mark as "inconclusive" with explanation; count as fail for overall status
+- **Build/test environment unavailable**: Log as gap with severity "medium", skip automated checks, perform static checks only
+- **All tasks pass all layers**: Set status to "pass" and report clean verification
+- **Any gap found**: Set status to "fail" regardless of gap severity; list all gaps for resolution

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

@@ -0,0 +1,172 @@
+---
+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:
+  - grep_search
+  - replace_file_content
+  - run_command
+  - view_file
+  - write_to_file
+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 --category coding`, `maestro spec load --keyword <slug>`

package/.agy/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
+view_file("${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/.agy/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_to_file(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/.agy/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 = run_command(`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 = run_command(`maestro spec add ${spec.category} "${spec.title}" "${spec.body}" --keywords "${spec.keywords}" 2>/dev/null`);
+
+  if (cliResult.exitCode !== 0) {
+    // 回退：直接追加到文件
+    replace_file_content(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).