skillcaddy 0.27.0

package/skills/skillcaddy-manager/scripts/version-manager.cjs

@@ -0,0 +1,146 @@
+#!/usr/bin/env node
+/**
+ * Skillcaddy 版本管理脚本
+ * 用法:
+ *   node version-manager.cjs check      - 检查版本
+ *   node version-manager.cjs sync       - 同步版本号
+ *   node version-manager.cjs changelog  - 查看更新日志
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+// 从 skill 目录向上找到项目根目录
+const skillDir = __dirname; // skills/skillcaddy-manager/scripts
+const skillcaddyRoot = path.resolve(skillDir, '..', '..', '..'); // 回到 skillcaddy 根目录
+
+const dataPath = path.join(skillDir, '..', 'references', 'featured-skills.json');
+const packagePath = path.join(skillcaddyRoot, 'package.json');
+
+console.log('');
+
+function loadJSON(filePath) {
+  try {
+    const content = fs.readFileSync(filePath, 'utf-8');
+    return JSON.parse(content);
+  } catch (err) {
+    console.error(`Error loading ${filePath}:`, err.message);
+    return null;
+  }
+}
+
+function checkVersion() {
+  const data = loadJSON(dataPath);
+  const pkg = loadJSON(packagePath);
+
+  if (!data || !pkg) {
+    console.error('Failed to load version information');
+    process.exit(1);
+  }
+
+  console.log('## 📦 Skillcaddy 版本信息\n');
+  console.log(`**Skillcaddy 版本**: ${pkg.version}`);
+  console.log(`**推荐数据版本**: ${data.version}`);
+  console.log(`**最后更新**: ${data.lastUpdated}\n`);
+
+  if (data.version !== pkg.version) {
+    console.log('⚠️ 版本不匹配!');
+    console.log(`  推荐数据版本: ${data.version}`);
+    console.log(`  当前项目版本: ${pkg.version}`);
+    console.log('\n建议运行: node version-manager.cjs sync\n');
+  } else {
+    console.log('✅ 版本同步\n');
+  }
+}
+
+function showChangelog() {
+  const data = loadJSON(dataPath);
+
+  if (!data || !data.changelog) {
+    console.error('No changelog available');
+    return;
+  }
+
+  console.log('## 📋 更新日志\n');
+
+  data.changelog.forEach(entry => {
+    console.log(`### Version ${entry.version} (${entry.date})`);
+    entry.changes.forEach(change => {
+      console.log(`  - ${change}`);
+    });
+    console.log('');
+  });
+}
+
+function syncVersion() {
+  const pkg = loadJSON(packagePath);
+  const data = loadJSON(dataPath);
+
+  if (!pkg || !data) {
+    console.error('Failed to load files');
+    process.exit(1);
+  }
+
+  console.log('## 🔄 同步版本\n');
+  console.log(`当前项目版本: ${pkg.version}`);
+  console.log(`推荐数据版本: ${data.version}\n`);
+
+  if (data.version === pkg.version) {
+    console.log('✅ 版本已同步,无需更新\n');
+    return;
+  }
+
+  const today = new Date().toISOString().split('T')[0];
+
+  // 同步版本号
+  data.version = pkg.version;
+  data.lastUpdated = today;
+
+  // 添加 changelog 条目
+  const newChange = {
+    version: pkg.version,
+    date: today,
+    changes: [
+      `同步至 Skillcaddy v${pkg.version}`,
+      "更新推荐数据和配置"
+    ]
+  };
+
+  if (!data.changelog) {
+    data.changelog = [];
+  }
+  data.changelog.unshift(newChange);
+
+  // 保存文件
+  fs.writeFileSync(dataPath, JSON.stringify(data, null, 2));
+
+  console.log('✅ 版本已同步\n');
+  console.log('记得提交更改:');
+  console.log('  git add references/featured-skills.json');
+  console.log(`  git commit -m "chore: sync recommendations to v${pkg.version}"`);
+}
+
+// 主程序
+const args = process.argv.slice(2);
+const command = args[0];
+
+switch (command) {
+  case 'check':
+    checkVersion();
+    break;
+
+  case 'sync':
+    syncVersion();
+    break;
+
+  case 'changelog':
+    showChangelog();
+    break;
+
+  default:
+    console.log('Usage:');
+    console.log('  node version-manager.cjs check      - 检查版本同步');
+    console.log('  node version-manager.cjs sync       - 同步版本号');
+    console.log('  node version-manager.cjs changelog  - 查看更新日志');
+    break;
+}

package/skills/skillcaddy-manager/scripts/view-recommendations.cjs

@@ -0,0 +1,279 @@
+#!/usr/bin/env node
+/**
+ * 查看推荐 skills 列表
+ * 用法: node view-recommendations.js [command] [args]
+ *
+ * Commands:
+ *   onboarding         - 查看空库引导
+ *   workflows          - 查看核心工作流推荐
+ *   scenario <name>    - 查看特定场景推荐
+ *   category <name>    - 查看特定分类
+ *   platforms          - 查看平台列表
+ *   all                - 查看所有内容
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+const dataPath = path.join(__dirname, '..', 'references', 'featured-skills.json');
+const platformsPath = path.join(__dirname, '..', 'references', 'skill-platforms.json');
+
+function loadJSON(filePath) {
+  try {
+    const content = fs.readFileSync(filePath, 'utf-8');
+    return JSON.parse(content);
+  } catch (err) {
+    console.error(`Error loading ${filePath}:`, err.message);
+    return null;
+  }
+}
+
+function printEssentialWorkflows(workflows) {
+  console.log('\n## 🎯 核心工作流推荐\n');
+  console.log('仅在明确开发场景时使用:\n');
+
+  for (const [key, workflow] of Object.entries(workflows)) {
+    console.log(`### ${workflow.label}`);
+    console.log(`${workflow.description}\n`);
+
+    workflow.collections.forEach((col, idx) => {
+      const typeIcon = col.type === 'workflow-suite' ? '📦' : '🔧';
+      const priorityLabel = col.priority === 1 ? '【必装】' : '【必装】';
+
+      console.log(`${idx + 1}. ${typeIcon} **${col.name}** ${priorityLabel}`);
+
+      if (col.setupSkill) {
+        console.log(`   ⚡ Setup: ${col.setupSkill} (一键配置)`);
+      }
+
+      console.log(`   📋 包含:`);
+      col.includes.forEach(item => {
+        console.log(`      - ${item}`);
+      });
+
+      console.log(`   🔧 安装: ${col.installCommand}`);
+
+      if (col.installs) {
+        console.log(`   📊 安装量: ${col.installs}`);
+      }
+      console.log('');
+    });
+
+    console.log(`💡 ${workflow.whyThisCombo}\n`);
+    console.log('---\n');
+  }
+}
+
+function printScenarioRecommendation(scenarios, scenarioName) {
+  const scenario = scenarios[scenarioName];
+  if (!scenario) {
+    console.error(`Scenario "${scenarioName}" not found.`);
+    console.log('Available scenarios:', Object.keys(scenarios).join(', '));
+    return;
+  }
+
+  console.log(`\n## 🎯 ${scenario.label}\n`);
+  console.log(`${scenario.description}\n`);
+
+  if (scenario.recommend) {
+    console.log('**推荐安装:**\n');
+
+    if (scenario.recommend.primary) {
+      console.log('核心推荐:');
+      scenario.recommend.primary.forEach((id, idx) => {
+        console.log(`  ${idx + 1}. ${id}`);
+      });
+    }
+
+    if (scenario.recommend.optional) {
+      console.log('\n可选推荐:');
+      scenario.recommend.optional.forEach((id, idx) => {
+        console.log(`  ${idx + 1}. ${id}`);
+      });
+    }
+
+    if (scenario.recommend.why) {
+      console.log(`\n💡 ${scenario.recommend.why}`);
+    }
+  }
+
+  if (scenario.setupSteps) {
+    console.log('\n**安装步骤:**');
+    scenario.setupSteps.forEach(step => {
+      console.log(`  ${step}`);
+    });
+  }
+
+  if (scenario.followUp) {
+    console.log('\n**后续判断:**');
+    scenario.followUp.forEach(step => {
+      console.log(`  - ${step}`);
+    });
+  }
+  console.log('');
+}
+
+function printOnboarding(data, platforms) {
+  console.log('\n## 🧭 空库引导\n');
+  console.log('当用户库里还没有任何 skills 时,先做发现入口推荐,不要直接默认安装具体库。\n');
+
+  if (data.scenarios?.['empty-library']) {
+    printScenarioRecommendation(data.scenarios, 'empty-library');
+  }
+
+  console.log('**推荐平台:**\n');
+  printPlatforms(platforms);
+
+  console.log('**分流原则:**');
+  console.log('  - 无法判断场景: 只给平台和分类入口');
+  console.log('  - 明确是开发项目: 再推荐 mattpocock-workflow 或 lencx-control');
+  console.log('  - 已有少量库: 优先补短板,不要重复推荐同类能力');
+}
+
+function printCollections(collections, category = null, priority = null) {
+  const categories = category ? { [category]: collections[category] } : collections;
+
+  for (const [catName, catData] of Object.entries(categories)) {
+    if (!catData || !catData.collections) continue;
+
+    console.log(`\n## ${catData.label}`);
+    console.log(`${catData.description}\n`);
+
+    const filtered = priority
+      ? catData.collections.filter(c => c.priority === priority)
+      : catData.collections;
+
+    filtered.forEach(col => {
+      const priorityIcon = {
+        essential: '🔥',
+        recommended: '⭐',
+        optional: '📦'
+      }[col.priority] || '•';
+
+      const suiteBadge = col.isSuite ? ' [套件]' : '';
+      console.log(`${priorityIcon} **${col.name}**${suiteBadge} (${col.priority})`);
+
+      if (col.setupSkill) {
+        console.log(`   ⚡ Setup: ${col.setupSkill}`);
+      }
+
+      console.log(`   Repo: ${col.repo}`);
+      console.log(`   Skills: ${col.skills.join(', ')}`);
+      console.log(`   Reason: ${col.reason}`);
+
+      if (col.installs) {
+        console.log(`   Installs: ${col.installs}`);
+      }
+
+      if (col.setupGuide) {
+        console.log(`   📝 Guide: ${col.setupGuide}`);
+      }
+      console.log('');
+    });
+  }
+}
+
+function printPlatforms(platforms) {
+  console.log('\n## 🌐 Skills 平台\n');
+  platforms.platforms.forEach(p => {
+    console.log(`**${p.name}** (${p.url})`);
+    console.log(`  ${p.description}`);
+    console.log(`  适合: ${p.bestFor}`);
+    console.log('');
+  });
+}
+
+function printStrategy(strategy) {
+  console.log('\n## 📋 推荐策略\n');
+  console.log(`**原则**: ${strategy.principle}`);
+  console.log(`**最多推荐**: ${strategy.maxRecommendations} 个库\n`);
+  console.log('要点:');
+  strategy.notes.forEach(note => {
+    console.log(`  - ${note}`);
+  });
+}
+
+// 主程序
+const args = process.argv.slice(2);
+const command = args[0];
+const subCommand = args[1];
+
+const data = loadJSON(dataPath);
+const platforms = loadJSON(platformsPath);
+
+if (!data) {
+  console.error('Failed to load featured-skills.json');
+  process.exit(1);
+}
+
+console.log('# Skillcaddy Recommendations');
+console.log(`Version: ${data.version}`);
+console.log(`Last Updated: ${data.lastUpdated}`);
+
+// 显示推荐策略
+if (data.recommendationStrategy) {
+  printStrategy(data.recommendationStrategy);
+}
+
+switch (command) {
+  case 'onboarding':
+    printOnboarding(data, platforms);
+    break;
+
+  case 'workflows':
+    if (data.essentialWorkflows) {
+      printEssentialWorkflows(data.essentialWorkflows);
+    }
+    break;
+
+  case 'scenario':
+    if (subCommand && data.scenarios) {
+      printScenarioRecommendation(data.scenarios, subCommand);
+    } else {
+      console.log('\n可用场景:');
+      Object.keys(data.scenarios || {}).forEach(key => {
+        const s = data.scenarios[key];
+        console.log(`  - ${key}: ${s.label}`);
+      });
+    }
+    break;
+
+  case 'category':
+    if (subCommand && data.featured) {
+      printCollections(data.featured, subCommand);
+    } else {
+      console.log('\n可用分类:');
+      Object.keys(data.featured || {}).forEach(key => {
+        const c = data.featured[key];
+        console.log(`  - ${key}: ${c.label}`);
+      });
+    }
+    break;
+
+  case 'platforms':
+    printPlatforms(platforms);
+    break;
+
+  case 'all':
+    if (data.essentialWorkflows) {
+      printEssentialWorkflows(data.essentialWorkflows);
+    }
+    if (data.featured) {
+      printCollections(data.featured);
+    }
+    printPlatforms(platforms);
+    break;
+
+  default:
+    printOnboarding(data, platforms);
+
+    console.log('\n---\n');
+    console.log('Usage:');
+    console.log('  node view-recommendations.cjs onboarding         - 空库引导');
+    console.log('  node view-recommendations.cjs workflows          - 核心工作流');
+    console.log('  node view-recommendations.cjs scenario new-project - 特定场景');
+    console.log('  node view-recommendations.cjs category development - 特定分类');
+    console.log('  node view-recommendations.cjs platforms          - 平台列表');
+    console.log('  node view-recommendations.cjs all                - 查看所有');
+    break;
+}

package/skills/skillcaddy-manager/skillcaddy.json

@@ -0,0 +1,9 @@
+{
+  "note": "管理 Skillcaddy skill 原件库、项目启用状态、冲突建议和 Web 管理器操作流程。",
+  "tags": [
+    "Developer Tools",
+    "Productivity",
+    "Workflow"
+  ],
+  "autoEnable": true
+}

package/skills/spec-pipeline/spec-direction-gate/SKILL.md

@@ -0,0 +1,119 @@
+---
+name: spec-direction-gate
+description: 技术方案文档的方向确认关卡。在 specs/<id>/TECH.md 草稿完成、进入实施之前，先确认方向、再确认内容，两次确认分开且有序；把关卡结论写回 TECH.md 作为批准状态的显式记录。拒绝语义：没有人在场就停止并报告，绝不自动放行。用于任何"文档获批才能开始写代码"的环节之前。
+disable-model-invocation: true
+---
+
+# 方向确认关卡（B）
+
+一条流程只有在"方向"这一格真的会挡住它的时候才算成立。这个技能就是那一格。
+
+输入是 `specs/<id>/TECH.md` 的草稿，输出是写回 `TECH.md` 的批准状态记录。中间没有任何自动放行的路径。
+
+## 何时使用
+
+- `TECH.md` 草稿已写完，尚未开始实施
+- 需要在实施前留下"谁在什么时候批准了方向"的可核验记录
+- 复盘时需要确认某个实施是否真的经过方向批准，而不是默认通过
+
+## 何时不使用
+
+- 纯 UI 改动、单文件修复等低复杂度变更，`TECH.md` 本身就不必产出
+- 方向已经单独确认过、这次只是修订若干小节时，改用下面的"增量修订"路径
+
+## 硬性约束
+
+1. **两次确认，不合并。** 先确认方向，确认通过之后才确认内容。合并这一步会破坏关卡：把大纲和方向放在同一次确认里，人会锚定在已经看到的具体大纲上，而不再重新考虑它上位的那个问题。
+2. **拒绝语义。** 没有人在场就停止并报告这个技能需要人，不要"先按草稿往下走，回头再确认"。
+3. **批准要落盘。** 两次确认的结论写进 `TECH.md`，不只留在对话里。实施阶段的验收要能读到"批准后文档仍存活"的证据。
+4. **批准的是方向，不是逐字内容。** 方向确认通过后，作者仍可改实现细节；实施者不得改方向。
+
+## 流程
+
+### 第 0 步：确认在场
+
+先确认当前是有人可以回答的交互会话。
+
+不是交互式会话时：**停下并报告**"这个关卡需要人在场确认方向"，然后结束。不要用默认值代替确认，也不要因为草稿看起来已经足够好就跳过。
+
+### 第 1 步：确认方向
+
+读 `TECH.md`，然后只向人提出**方向层面**的问题，不要展示具体大纲或章节结构：
+
+- 这份文档要解决的问题，和仓库当前状态对得上吗
+- 选定的方案，是这几个候选里最合适的那个吗
+- 哪些明确不在这次范围内
+- 还有什么上位问题，是这份文档答不了的
+
+把问题一次问完，然后等回答。
+
+**方向被拒时的处理**：记录被拒的方向和原因，停止。不要改写成新的大纲再问第二遍——那等于把第一次确认作废。修改草稿后必须从第 1 步重来。
+
+### 第 2 步：确认内容
+
+只有在第 1 步通过后才进入这一步。展示文档的实际章节和每节承担的内容，然后等确认。
+
+内容被拒时：按意见修订，同样从第 1 步重新开始（内容修订可能改变方向）。
+
+### 第 3 步：写回批准状态
+
+两次都通过后，把结论追加到 `TECH.md` 末尾：
+
+```markdown
+## Approval
+
+- 方向确认：通过 / 拒绝（时间：YYYY-MM-DD HH:MM CST，确认人：__）
+- 内容确认：通过 / 拒绝（时间：YYYY-MM-DD HH:MM CST，确认人：__）
+- 本次确认的范围：仅方向与结构。实现细节可由作者调整，方向变更须重新过本关卡。
+```
+
+批准状态是**显式记录**，不是推断依据。没有这段内容，验收阶段必须按"未批准"处理。
+
+写完用同目录的校验脚本自查：
+
+```bash
+python3 check-approval.py specs/<id>/TECH.md
+```
+
+退出码 `0` = 已批准可进入实施；`1` = 挡住（缺 `## Approval`、结论仍是 `通过 / 拒绝` 模板、缺时间戳、方向被拒、结论无法判定）；`2` = 用法错误。
+
+模板里的 `通过 / 拒绝` 必须二选一写死。**两个候选都留着会被判为未批准**——这是有意的，模板没填就等于没确认。
+
+## 实施前的机械检查
+
+上面的约束是文字。文字挡不住无人值守运行，所以本技能附带一个退出码校验：
+
+```bash
+python3 check-approval.py specs/<id>/TECH.md
+```
+
+进入实施之前跑一次，退出码非 `0` 就不要开始写代码。脚本只读不写，不会改文档。
+
+被挡住的常见情况：
+
+- 文件不存在
+- 没有 `## Approval` 段
+- 有 `## Approval` 段但里面没有方向确认结论（**摄入技能产出的就是这个状态**）
+- 结论仍是 `通过 / 拒绝` 模板
+- 通过但没写时间戳（批准必须可核验到"谁在什么时候批准"）
+- 方向被明确拒绝
+- 既不是通过也不是拒绝——按未批准处理
+
+`## Approval` 之后如果还有别的章节，脚本只读到下一个章节标题为止；把"方向确认：通过"藏在后面的章节里不算数。`## Source draft` 之类段落里出现的"通过"也不会被误读成批准。
+
+## 增量修订路径
+
+只改了措辞、补充了行级引用、调整了不影响方向的实施顺序时，不必重走两次确认。在现有的 `## Approval` 段下面追加一条修订记录，写明改了什么、为什么不需要重新确认方向。
+
+判断权在人手上。拿不准就走完整路径。
+
+## 与其他技能的衔接
+
+- 上游：`write-tech-spec` 产出 `TECH.md`（`specs/<id>/` 目录约定）
+- 下游：`implement-specs` 的前置条件只是"approved enough"这种软条件，**不构成关卡**。真正的关卡在这里，跑完本技能才算进入实施
+- 实施期间：`write-tech-spec` 的 *Keep the spec current* 要求 `TECH.md` 随实施同 PR 更新，且**不得删掉 `## Approval` 段**——批准状态是验收阶段要核验的东西
+- 验收阶段：新会话中对照文档验收，不对照对话
+
+## 验收用例
+
+要能构造"方向被拒"的用例，流程必须停止并报告，不得自动续跑。判定依据是对照 `write-feature-docs` 第 449–454 行的拒绝语义：不得重新加入无人值守路径，须停下并报告该技能需要人工在场。

package/skills/spec-pipeline/spec-direction-gate/check-approval.py

@@ -0,0 +1,110 @@
+#!/usr/bin/env python3
+"""
+Direction-confirmation gate check for specs/<id>/TECH.md.
+
+Thin shell over lib/specGate.js (decideApproval), so the decision a developer
+gets locally is the same one the test suite and any CI job assert. The logic
+lives in the repo because personal/ is git-ignored: a CI clone cannot see
+this file at all, so it must not be where the rule is defined.
+
+Exit codes:
+    0  APPROVED  - an `## Approval` section exists and direction is 通过
+    1  BLOCKED   - missing, malformed, or not approved. Do not start implementing.
+    2  USAGE     - wrong invocation (also: gate module not found)
+
+Usage:
+    python3 check-approval.py specs/<id>/TECH.md
+    python3 check-approval.py --quiet specs/<id>/TECH.md   # only the exit code
+
+The script never edits the document. It only reports.
+"""
+
+import json
+import os
+import subprocess
+import sys
+from pathlib import Path
+
+
+def find_repo_root(start: Path):
+    """Locate the checkout that owns lib/specGate.js.
+
+    Search order: upward from the document, then the script's own location,
+    then the current working directory. The middle case matters because a spec
+    can legitimately live outside the repository; without it, every such
+    invocation would fail looking for /some/where/lib/specGate.js instead of
+    reporting a real verdict.
+    """
+    candidates = [start, *start.parents]
+    here = Path(__file__).resolve().parent
+    candidates += [here, *here.parents, Path.cwd(), *Path.cwd().parents]
+    for candidate in candidates:
+        if (candidate / "lib" / "specGate.js").is_file():
+            return candidate
+    return None
+
+
+def decide(root: Path, text):
+    """Ask the JS module for the verdict. Returns (code, reason).
+
+    The document content is piped over stdin rather than passed as an argv
+    entry: paths with spaces or newlines would otherwise need escaping, and
+    argv offsets differ between `node -e` invocation styles.
+    """
+    module = root / "lib" / "specGate.js"
+    helper = (
+        "const { decideApproval } = await import(process.env.SPEC_GATE_MODULE);"
+        "const fs = await import('node:fs');"
+        "const t = fs.readFileSync(0, 'utf8');"
+        "const r = decideApproval(t);"
+        "process.stdout.write(JSON.stringify({ code: r.code, reason: r.reason }));"
+    )
+    env = dict(**os.environ, SPEC_GATE_MODULE=str(module))
+
+    try:
+        result = subprocess.run(
+            ["node", "--input-type=module", "-e", helper],
+            input=text, capture_output=True, text=True, env=env
+        )
+    except FileNotFoundError:
+        raise RuntimeError("找不到 node 可执行文件，无法调用 lib/specGate.js")
+
+    if result.returncode != 0:
+        detail = (result.stderr or "").strip().splitlines()
+        tail = detail[-1] if detail else "unknown error"
+        raise RuntimeError(f"调用 lib/specGate.js 失败：{tail}")
+
+    payload = json.loads(result.stdout)
+    return payload["code"], payload["reason"]
+
+
+def main(argv):
+    args = [a for a in argv[1:] if a != "--quiet"]
+    quiet = "--quiet" in argv[1:]
+
+    if len(args) != 1:
+        print(__doc__.strip(), file=sys.stderr)
+        return 2
+
+    path = Path(args[0])
+    if not path.is_file():
+        code, reason = 1, "BLOCKED: TECH.md 不存在。方向尚未确认，不得进入实施。"
+    else:
+        root = find_repo_root(path.resolve().parent)
+        if root is None:
+            print("USAGE: 找不到 lib/specGate.js，无法判定批准状态。"
+                  "请在本仓库内运行，或确认 lib/specGate.js 存在。", file=sys.stderr)
+            return 2
+        try:
+            code, reason = decide(root, path.read_text(encoding="utf-8"))
+        except RuntimeError as exc:
+            print(f"USAGE: {exc}", file=sys.stderr)
+            return 2
+
+    if not quiet or code != 0:
+        print(reason, file=sys.stdout if code == 0 else sys.stderr)
+    return code
+
+
+if __name__ == "__main__":
+    sys.exit(main(sys.argv))