@boyingliu01/xp-gate 0.19.2 → 0.20.0

package/plugins/qoder/skills/sprint-flow/references/phase-overview.md

@@ -0,0 +1,486 @@
+# Sprint Flow — Phase Overview & Detailed Instructions
+
+> **This file**: detailed phase descriptions, skill integration, parameter docs, output contract, templates, research evidence, and orchestration rules.
+> **Router file**: `../SKILL.md` — description, triggers, workflow steps, constraints, anti-patterns only.
+
+---
+
+## 核心原则
+
+| 原则 | 说明 |
+|------|------|
+| **单一入口** | 用户只需调用 `/sprint-flow`，自动串联全流程 |
+| **自动流水线** | 自动执行多个阶段，原生步骤 + 内置 Matt Pocock skill |
+| **关键节点暂停** | APPROVED 确认、DELPHI-GATE 通过、Ship 确认、⚠️ Phase 6 CLOSE 必须人工 |
+| **承认 Emergent** | 用户验收环节必须人工，无法自动化（78% 失败不可见） |
+| **复用现有 Skills** | 不重新发明，整合调用现有体系 |
+
+---
+
+## Unique Value Proposition
+
+Sprint Flow is NOT just a sequential launcher of existing skills. Here's what makes it different from manually running each skill:
+
+### Why Sprint Flow vs Manual Skill Execution
+
+| Dimension | Manual Execution | Sprint Flow |
+|-----------|-----------------|-------------|
+| **Context Continuity** | Each skill starts fresh; lost design decisions between phases | Phase summaries + sprint-state.json maintain full traceability across 6 phases |
+| **Gate Enforcement** | No enforcement — easy to skip Delphi, skip TDD, skip UAT | HARD-GATE: design must be APPROVED (≥90% Delphi consensus) before coding; UAT is mandatory (no bypass) |
+| **Token Efficiency** | Linear context accumulation across phases — ~150K+ tokens | Ralph-loop default: 40-67% token savings via clean REQ-level contexts |
+| **Emergent Requirements** | Discovered late, silently ignored or merged | Phase 6 CLOSE explicitly captures emergent issues via template; triggers Sprint 2 for critical issues |
+| **Quality Ecosystem** | No integration with quality gates | Integrated with xp-gate's full quality ecosystem: Gate 5 (coverage), Gate M2 (mock density), Delphi code-walkthrough |
+| **Progress Tracking** | Ad-hoc, memory-based | `.sprint-state/` persistence with phase history, timing, and metrics — `--status` renders progress dashboard |
+
+### Key Differentiators
+
+1. **40-67% Token Savings via Ralph Loop**: Phase 3 BUILD default (`ralph-loop`) processes one REQ at a time with clean context, avoiding the linear context accumulation that costs 150K+ tokens in parallel mode.
+
+2. **HARD-GATE Discipline**: Design must pass Delphi review with all three expert roles executed successfully, three distinct requested model IDs verified, and ≥90% aggregate consensus within five rounds before Phase 3 BUILD can start. This is enforced both in SKILL.md instructions and via the Claude Code plugin's PreToolUse hook.
+
+3. **Emergent Requirements Acknowledgment**: Based on research showing 78% of failures are invisible to AI (arXiv study), Phase 6 CLOSE includes mandatory manual UAT verification — cannot be automated, skipped, or bypassed.
+
+4. **XP-Gate Quality Ecosystem Integration**: Sprint Flow is part of the broader xp-gate ecosystem. Phase 3 BUILD integrates with Gate 5 (test coverage ≥80%), Gate M2 (mock density ≤30%), and Gate MW (code-walkthrough validation). Phase 4 VERIFY runs Delphi code-walkthrough that generates `.code-walkthrough-result.json` for pre-push enforcement.
+
+5. **Full Lifecycle Coverage**: From worktree isolation (PREP) to cleanup (CLOSE), sprint-flow covers the entire development lifecycle — not just the "write code" part. PREP (Phase 1/6) prevents over-engineering by routing lightweight changes through simplified workflows.
+
+---
+
+## 完整流程（默认无参数）
+
+调用 `/sprint-flow "[需求描述]"` 后，自动执行以下流程：
+
+```
+Phase 1/6: PREP → worktree隔离 + 规模评估 + 流程路由
+Phase 2/6: DESIGN → grill-with-docs → R1 需求评审 → 设计文档+APPROVAL → batch-grill-me → R2 delphi-review → to-issues → specification.yaml
+Phase 3/6: BUILD → BUILD-ENTRY-CONTRACT → GITHOOKS-GATE → DELPHI-GATE → ralph-loop/TDD → blind-review (read-only subagent) → verification
+Phase 4/6: VERIFY → delphi-review --mode code-walkthrough → test-alignment (#367 HARD-GATE) → xp-gate check --all → browser (Layer 4) → learnings + retro
+Phase 5/6: SHIP → VERSION-GATE → 分支完成决策(4选项) → native ship (PR) → native land (merge+CI+canary)
+Phase 6/6: CLOSE → USER ACCEPTANCE (⚠️ 人工) → #369 返工指标 → emergent issues → cleanup
+```
+
+**v2.0 Compact Redesign** (Issue #290): Merged from 11 phases to 6. PREP = old ISOLATE + AUTO-ESTIMATE. DESIGN = old THINK + PLAN. BUILD = old BUILD (unchanged). VERIFY = old REVIEW + FEEDBACK. SHIP = old SHIP + LAND. CLOSE = old USER ACCEPTANCE + CLEANUP.
+
+---
+
+## 暂停点设计（不是随时停，而是设计明确的暂停点）
+
+- **Phase 1/6 PREP**: 保护分支强制隔离 → 输出警告或自动创建 worktree → 自动恢复；AUTO-ESTIMATE 结果展示 → 用户确认 → 按路由继续
+- **Phase 2/6 DESIGN**: grill-with-docs 访谈 → R1 需求评审 GAPS_FOUND → 补充访谈（最多 2 轮）；设计文档未 APPROVED (HARD-GATE) → 用户修改 → APPROVED 后继续；batch-grill-me 批量决策 → 用户确认；R2 delphi-review 未 APPROVED → 修复 → APPROVED → specification.yaml
+- **Phase 3/6 BUILD**: BUILD-ENTRY-CONTRACT 未通过 → BLOCK；DELPHI-GATE 未通过 → BLOCK；验证失败 > max3 → 用户决策修复/放弃；成本超阈值 → 用户确认
+- **Phase 4/6 VERIFY**: delphi code-walkthrough REQUEST_CHANGES → 用户处理 → 重新评审；test-alignment 失败 (#367) → 回退 Phase 3（不暂停）；浏览器验证发现问题 → 回退 Phase 3（不暂停）
+- **Phase 5/6 SHIP**: 分支完成决策 (4选项) → 确认；native ship PR → 用户确认合并；native land 完成/失败 → 用户确认；⚠️ SHIP must complete merge to main + release before Phase 6
+- **Phase 6/6 CLOSE**: SHIP→CLOSE GATE (校验 merge 已完成 + git status clean + 当前在 main) → Backup sprint-state → #369 返工指标写入 → USER ACCEPTANCE ⚠️ 必须人工验收 → 用户确认后继续；cleanup 完成/失败 → 用户确认 → 结束流程
+
+---
+
+## Workflow Steps Detail
+
+| Step | Phase | Name | Key Actions | Output |
+|------|-------|------|-------------|--------|
+| 1 | **1/6** | **PREP** | Detect protected branch → Create git worktree → AUTO-ESTIMATE sizing → Classify (lightweight/standard/complex) | Worktree path + impact assessment |
+| 2 | **2/6** | **DESIGN** | grill-with-docs → R1 需求评审 → 设计文档+APPROVAL (HARD-GATE) → batch-grill-me → R2 delphi-review (≥90% consensus) → to-issues → specification.yaml | specification.yaml + slices-manifest.json + requirements-reviewed.json |
+| 3 | **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 | **4/6** | **VERIFY** | delphi-review --mode code-walkthrough → test-specification-alignment (#367 HARD-GATE) → xp-gate check --all → browser (Layer 4 optional) → learnings + xp-gate retro | Review report + feedback-log.md + test-alignment-report.json |
+| 5 | **5/6** | **SHIP** | VERSION-GATE → 分支完成决策 (4选项) → native ship (create PR) → native land (merge + CI + canary) → release | PR URL + deploy status + merge confirmation |
+| 6 | **6/6** | **CLOSE** | SHIP→CLOSE GATE (merge + release verified) → Backup sprint-state → #369 返工指标 → USER ACCEPTANCE (⚠️ mandatory manual) → Capture emergent issues → Cleanup worktree + branch → Sprint summary | Emergent issues list + cleanup report + metrics |
+
+**Phase Flow**:
+```
+PREP → DESIGN → BUILD → VERIFY → SHIP (merge to main + release) → CLOSE
+                                                        ↑
+                                               SHIP→CLOSE GATE
+                                               (merge verified + main clean)
+```
+
+**Hard Gates**:
+- **Phase 2/6 → 3/6 (DESIGN → BUILD)**: R1 需求评审 APPROVED + 设计文档用户 APPROVED + R2 delphi-review APPROVED (≥90% consensus) + GITHOOKS-GATE (hooks installed) + DELPHI-GATE (spec APPROVED) + BUILD-ENTRY-CONTRACT (manifest schema + slice↔REQ 一致性)
+- **Phase 4/6 → 5/6 (VERIFY → SHIP)**: feedback-log.md must exist + test-alignment-report.json PASS (#367 程序化 HARD-GATE)
+- **Phase 5/6 → 6/6 (SHIP → CLOSE)**: PR must be merged to main + release completed (HARD-GATE). See `references/phase-6-close.md#ship--close-gate`.
+
+---
+
+## 各 Phase 调用的 Skills
+
+### ⚠️ 强制输出格式规范（Mandatory Output Format）
+
+**执行每个 Phase 时，必须以以下固定格式输出阶段标题**，不可省略、不可合并、不可替换：
+
+```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 (收尾)
+```
+
+**规则**：
+1. 每个 Phase **开始执行时必须首先输出**对应的 `## Phase X/6: NAME` 标题行（作为该 Phase 输出的第一行）
+2. **禁止省略** "Phase" 关键词（如不能只写 "PREP" 或 "## 1/6"）
+3. **禁止合并**多个 Phase 的输出（每个 Phase 必须有独立标题）
+4. **格式必须精确匹配**：`## Phase X/6:` + 大写英文名 + ` (中文名)`
+5. 跳过某个 Phase（如 `--resume-from build` 跳过了 PREP, DESIGN）时，不输出被跳过 Phase 的标题
+6. 触发 `/sprint-flow` 后，**第一行输出应包含工作流阶段概览**：
+
+```
+Sprint Flow: PREP → DESIGN → BUILD → VERIFY → SHIP → CLOSE
+```
+
+### Phase 1/6: PREP (准备工作 — worktree 隔离 + 规模评估)
+
+**执行时机**: `/sprint-flow` 启动后 → Phase 2/6 DESIGN 前。**自动执行**。
+
+**对应旧模型**: Phase -1 ISOLATE + Phase -0.5 AUTO-ESTIMATE
+
+**详细指令**: 参见 `references/phase-1-prep.md` — 包含步骤表、参数处理、错误回退、sprint-state 格式、AUTO-ESTIMATE 指标计算、路由决策。
+
+**快速参考**:
+1. 检测保护分支 (main/master/develop) → 自动创建 worktree `.worktrees/sprint/sprint-YYYY-MM-DD-NN`
+2. Sprint Lock 检测（Issue #144）— stale 锁自动覆盖，非 stale 阻断
+3. 项目 setup (`npm install`/`go mod download`/`pip install`)
+4. `.gitignore` 校验 + Sprint State 记录 + 基线测试
+5. 识别需求类型 → 收集指标（引用计数、跨模块依赖、循环依赖）→ **轻量** / **标准** / **复杂**
+6. 输出评估结果 → 用户确认后按路由继续
+7. **参数**: `--no-isolate` (跳过), `--branch-name <name>`, `--force` (绕过保护分支)
+
+### Phase 2/6: DESIGN (设计 — 需求探索 + 双点评审)
+
+**对应旧模型**: Phase 0 THINK + Phase 1 PLAN
+
+**执行者**: orchestrator 直接执行全部步骤（交互式 skill）。
+
+**详细指令**: 参见 `references/phase-2-design.md` — 完整流程、条件分支、HARD-GATE。
+
+**快速参考**:
+- **Step 0: CONTEXT.md 预检 (#322)**: 存在则 SKIP grill 访谈，但 R1 需求评审仍执行（CONTEXT.md 可能陈旧）
+- **Step 1: grill-with-docs** — `skill(name="grill-with-docs")` — 逐个追问 + CONTEXT.md/ADR 沉淀。**HARD-GATE**: 设计未批准 → 不可进入实现
+- **Step 2: R1 需求评审 (#368)** — `/delphi-review --mode requirements` Agent skill — 所有路径都由三专家独立执行，验证 distinct model IDs 后聚合 ≥90% 共识，输出 requirements-reviewed.json（含可重新计算的 requirements_hash 与 exact-HEAD 防陈旧绑定）
+- **Step 3: 原生设计文档生成** — `docs/plans/YYYY-MM-DD-<topic>-design.md`（需求摘要、2-3 方案、推荐、成功标准）
+- **Step 4: HARD-GATE APPROVAL** — 用户审批设计文档
+- **Step 5: 路由分叉** — `change_type == "修改已存在代码"` → SKIP batch-grill-me, lightweight R2
+- **Step 6: batch-grill-me** — `skill(name="batch-grill-me")` — 批量前置决策（替代 autoplan taste_decisions）
+- **Step 7: R2 delphi-review** — `skill(name="delphi-review")` — 等待 APPROVED（≥90% 共识）
+- **Step 8: to-issues** — `skill(name="to-issues")` — 垂直切片 Issue 拆分 → slices-manifest.json
+- **Step 9: specification.yaml** — 从 APPROVED 设计文档自动提取（每 REQ 含验收标准 — #368）
+- **Web 前端额外注入**: OPTIONAL design-shotgun（如已安装）
+
+### Phase 2/6→3/6: GITHOOKS-GATE（质量门禁安装检查）
+
+**执行时机**: Phase 2/6 DESIGN 完全通过、准备进入 Phase 3/6 BUILD 之前。
+
+**必须执行**: 运行 `githooks/verify.sh` 检查当前项目的 hooks 是否安装。
+
+**检查结果处理**:
+- ✅ 全部存在 → 进入 Phase 3/6 BUILD 入口（仍必须先执行 DELPHI-GATE）
+- ❌ 部分/全部缺失 → 运行 `githooks/install.sh` 安装（包括 `.git/hooks/pre-commit`、`.git/hooks/pre-push`、`githooks/adapter-common.sh`、`githooks/adapters/`）
+  - 如果 githooks/ 目录不存在于项目根目录（即当前项目不是 xp-gate） → 从 xp-gate 仓库拉取 `githooks/` 目录结构
+  - 安装完成后再次 `verify.sh` 确认
+
+**核心原则**: 没有质量门禁的代码不可进入 BUILD 阶段。**GITHOOKS-GATE 失败 → 不可编码。**
+
+### Phase 3/6: BUILD (构建 — ralph-loop 默认 + TDD + 盲评 + 验证)
+
+**对应旧模型**: Phase 2 BUILD（功能不变）
+
+**详细指令**: 参见 `references/phase-3-build.md`。
+
+**快速参考**:
+1. **BUILD-ENTRY-CONTRACT (MANDATORY — v0.18.0+)**: `phase-transition 3 in_progress` 校验 slices-manifest.json schema + slice↔REQ 一致性 → 不合法 BLOCK
+2. **DELPHI-GATE**: 验证 `.sprint-state/delphi-reviewed.json` 存在且 `verdict = "APPROVED"` → 否则 BLOCK
+3. **TDD-GATE (MANDATORY — v0.14.0+)**: 在 delegation 前验证每个 REQ 存在 failing test。无 test → mark `[TDD-RED]`（ralph-loop 创建）。有 test 且 GREEN 且无实现 → BLOCK（TDD bypass）。详见 `references/phase-3-build.md#tdd-gate-pre-implementation-tdd-check-mandatory`。
+4. **输入**: `slices-manifest.json`（Phase 2/6 生成），按 `execution_order` 逐个执行
+5. **模式**: 默认 `ralph-loop`（逐 REQ 迭代，token 节约 40-67%），可选 `--mode parallel`
+6. **Skill 步骤**: BUILD-ENTRY-CONTRACT → hooks-install → TDD-GATE → TDD (RED/GREEN/REFACTOR) → blind-review (read-only subagent, tools: [Read, Grep, Glob]) → verification-before-completion → 成本监控 → learnings.md 写入
+7. **Mock Minimization**: integration-first, mock 仅限 external services, 密度 > 30% 需 `@mock-justified`
+
+### Phase 4/6: VERIFY (验证 — 代码走查 + QA + 反馈获取)
+
+**对应旧模型**: Phase 3 REVIEW + Phase 4 FEEDBACK
+
+**详细指令**: 参见 `references/phase-4-verify.md`。
+
+**快速参考**:
+- **Orchestrator 直接执行**: delphi-review code-walkthrough 需要用户确认 verdict（Issue #249），**必须由 orchestrator 直接调用** `skill(name="delphi-review")`
+- **执行顺序**: `delphi-review --mode code-walkthrough` → 等待 APPROVED → `test-specification-alignment` (#367 程序化 HARD-GATE: test-alignment-report.json + head_commit + spec_hash) → `xp-gate check --all` → 浏览器验证 (Layer 4: gstack browse > browser-use MCP > SKIP)
+- **Web 前端**: `xp-gate ui-review`（原生）+ OPTIONAL gstack qa/design-review/benchmark（如已安装）
+- **Feedback 子阶段**: learnings.md 写入（原生）+ `xp-gate retro`（原生，含 #369 返工率区块）+ OPTIONAL systematic-debugging（Layer 4，保留"无根因不修复"纪律）
+- 输出: 评审报告 + feedback-log.md + test-alignment-report.json
+- **HARD-GATE**: feedback-log.md must exist + test-alignment-report.json PASS before Phase 5/6
+
+### 负载/压力测试（可选）
+
+- **适用项目**：主要用于后端服务的压力测试 (k6/Locust/Gatling)，Web 前端已有 `benchmark` 技能覆盖 Core Web Vitals、加载时间和资源大小等性能指标
+- **Phase 4/6 技能注入**：可根据项目类型自动选择合适的负载测试工具 (`k6` for Go-based services, `locust` for Python services, `gatling` for JVM-based services)
+- **集成方式**：可作为 Phase 4/6 的可选扩展，在 code-walkthrough 之后执行，与基准测试形成完整性能验证链条
+- **配置文件**：通过 `.sprint-load-test.yaml` 进行配置（待实现），包含并发用户数、持续时间、SLA 指标等参数
+- **触发条件**：后端项目可通过 `--type backend-*` 自动启用，或通过 `--with-performance` 标志手动启用
+- **Web 项目补充说明**：对于 Web 前端项目，现有的 `benchmark` 技能已处理页面加载性能、Core Web Vitals 等前端性能指标；负载/压力测试主要针对服务器端承载能力
+
+### Phase 5/6: SHIP (发布 — 发布准备 + 合并部署)
+
+**对应旧模型**: Phase 5 SHIP + Phase 6 LAND
+
+**详细指令**: 参见 `references/phase-5-ship.md` — VERSION-GATE (MANDATORY) / finishing-a-development-branch / VERSION CHANGESET (Issue #142) / changeset schema。
+
+**快速参考**:
+- **Step 0: VERSION-GATE (MANDATORY — 必须在分支完成决策之前)**: bump VERSION → update CHANGELOG.md → run sync-version.sh → commit + push → verify PR updated。详见 `references/phase-5-ship.md#step-0-version-gate`
+- **Step 1: 分支完成决策（原生 4 选项）**: AskUserQuestion 菜单 (merge/PR/keep/discard)，默认推荐 Option 2 (Push and create a Pull Request)
+- **Step 2: 原生 Ship 步骤**: test → VERSION-GATE → commit → push → `gh pr create`
+- 输入: phase-4-summary.md + feedback-log.md → 输出: PR URL (含版本变更 commit)
+- **HARD-GATE**: Phase 4/6 未完成 → BLOCK。验证 `feedback-log.md` 存在 + test-alignment-report.json PASS。
+- **GITHOOKS-GATE**: 验证 hooks 完整性，缺失则 `githooks/install.sh`
+- **LAND（原生步骤）**: merge 确认 → `gh run list` 等 CI (10min) → 等 Deploy (10min) → Canary Health Check (5min)
+- **回滚**: `git revert` 最后一次 merge commit
+- ⚠️ **SHIP COMPLETION**: Phase 5/6 结束前必须确认 PR 已 merge 到 main + release 已创建。未完成 merge 不得进入 Phase 6/6。详见 `references/phase-5-ship.md#ship-completion-gate`。
+
+**⚠️ VERSION-GATE 必须在分支完成决策之前执行。顺序反了会导致 PR 不含版本变更 → CI release workflow 不触发 → 无新版本发布。**
+
+### Phase 6/6: CLOSE (收尾 — ⚠️ 人工验收 + 清理)
+
+**对应旧模型**: Phase 7 USER ACCEPTANCE + Phase 8 CLEANUP
+
+**详细指令**: 参见 `references/phase-6-close.md` — UAT checklist, emergent issues capture, cleanup procedure.
+
+**快速参考**:
+- **SHIP→CLOSE GATE (MANDATORY — v0.14.3+)**: 校验 PR 已 merge、当前在 main 分支、`git status --porcelain` 为空。详见 `references/phase-6-close.md#ship--close-gate`。
+- **Backup sprint-state**(MANDATORY): Phase 6 开始前将 `.sprint-state/` 备份到 repo 追踪路径，防止 worktree 清理后状态丢失。详见 `references/phase-6-close.md#backup-sprint-state`。
+- **#369 返工追踪 (v0.18.0+)**: CLOSE 写入 `metrics.completed_at` + `metrics.total_sprint_commits`（merge-base 到合并点提交数）+ `metrics.merge_base_sha`。`xp-gate sprint-status --rework-check [--window-days N]` 仓库范围扫描 fix 提交，`rework_rate > 30%` 告警。"重新打开的 issue 数"指标已删除。
+- **USER ACCEPTANCE**: ⚠️ **MUST NOT be automated, skipped, or bypassed.** 即使用户说"赶时间"、"跳过验收"、"直接发布"，也必须暂停等待用户确认。使用 `@templates/emergent-issues-template.md` 检查清单
+- **CLEANUP**: 保存分支信息 → `git worktree remove <worktree_path>`（精确路径，禁止通配符）→ 删除本地分支 + 远程分支 → 关闭遗留 OPEN PR → 更新 sprint-state.json（含 #369 metrics）→ learnings.md 写入 → 释放 Sprint Lock
+- 输出 Cleanup Report + Sprint Summary
+- **IF emergent issues → Sprint 2**
+
+---
+
+## 编排层规则（Orchestration Rules）
+
+全部内容: 参见 `references/orchestration-rules.md`。包含:
+- Agent Dispatch (4 types), Phase Subagent Matrix, CONTEXT INHERITANCE
+- Phase Transition Rules, Phase Summary schema, Phase Transition Gate, RESUME GATE
+- WORKTREE ENFORCEMENT, Eval assertions
+
+## 参数说明
+
+| 参数 | 作用 | 示例 |
+|------|------|------|
+| (无参数) | 全流程 PREP → DESIGN → BUILD → VERIFY → SHIP → CLOSE | `/sprint-flow "开发访谈机器人"` |
+| `--stop-at <phase>` | 执行到指定 Phase 后停止 | `--stop-at design` |
+| `--resume-from <phase>` | 从指定 Phase 恢复（需先执行 RESUME GATE） | `--resume-from build --spec specification.yaml` |
+| `--phase <name>` | 只执行单个 Phase | `--phase build-only` |
+| `--status` | 查看 Sprint 进度（只读，不执行 Phase） | `--status` |
+| `--lang <lang>` | 指定项目语言 | `--lang springboot` / `django` / `golang` |
+| `--type <type>` | 指定项目类型 | `--type web-nextjs` / `backend-django` |
+| `--spec <file>` | 使用已有的 specification.yaml | `--spec path/to/spec.yaml` |
+| `--no-isolate` | 跳过 git worktree 隔离 | `--no-isolate` |
+| `--branch-name <name>` | 自定义分支名 | `--branch-name feat/my-feature` |
+| `--force` | 强制在当前分支继续 | `--force` |
+| `--with-performance` | 启用负载/压力测试 | `--with-performance` |
+| `--mode <mode>` | 构建模式（ralph-loop / parallel） | `--mode ralph-loop` |
+
+**Backward Compatible Parameter Mapping** (`--stop-at` / `--resume-from` / `--phase`):
+
+| Legacy Value | Maps To |
+|-------------|---------|
+| `isolate`, `isolate-only` | `prep`, `prep-only` |
+| `think`, `think-only` | `design`, `design-only` |
+| `plan`, `plan-only` | `design`, `design-only` |
+| `build`, `build-only` | `build`, `build-only` |
+| `review`, `review-only` | `verify`, `verify-only` |
+| `ship`, `ship-only` | `ship`, `ship-only` |
+| `land`, `land-only` | `ship`, `ship-only` |
+| `cleanup`, `cleanup-only` | `close`, `close-only` |
+
+**`--status` 行为规则**:
+- 执行 `node scripts/render-sprint-progress.cjs`，读取 `.sprint-state/sprint-state.json` 并渲染 ASCII 进度看板
+- 如果 `sprint-state.json` 不存在 → `[INFO] 未找到活跃的 Sprint`
+- 如果 `status == "completed"` → 输出完整看板 + `[INFO] Sprint 已完成。`
+- `--status` 可与其他参数组合：`--status --resume-from build` → 先展示状态，再提示 "将从 Phase 3/6 BUILD 继续"
+
+**`--resume-from` 限制**：校验为**尽力而为**（git commit 可被 GC 回收、文件 mtime 可被 `git checkout` 修改）。校验失败时输出完整诊断日志，建议启动新 Sprint。
+
+**项目类型自动检测**（按顺序检查）：
+
+| 检测条件 | 类型 |
+|---------|------|
+| `package.json` + `next.config.js` | `web-nextjs` |
+| `package.json` + `vite.config.ts` + react 依赖 | `web-react` |
+| `package.json` + vue 依赖 | `web-vue` |
+| `pubspec.yaml` + `flutter:` | `mobile-flutter` |
+| `package.json` + react-native 依赖 or `ios/` + `android/` | `mobile-react-native` |
+| `go.mod` | `backend-go` (可选 k6) |
+| `pom.xml` | `backend-springboot` (可选 gatling) |
+| `manage.py` 或 `pyproject.toml` (django) | `backend-django` (可选 locust) |
+| 无匹配 | `backend-cli` |
+
+**项目类型 → Skill 注入映射**:
+
+| Phase | Backend (default) | Web Frontend | Mobile | Load Test |
+|-------|------------------|-------------|--------|-----------|
+| 2/6 DESIGN | `grill-with-docs` + R1 `delphi-review --mode requirements` + `batch-grill-me` + R2 `delphi-review` | + OPTIONAL `design-shotgun` | (同 web) | (通用) |
+| 3/6 BUILD | TDD + blind-review (read-only subagent) | (同 backend) | + `vercel-react-native-skills` / `flutter-review` | (同) |
+| 4/6 VERIFY | `delphi-review --mode code-walkthrough` + `test-specification-alignment` + `xp-gate check --all` + k6/locust/gatling | + `xp-gate ui-review` + OPTIONAL qa/design-review/benchmark | Flutter: `flutter-test` / RN: `detox E2E` | k6/locust/gatling |
+| 4/6 VERIFY (Feedback) | learnings.md + `xp-gate retro` | (同) | (同) | (同) |
+| 5/6 SHIP | VERSION-GATE + 原生 4 选项 + native ship + native land | (同) | + platform deploy | (同) |
+| 6/6 CLOSE | — 人工验收 → #369 返工指标 → cleanup | (同) | (同) | (同) |
+| Browse | Layer 4 可选链 (gstack browse > browser-use MCP > SKIP) | 部署 URL + 表单/交互 | Flutter Web / RN Web | (专用) |
+
+**Mobile 工具链**: Flutter — `flutter analyze/test/build/pub publish`; RN — `metro/detox/jest/react-native run-ios/android`
+
+---
+
+## 状态管理
+
+**Sprint State**: 存储于 `<project-root>/.sprint-state/` — `sprint-state.yaml`/`.json` + `phase-outputs/` (pain-document.md / specification.yaml / mvp-v1 / review-report.md / emergent-issues.md / feedback-log.md / sprint-summary.md)
+
+**Sprint 2 自动触发**: Phase 6/6 CLOSE 完成时 — `emergent_issues_count == 0` → 结束; `> 0` → Critical 自动启动 Sprint 2, Major/Minor 询问用户
+
+---
+
+### ⭐ Phase State Persistence（阶段状态持久化 — MANDATORY）
+
+**编排器必须在每个 Phase 完成后更新 `.sprint-state/sprint-state.json`**：
+
+1. **Phase 完成后立即更新**（每个 Phase 结束前）：
+   - `phase`: 更新为当前 Phase 编号（如 `1`, `2`, `3`...）
+   - `status`: 更新为 `"completed"`（已完成 Phase）
+   - `phase_history`: 追加新条目
+
+2. **`phase_history` 数组条目 schema**：
+   ```json
+   {
+     "phase": 1,
+     "phase_name": "PREP",
+     "status": "completed",
+     "timestamp": "2026-07-08T10:30:00Z"
+   }
+   ```
+
+3. **检查点**：
+   - `--status` 参数读取 `sprint-state.json` 并渲染进度看板
+   - TUI panel 显示当前 Phase 和历史
+   - `--resume-from` 校验 `phase_history` 中的最后完成 Phase
+
+4. **完整 sprint-state.json 示例**：
+   ```json
+   {
+     "id": "sprint-2026-07-08-01",
+     "phase": 3,
+     "status": "in_progress",
+     "phase_history": [
+       {"phase": 1, "phase_name": "PREP", "status": "completed", "timestamp": "2026-07-08T10:00:00Z"},
+       {"phase": 2, "phase_name": "DESIGN", "status": "completed", "timestamp": "2026-07-08T10:30:00Z"}
+     ],
+     "isolation": {
+       "worktree_path": "/home/boyingliu01/projects/xp-gate/.worktrees/sprint/sprint-2026-07-08-01",
+       "branch": "sprint/2026-07-08-01"
+     },
+     "outputs": {
+       "pain_document": "phase-outputs/phase-2-summary.md",
+       "specification": "phase-outputs/specification.yaml"
+     },
+     "metrics": {
+       "coverage_pct": 85.5
+     }
+   }
+   ```
+
+**Backward compat**: Old sprint-state.json files using negative/legacy phase numbers (`-1`, `-0.5`, `0`..`8`) remain readable. Dashboard renders them as-is. New sprints use phase numbers 1-6.
+
+---
+
+## 使用示例
+
+| 场景 | 命令 | 说明 |
+|------|------|------|
+| 完整流水线 | `/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)，sprint-flow 仅自动串联
+
+---
+
+## Output Contract
+
+**Phase Summary** (每个 Phase 必须输出 YAML frontmatter): `phase/N`, `phase_name`, `status`, `outputs[]`, `decisions[]`, `next_phase_context` + markdown body (≤50 lines)
+
+**Sprint State JSON**: `{id, phase, status, phase_history[], isolation {worktree_path, branch}, outputs, metrics}` — 存储于 `.sprint-state/sprint-state.json`
+
+**Final User-Facing Output**: Phase/status, file paths, validation results, next user decision, PR URL or cleanup report
+
+### Eval Assertions
+- `phase`, `phase_name`, `status`, `outputs`, `decisions`, `next_phase_context`
+- `id`, `isolation.worktree_path`, `isolation.branch`, `metrics.coverage_pct`
+
+## References
+
+详细指令文件位于 `@references/`:
+
+| File | Phase | Phase Name | Maps From (Old) |
+|------|-------|------------|-----------------|
+| `@references/phase-1-prep.md` | 1/6 | PREP | Phase -1 ISOLATE + Phase -0.5 AUTO-ESTIMATE |
+| `@references/phase-2-design.md` | 2/6 | DESIGN | Phase 0 THINK + Phase 1 PLAN |
+| `@references/phase-3-build.md` | 3/6 | BUILD | Phase 2 BUILD |
+| `@references/phase-4-verify.md` | 4/6 | VERIFY | Phase 3 REVIEW + Phase 4 FEEDBACK |
+| `@references/phase-5-ship.md` | 5/6 | SHIP | Phase 5 SHIP + Phase 6 LAND |
+| `@references/phase-6-close.md` | 6/6 | CLOSE | Phase 7 USER ACCEPTANCE + Phase 8 CLEANUP |
+
+Additional reference files:
+- `@references/force-levels.md` — Phase forcing rules
+- `@references/orchestration-rules.md` — Orchestration layer rules
+
+- `@references/components/` — Reusable phase building blocks
+
+---
+
+## Templates
+
+模板文件位于 `@templates/`:
+- `@templates/pain-document-template.md` — Pain Document 模板 (Phase 2/6 DESIGN)
+- `@templates/emergent-issues-template.md` — Emergent Issues 检查清单 (Phase 6/6 CLOSE)
+- `@templates/sprint-summary-template.md` — Sprint Summary 模板 (Phase 6/6 CLOSE)
+- `@templates/sprint-progress-template.md` — Sprint 进度看板（每个 Phase 完成后 + `--status` 查询时渲染）
+- `@templates/auto-estimate-output-template.md` — AUTO-ESTIMATE 输出格式 (Phase 1/6 PREP)
+
+---
+
+## 研究证据
+
+| 证据 | 来源 | 应用 |
+|------|------|------|
+| One-shot = 单次迭代执行 | Boris Cherny interview | Phase 3/6 BUILD 设计 |
+| 80% session 从 Plan Mode 开始 | Boris skill | Phase 2/6 DESIGN 设计 |
+| Verification improves 2-3x | Boris #1 tip | Phase 4/6 VERIFY 设计 |
+| Emergent requirements 无法消除 | Mike Cohn, Rafael Santos | Phase 6/6 CLOSE 人工设计 |
+| 78% failures invisible | arXiv research | Phase 6/6 必要性证明 |
+| Think → Plan → Build → Ship | 行业通用流程 | 整体流程设计 |
+
+---
+
+## Phase Flow Consistency
+
+This section documents the canonical 6-phase order to ensure all future edits keep the phase sequence synchronized across all locations in this document and its reference files.
+
+**Canonical Phase Order** (Phase 1/6..6/6):
+
+| Phase # | Name | Phase # | Name |
+|---------|------|---------|------|
+| 1/6 | PREP | 4/6 | VERIFY |
+| 2/6 | DESIGN | 5/6 | SHIP |
+| 3/6 | BUILD | 6/6 | CLOSE |
+
+**Locations that MUST keep this order synchronized**:
+1. **Frontmatter `workflow_steps`** — Phase list
+2. **Frontmatter `description` trigger text** — Flow string
+3. **Body "完整流程" section** — Phase descriptions in order
+4. **Body "Phase Flow" diagram** — ASCII flow diagram
+5. **Body "强制输出格式规范" section** — Output format
+6. **Body "Workflow Steps" table** — Step/Phase table
+7. **Body "References" section** — Reference file list
+8. **`references/orchestration-rules.md` Phase Subagent Dispatch Matrix** — Phase/Name order
+9. **`references/force-levels.md`** — Phase references
+
+**⚠️ Migration from old 11-phase model (v2.0)**: The 6-phase model was introduced in Issue #290 to reduce cognitive load. Old sprint-state.json files with negative/legacy phase numbers remain backward-compatible.

package/plugins/qoder/skills/sprint-flow/scripts/verify-sprint-state.sh

@@ -0,0 +1,38 @@
+#!/usr/bin/env bash
+# sprint-flow: Verify sprint state integrity
+# Checks that sprint-state.json is valid JSON and all expected keys exist.
+#
+# Usage: bash verify-sprint-state.sh [sprint-state-dir]
+
+set -euo pipefail
+
+STATE_DIR="${1:-.sprint-state}"
+STATE_FILE="$STATE_DIR/sprint-state.json"
+
+if [ ! -f "$STATE_FILE" ]; then
+    echo "SKIP: No sprint-state.json found at $STATE_FILE"
+    exit 0
+fi
+
+# Validate JSON
+if ! command -v node &>/dev/null; then
+    echo "WARN: node not available, skipping JSON validation"
+    exit 0
+fi
+
+node -e "
+const fs = require('fs');
+try {
+    const data = JSON.parse(fs.readFileSync('$STATE_FILE', 'utf8'));
+    const requiredKeys = ['sprint_id', 'status', 'current_phase', 'phases'];
+    const missing = requiredKeys.filter(k => !(k in data));
+    if (missing.length > 0) {
+        console.error('ERROR: Missing required keys in sprint-state.json:', missing.join(', '));
+        process.exit(1);
+    }
+    console.log('OK: sprint-state.json is valid with all required keys');
+} catch (e) {
+    console.error('ERROR: sprint-state.json is not valid JSON:', e.message);
+    process.exit(1);
+}
+"

package/plugins/qoder/skills/sprint-flow/tools.md

@@ -0,0 +1,29 @@
+# Tools Whitelist — Sprint Flow
+
+Sprint Flow is an **orchestration skill** that coordinates subagents and system commands.
+It does NOT implement code directly — it delegates implementation to subagents.
+
+## Allowed Tools
+
+| Tool | Usage | Rationale |
+|------|-------|-----------|
+| `Bash(git, gh, npm, node)` | git worktree/branch/commit, gh PR/release, npm/node CLI | Required for sprint infrastructure management |
+| `Read` | Read project files, configs, docs | Required for context gathering |
+| `Write` | Write sprint-state, specification.yaml, phase summaries | Required for sprint state persistence |
+| `Edit` | Edit sprint-state, CHANGELOG, VERSION | Required for version management |
+| `Glob` | Find project files by pattern | Required for project discovery |
+| `Grep` | Search file contents | Required for codebase understanding |
+| `Task` | Delegate to subagents (quick, deep, unspecified-high) | Core orchestration mechanism |
+| `Skill` | Invoke integrated skills (brainstorming, autoplan, delphi-review, etc.) | Required for skill chain execution |
+| `TodoWrite` | Track sprint progress | Required for progress visibility |
+| `Question` | Ask user at decision gates | Required for user decision points |
+
+## Denied Tools
+
+| Tool | Rationale |
+|------|-----------|
+| `rm -rf (any recursive force remove)` | Destructive — sprint flow only cleans up via `git worktree remove` |
+| `git push --force` | Destructive — never force push during sprint |
+| `DROP TABLE or destructive DB operations` | Destructive — sprint flow orchestrates, does not manage databases |
+| `Write(source code)` | Sprint flow NEVER writes implementation code directly — delegates to subagents via `Task` |
+| `Edit(source code)` | Sprint flow NEVER edits implementation code — delegates to subagents via `Task` |

package/plugins/qoder/skills/test-specification-alignment/AGENTS.md

@@ -1,9 +1,9 @@
 # SKILLS/TEST-SPECIFICATION-ALIGNMENT KNOWLEDGE BASE
 
-**Generated:** 2026-09-22
-**Commit:** 3d1d1bf
-**Branch:** main
-**Version:** 0.19.2.0
+**Generated:** 2026-10-07
+**Commit:** ff55f35b
+**Branch:** fix/batch-defects-20261007
+**Version:** 0.20.0.0
 
 ## OVERVIEW
 Test-Specification Alignment Engine — two-stage validation ensuring tests accurately reflect requirements and design specs.