Sprint Workflow

Sprint Workflow

Overview

Sprint Workflow describes the convergent diffusion execution model used by the Sprint plugin. A sprint progresses through six distinct phases -- from loading specifications through architectural planning, parallel implementation, testing, review, and finalization.

Prerequisites

• Sprint plugin installed (/​plugin install sprint)
• Project onboarded via /​sprint:setup (creates .claude/​project-goals.md and .claude/​project-map.md)
• Sprint created via /​sprint:new with a completed specs.md
• Understanding of the agent system (see the agent-patterns skill)

Instructions

1. Phase 0 -- Load Specifications. The orchestrator locates the sprint directory at .claude/​sprint/[N]/, reads specs.md for requirements, reads status.md if resuming a prior iteration, and detects the project type for framework-specific agent selection. See ${CLAUDE_SKILL_DIR}/​references/​sprint-phases.md for the full phase reference.
2. Phase 1 -- Architectural Planning. The project-architect agent reads project-map.md for architecture context and project-goals.md for business objectives. It produces specification files (api-contract.md, backend-specs.md, frontend-specs.md) and returns SPAWN REQUEST blocks for implementation agents.
3. Phase 2 -- Implementation. The orchestrator spawns implementation agents in parallel based on the architect's SPAWN REQUEST blocks. Agents include python-dev, nextjs-dev, cicd-agent, and allpurpose-agent. Each agent reads its assigned spec files and the shared api-contract.md, then returns a structured report.
4. Phase 3 -- Testing. Testing agents execute sequentially: qa-test-agent runs first (API and unit tests), then ui-test-agent runs browser-based E2E tests. Framework-specific diagnostics agents (e.g., nextjs-diagnostics-agent) run in parallel with UI tests. All agents produce test reports.
5. Phase 4 -- Review and Iteration. The architect reviews all agent reports, analyzes conformity against specifications, updates specs (removing completed items, adding fixes for failures), and updates status.md. The architect then decides: spawn more implementation agents, run more tests, or finalize.
6. Phase 5 -- Finalization. The orchestrator writes the final status.md summary, ensures all spec files are in a consistent state, cleans up temporary files like manual-test-report.md, and signals FINALIZE to end the sprint.
7. Convergence model. Each iteration reduces noise: completed work is removed from specs, working code is preserved, and only failures are re-addressed. Most sprints converge within 3-5 iterations. After 5 iterations without convergence, the orchestrator pauses and prompts for manual intervention.

Output

• Phase-by-phase execution log showing agent spawns, reports, and decisions
• Updated status.md after each iteration reflecting completed and remaining work
• Specification files that shrink with each iteration as requirements are satisfied
• Final status.md summary upon sprint completion
• FINALIZE signal to the orchestrator when all specs are satisfied

Error Handling

Examples

Starting a new sprint:

/​sprint:new       # Creates .claude/​sprint/​1/​specs.md
# Edit specs.md with requirements
/​sprint           # Executes the full phase lifecycle

Resuming after iteration pause:

# Review .claude/​sprint/​1/​status.md for blockers
# Adjust specs.md to narrow scope or fix conflicts
/​sprint           # Resumes from Phase 0, reads updated specs and status

Typical convergence flow:

Iteration 1: Architect plans → 3 agents implement → tests find 2 failures
Iteration 2: Architect narrows specs to 2 fixes → agents patch → tests pass
Iteration 3: All specs satisfied → FINALIZE

Resources

• ${CLAUDE_SKILL_DIR}/​references/​sprint-phases.md -- Detailed reference for all six phases with agent assignments and handoff rules
• Agent patterns skill for SPAWN REQUEST format and report structure
• Spec writing skill for authoring effective specs.md files
• API contract skill for designing the shared interface between agents