@boyingliu01/xp-gate 0.18.4 → 0.19.0

package/plugins/dsh/skills/sprint-flow/SKILL.md

@@ -0,0 +1,411 @@
+---
+name: sprint-flow
+version: 2.1.0
+description: >
+  Orchestrates a 6-phase end-to-end feature development pipeline (PREP → DESIGN → BUILD → VERIFY → SHIP → CLOSE).
+  Integrates grill-with-docs, batch-grill-me, delphi-review (R1 requirements + R2 design), TDD, ralph-loop, code-walkthrough, and native ship/land steps.
+  Pauses at key gates for user decisions. Acknowledges emergent requirements with mandatory manual UAT in CLOSE phase.
+
+  WHAT: Automates the full development lifecycle from worktree isolation to production deployment.
+  WHEN: User explicitly requests building a feature, developing new functionality, starting a sprint, or running /sprint-flow.
+  NOT WHEN: Asking HOW to implement something (educational), implementing a single function/algorithm, environment setup,
+  deployment-only requests, feature suggestions without execution intent, or casual "do it" requests without a feature scope.
+
+  TRIGGERS: "/sprint-flow", "start sprint", "开发新功能", "实现 X (where X is a feature/module)", "一键开发", "develop new feature",
+  "implement feature X", "one-shot development", "build X (where X is a feature)".
+  NEGATIVE TRIGGERS: "实现排序算法", "实现一下", "帮我实现这个函数", "怎么实现登录功能", "start spring boot", "开发环境配置",
+  "一键部署", "新功能建议", "implement a sort function", "how to implement auth".
+  On trigger, first line MUST output: `Sprint Flow: PREP → DESIGN → BUILD → VERIFY → SHIP → CLOSE`
+maturity: beta
+auto_continue: false    # Sprint-flow pauses at user decision gates (unlike delphi-review which auto-continues rounds)
+triggers:
+  - "/sprint-flow"
+  - "start sprint"
+  - "开发新功能"
+  - "一键开发"
+  - "implement feature"
+  - "one-shot development"
+  - "build a feature"
+triggers_negative_examples:
+  - "实现排序算法"          # algorithm implementation, not feature development
+  - "实现一下"              # casual "do it", not a sprint request
+  - "帮我实现这个函数"      # single function, not full feature
+  - "怎么实现登录功能"      # asking HOW, not requesting development
+  - "start spring boot"     # framework name, not sprint
+  - "开发环境配置"          # environment setup, not feature development
+  - "一键部署"              # deploy, not develop
+  - "新功能建议"            # feature suggestion/request, not execution
+  - "implement a sort function"  # algorithm, not full feature
+  - "how to implement auth"      # educational question
+  - "实现一个util函数"      # utility function, not feature
+  - "帮我写个脚本"          # script writing, not feature development
+  - "代码review"            # code review, not development
+  - "refactor this"         # refactoring, not new feature
+triggers_negative_test_cases:
+  - input: "实现排序算法"
+    expect: "NOT triggered"
+  - input: "实现一下"
+    expect: "NOT triggered"
+  - input: "帮我实现这个函数"
+    expect: "NOT triggered"
+  - input: "怎么实现登录功能"
+    expect: "NOT triggered"
+  - input: "start spring boot"
+    expect: "NOT triggered"
+  - input: "开发环境配置"
+    expect: "NOT triggered"
+  - input: "一键部署"
+    expect: "NOT triggered"
+  - input: "新功能建议"
+    expect: "NOT triggered"
+  - input: "implement a sort function"
+    expect: "NOT triggered"
+  - input: "how to implement auth"
+    expect: "NOT triggered"
+  - input: "开发用户认证模块"
+    expect: "triggered"
+  - input: "/sprint-flow \"开发访谈机器人\""
+    expect: "triggered"
+  - input: "一键开发 REST API"
+    expect: "triggered"
+  - input: "implement user authentication feature"
+    expect: "triggered"
+  - input: "start sprint for login module"
+    expect: "triggered"
+  - input: "帮我写个脚本"
+    expect: "NOT triggered"
+  - input: "代码review"
+    expect: "NOT triggered"
+  - input: "refactor this module"
+    expect: "NOT triggered"
+workflow_steps:
+  - "Phase 1/6: PREP → Output: ## Phase 1/6: PREP (准备工作)"
+  - "Phase 2/6: DESIGN → Output: ## Phase 2/6: DESIGN (设计)"
+  - "Phase 3/6: BUILD → Output: ## Phase 3/6: BUILD (构建)"
+  - "Phase 4/6: VERIFY → Output: ## Phase 4/6: VERIFY (验证)"
+  - "Phase 5/6: SHIP → Output: ## Phase 5/6: SHIP (发布)"
+  - "Phase 6/6: CLOSE → Output: ## Phase 6/6: CLOSE (收尾)"
+hooks:
+  security:
+    - "tools_denied": "Destructive commands blocked via tools_denied (rm -rf, git push --force, DROP TABLE)"
+    - "Security Notes": "See Security Notes section for safety guarantees"
+  operational:
+    - "sprint-state.json": "Native sprint state persistence + --resume-from for context restore"
+tools_allowed:
+  - "Bash(git, gh, npm, node)"  # git worktree/branch/commit, gh PR/release, npm/node CLI
+  - "Read"                       # read project files, configs, docs
+  - "Write"                      # write sprint-state, specification.yaml, phase summaries
+  - "Edit"                       # edit sprint-state, CHANGELOG, VERSION
+  - "Glob"                       # find project files by pattern
+  - "Grep"                       # search file contents
+  - "Task"                       # delegate to subagents (quick, deep, unspecified-high)
+  - "Skill"                      # invoke integrated skills (grill-with-docs, batch-grill-me, delphi-review, to-issues, etc.)
+  - "TodoWrite"                  # track sprint progress
+  - "Question"                   # ask user at decision gates
+tools_denied:
+  - "rm -rf (any recursive force remove)"
+  - "git push --force"
+  - "DROP TABLE or destructive DB operations"
+  - "Write(source code)"            # NEVER write implementation code directly — delegate to subagents via Task
+  - "Edit(source code)"             # NEVER edit implementation code — sprint-flow orchestrates, subagents implement
+---
+
+# Sprint Flow — 6-Phase Development Pipeline
+
+## Triggers
+
+| Trigger Type | Phrases |
+|--------------|---------|
+| **中文** | "开发新功能", "一键开发", "/sprint-flow", "开发用户登录", "创建 XXX 模块" |
+| **English** | "/sprint-flow", "start sprint", "implement feature", "one-shot development", "build a feature" |
+
+**Usage**: `/sprint-flow "[feature description]"`
+
+**Examples**:
+- `/sprint-flow "开发访谈机器人，支持多轮对话"`
+- `/sprint-flow "实现用户认证模块，支持 OAuth2"`
+- `/sprint-flow "开发 REST API 端点"`
+
+**Optional Parameters**:
+- `--no-isolate`: Skip auto worktree isolation (⚠️ risk of polluting protected branches)
+- `--branch-name <name>`: Custom branch name (default: `sprint/YYYY-MM-DD-NN`)
+- `--force`: Force continue on current branch even if protected (⚠️ requires explicit confirmation)
+- `--stop-at <phase>`: Stop after specified phase (prep/design/build/verify/ship/close)
+- `--resume-from <phase>`: Resume from specified phase
+- `--phase <phase>`: Execute only single phase (prep-only/design-only/build-only/verify-only/ship-only/close-only)
+- `--lang <language>`: Specify project language (springboot/django/golang)
+- `--type <project_type>`: Specify project type (web-nextjs/web-react/web-vue/backend-go/backend-django/backend-springboot)
+- `--spec <file>`: Use existing specification.yaml file
+- `--with-performance`: Enable load/stress testing (backend projects)
+- `--mode <build_mode>`: Phase 3 BUILD build mode. Default = ralph-loop. parallel = legacy all-at-once mode
+- `--status`: View Sprint progress dashboard (read-only, no execution)
+
+## Security Notes
+
+- Sprint flow **does NOT execute destructive commands** (no `rm -rf`, `git push --force`, `DROP TABLE`, etc.)
+- `git worktree remove` only deletes temporary worktree directories created by the sprint, never affects the main repo
+- Phase 5 SHIP only creates PRs (`gh pr create`), never auto-merges without explicit user confirmation
+- Sprint flow does not download, install, or execute external binaries
+
+## Permissions
+
+- `git`: read/write (worktree, branch, commit)
+- `gh` (GitHub CLI): read/write (PR create, merge, CI query)
+- `filesystem`: read/write (project dir + `.worktrees/` only)
+- `network`: read-only (CI status, canary health)
+
+---
+
+## 6-Phase Pipeline
+
+```
+PREP → DESIGN → BUILD → VERIFY → SHIP → CLOSE
+```
+
+| Phase | Name | Key Actions | Output |
+|-------|------|-------------|--------|
+| 1/6 | PREP | Detect protected branch → Create git worktree → AUTO-ESTIMATE sizing → Classify (lightweight/standard/complex) | Worktree path + impact assessment |
+| 2/6 | DESIGN | CONTEXT.md 预检 (#322) → grill-with-docs → R1 需求评审 → 设计文档+APPROVAL (HARD-GATE) → batch-grill-me → R2 delphi-review (3 distinct models, ≥90% consensus, max 5 rounds) → to-issues → specification.yaml | specification.yaml + slices-manifest.json + requirements-reviewed.json |
+| 3/6 | BUILD | BUILD-ENTRY-CONTRACT → GITHOOKS-GATE → DELPHI-GATE → ralph-loop (default) or parallel → TDD → blind-review (read-only subagent) → verification | MVP code |
+| 4/6 | VERIFY | delphi-review --mode code-walkthrough → test-specification-alignment (#367 HARD-GATE) → xp-gate check --all → browser (Layer 4) → learnings + xp-gate retro | Review report + feedback-log.md + test-alignment-report.json |
+| 5/6 | SHIP | VERSION-GATE → 分支完成决策 (4选项) → native ship (create PR) → native land (merge + CI + canary) | PR URL + deploy status + merge confirmation |
+| 6/6 | CLOSE | SHIP→CLOSE GATE (merge verified) → Backup sprint-state → #369 返工指标 → USER ACCEPTANCE (⚠️ mandatory manual) → Capture emergent issues → Cleanup worktree + branch | Emergent issues list + cleanup report + metrics |
+
+**Hard Gates**:
+- **DESIGN → BUILD**: R1 and R2 invoke all three expert roles independently, verify successful results with three distinct requested models, then aggregate APPROVED consensus ≥90% within 5 rounds, plus GITHOOKS-GATE + DELPHI-GATE + BUILD-ENTRY-CONTRACT (manifest schema + slice↔REQ)
+- **VERIFY → SHIP**: feedback-log.md must exist + test-alignment-report.json PASS (#367 程序化 HARD-GATE)
+- **SHIP → CLOSE**: PR must be merged to main + release completed (HARD-GATE)
+
+---
+
+## ⚠️ Required Output Format (MANDATORY for L3 Step Adherence)
+
+Every phase MUST output its header as the first line of that phase's output. Format MUST be exact:
+
+```markdown
+## Phase 1/6: PREP (准备工作)
+## Phase 2/6: DESIGN (设计)
+## Phase 3/6: BUILD (构建)
+## Phase 4/6: VERIFY (验证)
+## Phase 5/6: SHIP (发布)
+## Phase 6/6: CLOSE (收尾)
+```
+
+**Rules**:
+1. First line of every phase output MUST be `## Phase X/6: NAME (中文名)`
+2. NEVER omit "Phase" keyword (not "## 1/6" or "PREP" alone)
+3. NEVER merge phase output — each phase gets its own header
+4. On `/sprint-flow` trigger, first line MUST output: `Sprint Flow: PREP → DESIGN → BUILD → VERIFY → SHIP → CLOSE`
+5. Each phase completion MUST write Phase Summary to `.sprint-state/phase-outputs/phase-{N}-summary.md`
+
+### Phase Transition — TodoWrite Embedded (MANDATORY, resolves #366)
+
+6. **Sprint initialization**: Phase 1 PREP MUST begin with `npx xp-gate sprint-init "<task_description>"` — this is the single entry point for sprint creation. NEVER manually write sprint-state.json.
+
+7. **Phase transitions are embedded in TodoWrite items**, not as separate post-actions. Each phase's TodoWrite item MUST include the phase-transition call as part of the same atomic step:
+
+   ```
+   TodoWrite item format:
+   - "Phase N: <main task> + phase-transition N completed → N+1 in_progress --render"
+   ```
+
+   Example TodoWrite items for a sprint:
+   ```
+   - Phase 1: PREP — estimate + sprint-init + phase-transition 1 completed --render
+   - Phase 2: DESIGN — delphi review + phase-transition 2 completed --render
+   - Phase 3: BUILD — implementation + phase-transition 3 completed --render
+   ```
+
+   **Rationale**: TodoWrite items are the LLM's most consistently executed operations. Embedding phase-transition elevates it from "post-action meta-info" (priority 4, ignored) to "main task step" (priority 2, executed).
+
+8. **NEVER** manually write to `sprint-state.json` or manually render the dashboard. ALWAYS use:
+   ```
+   npx xp-gate phase-transition <phase> <status> --render [--outputs '<json>']
+   ```
+   - `<phase>`: 1-6
+   - `<status>`: `in_progress` | `completed` | `skipped` | `failed` | `paused`
+   - `--render`: Auto-renders ASCII progress dashboard after state update
+   - `--outputs '<json>'`: Optional JSON of phase outputs to record
+
+   This is a **HARD GATE** — the CLI is the single source of truth for state transitions and dashboard rendering.
+
+### Phase Output Status Schema (MANDATORY per phase)
+
+Each phase MUST close with structured status:
+
+```
+status: completed | blocked | user_decision_required
+outputs: [list of files produced]
+decisions: [list of decisions made]
+next_phase_context: [key info for next phase]
+```
+
+---
+
+## Phase 1/6: PREP (准备工作)
+
+**触发条件**：用户输入匹配 Triggers 表中任一短语，或显式调用 `/sprint-flow`。
+
+**输入**：
+| 输入 | 来源 | 必需 |
+|------|------|------|
+| 功能描述 | 用户命令参数 | 是 |
+| 当前分支 | `git branch --show-current` | 自动检测 |
+| 项目语言 | `--lang` 参数或自动检测 | 否 |
+
+**步骤**：
+1. 输出首行：`Sprint Flow: PREP → DESIGN → BUILD → VERIFY → SHIP → CLOSE`
+2. 检测当前分支是否为保护分支（main/master/develop）
+3. 创建 git worktree 隔离（除非 `--no-isolate`）：
+   ```bash
+   git worktree add .worktrees/sprint-$(date +%Y%m%d-%H%M%S) -b sprint/YYYY-MM-DD-NN
+   ```
+4. AUTO-ESTIMATE 规模评估（分析功能描述复杂度）
+5. 分类：lightweight / standard / complex
+6. 执行 `npx xp-gate sprint-init "<task_description>"` 初始化状态
+7. 执行 `npx xp-gate phase-transition 1 completed --render`
+
+**输出**：
+| 输出物 | 路径 | 格式 |
+|--------|------|------|
+| Worktree 路径 | `.worktrees/sprint-*` | 目录 |
+| Sprint 状态 | `.sprint-state/sprint-state.json` | JSON |
+| Phase Summary | `.sprint-state/phase-outputs/phase-1-summary.md` | Markdown |
+
+**详细参考**：`@references/phase-1-prep.md`
+
+---
+
+## 门禁条件表 (Gate Conditions)
+
+| 门禁 | 位置 | 条件 | 失败处理 |
+|------|------|------|----------|
+| BUILD-ENTRY-CONTRACT | Phase 2→3 | slices-manifest.json schema 合法 + slice↔REQ 一致 | BLOCK，返回 Phase 2 修复 |
+| GITHOOKS-GATE | Phase 2→3 | hooks 已安装且可执行 | 自动修复 (`xp-gate doctor --fix`)，失败则 BLOCK |
+| DELPHI-GATE | Phase 2→3 | R2 delphi-review APPROVED (≥90%) | 重新设计或用户覆盖（记录原因） |
+| VERSION-GATE | Phase 4→5 | VERSION 文件与 package.json 一致 | 执行 `node scripts/sync-version.cjs` |
+| #367 EVIDENCE-GATE | Phase 4→5 | test-alignment-report.json PASS + head_commit + spec_hash | BLOCK（--skip-evidence 需 --reason，≤2 次/sprint） |
+| SHIP→CLOSE GATE | Phase 5→6 | PR 已合并 + release 完成 | BLOCK，等待合并确认 |
+| feedback-log GATE | Phase 4→5 | feedback-log.md 存在 | BLOCK，必须完成 VERIFY |
+
+---
+
+## Phase 2–6 详细指令
+
+> Phase 2–6 的完整步骤、输入/输出契约、模板和 Skill 集成详情见 `references/` 目录。本节提供路由摘要。
+
+| Phase | 参考文件 | 核心 Skill 链 |
+|-------|----------|---------------|
+| 2/6 DESIGN | `@references/phase-2-design.md` | CONTEXT.md 预检 → grill-with-docs → R1 需求评审 → 设计文档+APPROVAL → batch-grill-me → R2 delphi-review → to-issues |
+| 3/6 BUILD | `@references/phase-3-build.md` | BUILD-ENTRY-CONTRACT → GITHOOKS-GATE → DELPHI-GATE → ralph-loop (TDD) → blind-review (read-only subagent) |
+| 4/6 VERIFY | `@references/phase-4-verify.md` | delphi code-walkthrough → test-spec-alignment (#367) → xp-gate check --all → browser (Layer 4) → learnings + retro |
+| 5/6 SHIP | `@references/phase-5-ship.md` | VERSION-GATE → 分支完成决策 (4选项) → native ship (PR) → native land (merge+CI+canary) |
+| 6/6 CLOSE | `@references/phase-6-close.md` | SHIP→CLOSE GATE → backup → #369 返工指标 → USER ACCEPTANCE → emergent → cleanup |
+
+**路径约定**：`@references/` 和 `@templates/` 相对于 skill 目录（`skills/sprint-flow/`）解析。
+
+**完整参考文件索引**：
+| 文件 | 内容 |
+|------|------|
+| `@references/phase-overview.md` | 全阶段详情、Skill 集成、参数、输出契约 |
+| `@references/orchestration-rules.md` | Agent 调度、上下文继承、转换门禁 |
+| `@references/force-levels.md` | 阶段强制执行规则 |
+| `@templates/` | Pain doc、emergent issues、sprint summary、progress 模板 |
+
+---
+
+## Anti-Patterns
+
+| ❌ Error | ✅ Correct |
+|----------|-----------|
+| Route Q&A, explanation, or code-search requests to sprint-flow | Only trigger for explicit feature development/implementation requests |
+| Skip Phase 1/6 PREP isolation, edit directly on main/master/develop | Default: create worktree; only bypass with `--no-isolate` or `--force` + user confirmation |
+| Skip AUTO-ESTIMATE and apply full heavy pipeline blindly | Evaluate lightweight/standard/complex first, follow recommended or user-confirmed flow |
+| Skip Delphi review in DESIGN, go straight to BUILD | All requirement levels (lightweight/standard/complex) must pass R1 需求评审 + R2 delphi-review; APPROVED before coding |
+| Skip TDD, implement code directly | Phase 3/6 BUILD must follow RED → GREEN → REFACTOR; tests and implementation delivered together |
+| Skip user acceptance, go straight to Ship | Phase 6/6 CLOSE USER ACCEPTANCE must be manual; never automate, skip, or fake |
+| Enter CLOSE without SHIP completing merge to main | Phase 5/6 SHIP must complete merge to main + release before entering Phase 6/6 CLOSE; otherwise worktree cleanup leaves residue + UAT reviews unmerged code |
+| Clean up CLOSE without backing up sprint-state first | `.sprint-state/` is inside worktree; it's lost on worktree removal. CLOSE step 1 MUST back up to repo-tracked path first |
+| Keep adding random changes after verification failures | Max 3 fix cycles; if still failing, BLOCK and request user decision |
+| Enter next phase without generating Phase Summary | Every phase MUST write `.sprint-state/phase-outputs/phase-{N}-summary.md` and pass transition gate |
+| Complete implementation change without running verification | After every file edit/refactor/feature, MUST run `npm test` + `npm run lint` + `npx tsc --noEmit` and record the structured verification event (see `phase-3-build.md` §In-Session Verification) |
+
+---
+
+## 状态机 (State Machine)
+
+```mermaid
+stateDiagram-v2
+    [*] --> PREP : trigger matched
+    PREP --> DESIGN : worktree ready
+    DESIGN --> BUILD : APPROVED ≥90%
+    DESIGN --> DESIGN : REQUEST_CHANGES (max 5 Delphi rounds)
+    BUILD --> VERIFY : tests pass
+    BUILD --> BUILD : fix cycle (max 3)
+    VERIFY --> SHIP : feedback-log exists
+    VERIFY --> BUILD : critical issues found
+    SHIP --> CLOSE : PR merged
+    SHIP --> SHIP : CI failed (retry)
+    CLOSE --> [*] : UAT confirmed
+    BUILD --> BLOCKED : 3 fix cycles exhausted
+    DESIGN --> BLOCKED : 5 Delphi rounds exhausted
+    BLOCKED --> [*] : user decision
+```
+
+---
+
+## 决策记录模板 (Decision Record)
+
+每个用户决策点必须记录到 `.sprint-state/decisions.md`：
+
+```markdown
+## Decision DR-{NNN}
+- **Phase**: {phase_number}/6 {PHASE_NAME}
+- **Question**: {what was asked}
+- **Options**: {options presented}
+- **Choice**: {user's selection}
+- **Rationale**: {why this choice}
+- **Timestamp**: {ISO 8601}
+```
+
+**强制决策点**：
+| 决策点 | 阶段 | 触发条件 |
+|--------|------|----------|
+| 规模确认 | PREP | AUTO-ESTIMATE 结果与用户预期不符 |
+| 设计审批 | DESIGN | delphi-review 返回 REQUEST_CHANGES |
+| 修复策略 | BUILD | 修复循环达到 3 次上限 |
+| 发布确认 | SHIP | PR 创建后等待用户确认合并 |
+| UAT 结果 | CLOSE | 用户手动验收（必须手动，禁止自动化） |
+
+---
+
+## 失败处理 (Failure Handling)
+
+| 失败场景 | 处理策略 | 升级条件 |
+|----------|----------|----------|
+| Worktree 创建失败 | 重试 1 次，失败则提示用户手动处理 | 磁盘空间不足或权限问题 |
+| delphi-review 连续 REQUEST_CHANGES | 最多 3 轮重设计，超过则 BLOCK | 3 轮后仍未 APPROVED |
+| BUILD 修复循环超限 | 最多 3 次 fix cycle，超过则 BLOCK + 用户决策 | 测试持续失败 |
+| CI 失败 | 分析失败原因，尝试 1 次自动修复 | 非 flaky 失败 |
+| PR 合并冲突 | 提示用户手动解决 | 始终（禁止自动 force） |
+| 工具缺失 | SKIP（不 BLOCK），记录到 phase summary | 始终不阻断 |
+
+**BLOCK 状态处理**：
+1. 写入 `.sprint-state/sprint-state.json` 状态为 `blocked`
+2. 输出阻塞原因 + 已完成工作 + 建议操作
+3. 等待用户决策（继续/放弃/降级）
+4. 记录决策到 `decisions.md`
+
+---
+
+## 使用示例
+
+| 场景 | 命令 | 说明 |
+|------|------|------|
+| 完整流水线 | `/sprint-flow "开发访谈机器人"` | 自动执行 6 阶段 → specification.yaml + PR URL |
+| 设计后停止 | `/sprint-flow "开发认证模块" --stop-at design` | 输出 specification.yaml 后停止，供评审 |
+| 仅构建阶段 | `/sprint-flow "开发 API" --lang django --phase build-only` | 跳过准备/设计，直接 Build |
+
+## 底层 Skills 保持独立
+
+所有被调用的 Skills 独立可用：`delphi-review` (单独评审), `test-driven-development` (TDD), `grill-with-docs` (需求访谈), `batch-grill-me` (批量决策), `to-issues` (切片拆分)，sprint-flow 仅自动串联