https://github.com/ikunin/sprintpilot
Sprint autopilot for BMad Method — drives stories from plan to PR-ready code with git worktrees, commits, and stacked PRs. Plus 7 multi-agent skills: code review, codebase mapping, tech-debt assessment, reverse-architecture, migration planning, research, and multi-persona debate.
https://github.com/ikunin/sprintpilot
autonomous-agents bmad-method-addon claude-code code-review codebase-analysis cursor git-workflow migration-planning multi-agent sprint-autopilot
Last synced: 12 days ago
JSON representation
Sprint autopilot for BMad Method — drives stories from plan to PR-ready code with git worktrees, commits, and stacked PRs. Plus 7 multi-agent skills: code review, codebase mapping, tech-debt assessment, reverse-architecture, migration planning, research, and multi-persona debate.
- Host: GitHub
- URL: https://github.com/ikunin/sprintpilot
- Owner: ikunin
- License: apache-2.0
- Created: 2026-04-17T12:00:50.000Z (about 2 months ago)
- Default Branch: main
- Last Pushed: 2026-05-27T21:32:21.000Z (15 days ago)
- Last Synced: 2026-05-27T22:17:27.985Z (15 days ago)
- Topics: autonomous-agents, bmad-method-addon, claude-code, code-review, codebase-analysis, cursor, git-workflow, migration-planning, multi-agent, sprint-autopilot
- Language: TypeScript
- Homepage: https://www.npmjs.com/package/sprintpilot
- Size: 14.3 MB
- Stars: 2
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: docs/CONTRIBUTING.md
- License: LICENSE
- Roadmap: docs/ROADMAP.md
- Agents: AGENTS.md
Awesome Lists containing this project
README
# Sprintpilot — Autopilot & Multi-Agent Addon for BMad Method
[](https://www.npmjs.com/package/@ikunin/sprintpilot)
[](https://www.npmjs.com/package/@ikunin/sprintpilot)
[](LICENSE)
[](https://github.com/bmad-code-org/BMAD-METHOD)
[](https://nodejs.org)
[](#compatibility)
Sprintpilot drives [BMad Method](https://github.com/bmad-code-org/BMAD-METHOD) v6 sprints to completion autonomously. One slash command turns your sprint plan into reviewed, tested, PR-ready code — story by story, with full git workflow.
> **Independent project.** Sprintpilot is not affiliated with or endorsed by BMad Code, LLC. See [TRADEMARK.md](TRADEMARK.md).
> Migrating from `bmad-autopilot-addon` v1? See [MIGRATION.md](MIGRATION.md).
## What it does
Per story, in one autonomous loop:
- Creates an isolated worktree + branch, runs `bmad-dev-story` TDD-style (RED then GREEN), lints changed files only.
- Stages explicitly (never `git add -A`), commits with a conventional message, runs **three parallel reviewers** on the diff.
- Auto-applies every PATCH finding as a separate commit, pushes, opens a PR (or merges directly, or lands as you go — your choice).
- Moves to the next story. At end-of-epic, writes a retrospective and lists PRs ready to merge.
The orchestrator (`_Sprintpilot/bin/autopilot.js`) is a deterministic Node state machine. It decides what runs next and enforces BMad's 7-step cycle. The LLM owns in-skill execution and small-judgment decisions. BMad skills are invoked verbatim — Sprintpilot never invents workflows of its own.
## Quick Start
```bash
# 1. Install BMad Method (interactive — pick your tool when prompted)
npx bmad-method install --modules bmm,tea
# 2. Install Sprintpilot (interactive — pick tool + complexity profile)
npx @ikunin/sprintpilot@latest
# 3. In your IDE chat:
/sprint-autopilot-on
```
**What you'll see next.** The orchestrator emits one BMad skill at a time and the LLM executes it. First skill is `bmad-create-story` for the next pending story in `sprint-status.yaml`. You'll watch RED→GREEN tests (scoped to affected files by default — `vitest --changed`, `jest --findRelatedTests`, `pytest --testmon`; CI runs the full suite as the safety net), a 3-reviewer review pass, patch commits, and a push or PR. The autopilot drives until `session_story_limit` stories are done (default 3), then halts cleanly. Re-run `/sprint-autopilot-on` to continue.
**Start at a specific story or epic:**
```
/sprint-autopilot-on epic 4
/sprint-autopilot-on stories 3.1, 3.2, 4.5
/sprint-autopilot-on 4-8-realm-wide-matcher-and-session-lock
/sprint-autopilot-on voice identity matcher
```
The skill resolves the natural-language directive against `sprint-status.yaml` and queues the matching stories. Ambiguous matches surface a candidate list — never picks arbitrarily.
**Non-interactive install:**
```bash
npx @ikunin/sprintpilot@latest install --tools claude-code --profile medium --yes
```
Runs on Windows, macOS, and Linux.
## Choose your workflow
One config decision shapes how code reaches `main`. Pick once at install (or edit `_Sprintpilot/modules/git/config.yaml` later):
| Mode | When to use | One PR per | Code reaches `main` |
|---|---|---|---|
| **Stacked PRs** *(default)* | Team workflow where every story needs review before it lands | story | After human PR approval & merge |
| **Land-as-you-go** | Solo / fast-iteration sprint, no end-of-sprint merge marathon | story | Right after each story (CI / review gated) |
| **Direct merge** | Prototype, tutorial, internal tool without CI | — *(no PR opened)* | Right after each story's push |
| **Reuse your branch** | Feature-branch workflow where you already have the branch | sprint | After human PR approval & merge |
All modes use isolated worktrees (`.worktrees//`) so `main` never has half-finished story code. ASCII diagrams of each mode are in [Git workflow](#git-workflow-detailed) below.
## Choose your profile
The right amount of process for a 2-story bugfix is different from a 30-story rebuild. One knob picks the balance:
| Profile | Per-story flow | Branching | Parallel | Use it for |
|---|---|---|---|---|
| `nano` | `bmad-quick-dev` (one-shot) | one PR per epic | n/a | Tiny patch sprints, hot-fix runs |
| `small` | Full 7-step BMad cycle | one PR per story | off | Single-developer projects, ≤ 10 stories |
| `medium` *(default)* | Full 7-step BMad cycle | one PR per story | off | Most sprints — balanced |
| `large` | Full 7-step BMad cycle | one PR per story | **on** (Claude Code) | Multi-epic sprints, 20+ stories |
| `legacy` | Pinned legacy behavior | one PR per story | off | Existing installs that want zero change |
Pick at install: `--profile `. Missing profile defaults to `medium`.
**Nano safety net:** if `bmad-quick-dev` tests fail or its review classifies a finding as `high` severity, the autopilot escalates that session to the full 7-step cycle (session-scoped, never written back to config).
## Running a session
The autopilot scans the host chat for your interjections every turn — you can steer it without learning a command vocabulary:
- *"skip this story, the spec is wrong"* → `skip_story`
- *"close out epic 4 with retro, the remaining stories are deferred"* → `trigger_retrospective`
- *"pause"* → `pause` (halts cleanly; resume with `/sprint-autopilot-on`)
- *"continue, the diff is fine"* → `force_continue` (accept a `verify_rejected` or `resume_divergence`)
The LLM maps your phrasing to the right command + arguments and emits a `user_input` signal. Full command vocabulary in [docs/USAGE.md](docs/USAGE.md#user-commands).
### When it halts
The autopilot drives until one of these conditions is true:
1. **`session_story_limit` reached** (default 3, nano 5) — checkpoints state, prints the handoff report, releases the lock. Re-run `/sprint-autopilot-on` to continue.
2. **Sprint complete** — runs end-of-sprint cleanup, prints the final report. Done.
3. **One of the 5 true blockers** — `creative_user_input_required`, `new_external_dependency`, `security_architectural_decision`, `contradictory_acceptance_criteria`, or 3 consecutive test failures with no forward progress. Halts with a `user_prompt`. Answer it and resume.
4. **Retry budget exhausted on a single phase** — halts with the underlying issue surfaced. Inspect, fix, resume.
5. **You explicitly pause** — `/pause` or any natural-language pause instruction.
Everything else — the autopilot decides, logs the decision in one sentence to `decision-log.yaml`, and moves on.
## Configuration
### By use case
Most projects only ever change a handful of settings. Pick the change you want, edit the listed key:
**I want each story to land on `main` as soon as it's reviewed**
→ `git.merge_strategy: land_as_you_go` (file: `_Sprintpilot/modules/git/config.yaml`)
→ Optional: `git.land_when: ci_pass | ci_and_review | no_wait`
**I want every story reviewed before it lands**
→ Keep the default `git.merge_strategy: stacked`
**I'm working on my own feature branch and want one PR at sprint-end**
→ `git.reuse_user_branch: true`
**I don't want PRs — merge directly to base**
→ `git.push.create_pr: false`
**I want lint failures to halt the sprint until fixed**
→ `git.lint.enabled: true` + `git.lint.blocking: true` (file: `_Sprintpilot/modules/git/config.yaml`)
→ Lint runs `scripts/post-green-gates.js` after `dev_green` verify passes.
**My sprint is a hotfix or 1-2 small changes**
→ `complexity_profile: nano` (file: `_Sprintpilot/modules/autopilot/config.yaml`)
**My sprint is 20+ stories**
→ `complexity_profile: large` — enables parallel story dispatch on Claude Code
**I want the autopilot to run more (or fewer) stories before checkpointing**
→ `autopilot.session_story_limit: ` — `0` is unlimited
**I want to inspect worktrees after epic merge instead of auto-cleaning**
→ `git.worktree.cleanup_on_merge: false`
### Reference table
| Setting | File | Default | What it controls |
|---|---|---|---|
| `complexity_profile` | `autopilot/config.yaml` | `medium` | Per-story flow + which optimization layers are enabled |
| `autopilot.session_story_limit` | `autopilot/config.yaml` | `3` (nano: `5`) | Stories per session before checkpoint. `0` = unlimited |
| `autopilot.retrospective_mode` | `autopilot/config.yaml` | `auto` | `auto` / `stop` / `skip` |
| `git.merge_strategy` | `git/config.yaml` | `stacked` | `stacked` / `land_as_you_go` |
| `git.push.create_pr` | `git/config.yaml` | `true` | `false` = direct merge to base |
| `git.reuse_user_branch` | `git/config.yaml` | `false` | Commit every story onto the current user branch |
| `git.land_when` | `git/config.yaml` | `ci_pass` | Land-as-you-go gating: `no_wait` / `ci_pass` / `ci_and_review` |
| `git.land_wait_minutes` | `git/config.yaml` | `30` | Max wait for CI / review before halting |
| `git.branch_prefix` | `git/config.yaml` | `story/` | Prefix for autopilot-created branches |
| `git.lint.enabled` | `git/config.yaml` | `false` | Run post-GREEN lint pipeline |
| `git.lint.blocking` | `git/config.yaml` | `false` | Lint failures reject verify (LLM fix-loops) |
| `git.lint.output_limit` | `git/config.yaml` | `100` | Lines of lint output injected back as context |
| `git.lint.linters.` | `git/config.yaml` | (auto-detect) | Per-language preference; `[]` disables; `javascript` + `typescript` merge into `js-ts` |
| `git.lock.stale_timeout_minutes` | `git/config.yaml` | `30` | `.autopilot.lock` older than this is auto-taken-over; `0` disables |
| `git.worktree.health_check_on_boot` | `git/config.yaml` | `true` | Halt on orphan worktrees at session start |
| `git.worktree.cleanup_on_merge` | `git/config.yaml` | `true` | Remove `.worktrees//` after epic merge |
| `ma.enabled` | `ma/config.yaml` | `true` | Enable parallel agent skills |
**Profile-level overrides** — `parallel_stories`, `state_sharding`, `phase_timings`, `cache_shared_reads`, `conditional_boot_work` live in `_Sprintpilot/modules/autopilot/profiles/.yaml`. Their effective value depends on the active `complexity_profile`.
Full reference: [docs/CONFIGURATION.md](docs/CONFIGURATION.md).
## Sessions
A long sprint doesn't fit in one LLM context. The autopilot checkpoints every N stories, prints a handoff report, and resumes exactly where it left off in a fresh session.
**Resume divergence detection.** On the next `autopilot start`, the orchestrator fingerprints `_bmad-output/`, `sprint-status.yaml`, and branch HEADs against the fingerprint stamped at the last halt. Two escape paths proceed without manual surgery:
- **External-completion auto-acknowledge** — when the persisted `current_story` is `done` in sprint-status (you merged it manually, hot-fix, UI action), the stale identity is cleared and the next pending story is picked.
- **`--accept-divergence` flag** — catch-all for divergence the auto-path doesn't cover.
**Crash recovery.** On every boot, the autopilot health-checks `.worktrees/`. Orphan worktrees from crashed sessions are detected and surfaced. Stale `.autopilot.lock` files (older than `stale_timeout_minutes`) are auto-taken-over.
**Fresh-context finalize.** When the last story hits `STORY_DONE`, the state machine transitions to `sprint_finalize_pending` instead of running cleanup in the same session. The next `/sprint-autopilot-on` reads the marker, runs deterministic cleanup with a clean context. One short extra session (~60–100 turns) for reliable end-of-sprint hygiene.
Full handoff report format + ledger semantics: [docs/USAGE.md](docs/USAGE.md#handoff-report).
## Skills
| Command | What it does |
|---|---|
| `/sprint-autopilot-on` | Engage autonomous sprint execution |
| `/sprint-autopilot-off` | Disengage and show status |
| `/sprintpilot-update` | Check for updates and install the latest version |
| `/sprintpilot-codebase-map` | 5-stream brownfield codebase analysis |
| `/sprintpilot-assess` | Tech debt, dependency audit, migration assessment |
| `/sprintpilot-reverse-architect` | Extract architecture document from existing code |
| `/sprintpilot-migrate` | 12-step legacy migration planning |
| `/sprintpilot-research` | Parallel web research fan-out |
Multi-agent skill internals: [docs/USAGE.md](docs/USAGE.md#multi-agent-skills).
## Compatibility
**Tools.** Sprintpilot uses the universal `SKILL.md` format — same skills work everywhere:
| Tool | Directory | Tool | Directory |
|---|---|---|---|
| Claude Code | `.claude/skills/` | Roo Code | `.roo/skills/` |
| Cursor | `.cursor/skills/` | Trae | `.trae/skills/` |
| Windsurf | `.windsurf/skills/` | Kiro | `.kiro/skills/` |
| Gemini CLI | `.gemini/skills/` | GitHub Copilot | `.github/copilot/skills/` |
| Cline | `.cline/skills/` | | |
Non-interactive: `--tools ,` (or `all`). Valid values: `claude-code`, `cursor`, `windsurf`, `gemini-cli`, `cline`, `roo`, `trae`, `kiro`, `github-copilot`.
**Git platforms.**
| Platform | CLI | Auto-detect | API fallback |
|---|---|---|---|
| GitHub | `gh` | `github.com` | No |
| GitLab | `glab` | `gitlab.*` | No |
| Bitbucket | `bb` | `bitbucket.org` | Yes (`BITBUCKET_TOKEN`) |
| Gitea | `tea` | Explicit config | Yes (`GITEA_TOKEN` + `base_url`) |
No CLI installed? Falls back to **git_only mode** (direct merge, no PRs).
**Linters** (auto-detected on changed files only). First found per language wins.
| Language | Linters | Language | Linters |
|---|---|---|---|
| Python | ruff, flake8, pylint | Java | checkstyle, pmd |
| JavaScript / TS | eslint, biome | C / C++ | cppcheck, clang-tidy |
| Rust | cargo clippy | C# | dotnet format |
| Go | golangci-lint | Swift | swiftlint |
| Ruby | rubocop | PL/SQL | sqlfluff |
| Kotlin | ktlint, detekt | PHP | phpstan, phpcs |
Multi-language monorepos lint all languages in one pass. Override priority via `git.lint.linters.: [list]`. See [docs/EXTENDING.md](docs/EXTENDING.md) to add more.
## Troubleshooting
**`resume_divergence` halts on every start.** Sprint-status or the working tree moved between sessions. If the persisted `current_story` is now `done`, the autopilot auto-acknowledges and proceeds — no action needed. For other divergences, pass `--accept-divergence`, or finish the externally-merged story first so sprint-status reflects reality.
**`verify_rejected` on `dev_red`: "no test_files reported".** The verifier auto-detects test files from `git diff` + untracked files by language convention — if it still can't find any, the work didn't produce a test-shaped file. Check the actual changes; re-run `bmad-dev-story` if needed.
**`verify_rejected` on `dev_red`: "test file missing: \".** The LLM reported a path that doesn't exist. Relative paths resolve against `projectRoot` — verify the file is where the LLM said.
**`verify_rejected` on `story_done`: "git_steps_completed must be true".** The flag is the canonical signal but the verifier also probes `git cat-file -e ` + `git ls-remote --heads origin `. If both pass, the signal is accepted. If the probe fails, `git push` likely didn't complete — re-run the push step manually.
**Epic won't close out with retrospective.** `remaining_stories_in_epic > 0`. Either mark the deferred stories as `skipped` / `deferred` / `cancelled` / `wont_do` in sprint-status (all are accepted as terminal), or emit `trigger_retrospective` to force-route to RETROSPECTIVE.
**`.autopilot.lock` held but no session is running.** The previous session crashed before releasing. Wait `git.lock.stale_timeout_minutes` (default 30) and the next `autopilot start` will auto-take-over. To skip the wait, `rm .autopilot.lock`.
**LLM keeps inventing pause justifications ("context budget", "natural checkpoint").** The autopilot's `workflow.orchestrator.md` contract forbids LLM-initiated pause. If you're seeing this pattern in your ledger, the LLM isn't reading the contract — `/sprintpilot-update` may help, or check `_Sprintpilot/skills/sprint-autopilot-on/SKILL.md` is current.
More scenarios: [docs/USAGE.md](docs/USAGE.md#troubleshooting).
## How it works
The orchestrator emits one typed Action at a time (`invoke_skill`, `run_script`, `git_op`, `parallel_batch`, `user_prompt`, `halt`) and consumes typed Signals from the LLM (`success`, `failure`, `blocked`, `propose_alternative`, `user_input`, `verify_override`). State writes go through a single chokepoint with critical-key carve-outs for crash recovery; non-critical writes coalesce at story boundaries.
`verify.js` enforces BMad bookkeeping after every `success` signal: acceptance-criteria bullets exist, `[ ]` task boxes are flipped to `[x]`, `commit_sha` + `branch` are reported and verified, review findings are recorded. Auto-recovery paths handle common signal-format omissions (test_files / tests_run / git_steps_completed) by probing the underlying world rather than punishing the LLM for missing echo fields.
Full architecture: [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md). State-machine diagram, action / signal vocabulary, verify contracts, and the LLM-as-peer protocol.
## Git workflow (detailed)
The 4 modes from [Choose your workflow](#choose-your-workflow) with their full branch graphs.
### Stacked PRs (default)
Each story branches from the previous story's branch and targets it. Reviewers see each story's diff in isolation while the next story is already in progress. When a PR merges on the platform, subsequent PRs auto-retarget.
```
main ─────────────────────────────────────────────────────────
│ (artifacts only)
├── story/1-1 ──→ push + PR #42 (→ main)
│ │
│ └── story/1-2 ──→ push + PR #43 (→ story/1-1)
│ │
│ └── story/1-3 ──→ push + PR #44 (→ story/1-2)
│
Epic 1 complete → retrospective
→ "Ready to merge: PR #42, #43, #44"
```
Trade-off: zero waiting for review during the sprint, but you end up with a stack to merge afterward.
### Land-as-you-go
After every `STORY_DONE`, the orchestrator runs a `STORY_LAND` state to merge that story's PR immediately. Each subsequent story branches from the already-merged base, so there's no stack to unwind.
```
main ── story/1-1 ──→ PR #42 ──→ ✓ CI / review ──→ merge ──→
│ ╲
├── story/1-2 ──→ PR #43 ──→ ✓ CI / review ──→ merge ──→ ╲
│ ╲
└── story/1-3 ──→ PR #44 ──→ ✓ CI / review ──→ merge ──→ done
```
Knobs: `git.land_when` (`no_wait` / `ci_pass` / `ci_and_review`), `git.land_wait_minutes` (default 30). Rebase recovery is automatic; conflicts halt with a `user_prompt`.
Trade-off: cleaner history, no end-of-sprint merge marathon — but each story blocks on CI before the next starts.
### Direct merge (no PR)
Stories merge straight into the base after push — no PR, no human review gate. Use only for prototypes / tutorials / dev branches.
```
main ── story/1-1 ──→ merge ── story/1-2 ──→ merge ── story/1-3 ──→ merge
```
### Reuse your branch
You create the branch; the autopilot detects it on boot and commits every story directly onto it. No `story/*` branches. One PR opens against `base_branch` at sprint-end.
```
main ─────────────────────────────────────────────────
│
└── feature/payments-rewrite (your branch, you created it)
├── feat(1): story 1-1 ─→ commit
├── feat(1): story 1-2 ─→ commit
└── … ─→ push + PR (→ main, at sprint-end)
```
### Branch naming
- Story granularity (default): `` → `story/1-3-add-auth`
- Epic granularity (nano): `epic-` → `story/epic-1`
- Reuse mode: no autopilot branches; your branch is used as-is
### Pre-commit safety
Before every commit, deterministic Node scripts run against staged files:
| Check | What it does |
|---|---|
| Explicit staging | `git add -- file1 file2` — never `-A`/`-u`/`.`. Cross-referenced against the story's `## File List`. |
| Secrets scan | Greps for `API_KEY`, `SECRET`, `TOKEN`, `PASSWORD`, `aws_access`, `private_key`. WARN severity; allowlist via `.secrets-allowlist`. |
| File size | Rejects files over `staging.max_file_size_mb` (default 1). |
| Binary detection | Warns on binary files. |
| Gitignore check | Verifies `.gitignore` covers `.autopilot.lock` and `.claude/.sprintpilot-backups/`. |
Decision matrix and additional knobs: [`modules/git/branching-and-pr-strategy.md`](_Sprintpilot/modules/git/branching-and-pr-strategy.md).
## Multi-Agent Intelligence
Beyond the autopilot, multi-agent skills launch parallel subagents for tasks that benefit from diverse perspectives.
**`/sprintpilot-codebase-map`** — 5 parallel agents scan an existing codebase: stack, architecture, quality, concerns, integrations. Output under `_bmad-output/codebase-analysis/`. Inspired by [GSD's map-codebase](https://github.com/gsd-build/get-shit-done) — see [NOTICES.md](NOTICES.md).
**`/sprintpilot-assess`** — Dependency auditor (CVEs), debt classifier (prioritized), migration analyzer. Output: prioritized findings with severity / confidence / effort.
**`/sprintpilot-reverse-architect`** — Component mapper + data flow tracer + pattern extractor. Output: BMad Method-compatible `architecture.md` that feeds `bmad-create-epics-and-stories`.
**`/sprintpilot-migrate`** — 12-step migration planner with 4 subagent fan-outs. Strategy, compatibility matrix, phased roadmap, per-component cards, data + API migration, risk matrix.
**`/sprintpilot-research`** — Fan out research across multiple topics in parallel; synthesized into a unified report.
Skill internals + output schemas: [docs/USAGE.md](docs/USAGE.md#multi-agent-skills).
## Requirements
- [BMad Method](https://github.com/bmad-code-org/BMAD-METHOD) v6.2.1+ (tested through v6.8.0)
- Node.js 20.12+
- A supported AI code agent (see [Compatibility](#compatibility))
- Git repository with at least one commit
- Platform CLI for PR creation (optional — falls back to git_only mode)
- BMad's own runtime prerequisites if you run a recent BMad: 6.3.0+ skill hooks invoke `_bmad/scripts/resolve_customization.py` (needs Python 3.10+ and [`uv`](https://github.com/astral-sh/uv)). Core skill logic still runs without them, but terminal `on_complete` hooks will fail.
## Documentation
- [Installation Guide](docs/INSTALLATION.md)
- [Usage Guide](docs/USAGE.md) — handoff report, user commands, multi-agent skill internals, troubleshooting
- [Architecture](docs/ARCHITECTURE.md) — state machine, action / signal vocabulary, verify contracts
- [Configuration Reference](docs/CONFIGURATION.md) — every setting, default, profile override
- [Extending (Platforms & Languages)](docs/EXTENDING.md)
- [Contributing](docs/CONTRIBUTING.md)
- [Changelog](CHANGELOG.md)
## License
Apache 2.0