Sprint Runner is a CLI tool that orchestrates human-in-the-loop AI-assisted software development across distinct workflow phases. It codifies a battle-tested sprint methodology — separate contexts for discovery, building, review, documentation, and planning — into a tool that eliminates the manual copy-paste orchestration while preserving the human as the decision-maker at every gate.
The workflow it automates was developed over 30+ sprints across two production projects (FindMyHygienist.org and Project GridStream). The methodology works. The paperwork around it — zipping repos, pasting prompts, typing git add paths, reformatting commit plans — is what Sprint Runner replaces.
For the system design, see Architecture and the ADR record.
AI-assisted sprint development with separate chat contexts produces better results than monolithic conversations — tighter attention, cleaner handoffs, forced reflection at phase boundaries. But the human orchestration cost is significant:
- Copy-pasting prompt templates and filling in sprint-specific details
- Zipping repos and feeding them to fresh contexts
- Manually transcribing
git diff,git add, andgit commitcommands from sprint plans - Reformatting Claude's structured output into executable shell commands
- Tracking which phase you're in and what context to feed next
- Enforcing review gates through pure discipline rather than tooling
Sprint Runner keeps the methodology and removes the paperwork. The human remains the decision-maker: approving every commit, passing comprehension checks before code lands, and steering the sprint plan as understanding deepens. The CLI handles mode switching, prompt assembly, repo context packaging, and structured command output.
Sprint Runner is implemented in two languages, chosen for architectural reasons — not to check boxes.
Go is the orchestrator. The CLI shell, mode management, Claude API integration, SSE streaming, subprocess spawning, and user interaction loop are all Go. This is what Go was designed for: reliable concurrent I/O, fast compilation to a single binary, and a standard library that covers HTTP clients, process management, and terminal interaction without external dependencies. The orchestration layer is the largest surface area of the project and benefits from Go's fast development velocity.
Rust is the trust boundary. Claude's structured output — commit plans with file paths, git add lists, install instructions, shell commands — is untrusted input that Sprint Runner will execute against a real repository. Rust parses, validates, and types this output before anything touches the filesystem. A malformed path, a hallucinated file in a git add list, or a structurally invalid commit plan is a compile-time-prevented category of error, not a runtime surprise. Rust's enum system also models the review gate state machine — "you cannot reach the Commit state without passing through Quiz" — as a type-level guarantee.
The Rust surface is intentionally small: structured output parsing, the review gate engine, and the learning database writer. Everything else is Go. The architecture story is: "Go orchestrates, Rust validates. Unvalidated LLM output never touches the filesystem."
The trust boundary grows naturally as Sprint Runner matures. These are capabilities where Rust's guarantees pay for themselves — not speculative features, but problems that surface once the MVP is in daily use.
| Capability | Why Rust | When It Matters |
|---|---|---|
| Diff analysis engine | Parsing and validating git diff output into structured change sets. Pattern matching on hunks, detecting renames vs. new files, flagging unexpected changes. Correctness matters — this feeds the review gate. |
When review mode needs to present diffs structurally rather than as raw text |
| Commit plan evolution tracker | The commit plan is living — it grows during review. Tracking insertions, reorderings, and dependency changes between the original plan and the current state requires a merge model, not string comparison. | When sprint plans routinely grow 30%+ during review |
| Shell command sandboxing | Validating that generated shell commands are within an allowlist (git operations, test runners, package managers) before execution. Parsing shell syntax to reject pipes, redirects, or command substitution that shouldn't appear in a commit plan. | When the tool moves from "Nicole runs commands manually" to "CLI executes approved commands" |
| Context window estimator | Token-counting repo contents, sprint plans, and conversation history to warn before a phase's context would exceed the model's window. Needs to be fast (runs on every mode switch) and accurate (tiktoken-compatible). | When the tool manages API calls directly rather than pasting into claude.ai |
| Learning database query engine | Structured queries over the SQLite learning store — concept retrieval by topic, spaced-repetition scheduling, similarity matching for "have I seen this pattern before?" | When study mode graduates from basic logging to active retrieval |
| Template validation | Parsing prompt templates with placeholder slots, validating that all required context variables are bound before assembly, type-checking template composition. | When the prompt library grows beyond the original four modes |
Sprint Runner has four active modes and one async mode. Each mode maps to a separate Claude chat context with a specific job, specific input, and specific output. The boundaries are deliberate — fresh eyes at phase transitions catch drift that accumulated context normalizes.
| Mode | Job | Input | Output |
|---|---|---|---|
| Discovery | Project architect and documentarian | Conversation + reference materials | README.md, docs/architecture.md, docs/adr/, docs/remaining-sprints.md — the repo's own docs |
| Sprint Runner | Builder and pair programmer | Repo state + current sprint from remaining-sprints.md |
Structured commit plan with install instructions, git diff paths, git add file lists, test commands |
| Review | Commit gatekeeper, comprehension checker, learning synthesizer. Then (fresh context): doc reviewer and sprint replanner | Per-commit diffs + quiz interaction. Then: full repo state post-sprint | Approved/revised commits + learning topics → SQLite. Then: updated docs + revised remaining-sprints.md |
| Study | Tutor and quizmaster | Learning database contents | Quizzes, elaborations, concept reinforcement — never touches the repo |
Discovery ──→ Sprint Runner ──→ Review (per-commit gates)
│
├── learning → SQLite (before advancing)
│
╰── tests pass ──→ Doc Review + Replan (fresh context)
│
╰──→ next Sprint Runner
Review may span multiple chat contexts within a single sprint if a commit's learning section gets long enough to degrade attention. The human and AI use judgment here — there is no mechanical rule.
The Doc Review + Replan phase gets a fresh chat context deliberately. After a full sprint of building, a new context catches documentation drift and sprint plan assumptions that the builder context has normalized. First prompt: documentation and comments pass. Second prompt: do remaining sprints still make sense, reorder, resize, absorb housekeeping.
Study mode is fully decoupled from the sprint cycle. It pulls from the learning database on its own schedule.
Sprint Runner does not maintain its own state directory, database, or config beyond a small ~/.sprint-runner/config.toml for API keys and preferences. The project repository's own documentation is the sprint state:
docs/remaining-sprints.mddefines what's nextdocs/completed-sprints.mdrecords what's donedocs/adr/captures decisionsdocs/architecture.mddescribes the systemREADME.mdis the public face- Git tags (
sprint-N) mark phase boundaries - Git history is the audit trail
This means Sprint Runner works with any project that follows this doc structure. It also means the state is human-readable, git-tracked, GitHub-renderable, and backed up for free.
The one exception is the learning database (~/.sprint-runner/learning.db or project-local), which stores concepts synthesized during review for later study. This is personal learning state, not project state — it doesn't belong in the repo.
Status: Discovery phase complete. Sprint 1 not yet started.
- Go 1.22+
- Rust (stable toolchain via
rustup) - SQLite3
- An Anthropic API key (for Claude integration)
.
├── cmd/
│ └── sprint-runner/
│ └── main.go # CLI entrypoint
├── internal/
│ ├── modes/ # Mode management (discovery, runner, review, study)
│ ├── api/ # Claude API client, SSE streaming
│ ├── context/ # Repo packaging, doc extraction, context assembly
│ ├── prompt/ # Prompt template loading and variable binding
│ └── ui/ # Terminal interaction, approval gates, display
├── crates/
│ ├── plan-parser/ # Rust: structured commit plan parsing + validation
│ ├── review-gate/ # Rust: quiz state machine, comprehension checks
│ └── learn-store/ # Rust: SQLite learning database writer
├── docs/
│ ├── architecture.md
│ ├── remaining-sprints.md
│ ├── completed-sprints.md
│ └── adr/
├── prompts/ # Prompt templates per mode
├── README.md
├── go.mod
├── Cargo.toml # Workspace root for Rust crates
└── Makefile
Each sprint produces a working increment. See remaining-sprints.md for the full breakdown.
| Sprint | Focus | Cut-off Artifact |
|---|---|---|
| Sprint 1 | Go CLI skeleton + mode switching | CLI boots, switches modes, loads prompt templates. No Claude integration yet. |
| Sprint 2 | Rust commit plan parser | Parses and validates structured sprint plans into typed Rust structs. Callable from Go via CLI subprocess or FFI. |
| Sprint 3 | Claude API integration | Modes send prompts and receive streaming responses. Sprint Runner mode produces structured commit plans. |
| Sprint 4 | Review gate engine | Per-commit quiz gates in Rust. Learning topic synthesis to SQLite. Human must pass before commit advances. |
| Sprint 5 | Doc Review + Replan mode | Fresh-context doc assessment and sprint replanning. The full loop works end-to-end. |
| Sprint 6 | Study mode + polish | Learning database queries, quiz retrieval, spaced repetition basics. CLI UX polish. |
Author: N.L. Rowsey · Staff Backend & Data Platform Engineer · Distributed Systems · Python · Rust · Go · PhD EE · github.com/sooperD00
Project Status: Discovery phase complete. Ready for Sprint 1.
License: Documentation licensed under CC BY-ND 4.0. Implementation is proprietary.