maestro-flow 0.3.43 → 0.3.45

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 --category coding`, `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).

package/.claude/skills/codify-to-knowhow/phases/04-index-verify.md

@@ -0,0 +1,119 @@
+# Phase 4: Index and Verify
+
+刷新 wiki 索引，验证所有创建的资产已正确索引和链接。
+
+## Objective
+
+- 刷新 wiki-index.json 以包含新创建的资产
+- 验证 knowhow 文件存在并已索引
+- 验证 spec 条目已写入
+- 验证 ref 链接从 spec 指向 knowhow
+- 输出完成报告
+
+## Execution
+
+### Step 4.1: Refresh Wiki Index
+
+触发 wiki 索引刷新以识别新增的 knowhow 文件：
+
+```bash
+# 刷新 wiki 索引
+maestro wiki health 2>/dev/null || echo "Wiki index refresh skipped (command not available)"
+```
+
+索引刷新确保 `wiki-index.json` 包含新创建的 AST-/DCS- 文件的 WikiEntry。
+
+### Step 4.2: Verify Knowhow Files
+
+检查所有预期的 knowhow 文件是否存在：
+
+```bash
+echo "=== Knowhow 资产验证 ==="
+
+# 必需文件
+for file in ${knowhowPaths}; do
+  if test -f "$file"; then
+    echo "  OK: $file"
+  else
+    echo "  MISSING: $file"
+  fi
+done
+```
+
+### Step 4.3: Verify Spec Entries
+
+检查 spec 文件中是否包含新增的条目：
+
+```bash
+echo "=== Spec 条目验证 ==="
+
+# 检查 coding-conventions.md 中是否含 slug 相关条目
+grep -c "${slug}" .workflow/specs/coding-conventions.md 2>/dev/null && \
+  echo "  OK: coding-conventions.md (${slug} entries found)" || \
+  echo "  MISSING: No ${slug} entries in coding-conventions.md"
+
+# 检查 architecture-constraints.md 中是否含 slug 相关条目
+grep -c "${slug}" .workflow/specs/architecture-constraints.md 2>/dev/null && \
+  echo "  OK: architecture-constraints.md (${slug} entries found)" || \
+  echo "  MISSING: No ${slug} entries in architecture-constraints.md"
+```
+
+### Step 4.4: Verify Ref Links
+
+检查 spec 条目中的 ref 属性指向的 knowhow 文件是否存在：
+
+```bash
+echo "=== Ref 链接验证 ==="
+
+# 从 spec 文件中提取 ref 属性值
+refs=$(grep -oP 'ref="knowhow/[^"]*"' .workflow/specs/coding-conventions.md .workflow/specs/architecture-constraints.md 2>/dev/null | grep "${slug}" || true)
+
+if [ -n "$refs" ]; then
+  echo "$refs" | while IFS= read -r ref; do
+    # 提取文件路径
+    filepath=$(echo "$ref" | grep -oP 'knowhow/[^"]*')
+    if test -f ".workflow/$filepath"; then
+      echo "  OK: $filepath"
+    else
+      echo "  BROKEN: $filepath (file not found)"
+    fi
+  done
+else
+  echo "  WARNING: No ref links found for ${slug}"
+fi
+```
+
+### Step 4.5: Generate Completion Report
+
+```
+=== Codify to Knowhow 完成 ===
+
+包: {slug}
+来源: {packagePath}
+
+Knowhow 资产:
+  AST-{slug}-tokens.md       — 设计 token 资产
+  AST-{slug}-components.md   — 组件模式资产
+  DCS-{slug}-decisions.md    — 设计决策 {仅当有冲突}
+
+Spec 条目 ({specEntryCount} 条):
+  coding: 颜色约定, 排版约定, 间距约定
+  arch: 组件分类约束{, 设计决策约束 — 仅当有冲突}
+
+Ref 链接: spec → knowhow 桥梁已建立
+Wiki 索引: 已刷新
+
+后续操作:
+  maestro wiki list --category coding    # 按角色浏览
+  maestro spec load --keyword {slug}    # 加载相关 spec
+  maestro wiki load <id>                # 加载详文
+```
+
+## Output
+
+- **Report**: 验证结果（所有资产/条目/链接状态）
+- **TodoWrite**: Mark Phase 4 completed (all tasks done)
+
+## Completion
+
+Codify to Knowhow 已完成。设计包已固化为知识资产。