team-skills 1.2.0 → 1.2.1

package/README.md

@@ -180,22 +180,26 @@ npx team-skills@latest update
 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 git fill:#e8f5e9,stroke:#2e7d32,stroke-width:2px,color:#1b5e20;
     classDef kill fill:#ffebee,stroke:#c62828,stroke-width:2px,stroke-dasharray: 5 5,color:#b71c1c;
 
     START(("用户提出需求"))
     H1["H1: 人类确认目标理解<br/>← 人类介入点 #1"]:::human
+    BRANCH["创建功能分支<br/>{slug} 分支"]:::git
     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
+    FINISH["team-finish — 分支完成<br/>merge / PR / keep"]:::git
     H4["H4: 人类验收交付物<br/>← 人类介入点 #4"]:::human
     H3("H3: 人类介入 #3<br/>阻塞 / 决策 / Kill Switch"):::human
 
     START --> H1
-    H1 -->|确认| SPEC
+    H1 -->|确认| BRANCH
     H1 -->|不确认| START
 
+    BRANCH --> SPEC
     SPEC --> H2
     H2 -->|确认| IMPL
     H2 -->|不确认| SPEC
@@ -208,16 +212,18 @@ flowchart TD
     TEST -->|spec 遗漏| SPEC
     TEST -.->|不可行| H3
 
-    REVIEW -->|无问题| H4
+    REVIEW -->|无问题| FINISH
     REVIEW -->|P0/P1| IMPL
     REVIEW -->|spec 遗漏| SPEC
     REVIEW -.->|不可行| H3
 
+    FINISH --> H4
     H4 -->|验收通过| DONE(("完成 ✅"))
     H4 -->|不通过| IMPL
 ```
 
 > H3 可在**任何阶段**触发，包括：发现任务不可行（Kill Switch）、回退超限、或需要人类决策的复杂问题。
+> 功能分支在 H1 确认后自动创建，在 Review 通过后由 team-finish 处理（merge/PR/keep/discard）。
 
 ---
 
@@ -272,7 +278,7 @@ graph TD
 | `team-impl` | TDD 红-绿-重构循环实现 | "规格有了，开始写代码" |
 | `team-test` | 四维测试矩阵 + 补充测试 | "测试覆盖够吗？" |
 | `team-review` | 五维审查 + 资产沉淀 + 复盘 | "代码质量如何？" |
-| `team-orchestrator` | 有向图流程编排，4 个人类介入点 | "我要完整交付流水线" |
+| `team-orchestrator` | 有向图流程编排 + 分支管理，4 个人类介入点 | "我要完整交付流水线" |
 | `team-verify` | 5 步验证门禁，杜绝虚假通过 | "测试真的过了吗？" |
 | `team-debug` | 四阶段根因分析 + 修复 | "这个 bug 怎么回事？" |
 | `team-feedback` | 先验证再实施，非表演性同意 | "Review 反馈来了" |
@@ -283,30 +289,63 @@ graph TD
 
 ---
 
-## 📋 每个任务最多产出 18 个结构化文档
+## 📋 结构化文档体系
+
+团队协作过程中产出的所有文档，统一存放在 `docs/` 目录下：
 
 ```
-docs/tasks/{slug}/
-├── 00-design-brief.md      # 设计概要（team-brainstorm 产出，可选）
-├── 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             # 答辩提纲
+docs/
+├── tasks/                          # 任务文档（核心目录）
+│   ├── progress.md                 # 进度账本 — 所有任务的状态追踪表
+│   │
+│   ├── {NNNN}-{keyword}/           # 单个任务目录（最多产出 18 个结构化文档）
+│   │   ├── 00-design-brief.md      #   设计概要（team-brainstorm 产出，可选）
+│   │   ├── 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             #   答辩提纲
+│   │
+│   └── ...                         # 更多任务目录
+│
+├── review-checklist.md             # Review 检查清单（项目级，跨任务累积）
+├── delivery-checklist.md           # 交付检查清单（项目级，跨任务累积）
+└── specs/                          # SDD 归档（任务验收通过后存档）
 ```
 
+### 文档职责分层
+
+| 层级 | 目录 | 生命周期 | 说明 |
+|------|------|----------|------|
+| **进度追踪** | `tasks/progress.md` | 持续更新 | 防止跨 session 任务重复派发，记录所有任务状态 |
+| **任务文档** | `tasks/{slug}/` | 随任务创建 | 每个任务独立目录，slug 格式 `{NNNN}-{keyword}` |
+| **项目级清单** | `review-checklist.md` | 跨任务累积 | 每次 Review 发现新检查项后追加，持续积累 |
+| **项目级清单** | `delivery-checklist.md` | 跨任务累积 | 每次交付发现新检查项后追加，持续积累 |
+| **规格归档** | `specs/` | 验收后存档 | SDD 快照归档，供后续任务参考 |
+
+### 任务文档产出阶段
+
+| 阶段 | 产出文件 | 负责 Skill |
+|------|----------|------------|
+| 头脑风暴 | `00-design-brief.md` | `team-brainstorm` |
+| 规格设计 | `01-plan.md` ~ `05-risk.md` + `prompt-template.md` | `team-spec` |
+| TDD 实现 | `06-tdd-log.md` ~ `08-ai-decisions.md` | `team-impl` |
+| 测试审计 | `09-test-matrix.md` ~ `10-test-report.md` | `team-test` |
+| 代码审查 | `11-review.md` ~ `13-retrospective.md` + `task-rules.md` | `team-review` |
+| 团队交付 | `14-team.md` + `15-brief.md` | `team-orchestrator` |
+
 ---
 
 ## 🔧 兼容性

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "team-skills",
-  "version": "1.2.0",
+  "version": "1.2.1",
   "description": "AI Agent Skills framework — Spec-Driven development with directed-graph rollback and quality gates",
   "type": "module",
   "bin": {

package/skills/team-finish/SKILL.md

@@ -9,6 +9,8 @@ description: Use when implementation is complete, all tests pass, and you need t
 
 你是分支完成处理者。你的核心职责是：验证测试 → 展示选项 → 执行选择 → 清理。
 
+> **分支生命周期**：`team-orchestrator` 在 H1 确认后创建功能分支（Step 1.5），本 Skill 在流程尾部（Step 7.3）负责分支收尾。两者配合形成完整的分支生命周期闭环。
+
 ### 系统提示词
 
 ```
@@ -68,7 +70,14 @@ Cannot proceed with merge/PR until tests pass.
 
 ### Step 2：确定基准分支
 
-运行项目版本控制命令获取当前分支与基准分支的合并基点（如 `git merge-base HEAD main`）。
+按以下优先级确定基准分支：
+
+1. **从 checkpoint 读取**：如果 `docs/tasks/{slug}/.checkpoint.json` 存在且包含 `base_branch` 字段，直接使用（orchestrator Step 1.5 已确定）
+2. **从项目 AI 规范读取**：在 CLAUDE.md / .cursor/rules/ 中查找 `base_branch` 或 `default_branch` 配置项
+3. **从 Git 远程推断**：`git symbolic-ref refs/remotes/origin/HEAD | sed 's|refs/remotes/origin/||'`
+4. **常见分支名兜底**：按 `main` → `master` → `develop` 顺序检查本地是否存在
+
+确定后运行 `git merge-base HEAD {base_branch}` 获取合并基点。
 
 ### Step 3：展示选项
 

package/skills/team-orchestrator/SKILL.md

@@ -11,7 +11,8 @@ description: Use when task needs full spec→impl→test→review pipeline with
 
 ```mermaid
 flowchart TD
-    H1["H1: 人类确认目标"] --> specAgent["specAgent: 规格制定"]
+    H1["H1: 人类确认目标"] --> branch["创建功能分支"]
+    branch --> specAgent["specAgent: 规格制定"]
     specAgent --> H2["H2: 人类确认规格"]
     H2 --> implAgent["implAgent: TDD 实现"]
     implAgent --> testAgent["testAgent: 测试审计"]
@@ -20,7 +21,8 @@ flowchart TD
     testAgent -->|"全部通过"| reviewAgent["reviewAgent: 代码审查"]
     reviewAgent -->|"P0/P1 问题"| implAgent
     reviewAgent -->|"spec 遗漏"| specAgent
-    reviewAgent -->|"无问题"| H4["H4: 人类验收"]
+    reviewAgent -->|"无问题"| finish["team-finish: 分支完成"]
+    finish --> H4["H4: 人类验收"]
     H3["H3: 人类介入（任何阶段）"] -.->|"阻塞/决策"| H3
 ```
 
@@ -123,6 +125,12 @@ NO AGENT DISPATCH WITHOUT H1 HUMAN CONFIRMATION FIRST
                      │ 确认  │ 不确认 → 返回修改
                      ▼       └────────┐
               ┌──────────────────┐     │
+              │  创建功能分支     │     │
+              │  {slug} 分支     │     │
+              └──────┬───────────┘     │
+                     │                 │
+                     ▼                 │
+              ┌──────────────────┐     │
               │  specAgent       │     │
               │  产出 01-05 文件  │     │
               │  + 分期建议(P1/P2)│     │
@@ -177,6 +185,13 @@ NO AGENT DISPATCH WITHOUT H1 HUMAN CONFIRMATION FIRST
                      ├── 发现人类需决策 ─────────→ H3: 人类介入点 #3
                      │                           │
                      ▼                           │
+              ┌──────────────────┐               │
+              │  team-finish     │               │
+              │  分支完成处理     │               │
+              │  (merge/PR/keep) │               │
+              └──────┬───────────┘               │
+                     │                           │
+                     ▼                           │
               ┌──────────────────────────┐       │
               │  H4: 人类验收最终交付物    │       │
               │  (展示 14-team + 15-brief │       │
@@ -304,10 +319,12 @@ NO AGENT DISPATCH WITHOUT H1 HUMAN CONFIRMATION FIRST
    {
      "slug": "0001-add-tooltip",
      "task_description": "实现用户注册功能",
+     "branch": "0001-add-tooltip",
+     "base_branch": "main",
      "current_step": "H2",
      "next_step": "Step 3",
      "phase": "spec",
-     "completed_steps": ["Step 1", "H1", "Step 2"],
+     "completed_steps": ["Step 1", "H1", "Step 1.5", "Step 2"],
      "pending_decision": "用户确认规格方案",
      "completed_at": "2026-01-15T10:30:00Z",
      "rollback_counts": {
@@ -325,7 +342,7 @@ NO AGENT DISPATCH WITHOUT H1 HUMAN CONFIRMATION FIRST
    - 如存在且 `status = DONE` → 从 `next_step` 对应的 Step 继续
    - 如存在且 `status = BLOCKED` → 触发 H3 展示 `blocked_reason`
    - 如不存在 → 检查已有文件推断阶段：
-     - 仅有 00-design-brief.md → 从 Step 2（specAgent）
+     - 仅有 00-design-brief.md → 从 Step 1.5（分支初始化）或 Step 2（specAgent），视当前分支判断
      - 有 03-sdd.md + 04-boundary.md（精简模式最小集）或 01-05 齐全（完整模式）→ 从 Step 3（implAgent）
      - 有 06-tdd-log.md 但无 09-test-matrix.md → 从 Step 4（testAgent）
      - 有 09-test-matrix.md + 10-test-report.md 但无 11-review.md → 从 Step 5（reviewAgent）
@@ -343,12 +360,39 @@ NO AGENT DISPATCH WITHOUT H1 HUMAN CONFIRMATION FIRST
 4. **写入 checkpoint**：`current_step=Step 1, next_step=H1, phase=init, task_description={任务描述}`
 5. **进度账本检查**：如果 `docs/tasks/progress.md` 不存在则创建（含表头）。**注意：progress.md 是跨任务进度索引，必须位于 `docs/tasks/` 根目录，不在 slug 子目录中**。读取 progress.md 确认 `{slug}` 未被重复派发（如已存在且状态为 DONE，提示用户该任务已完成，询问是否新建变体任务）
 6. 记录启动时间
-7. **写入 checkpoint**：`current_step=H1, next_step=Step 2, pending_decision=确认目标理解`
+7. **写入 checkpoint**：`current_step=H1, next_step=Step 1.5, pending_decision=确认目标理解`
 8. **向用户展示任务理解 + 初步方案 + 风险预判 + 分期建议**，等待确认（设置 30 分钟超时提醒）。如果存在 `00-design-brief.md`，将其摘要纳入展示
-9. 用户确认后，**写入 checkpoint**：`current_step=Step 2, completed_steps 追加 H1`。继续下一步，否则根据反馈调整
+9. 用户确认后，**写入 checkpoint**：`current_step=Step 1.5, completed_steps 追加 H1`。继续下一步，否则根据反馈调整
 
 **Kill Switch 预检查**：如果任务明显不可行（技术不可行、依赖不可用、范围远超预期），在 H1 阶段直接向用户提出终止建议。
 
+### Step 1.5：Git 分支初始化
+
+H1 确认后、specAgent 启动前，创建功能分支隔离本次任务的所有变更。
+
+#### 1.5.1 确定基准分支（三层 Fallback）
+
+按以下优先级确定 `base_branch`，取第一个成功的结果：
+
+1. **项目 AI 规范显式声明**：在 CLAUDE.md / .cursor/rules/ 中查找 `base_branch` 或 `default_branch` 配置项（如 `base_branch: develop`）
+2. **Git 远程默认分支**：`git symbolic-ref refs/remotes/origin/HEAD` 解析出分支名；失败则 `git remote show origin` 解析 HEAD branch
+3. **常见分支名兜底**：按 `main` → `master` → `develop` 顺序检查本地是否存在（`git show-ref --verify refs/heads/{name}`）
+
+如果三层均失败 → 触发 H3，请求用户指定基准分支。
+
+#### 1.5.2 创建功能分支
+
+1. **检测当前分支**：获取当前分支名（`git branch --show-current`）
+2. **创建功能分支**：`git checkout -b {slug}`（分支名直接使用 slug，如 `0012-refactor-auth`）
+3. **写入 checkpoint**：`current_step=Step 2, branch={slug}, base_branch={基准分支名}, completed_steps 追加 Step 1.5`
+
+**跳过条件**（不创建分支）：
+
+- 用户已在功能分支上（当前分支名不等于 `base_branch`）→ 使用当前分支，checkpoint 中 `branch` 记录当前分支名
+- 用户明确指定 `--no-branch` → 直接在当前分支上工作
+
+**恢复场景**：断点续传（`docs/tasks/{slug}/.checkpoint.json` 已有 `branch` 字段）时，检查当前分支是否与 checkpoint 记录一致。不一致则提示用户切换分支（`git checkout {branch}`），不自动切换。
+
 ### Step 2：调度 specAgent
 
 **REQUIRED SUB-SKILL:** `team-spec`
@@ -545,10 +589,13 @@ TDD 强制要求：每个功能点必须先 git commit 失败测试（test: {功
 
 在归档前，检查 reviewAgent 产出的 `12-asset-update.md` 中是否有 CHANGELOG.md 更新。如果 CHANGELOG.md 需要更新但尚未更新，在此处补全。
 
-同时检查 `team-finish` 流程是否已执行：
+调度 `team-finish` 完成分支处理：
 
-- 如果分支尚未合并，推荐使用 `team-finish` 完成分支处理
-- 如果已合并，确认合并 commit 已推送
+- 传递 checkpoint 中的 `branch` 和 `base_branch` 信息
+- `team-finish` 将验证测试 → 展示选项（merge/PR/keep/discard）→ 执行用户选择
+- 如果用户选择 merge，合并后确认合并 commit 已推送
+- 如果用户选择 PR，确认 PR 已创建
+- 如果用户选择 keep/discard，记录用户决策
 
 ### Step 7.5：归档与知识合并