team-skills 1.0.0

package/README.md

@@ -0,0 +1,421 @@
+<div align="center">
+
+# Team Skills
+
+**让 AI Agent 团队像专业开发团队一样协作**
+
+[![GitHub stars](https://img.shields.io/badge/dynamic/json?logo=github&label=Stars&style=flat-square&color=blue&query=%24.stargazers_count&url=https%3A%2F%2Fapi.github.com%2Frepos%2Fandeya%2Fteam-skills)](https://github.com/andeya/team-skills)
+[![CI](https://img.shields.io/github/actions/workflow/status/andeya/team-skills/ci.yml?branch=master&style=flat-square&label=CI)](https://github.com/andeya/team-skills/actions)
+[![License](https://img.shields.io/badge/license-MIT-green?style=flat-square)](LICENSE)
+[![Claude Code](https://img.shields.io/badge/Claude%20Code-Ready-purple?style=flat-square)](https://claude.ai)
+[![Cursor](https://img.shields.io/badge/Cursor-Ready-orange?style=flat-square)](https://cursor.sh)
+[![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen?style=flat-square)](CONTRIBUTING.md)
+[![Conventional Commits](https://img.shields.io/badge/Conventional%20Commits-1.0.0-yellow?style=flat-square)](https://conventionalcommits.org)
+
+**Spec-Driven · 有向图回退 · 质量门禁 · 100 分制评分**
+
+</div>
+
+---
+
+## 🤔 你是否有过这些经历？
+
+| 场景 | 传统做法 | 结果 |
+|------|----------|------|
+| 给 AI 一句话就写代码 | AI 产出随机，改 5 轮才接近需求 | ❌ 浪费时间 |
+| AI 说"测试通过了" | 你相信了，结果 CI 全红 | ❌ 信任崩塌 |
+| Review 发现 bug | 只能手动修，没有回退机制 | ❌ 重复劳动 |
+| 换了 session 一切归零 | 规则不沉淀，每次从零开始 | ❌ 没有积累 |
+| 不知道项目做得好不好 | 凭感觉判断 | ❌ 无法量化 |
+
+**Team Skills 用工程化的方式解决了这些问题。**
+
+---
+
+## ✨ 为什么 Team Skills 与众不同？
+
+### 🎯 Spec-Driven，不是 Chat-Driven
+
+```
+传统方式：用户 → AI（一句话）→ 代码（随机产出）
+Team Skills：用户 → H1确认 → SDD规格 → H2确认 → TDD实现 → 测试 → Review → H4验收
+```
+
+每个环节有明确的输入/输出标准，AI 不是"猜需求"，而是**执行规格**。
+
+### 🔄 有向图回退，不是线性流水线
+
+```
+testAgent 发现 bug ──→ 自动回退 implAgent
+reviewAgent 发现 spec 遗漏 ──→ 自动回退 specAgent
+同一阶段回退 ≤ 2 次，超过触发人类介入
+```
+
+**发现问题立即回退，不是"先记着后面修"**。
+
+### 🛡️ 质量门禁，不是"我觉得"
+
+- **5 步验证协议**：确定命令 → 新鲜执行 → 完整阅读 → 检查退出码 → 声明通过
+- **8 条 Constitutional Rules**：不可覆盖的硬约束
+- **反规避条款**：预判 6 种常见借口并逐一反驳
+- **三视角对抗审查**：攻击者/怀疑者/用户视角反向验证
+
+### 📊 100 分制评分，不是凭感觉
+
+```
+7 项硬门槛（任一不通过则整体不通过）
+5 个维度 × 25 子项
+每个子项有可检查的证据要求
+```
+
+---
+
+## 🚀 安装与使用
+
+### 前置条件
+
+- **Node.js** >= 18
+- **Claude Code** 或 **Cursor**：至少安装其中之一
+
+### 方式一：npx 安装（推荐）
+
+无需 clone 仓库，直接全局安装 Skills：
+
+```bash
+npx team-skills setup
+```
+
+### 方式二：clone 后安装
+
+```bash
+git clone https://github.com/andeya/team-skills.git
+cd team-skills
+npm install
+npm run setup
+```
+
+### 方式三：初始化到项目（版本控制）
+
+将 Skills 复制到你的项目中，可以版本控制和自定义：
+
+```bash
+npx team-skills init
+# 或在已 clone 的仓库中
+node bin/team-skills.js init /path/to/your-project
+```
+
+这会在项目中创建 `.team-skills/` 目录，包含所有 Skills、Hooks 和命令文件。
+
+### 安装内容
+
+| 安装内容 | 说明 |
+|----------|------|
+| 12 个 Agent Skills | 安装到 `~/.agents/skills/`，Cursor 自动发现 |
+| 斜杠命令 | 安装到 `~/.claude/commands/`，Claude Code 可用 `/team-{name}` |
+| 共享规则 | `_team-rules/` 被所有 Skill 引用 |
+| Hooks（可选） | session-start 钩子，每次新 session 自动加载 |
+
+### CLI 命令
+
+| 命令 | 说明 |
+|------|------|
+| `team-skills setup [target]` | symlink 安装到全局目录（开发者模式） |
+| `team-skills init [dir]` | 复制到用户项目（消费者模式） |
+| `team-skills update [dir]` | 增量更新 init 的副本 |
+| `team-skills uninstall [target]` | 移除所有 symlink |
+| `team-skills list` | 列出已安装 Skills 及状态 |
+| `team-skills --version` | 显示版本 |
+
+所有命令支持 `--dry-run` 查看将执行的操作。
+
+### 验证安装
+
+安装后，在聊天框中输入 `/` 查看是否出现 `team-` 开头的命令列表。或使用 CLI 检查：
+
+```bash
+team-skills list
+
+# 或在 Claude Code / Cursor 中
+/using-team-skills
+
+# 评估项目协作成熟度
+/team-score
+```
+
+### 更新 Skills
+
+```bash
+# npx 安装用户
+npx team-skills setup
+
+# 项目内 init 用户
+npx team-skills update
+
+# clone 安装用户
+git pull && npm run setup
+```
+
+### 使用方式
+
+#### 方式一：全自动编排（推荐）
+
+一条命令启动完整流水线，适合从零开始的功能开发：
+
+```bash
+/team-orchestrator 实现用户登录功能
+```
+
+编排器会自动完成 7 个步骤：
+
+```
+
+1. H1: 向你确认目标理解
+2. specAgent: 产出 SDD 规格
+3. H2: 向你确认规格方案
+4. implAgent: TDD 实现
+5. testAgent: 四维测试
+6. reviewAgent: 五维审查
+7. H4: 向你交付验收
+
+```
+
+简单任务可用精简模式（H1 简化为单句确认，跳过 H2，H4 保留）：
+
+```bash
+/team-orchestrator --compact 修复登录页按钮样式
+```
+
+#### 方式二：按需调用单个 Skill
+
+你可以在任意阶段单独调用某个 Skill，适合只想做其中一步的场景：
+
+| 场景 | 命令 |
+|------|------|
+| 需求模糊，需要讨论 | `/team-brainstorm 这个功能怎么做？` |
+| 一句话需求展开为规格 | `/team-spec 实现登录功能` |
+| 已有规格，开始编码 | `/team-impl` |
+| 测试覆盖够吗？ | `/team-test` |
+| 代码质量如何？ | `/team-review` |
+| 这个 bug 怎么回事？ | `/team-debug` |
+| 测试真的过了吗？ | `/team-verify` |
+| Review 反馈来了 | `/team-feedback` |
+| 代码写完了 | `/team-finish` |
+| 不知道用哪个 | `/using-team-skills` |
+
+#### 方式三：评估项目成熟度
+
+```bash
+/team-score
+# 输出 100 分制评分报告 + 改进建议
+```
+
+---
+
+## 🏗️ 核心架构
+
+```mermaid
+flowchart TD
+    classDef human fill:#e3f2fd,stroke:#1565c0,stroke-width:2px,color:#1565c0;
+    classDef agent fill:#f3e5f5,stroke:#7b1fa2,stroke-width:2px,color:#4a148c;
+    classDef kill fill:#ffebee,stroke:#c62828,stroke-width:2px,stroke-dasharray: 5 5,color:#b71c1c;
+
+    START(("用户提出需求"))
+    H1["H1: 人类确认目标理解<br/>← 人类介入点 #1"]:::human
+    SPEC["specAgent — 规格制定<br/>产出 01-05 + prompt-template<br/>Socratic 提问 → SDD 规格"]:::agent
+    H2["H2: 人类确认规格方案<br/>← 人类介入点 #2"]:::human
+    IMPL["implAgent — TDD 实现<br/>红-绿-重构循环<br/>增量提交 + 决策记录"]:::agent
+    TEST["testAgent — 四维测试<br/>功能/边界/异常/代码分支"]:::agent
+    REVIEW["reviewAgent — 五维审查<br/>资产沉淀 + 复盘"]:::agent
+    H4["H4: 人类验收交付物<br/>← 人类介入点 #4"]:::human
+    H3("H3: 人类介入 #3<br/>阻塞 / 决策 / Kill Switch"):::human
+
+    START --> H1
+    H1 -->|确认| SPEC
+    H1 -->|不确认| START
+
+    SPEC --> H2
+    H2 -->|确认| IMPL
+    H2 -->|不确认| SPEC
+    H2 -.->|Kill Switch| H3
+
+    IMPL --> TEST
+
+    TEST -->|全部通过| REVIEW
+    TEST -->|发现 bug| IMPL
+    TEST -->|spec 遗漏| SPEC
+    TEST -.->|不可行| H3
+
+    REVIEW -->|无问题| H4
+    REVIEW -->|P0/P1| IMPL
+    REVIEW -->|spec 遗漏| SPEC
+    REVIEW -.->|不可行| H3
+
+    H4 -->|验收通过| DONE(("完成 ✅"))
+    H4 -->|不通过| IMPL
+```
+
+> H3 可在**任何阶段**触发，包括：发现任务不可行（Kill Switch）、回退超限、或需要人类决策的复杂问题。
+
+---
+
+## 🗺️ Skill 使用地图
+
+> 从你的场景出发，找到对应的 Skill。实线是你主动调用，虚线是编排器自动调度。
+
+```mermaid
+graph TD
+    classDef user fill:#e3f2fd,stroke:#1565c0,stroke-width:3px,color:#1565c0;
+    classDef skill fill:#f3e5f5,stroke:#7b1fa2,stroke-width:2px,color:#4a148c;
+    classDef orch fill:#fff3e0,stroke:#e65100,stroke-width:3px,color:#bf360c;
+
+    YOU((👤 你)):::user
+    YOU -->|"判断你的场景"| Q{你处于哪个阶段？}
+
+    Q -->|"需求模糊，需要讨论"| BRAIN[🧠 team-brainstorm<br/>→ 设计思路]:::skill
+    Q -->|"需求明确，需要规格"| SPEC[📝 team-spec<br/>→ SDD 规格文档]:::skill
+    Q -->|"规格就绪，需要实现"| IMPL[💻 team-impl<br/>→ 代码 + TDD 日志]:::skill
+    Q -->|"实现完成，需要测试"| TEST[🧪 team-test<br/>→ 四维测试报告]:::skill
+    Q -->|"代码就绪，需要审查"| REVIEW[🔍 team-review<br/>→ 五维审查报告]:::skill
+    Q -->|"收到审查反馈"| FB[💬 team-feedback<br/>→ 修改方案]:::skill
+    Q -->|"遇到 Bug"| DEBUG[🐛 team-debug<br/>→ 根因分析 + 修复]:::skill
+    Q -->|"实现完成，准备合并"| FINISH[🏁 team-finish<br/>→ 合并/PR/清理]:::skill
+    Q -->|"声称完成"| VERIFY[✅ team-verify<br/>→ 验证证据链]:::skill
+    Q -->|"评估项目成熟度"| SCORE[📊 team-score<br/>→ 100 分制评分]:::skill
+    Q -->|"不知道用哪个"| USING[🧭 using-team-skills<br/>→ Skill 推荐]:::skill
+    Q -->|"需要完整交付流水线"| ORCH[⚙️ team-orchestrator<br/>→ 全自动编排]:::orch
+
+    ORCH -.->|自动调度| SPEC
+    ORCH -.->|自动调度| IMPL
+    ORCH -.->|自动调度| TEST
+    ORCH -.->|自动调度| REVIEW
+    ORCH -.->|自动调度| FB
+    ORCH -.->|自动调度| FINISH
+    ORCH -.->|自动调度| VERIFY
+```
+
+**使用说明：**
+
+- **实线箭头 →**：你主动调用某个 Skill，适合只做其中一步
+- **虚线箭头 ⇢**：编排器自动调度，适合需要完整流水线
+- 每个 Skill 下方标注了它的产出物
+
+---
+
+## 📦 包含 12 个可独立使用的 Skill
+
+| Skill | 一句话说明 | 使用场景 |
+|-------|-----------|----------|
+| `team-brainstorm` | 需求模糊时讨论形成方案 | "这个功能怎么做？" |
+| `team-spec` | 一句话需求展开为完整 SDD 规格 | "实现登录功能" |
+| `team-impl` | TDD 红-绿-重构循环实现 | "规格有了，开始写代码" |
+| `team-test` | 四维测试矩阵 + 补充测试 | "测试覆盖够吗？" |
+| `team-review` | 五维审查 + 资产沉淀 + 复盘 | "代码质量如何？" |
+| `team-orchestrator` | 有向图流程编排，4 个人类介入点 | "我要完整交付流水线" |
+| `team-verify` | 5 步验证门禁，杜绝虚假通过 | "测试真的过了吗？" |
+| `team-debug` | 四阶段根因分析 + 修复 | "这个 bug 怎么回事？" |
+| `team-feedback` | 先验证再实施，非表演性同意 | "Review 反馈来了" |
+| `team-finish` | 分支完成处理（合并/PR/保留/丢弃） | "代码写完了" |
+| `team-score` | 100 分制扫描评估 | "项目协作成熟度如何？" |
+| `using-team-skills` | Meta-skill，自动引导你选正确的 Skill | "我该用哪个？" |
+
+> 每个 Skill 可独立使用，也可通过 `team-orchestrator` 串联成完整流水线。
+
+---
+
+## 📋 每个任务产出 17 个结构化文档
+
+```
+docs/tasks/{slug}/
+├── 01-plan.md              # 任务规划（目标 + 分期 + 预算）
+├── 02-context.md           # 上下文选择（术语 + 引用 + 排除）
+├── 03-sdd.md               # SDD 规格（七部分完整）
+├── 04-boundary.md          # 修改边界（allow + deny）
+├── 05-risk.md              # 风险 + 验证计划
+├── prompt-template.md      # AI 任务提示词模板
+├── 06-tdd-log.md           # TDD 日志（红-绿-重构循环）
+├── 07-prompt-log.md        # Prompt 工程记录（五要素 + 纠偏）
+├── 08-ai-decisions.md      # AI 决策记录（选择 + 拒绝 + 理由）
+├── 09-test-matrix.md       # 四维测试矩阵
+├── 10-test-report.md       # 测试运行报告（证据链）
+├── 11-review.md            # 代码审查报告（五维度 + 合规）
+├── 12-asset-update.md      # 资产更新记录（消费方契约）
+├── 13-retrospective.md     # 个人复盘（新规则沉淀）
+├── task-rules.md           # 任务级规则
+├── 14-team.md              # 团队协作记录
+└── 15-brief.md             # 答辩提纲
+```
+
+---
+
+## 🔧 兼容性
+
+| 工具 | 调用方式 | 自动发现 |
+|------|----------|----------|
+| **Claude Code** | `/team-{name}` 斜杠命令 | `~/.claude/commands/` |
+| **Cursor** | Skill 自动发现 | `~/.agents/skills/` |
+
+---
+
+## 📚 体系来源
+
+Team Skills 融合了业界多个 AI 协作框架的精华：
+
+| 来源 | 吸收的精华 |
+|------|-----------|
+| **SuperPowers** (obra) | 5 步验证协议、四态完成状态、反规避条款、Socratic 探索 |
+| **OpenSpec** (Fission AI) | Delta Spec 增量规格、RFC 2119 + Given/When/Then |
+| **Karpathy Skills** | 过度抽象防御、死代码清理、困惑管理 |
+| **Agent-Style** | 5 条 LLM 输出质量约束 |
+| **独创** | 有向图回退、评分追溯矩阵、消费方契约、H1-H4 人类介入点 |
+
+---
+
+## 🔧 本地开发
+
+### 前置要求
+
+- Node.js >= 18
+
+### 安装依赖
+
+```bash
+npm install
+```
+
+### 开发命令
+
+```bash
+npm run lint       # 检查 Markdown 格式 + Skill 结构完整性（CI 同款）
+npm run format     # 自动修复 Markdown 格式
+npm run cli-test   # CLI 冒烟测试
+npm run setup      # 安装 Skills 到全局目录
+```
+
+### CI 流程
+
+提交后 GitHub Actions 自动运行：
+
+| Workflow | Job | 说明 |
+|----------|-----|------|
+| CI | Lint | Markdown 格式 + Skill 结构检查 |
+| CI | CLI Smoke Test | CLI 功能验证 |
+| CI | Check Links | 外部链接有效性 |
+| Release | Publish to npm | `v*` tag 触发，自动发布到 npm |
+
+---
+
+## 🤝 贡献
+
+欢迎贡献！请先阅读 [CONTRIBUTING.md](CONTRIBUTING.md)。
+
+- 🐛 [报告 Bug](https://github.com/andeya/team-skills/issues/new?template=bug_report.md)
+- 💡 [提出新功能](https://github.com/andeya/team-skills/issues/new?template=feature_request.md)
+- 📖 [改进文档](https://github.com/andeya/team-skills/pulls)
+
+---
+
+<div align="center">
+
+**如果 Team Skills 对你有帮助，请给一个 ⭐ — 让更多人看到工程化的 AI 协作方式。**
+
+</div>

package/bin/team-skills.js

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+import '../src/cli.js';

package/hooks/hooks.json

@@ -0,0 +1,16 @@
+{
+    "hooks": {
+        "SessionStart": [
+            {
+                "matcher": "startup|clear|compact",
+                "hooks": [
+                    {
+                        "type": "command",
+                        "command": "\"${CURSOR_PLUGIN_ROOT}/hooks/session-start\"",
+                        "async": false
+                    }
+                ]
+            }
+        ]
+    }
+}

package/hooks/session-start

@@ -0,0 +1,34 @@
+#!/usr/bin/env bash
+# SessionStart hook for team-skills
+# Injects using-team-skills meta-skill into session context
+
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+PROJECT_ROOT="$(cd "${SCRIPT_DIR}/.." && pwd)"
+
+meta_skill_content=$(cat "${PROJECT_ROOT}/skills/using-team-skills/SKILL.md" 2>&1 || echo "")
+
+escape_for_json() {
+    local s="$1"
+    s="${s//\\/\\\\}"
+    s="${s//\"/\\\"}"
+    s="${s//$'\n'/\\n}"
+    s="${s//$'\r'/\\r}"
+    s="${s//$'\t'/\\t}"
+    printf '%s' "$s"
+}
+
+meta_skill_escaped=$(escape_for_json "$meta_skill_content")
+
+session_context="You have Team Skills available. Use /team-orchestrator for full pipeline, or ask which skill fits your scenario.\n\n**Below is the using-team-skills meta-skill for reference:**\n\n${meta_skill_escaped}"
+
+if [ -n "${CURSOR_PLUGIN_ROOT:-}" ]; then
+  printf '{\n  "additional_context": "%s"\n}\n' "$session_context"
+elif [ -n "${CLAUDE_PLUGIN_ROOT:-}" ] && [ -z "${COPILOT_CLI:-}" ]; then
+  printf '{\n  "hookSpecificOutput": {\n    "hookEventName": "SessionStart",\n    "additionalContext": "%s"\n  }\n}\n' "$session_context"
+else
+  printf '{\n  "additionalContext": "%s"\n}\n' "$session_context"
+fi
+
+exit 0

package/package.json

@@ -0,0 +1,58 @@
+{
+  "name": "team-skills",
+  "version": "1.0.0",
+  "description": "AI Agent Skills framework — Spec-Driven development with directed-graph rollback, quality gates, and 100-point scoring",
+  "type": "module",
+  "bin": {
+    "team-skills": "./bin/team-skills.js"
+  },
+  "files": [
+    "bin/",
+    "src/",
+    "skills/",
+    "hooks/",
+    ".claude/commands/",
+    "scripts/",
+    "README.md",
+    "LICENSE",
+    "CHANGELOG.md"
+  ],
+  "scripts": {
+    "lint": "markdownlint-cli2 '**/*.md' '#node_modules' --config .markdownlint.json && node scripts/check-skill-structure.js",
+    "format": "markdownlint-cli2 '**/*.md' '#node_modules' --config .markdownlint.json --fix",
+    "cli-test": "node bin/team-skills.js --version && node bin/team-skills.js list && node bin/team-skills.js setup --dry-run",
+    "prepare": "git config core.hooksPath .githooks 2>/dev/null || true",
+    "setup": "node bin/team-skills.js setup",
+    "uninstall": "node bin/team-skills.js uninstall"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "keywords": [
+    "ai",
+    "agent",
+    "skills",
+    "spec-driven",
+    "tdd",
+    "claude",
+    "cursor",
+    "code-review",
+    "ai-collaboration"
+  ],
+  "author": "Andeya <andeyalee@outlook.com>",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/andeya/team-skills.git"
+  },
+  "homepage": "https://github.com/andeya/team-skills#readme",
+  "bugs": {
+    "url": "https://github.com/andeya/team-skills/issues"
+  },
+  "dependencies": {
+    "commander": "^13.0.0"
+  },
+  "devDependencies": {
+    "markdownlint-cli2": "^0.17.2"
+  }
+}

package/scripts/check-skill-structure.js

@@ -0,0 +1,89 @@
+#!/usr/bin/env node
+
+/**
+ * Verify Skill structure: SKILL.md existence, required sections, shared rules.
+ * Used by both `npm run lint` and CI.
+ */
+
+import { readdirSync, readFileSync, existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { execSync } from 'node:child_process';
+
+const root = execSync('git rev-parse --show-toplevel', { encoding: 'utf8' }).trim();
+
+const REQUIRED_SECTIONS = [
+  ['角色定位'],
+  ['系统提示词'],
+  ['推理指引', '路由推理'],
+  ['Iron Law'],
+  ['执行步骤'],
+  ['自检门禁'],
+  ['完成标志'],
+  ['STOP Signals'],
+];
+
+const SHARED_RULES = [
+  'constitutional-rules.md',
+  'verification-protocol.md',
+  'four-state-protocol.md',
+];
+
+let failed = false;
+
+// 1. Discover skill directories
+const skillDirs = [];
+const skillsPath = join(root, 'skills');
+for (const name of readdirSync(skillsPath)) {
+  if (name.startsWith('_') || name === 'CLAUDE.md') continue;
+  const dir = join(skillsPath, name);
+  try {
+    if (!readdirSync(dir)) continue;
+  } catch { continue; }
+  skillDirs.push({ name, dir });
+}
+
+// 2. Check SKILL.md existence
+for (const { name, dir } of skillDirs) {
+  const skillFile = join(dir, 'SKILL.md');
+  if (!existsSync(skillFile)) {
+    console.error(`❌ ${name}: missing SKILL.md`);
+    failed = true;
+  }
+}
+
+// 3. Check required sections
+for (const { name, dir } of skillDirs) {
+  const skillFile = join(dir, 'SKILL.md');
+  if (!existsSync(skillFile)) continue;
+
+  const content = readFileSync(skillFile, 'utf8');
+
+  for (const alternatives of REQUIRED_SECTIONS) {
+    const found = alternatives.some(alt => {
+      const pattern = new RegExp(`^#{2,3} ${alt}`, 'm');
+      return pattern.test(content);
+    });
+
+    if (!found) {
+      const label = alternatives.join('|');
+      console.error(`❌ ${name}: missing section '${label}'`);
+      failed = true;
+    }
+  }
+}
+
+// 4. Check shared rules
+for (const file of SHARED_RULES) {
+  const p = join(root, 'skills', '_team-rules', file);
+  if (!existsSync(p)) {
+    console.error(`❌ Missing _team-rules/${file}`);
+    failed = true;
+  }
+}
+
+if (failed) {
+  console.error('\nSkill structure check failed.');
+  process.exit(1);
+}
+
+console.log('✅ All skill structure checks passed.');