Read the **Profile:** line from CLAUDE.md to determine the active project profile.
**Lean mode:** Skip steps 1.5 (Metrics Health Check), 1.6 (Debt Health Check), and step 3 (Sprint Planning ceremony — no sprint spec generation, no story selection, no PRD check). Perform only: 1a-1d (pre-flight checks), step 2 (create feature branch), and update `docs/progress.md` with branch name and sprint number.
**Strict mode:** All steps mandatory. Metrics and debt checks must produce actionable output (not just "all clear"). Sprint spec generation is required with explicit quality gate plan section.
1. Pre-flight Checks
Verify the workspace is ready for new work:
1a. Check for open PRs
gh pr list --author @me --state open
If open PRs exist:
Check if any are approved → merge them: gh pr merge --squash --delete-branch
If awaiting review → inform user and ask whether to proceed or wait
1b. Verify clean working tree
git status
If uncommitted changes exist:
Warn user — they must commit, stash, or discard before proceeding
Do NOT proceed with dirty working tree
1c. Ensure on default branch and up to date
Read the Default branch from CLAUDE.md's Git Workflow section. If not set, detect it at runtime:
# Read from CLAUDE.md first, fall back to detection
DEFAULT_BRANCH=$(grep -oP '^\- \*\*Default branch:\*\* \K\S+' CLAUDE.md 2>/dev/null)
if [ -z "$DEFAULT_BRANCH" ]; then
DEFAULT_BRANCH=$(git symbolic-ref refs/remotes/origin/HEAD 2>/dev/null | sed 's@^refs/remotes/origin/@@')
fiif [ -z ];
branch main master develop;
git show-ref --verify --quiet ;
DEFAULT_BRANCH=
Scan `docs/technical-debt.md` for debt that should influence sprint planning:
After branch creation, ask the user if they want to create a draft PR for early CI feedback:
**Sprint Definition of Done** (derived from PRD): Read PRD Section 6 (NFRs) and Section 7 (scope boundaries). Include applicable thresholds:
- Performance targets from NFRs (e.g., "API < 200ms P95")
- Security requirements from NFRs (e.g., "all PII encrypted")
- Implementation boundaries from Section 7 (Always/Ask first/Never rules)
Debt neglect check — scan the Resolved section for dates. If no items resolved in the last 2 sprints, flag: "No debt resolved in 2+ sprints — debt is accumulating without remediation."
Present findings before story selection in step 3, framed as recommendations:
"Debt register: [N] active items ([N] critical, [N] growing). Sprint candidates: TD-NNN [title], TD-NNN [title]. Consider including at least 1 debt remediation story."
If Critical items exist, present them as P0 stories alongside backlog stories in the step 3 story table. If Growing items exist, note them as recommended additions.
2. Create Feature Branch
Determine the next sprint number by reading docs/progress.md and finding the highest sprint number, then adding 1.
Standard Mode (default)
Create a new branch from the default branch:
git checkout -b sprint-<number>
Worktree Mode (when --worktree is in $ARGUMENTS or user requests it)
Create an isolated worktree for parallel development:
**Worktree created:**`../<project>-sprint-<number>`
To work in this worktree, open a new Claude Code instance in that directory.
Each worktree has its own branch and working tree, so you can work on multiple stories in parallel.
**Important:** When done, run `/sprint-end` from within the worktree. It will clean up after merge.
The number is always the next sequential sprint number
Optional: Draft PR for Early CI Feedback
git push -u origin sprint-<number>
gh pr create --draft --title "Sprint <N>: <sprint-goal>" --body "Work in progress — sprint branch for early CI feedback."
Draft PRs enable CI to run on every push during the sprint, catching issues early. They block merging and suppress CODEOWNERS notifications until marked ready.
If user declines, skip — the branch is pushed and PR created at sprint-end.
3. Sprint Planning
Show Upcoming Stories
Read docs/reference/BACKLOG_INDEX.md and scan epic files for stories with status ready, grouped by priority:
### Ready Stories (by priority)
| Priority | ID | Title | Type | Size | Epic |
|----------|----|-------|------|------|------|
| P0 | PROJ-001 | [title] | feature | S | E01 |
| P1 | PROJ-003 | [title] | bugfix | S | E01 |
If no stories have ready status, check for draft stories and suggest running /ideate to refine them, or /backlog-review to assess backlog health.
Define Sprint Goal and Scope
Ask the user to select stories for this sprint and define a sprint goal. Guide them:
Sprint goal: One sentence describing the outcome (not a list of stories). Example: "Enable users to authenticate via OAuth2"
Story selection: Based on ready stories, capacity (estimated sessions available), and priority order
Sizing: S (1 session), M (2-3 sessions), L (3-5 sessions) — based on complexity, not effort hours
Buffer: Reserve ~15% of sessions for unplanned work
Create Sprint Spec
Copy docs/sprints/_TEMPLATE.md to docs/sprints/sprint-<number>.md and fill in:
Sprint number and goal (from user input above)
Start date (today)
Branch name
Stories table (from selected stories, with sizes)
Boundaries: Done means, out of scope, risks
Capacity: available sessions, buffer, constraints
Leave the Decisions, Notes, and Outcome sections empty — they're filled during and after the sprint.
Update progress.md
Update docs/progress.md → ## Current Sprint section with:
### Sprint Ready**Sprint [N]: [goal]****Branch:**`sprint-<number>`**Mode:** [Standard / Worktree at ../<path>]
**Main status:** Tests passing, up to date
**Open PRs:** None (or list any that exist)
**Stories:** [count] selected ([total size estimate])
**Sprint spec:**`docs/sprints/sprint-<number>.md`
Ready to start work.
**Next steps:**1. Clear your context window: `/clear`2. Start the first story: `/story-cycle [first-story-id]`
Always show the actual first story ID from the sprint plan (e.g., /story-cycle E01-S01), not a placeholder.
