Claude Sprint Workflow

A production AI-assisted sprint management system built on Claude Code. I built this to solve a specific problem: as one of two developers on a two-week release cycle, I needed to get features QA-ready faster without sacrificing quality or losing track of what still needs to happen in a build.

The result: new features are typically QA-ready within the first day of a sprint. That leaves a full week for QA, security review, and a nearly-complete product demo before the sprint is even halfway done.

---

The problem it solves

Our product team structures work the way most do: epics contain many small, tightly related tickets. A ticket might be "add validation to the agency form" — but to implement it correctly, you need to understand how the agency form interacts with three other features in the same epic.

Before this workflow, I was feeding Claude individual tickets (or small batches) via /ship. The results were inconsistent — Claude would implement the ticket correctly in isolation but miss how it was supposed to interact with adjacent work. I was burning tokens correcting context mid-implementation and spending the back half of every sprint scrambling to address QA feedback.

The core insight: the ticket is the unit of work, but the epic is the unit of understanding. Claude needs the latter to make good decisions about the former.

---

How it works

At sprint start, /sprint-init pulls all my Jira tickets, groups them by epic, and generates a Build-Plan for each ticket — a Markdown spec synthesized from the full epic context, the BRD, and the ticket's acceptance criteria. I audit those plans (and resolve any open questions Claude flags) before a single line of code is written.

Then /epic PROJ-100 runs all tickets in that epic sequentially: for each ticket, it implements, runs QA with a browser-driving agent, and iterates up to three times before escalating to me. By the time the implementation agent touches code, the intent has already been reviewed and approved.

Sprint start (Monday)
  └─ /sprint-init
       ├─ fetch tickets + epics from Jira
       ├─ create one git worktree per epic
       ├─ synthesize Build-Plans from BRD + Jira AC
       └─ generate Todos.md

Day 1–2
  └─ /epic PROJ-100
       ├─ [1/N] PROJ-104 → implement → QA loop → Jira: In Review
       ├─ [2/N] PROJ-105 → implement → QA loop → Jira: In Review
       └─ [3/N] PROJ-106 → implement → QA loop → Jira: In Review

Week 1 Friday (Demo)
  └─ Product + CX feedback collected in Demo.md
  └─ /qa-fix processes demo issues → new Jira tickets → fixes → re-verify

Week 2
  └─ QA team works through features
  └─ /qa-fix for any returns
  └─ /sprint-release → one PR per epic → Jira transitions → release notes

---

Design decisions

Build-Plans shift review earlier

The most impactful change wasn't the automation — it was moving review from code to intent. Before, I was reviewing Claude's output after implementation. Now I review the Build-Plan before it. Claude generates the plan; I audit it and resolve open questions; then implementation runs with context already locked in.

This means the coder agent is never guessing about cross-ticket interactions, BRD requirements, or scope boundaries. It has a spec. The hard thinking happened at plan time.

Epic-level context, not ticket-level

/sprint-init synthesizes Build-Plans from three sources in priority order: the BRD, the Jira epic description, and the individual ticket's AC. The BRD provides business rules and acceptance criteria; Jira fills gaps; the ticket scopes the work. Each Build-Plan has the full picture of where its ticket sits within the epic.

This is what fixed the "implements correctly in isolation but misses interactions" problem. The coder agent knows what other tickets in the epic are doing.

One worktree per epic

Our product team's ticket structure — many small tickets per epic — means the tickets are too closely related to warrant separate branches. Rather than asking product to change how they cut tickets, I adapted the tooling to match their workflow. One worktree per epic, all tickets commit to the same branch, one PR per epic at release.

This also keeps the staging branch clean: /deploy rebuilds it from scratch by merging all epic branches into a personal staging branch. QA always has an accurate snapshot of what's in the current sprint — no drift from accumulated merges.

The QA loop has a hard stop at 3

The coder and qa-engineer agents iterate: QA fails, coder fixes, QA re-verifies — up to three times. Three was tuned empirically. In practice, most issues resolve in one or two passes. When something hits the limit, it's almost always because the requirements were ambiguous, not because the implementation is broken — and that's a human call, not a fourth iteration.

The vault maps to the meeting schedule

The Obsidian vault isn't just documentation — it's structured around the feedback touchpoints in our sprint:

Day	Meeting	Vault artifact
Monday (sprint start)	Planning session	Sprint-Overview.md generated by /sprint-init
Friday week 1	Demo	Demo.md — product and CX feedback captured here
Following Tuesday	Post-mortem	Post-Mortem.md stub ready to fill
Anytime	—	Todos.md — live checklist of remaining verification items and deployment dependencies

Demo.md is particularly useful: any issues raised during the demo are logged there, and /qa-fix converts them into Jira tickets and fixes them without me having to manually track anything. Todos.md aggregates open verification items and deployment checklist entries across all tickets so nothing falls through between sprint and release.

The vault is personal state, not shared state

Each developer runs their own instance. The vault is backed up to git, so if context needs to be shared (or I need to recover from a dead machine), it's accessible. But day-to-day it's mine — which means it stays lean and doesn't require any team coordination to maintain.

---

The agent pipeline

Four specialized agents with hard role boundaries:

Agent	Does	Does not
coder	Writes and edits code, runs builds	Browse URLs, run tests, write docs
qa-engineer	Browses the running app, verifies behavior	Edit files, make assumptions
tech-writer	Writes release notes and deployment docs	Touch source code
pr-reviewer	Reviews diffs for bugs, security, conventions	Flag style preferences

Separating these prevents the failure mode where a single agent "fixes" something, re-reads the code to verify, and declares success without actually testing behavior.

---

Vault structure

vault/
├── Sprints/
│   └── Sprint 12/
│       ├── docs/
│       │   ├── Sprint-Overview.md      ← ticket table + worktree info
│       │   └── BRD-PROJ-100.md         ← add before /sprint-init continues
│       ├── PROJ-456-feature-slug.md    ← Build-Plan per ticket
│       ├── Todos.md                    ← live checklist, auto-generated
│       ├── Release-Notes-epic-slug.md  ← auto-generated at release
│       └── Meetings/
│           ├── Dev-Planning.md
│           ├── Planning-Session.md
│           ├── Post-Mortem.md
│           └── Demo.md
└── Templates/

---

Command reference

Command	What it does
/sprint-init [EPIC-IDs...]	Fetch tickets, create worktrees, generate Build-Plans, scaffold vault
/ticket PROJ-XXX	Full pipeline for one ticket: implement → QA → Jira → vault
/epic PROJ-XXX	Run all tickets in an epic sequentially
/ship <description>	Standalone feature: plan → implement → QA → docs → PR
/qa-fix PROJ-XXX	Fix QA-returned ticket + any demo issues, re-verify
/qa-loop	Re-run QA only, no implementation
/sprint-release [PROJ-XXX]	Release notes → PRs → Jira transitions
/deploy	Reset personal staging branch, merge all epic branches, push
/todos [sprint name]	Regenerate Todos.md from Build-Plans (fast, no LLM)

---

Setup

Prerequisites

• Claude Code with the Atlassian MCP connected
• gh CLI authenticated
• Git (worktrees are standard git)
• Python 3 (stdlib only — no dependencies)
• Obsidian or any Markdown editor

Configure for your project

1. Copy .claude/ into your home directory (merges with existing ~/.claude/)
2. Copy vault/ to your Obsidian vault location
3. Fill in the four config vars in CLAUDE.md:

PROJECT_KEY=MYAPP
REPO_PATH=~/repos/myapp
VAULT_PATH=~/Documents/vault
JIRA_URL=https://your-org.atlassian.net

4. Edit ~/.claude/agents/coder.md — add your stack's tech details, security rules, and build commands
5. Edit ~/.claude/scripts/generate-todos.py — set the three constants at the top (VAULT, JIRA, KEY)
6. Run /sprint-init at the start of your next sprint

Adapting to other issue trackers

The Atlassian MCP handles Jira. For Linear or GitHub Issues, replace the mcp__claude_ai_Atlassian__* ToolSearch calls in each command with your tracker's MCP tools or REST API calls. The Build-Plan generation, vault structure, and agent pipeline are tracker-agnostic.