Sprint Flow — 6-Phase Development Pipeline

Triggers

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

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:

## 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。

输入：

步骤：

1. 输出首行：Sprint Flow: PREP → DESIGN → BUILD → VERIFY → SHIP → CLOSE
2. 检测当前分支是否为保护分支（main/master/develop）
3. 创建 git worktree 隔离（除非 --no-isolate）：

   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

输出：

详细参考：@references/phase-1-prep.md

门禁条件表 (Gate Conditions)

Phase 2–6 详细指令

Phase 2–6 的完整步骤、输入/输出契约、模板和 Skill 集成详情见 references/ 目录。本节提供路由摘要。

路径约定：@references/ 和 @templates/ 相对于 skill 目录（skills/sprint-flow/）解析。

完整参考文件索引：

Anti-Patterns

状态机 (State Machine)

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：

## 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}

强制决策点：

失败处理 (Failure Handling)

BLOCK 状态处理：

1. 写入 .sprint-state/sprint-state.json 状态为 blocked
2. 输出阻塞原因 + 已完成工作 + 建议操作
3. 等待用户决策（继续/放弃/降级）
4. 记录决策到 decisions.md

使用示例

底层 Skills 保持独立

所有被调用的 Skills 独立可用：delphi-review (单独评审), test-driven-development (TDD), grill-with-docs (需求访谈), batch-grill-me (批量决策), to-issues (切片拆分)，sprint-flow 仅自动串联