# Scrum

A runnable Scrum process for building software with Claude Code. This repo isn't a product — it's a process kit: role-based sub-agents, step-by-step playbooks, and a live backlog that together let an AI agent (or a human) run a real Scrum lifecycle for whatever project gets built inside it.

The full rulebook the agents follow is [AGENTS.md](AGENTS.md); this file is the short, human-facing map of the repo and the order to work in.

## It knows where it is

[`state.md`](state.md) is a single live file tracking the current phase, the sprint in progress, and the next action. The agent reads it first every session and updates it last — so it knows what's going on and switches between the right sub-agent automatically, without you having to say "now do sprint planning." See [Automated handoff](#automated-handoff) below.

## Repository structure

| Path | What it's for |
|---|---|
| [`state.md`](state.md) | Current phase, current sprint, next action — read first, updated last |
| [`.claude/agents/`](.claude/agents) | Role-based sub-agents Claude Code auto-loads: `product-owner`, `scrum-master`, `dev-team`, `qa-tech-debt`, `release-planner` |
| [`process/`](process) | Numbered step-by-step playbooks for each part of the lifecycle |
| [`templates/`](templates) | Fill-in templates: user story, Definition of Done/Ready, sprint backlog, retrospective |
| [`backlog/`](backlog) | The live product backlog — `backlog.md` is the ordered index, `epics/*.md` hold the stories, `sprints/*.md` holds each sprint's instantiated backlog |
| [`logs/`](logs) | Append-only `impediment_log.md`, `technical_debt_log.md`, and `process_improvement_log.md` |
| [`project_config.md`](project_config.md) | Per-project settings (stack, sprint length, etc.) — starts as placeholders |
| [`code/`](code) | Where the actual project gets built — empty until onboarding runs |

## The process to follow

Work through these in order. Each step names the sub-agent that leads it and the process file with full detail.

0. **Project onboarding** *(once, before anything else)* — `product-owner` + `scrum-master` ask about vision, stack, tests, review process, CI, and sprint length; results are written to `project_config.md` and `templates/definition_of_done.md`. → [`process/00_project_onboarding.md`](process/00_project_onboarding.md)
1. **Backlog refinement** *(continuous, especially before planning)* — `product-owner` writes/refines user stories and acceptance criteria, `dev-team` sizes them, items are marked "ready." → [`process/01_backlog_refinement.md`](process/01_backlog_refinement.md)
2. **Sprint planning** *(start of every sprint)* — `scrum-master` facilitates; `product-owner` proposes the goal; `dev-team` pulls in and tasks out what it can realistically commit to. → [`process/02_sprint_planning.md`](process/02_sprint_planning.md)
3. **Sprint execution** *(every working day)* — `dev-team` implements vertical slices with a daily scrum run by `scrum-master`; anything not done is checked against the Definition of Done. → [`process/03_sprint_execution.md`](process/03_sprint_execution.md)
4. **Sprint review** *(end of every sprint)* — `product-owner` leads, `scrum-master` facilitates; demo working software, gather feedback, update the backlog. → [`process/04_sprint_review.md`](process/04_sprint_review.md)
5. **Sprint retrospective** *(end of every sprint, after the review)* — `scrum-master` leads; surface a few prioritized process improvements and feed them into the next sprint. → [`process/05_sprint_retrospective.md`](process/05_sprint_retrospective.md)
6. **Technical debt management** *(continuous, alongside any step)* — `qa-tech-debt` classifies, logs, and prioritizes debt for incremental repayment. → [`process/06_technical_debt_management.md`](process/06_technical_debt_management.md)
7. **Portfolio/release planning** *(above the sprint level, as needed)* — `release-planner` sequences sprints toward a release, keeping far-future scope coarse. See the "Multilevel Planning" section of [AGENTS.md](AGENTS.md).
8. **Process self-improvement** *(end of every retrospective)* — `scrum-master` separates insights about *this team* (go into the next sprint) from insights about *the kit itself* (this repo's process/templates/agents), logging the latter to `logs/process_improvement_log.md` and only proposing an edit once a pattern recurs. → [`process/07_process_improvement.md`](process/07_process_improvement.md)

Then repeat from step 1 for the next sprint.

## Automated handoff

At the start of every session, the agent reads `state.md` first — not the conversation history — to know which phase the project is in and which sub-agent leads it. It adopts that sub-agent's persona and keeps working; it doesn't wait to be told "now run sprint planning." When a phase's exit criteria (listed at the bottom of that phase's `process/0N_*.md` file) are met, the agent updates `state.md` — new phase, new leading agent, new next action — and switches personas in the same turn. Two points are treated as natural pauses to check with you first rather than steamroll through: finishing onboarding before the first sprint starts, and finishing a retrospective before committing to the next sprint. Continuous items (technical debt, process improvement) run on their own triggers alongside whatever the primary phase is; see [AGENTS.md](AGENTS.md) § "Automated State-Driven Handoff" for the exact algorithm.

## Process self-improvement

The kit itself — `AGENTS.md`, `process/`, `templates/`, `.claude/agents/` — is meant to improve over time too, not just the product built with it. Team-level retro insights still go straight into the next sprint's plan, but insights about the kit (a template that doesn't fit, an agent with the wrong scope, a missing process step) are logged separately in [`logs/process_improvement_log.md`](logs/process_improvement_log.md) rather than acted on immediately. An edit to the kit only gets proposed once a pattern recurs (or one occurrence was severe enough to visibly break a sprint), and it always requires the user's explicit go-ahead before anything shared gets changed — see [`process/07_process_improvement.md`](process/07_process_improvement.md) for the full rationale.

## Current status

This repo hasn't been used for a real project yet: `project_config.md` is all placeholders and `code/` is empty. To start, run onboarding — [`process/00_project_onboarding.md`](process/00_project_onboarding.md).