team-skills 1.0.0

package/skills/using-team-skills/SKILL.md

@@ -0,0 +1,137 @@
+---
+name: using-team-skills
+description: Use when starting any conversation with Team Skills - establishes how to find and use team skills, with skill selection matrix
+---
+
+# Using Team Skills
+
+<SUBAGENT-STOP>
+If you were dispatched as a subagent to execute a specific task, skip this skill.
+</SUBAGENT-STOP>
+
+## 角色定位
+
+你是 Team Skills 的**向导**。你的职责是帮助用户在正确的场景选择正确的 Skill，并确保用户了解 Team Skills 体系的能力边界。
+
+### 系统提示词
+
+```
+你是一个 Team Skills 向导。你的任务是：
+
+1. 理解用户当前场景（需求模糊/明确/已有规格/已有实现/遇到 bug 等）
+2. 根据 Skill 选择矩阵推荐最合适的 Skill
+3. 如果用户不确定，引导使用 team-brainstorm 先讨论
+4. 如果用户需要完整流水线，推荐 team-orchestrator
+
+```
+
+### 推理指引
+
+根据用户描述的当前阶段（需求/规格/实现/测试/审查/调试/完成），从选择矩阵中匹配最合适的 Skill 并说明理由。
+
+## Iron Law
+
+```
+NO SKILL RECOMMENDATION WITHOUT SCENE ANALYSIS FIRST
+```
+
+## 质量职责
+
+| 质量维度 | 产出文件 |
+| -------- | -------- |
+| 场景分析 | 推荐 Skill（对话中） |
+| 推荐理由 | 推荐说明（对话中） |
+
+## Skill 选择矩阵
+
+| 场景 | 推荐 Skill |
+|------|-----------|
+| 需求模糊，先讨论再决定 | team-brainstorm |
+| 需求明确，需完整规格 | team-spec |
+| 规格已有，需 TDD 实现 | team-impl |
+| 实现已有，需测试审计 | team-test |
+| 代码 + 测试已有，需审查 | team-review |
+| 收到代码审查反馈，需应对 | team-feedback |
+| 遇到 bug，需根因分析 | team-debug |
+| 声明完成，需验证门禁 | team-verify |
+| 实现完成，需处理分支 | team-finish |
+| 需完整交付流水线 | team-orchestrator |
+| 评估项目协作成熟度 | team-score |
+
+## 执行步骤
+
+### Step 1：分析用户场景
+
+从用户描述中判断当前所处阶段：
+
+- 需求模糊 → 推荐 `team-brainstorm`
+- 需求明确 → 推荐 `team-spec`
+- 已有规格 → 推荐 `team-impl`
+- 已有实现 → 推荐 `team-test`
+- 已有代码 + 测试 → 推荐 `team-review`
+- 遇到 bug → 推荐 `team-debug`
+- 收到审查反馈 → 推荐 `team-feedback`
+- 实现完成 → 推荐 `team-finish`
+- 需要完整流水线 → 推荐 `team-orchestrator`
+- 评估成熟度 → 推荐 `team-score`
+
+### Step 2：推荐并说明理由
+
+给出推荐 Skill 的同时，说明为什么适合当前场景。
+
+### Step 3：可选 — 展示流程图
+
+如果用户需要了解全貌，展示 Mermaid 流程图。
+
+## 指令优先级
+
+1. **用户显式指令**（CLAUDE.md、直接请求）— 最高优先级
+2. **Team Skills** — 覆盖默认系统行为
+3. **默认系统提示** — 最低优先级
+
+## 使用规则
+
+**Invoke relevant skills BEFORE any response or action.** 即使只有 1% 的可能适用，也应该加载 skill 检查。
+
+## 自检门禁
+
+在推荐 Skill 前执行以下自检：
+
+- [ ] 已分析用户场景（需求/规格/实现/测试/审查/调试/完成？）
+- [ ] 推荐理由与场景匹配
+- [ ] 如果场景模糊，已推荐 team-brainstorm
+- [ ] 如果用户需要完整流水线，已推荐 team-orchestrator
+
+## 完成标志
+
+```
+状态：DONE
+推荐 Skill：{skill-name}
+推荐理由：{reason}
+```
+
+## STOP Signals
+
+如果你发现自己即将做以下任何一件事——立即停止，重新审视：
+
+- 不分析场景就直接推荐 Skill
+- 场景模糊时跳过 team-brainstorm 直接推荐实现类 Skill
+- 凭记忆推荐 Skill 而不读取当前版本的选择矩阵
+
+## 集成关系
+
+**被谁调用：**
+
+- Session hook（会话启动时自动加载）
+- 用户直接调用
+
+**配对使用：**
+
+- `team-brainstorm` — 需求模糊时先讨论
+- `team-orchestrator` — 需要完整流水线时使用
+
+## 下一步
+
+- 根据 Skill 选择矩阵选择对应 skill 开始工作
+- 不确定时使用 `team-brainstorm` 先讨论再决定
+- 需要完整交付流水线时使用 `team-orchestrator`

package/src/cli.js

@@ -0,0 +1,27 @@
+import { Command } from 'commander';
+import { readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { dirname, join } from 'node:path';
+import { registerSetup } from './commands/setup.js';
+import { registerUninstall } from './commands/uninstall.js';
+import { registerInit } from './commands/init.js';
+import { registerUpdate } from './commands/update.js';
+import { registerList } from './commands/list.js';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const pkg = JSON.parse(readFileSync(join(__dirname, '..', 'package.json'), 'utf8'));
+
+const program = new Command();
+
+program
+  .name('team-skills')
+  .description('AI Agent Skills framework — install, manage, and update team skills')
+  .version(pkg.version);
+
+registerSetup(program);
+registerUninstall(program);
+registerInit(program);
+registerUpdate(program);
+registerList(program);
+
+program.parse();

package/src/commands/init.js

@@ -0,0 +1,115 @@
+import { join } from 'node:path';
+import { existsSync } from 'node:fs';
+import {
+  PACKAGE_ROOT, LOCAL_INSTALL_DIR, SKILLS_DIR, HOOKS_DIR, COMMANDS_DIR,
+} from '../lib/constants.js';
+import { discoverSkills, discoverSharedRules, discoverCommands, discoverHooks, discoverSkillsModuleClaude } from '../lib/inventory.js';
+import { copyRecursive, computeDirectoryHashes, ensureDir } from '../lib/fs-utils.js';
+import { createManifest, writeManifest, readManifest, getPackageVersion } from '../lib/manifest.js';
+import * as log from '../lib/logger.js';
+import { copyFileSync as fsCopyFile } from 'node:fs';
+
+export function registerInit(program) {
+  program
+    .command('init')
+    .description('Copy skills into your project for version-controlled local use')
+    .argument('[dir]', 'Project directory', '.')
+    .option('--no-hooks', 'Skip hooks')
+    .option('--no-commands', 'Skip command files')
+    .option('--dry-run', 'Show what would be copied', false)
+    .action(runInit);
+}
+
+function runInit(dir, opts) {
+  const { hooks, commands, dryRun } = opts;
+  const installDir = join(dir, LOCAL_INSTALL_DIR);
+
+  const existing = readManifest(installDir);
+  if (existing) {
+    log.error(`${installDir} 已存在（v${existing.version}）。使用 team-skills update 更新。`);
+    process.exit(1);
+  }
+
+  const tag = dryRun ? '[dry-run] ' : '';
+  let fileCount = 0;
+
+  log.heading('初始化 team-skills 到项目');
+  log.info(`目标目录: ${installDir}`);
+
+  // Copy skills/
+  log.heading('复制 Skills');
+  const skillsSrc = join(PACKAGE_ROOT, SKILLS_DIR);
+  const skillsDst = join(installDir, 'skills');
+  if (dryRun) {
+    log.info(`${tag}${skillsSrc} → ${skillsDst}`);
+  } else {
+    copyRecursive(skillsSrc, skillsDst);
+  }
+  const skills = discoverSkills();
+  const rules = discoverSharedRules();
+  fileCount += skills.length + rules.length;
+  for (const s of skills) log.success(`${tag}Skill: ${s.name}`);
+  for (const r of rules) log.success(`${tag}Rule: ${r.name}`);
+
+  // Copy skills/CLAUDE.md if exists
+  const skillsClaude = discoverSkillsModuleClaude();
+  if (skillsClaude) {
+    if (!dryRun) {
+      fsCopyFile(skillsClaude, join(skillsDst, 'CLAUDE.md'));
+    }
+    log.success(`${tag}skills/CLAUDE.md`);
+    fileCount++;
+  }
+
+  // Copy hooks/
+  if (hooks !== false) {
+    log.heading('复制 Hooks');
+    const hookFiles = discoverHooks();
+    const hooksDst = join(installDir, 'hooks');
+    if (hookFiles.length > 0) {
+      if (!dryRun) ensureDir(hooksDst);
+      for (const h of hookFiles) {
+        if (!dryRun) {
+          fsCopyFile(h.path, join(hooksDst, h.name));
+        }
+        log.success(`${tag}Hook: ${h.name}`);
+        fileCount++;
+      }
+    }
+  }
+
+  // Copy commands/
+  if (commands !== false) {
+    log.heading('复制 Commands');
+    const cmds = discoverCommands();
+    const cmdsDst = join(installDir, 'commands');
+    if (cmds.length > 0) {
+      if (!dryRun) ensureDir(cmdsDst);
+      for (const c of cmds) {
+        if (!dryRun) {
+          fsCopyFile(c.path, join(cmdsDst, c.filename));
+        }
+        log.success(`${tag}Command: ${c.filename}`);
+        fileCount++;
+      }
+    }
+  }
+
+  // Write manifest
+  if (!dryRun) {
+    const hashes = computeDirectoryHashes(installDir);
+    const manifest = createManifest(getPackageVersion(), hashes);
+    writeManifest(installDir, manifest);
+    log.success('manifest.json 已生成');
+  }
+
+  log.done(`初始化完成${dryRun ? ' (dry-run)' : ''}！共 ${fileCount} 个组件。`);
+
+  console.log(`
+集成说明:
+  Cursor:     将 ${installDir}/skills 设为 agent skills 目录
+  Claude Code: 将 ${installDir}/commands/*.md 链接到 .claude/commands/
+  Hooks:      将 ${installDir}/hooks/ 链接到 ~/.cursor/hooks/ 或 ~/.claude/hooks/
+  更新:       运行 team-skills update
+`);
+}

package/src/commands/list.js

@@ -0,0 +1,150 @@
+import { join } from 'node:path';
+import { existsSync, readlinkSync } from 'node:fs';
+import {
+  DEFAULT_SKILLS_TARGET, DEFAULT_COMMANDS_TARGET,
+  CURSOR_HOOKS_DIR, CLAUDE_HOOKS_DIR, LOCAL_INSTALL_DIR,
+} from '../lib/constants.js';
+import { discoverSkills, discoverSharedRules, discoverCommands, discoverHooks } from '../lib/inventory.js';
+import { isSymlink } from '../lib/fs-utils.js';
+import { readManifest } from '../lib/manifest.js';
+import * as log from '../lib/logger.js';
+
+export function registerList(program) {
+  program
+    .command('list')
+    .description('List installed skills and their status')
+    .option('--target <dir>', 'Check a specific target directory', DEFAULT_SKILLS_TARGET)
+    .option('--json', 'Output as JSON')
+    .action(runList);
+}
+
+function runList(opts) {
+  const { target, json } = opts;
+  const results = { skills: [], rules: [], commands: [], hooks: [], localInit: null };
+
+  // Check symlink-based install
+  const skills = discoverSkills();
+  for (const skill of skills) {
+    const dest = join(target, skill.name);
+    results.skills.push({
+      name: skill.name,
+      type: 'symlink',
+      status: getStatus(dest, skill.path),
+      path: dest,
+    });
+  }
+
+  // Shared rules
+  for (const rule of discoverSharedRules()) {
+    const dest = join(target, '_team-rules', rule.name);
+    results.rules.push({
+      name: rule.name,
+      status: getStatus(dest, rule.path),
+      path: dest,
+    });
+  }
+
+  // Commands
+  for (const cmd of discoverCommands()) {
+    const dest = join(DEFAULT_COMMANDS_TARGET, cmd.filename);
+    results.commands.push({
+      name: cmd.name,
+      status: getStatus(dest, cmd.path),
+      path: dest,
+    });
+  }
+
+  // Hooks
+  for (const dir of [CURSOR_HOOKS_DIR, CLAUDE_HOOKS_DIR]) {
+    const platform = dir.includes('.cursor') ? 'Cursor' : 'Claude Code';
+    for (const hook of discoverHooks()) {
+      const dest = join(dir, hook.name);
+      results.hooks.push({
+        name: `${platform}/${hook.name}`,
+        status: getStatus(dest, hook.path),
+        path: dest,
+      });
+    }
+  }
+
+  // Check for local init
+  const localManifest = readManifest(LOCAL_INSTALL_DIR);
+  if (localManifest) {
+    results.localInit = {
+      version: localManifest.version,
+      installedAt: localManifest.installedAt,
+      sourceCommit: localManifest.sourceCommit,
+      fileCount: Object.keys(localManifest.files).length,
+    };
+  }
+
+  if (json) {
+    console.log(JSON.stringify(results, null, 2));
+    return;
+  }
+
+  // Pretty print
+  log.heading('Agent Skills');
+  printTable(results.skills);
+
+  log.heading('共享规则');
+  printTable(results.rules);
+
+  log.heading('Claude Code 命令');
+  printTable(results.commands);
+
+  log.heading('Hooks');
+  printTable(results.hooks);
+
+  if (results.localInit) {
+    log.heading('项目内安装 (.team-skills/)');
+    log.info(`版本: ${results.localInit.version}`);
+    log.info(`安装时间: ${results.localInit.installedAt}`);
+    log.info(`来源 commit: ${results.localInit.sourceCommit}`);
+    log.info(`文件数: ${results.localInit.fileCount}`);
+  }
+
+  // Summary
+  const installed = results.skills.filter(s => s.status === 'ok').length;
+  const total = results.skills.length;
+  console.log(`\nSkills: ${installed}/${total} 已安装`);
+}
+
+function getStatus(dest, expectedSource) {
+  if (!existsSync(dest) && !isSymlink(dest)) return 'missing';
+  if (isSymlink(dest)) {
+    try {
+      const actual = readlinkSync(dest);
+      if (actual === expectedSource) return 'ok';
+      return 'foreign';
+    } catch {
+      return 'broken';
+    }
+  }
+  return 'file';
+}
+
+function printTable(items) {
+  if (items.length === 0) {
+    log.skip('（无）');
+    return;
+  }
+
+  const maxName = Math.max(...items.map(i => i.name.length), 4);
+  for (const item of items) {
+    const name = item.name.padEnd(maxName);
+    const icon = statusIcon(item.status);
+    console.log(`  ${icon} ${name}  ${item.path}`);
+  }
+}
+
+function statusIcon(status) {
+  switch (status) {
+    case 'ok': return '\x1b[32m✓\x1b[0m';
+    case 'missing': return '\x1b[90m✗\x1b[0m';
+    case 'broken': return '\x1b[31m!\x1b[0m';
+    case 'foreign': return '\x1b[33m?\x1b[0m';
+    case 'file': return '\x1b[36m◆\x1b[0m';
+    default: return ' ';
+  }
+}

package/src/commands/setup.js

@@ -0,0 +1,125 @@
+import { join } from 'node:path';
+import {
+  PACKAGE_ROOT, DEFAULT_SKILLS_TARGET, DEFAULT_COMMANDS_TARGET,
+  CURSOR_HOOKS_DIR, CLAUDE_HOOKS_DIR,
+} from '../lib/constants.js';
+import { discoverSkills, discoverSharedRules, discoverCommands, discoverHooks } from '../lib/inventory.js';
+import { createSymlinkSafe, ensureDir, isSymlink } from '../lib/fs-utils.js';
+import * as log from '../lib/logger.js';
+
+export function registerSetup(program) {
+  program
+    .command('setup')
+    .description('Install skills via symlinks to global directories (developer mode)')
+    .argument('[target]', 'Target skills directory', DEFAULT_SKILLS_TARGET)
+    .option('--no-hooks', 'Skip hook installation')
+    .option('--no-commands', 'Skip Claude Code command symlinks')
+    .option('--force', 'Overwrite existing symlinks', false)
+    .option('--dry-run', 'Show what would be done without doing it', false)
+    .action(runSetup);
+}
+
+function runSetup(target, opts) {
+  const { hooks, commands, force, dryRun } = opts;
+  const tag = dryRun ? '[dry-run] ' : '';
+  let count = 0;
+
+  log.heading('安装 Agent Skills');
+  const skills = discoverSkills();
+  for (const skill of skills) {
+    const dest = join(target, skill.name);
+    const result = createSymlinkSafe(skill.path, dest, { force, dryRun });
+    logResult(`${tag}Skill: ${skill.name}`, result, dest);
+    if (result === 'created' || result === 'dry-run') count++;
+  }
+
+  log.heading('安装共享规则 (_team-rules)');
+  const rules = discoverSharedRules();
+  const rulesTarget = join(target, '_team-rules');
+  if (!dryRun) ensureDir(rulesTarget);
+  for (const rule of rules) {
+    const dest = join(rulesTarget, rule.name);
+    const result = createSymlinkSafe(rule.path, dest, { force, dryRun });
+    logResult(`${tag}Rule: ${rule.name}`, result, dest);
+    if (result === 'created' || result === 'dry-run') count++;
+  }
+
+  if (commands !== false) {
+    log.heading('安装 Commands（Skill 形式 + Claude Code 斜杠命令）');
+    const cmds = discoverCommands();
+    for (const cmd of cmds) {
+      // As Skill directory (for Cursor discovery)
+      const skillDest = join(target, cmd.name);
+      if (isSymlink(skillDest)) {
+        log.skip(`Command Skill ${cmd.name} 跳过：已存在同名 Skill 目录`);
+      } else {
+        if (!dryRun) ensureDir(skillDest);
+        const dest = join(skillDest, 'SKILL.md');
+        const result = createSymlinkSafe(cmd.path, dest, { force, dryRun });
+        logResult(`${tag}Command Skill: ${cmd.name}`, result, dest);
+        if (result === 'created' || result === 'dry-run') count++;
+      }
+
+      // As Claude Code command
+      const cmdDest = join(DEFAULT_COMMANDS_TARGET, cmd.filename);
+      if (!dryRun) ensureDir(DEFAULT_COMMANDS_TARGET);
+      const result = createSymlinkSafe(cmd.path, cmdDest, { force, dryRun });
+      logResult(`${tag}Claude Command: ${cmd.filename}`, result, cmdDest);
+      if (result === 'created' || result === 'dry-run') count++;
+    }
+  }
+
+  if (hooks !== false) {
+    log.heading('安装 Hooks');
+    const hookFiles = discoverHooks();
+    for (const dir of [CURSOR_HOOKS_DIR, CLAUDE_HOOKS_DIR]) {
+      const platform = dir.includes('.cursor') ? 'Cursor' : 'Claude Code';
+      if (!dryRun) ensureDir(dir);
+      for (const hook of hookFiles) {
+        const dest = join(dir, hook.name);
+        const result = createSymlinkSafe(hook.path, dest, { force, dryRun });
+        logResult(`${tag}${platform} ${hook.name}`, result, dest);
+        if (result === 'created' || result === 'dry-run') count++;
+      }
+    }
+  }
+
+  log.heading('验证安装');
+  let errors = 0;
+  for (const skill of skills) {
+    const dest = join(target, skill.name);
+    if (isSymlink(dest)) {
+      log.success(`${skill.name}`);
+    } else if (!dryRun) {
+      log.error(`${skill.name} 未正确安装`);
+      errors++;
+    }
+  }
+
+  if (errors > 0) {
+    log.error(`有 ${errors} 个组件安装异常，请检查。`);
+    process.exit(1);
+  }
+
+  log.done(`安装完成！${dryRun ? '(dry-run)' : `共处理 ${count} 个组件。`}`);
+  if (!dryRun) {
+    console.log('\n后续可通过 team-skills setup 重新安装，或 team-skills uninstall 卸载。');
+  }
+}
+
+function logResult(label, result, dest) {
+  switch (result) {
+    case 'created':
+    case 'dry-run':
+      log.success(label);
+      break;
+    case 'exists':
+      log.skip(`${label}（已存在，跳过）`);
+      break;
+    case 'conflict':
+      log.warn(`${label}（已存在非 symlink，使用 --force 覆盖）`);
+      break;
+    default:
+      log.info(label);
+  }
+}

package/src/commands/uninstall.js

@@ -0,0 +1,113 @@
+import { join } from 'node:path';
+import { readdirSync } from 'node:fs';
+import {
+  PACKAGE_ROOT, DEFAULT_SKILLS_TARGET, DEFAULT_COMMANDS_TARGET,
+  CURSOR_HOOKS_DIR, CLAUDE_HOOKS_DIR,
+} from '../lib/constants.js';
+import { discoverSkills, discoverSharedRules, discoverCommands, discoverHooks } from '../lib/inventory.js';
+import { removeSymlinkSafe, rmdirIfEmpty } from '../lib/fs-utils.js';
+import * as log from '../lib/logger.js';
+
+export function registerUninstall(program) {
+  program
+    .command('uninstall')
+    .description('Remove all team-skills symlinks')
+    .argument('[target]', 'Target skills directory', DEFAULT_SKILLS_TARGET)
+    .option('--keep-hooks', 'Do not remove hooks')
+    .option('--keep-commands', 'Do not remove Claude Code commands')
+    .option('--dry-run', 'Show what would be removed', false)
+    .action(runUninstall);
+}
+
+function runUninstall(target, opts) {
+  const { keepHooks, keepCommands, dryRun } = opts;
+  let removed = 0;
+
+  log.heading('移除 Agent Skills');
+  for (const skill of discoverSkills()) {
+    const dest = join(target, skill.name);
+    if (dryRun) {
+      log.info(`[dry-run] 将移除: ${dest}`);
+      removed++;
+      continue;
+    }
+    const result = removeSymlinkSafe(dest, skill.path);
+    if (result === 'removed') {
+      log.success(`Skill: ${skill.name}`);
+      removed++;
+    } else if (result === 'foreign') {
+      log.skip(`${skill.name}（指向其他来源，跳过）`);
+    }
+  }
+
+  log.heading('移除共享规则');
+  for (const rule of discoverSharedRules()) {
+    const dest = join(target, '_team-rules', rule.name);
+    if (dryRun) {
+      log.info(`[dry-run] 将移除: ${dest}`);
+      removed++;
+      continue;
+    }
+    const result = removeSymlinkSafe(dest, rule.path);
+    if (result === 'removed') {
+      log.success(`Rule: ${rule.name}`);
+      removed++;
+    }
+  }
+  if (!dryRun) rmdirIfEmpty(join(target, '_team-rules'));
+
+  if (!keepCommands) {
+    log.heading('移除 Command Skills + Claude Code 命令');
+    for (const cmd of discoverCommands()) {
+      // Command Skill directory
+      const skillDest = join(target, cmd.name, 'SKILL.md');
+      if (!dryRun) {
+        const result = removeSymlinkSafe(skillDest, cmd.path);
+        if (result === 'removed') {
+          log.success(`Command Skill: ${cmd.name}`);
+          removed++;
+          rmdirIfEmpty(join(target, cmd.name));
+        }
+      } else {
+        log.info(`[dry-run] 将移除: ${skillDest}`);
+        removed++;
+      }
+
+      // Claude Code command
+      const cmdDest = join(DEFAULT_COMMANDS_TARGET, cmd.filename);
+      if (!dryRun) {
+        const result = removeSymlinkSafe(cmdDest, cmd.path);
+        if (result === 'removed') {
+          log.success(`Claude Command: ${cmd.filename}`);
+          removed++;
+        }
+      } else {
+        log.info(`[dry-run] 将移除: ${cmdDest}`);
+        removed++;
+      }
+    }
+  }
+
+  if (!keepHooks) {
+    log.heading('移除 Hooks');
+    const hookFiles = discoverHooks();
+    for (const dir of [CURSOR_HOOKS_DIR, CLAUDE_HOOKS_DIR]) {
+      for (const hook of hookFiles) {
+        const dest = join(dir, hook.name);
+        if (!dryRun) {
+          const result = removeSymlinkSafe(dest, hook.path);
+          if (result === 'removed') {
+            log.success(`Hook: ${dest}`);
+            removed++;
+          }
+        } else {
+          log.info(`[dry-run] 将移除: ${dest}`);
+          removed++;
+        }
+      }
+    }
+  }
+
+  log.done(`卸载完成${dryRun ? ' (dry-run)' : ''}，共移除 ${removed} 个软链接。`);
+  if (!dryRun) console.log('本仓库源文件未受影响。');
+}