bootspring build | Bootspring Docs

The build command is Bootspring's autonomous MVP build system. It manages your task queue and enables AI coding assistants (Claude Code, Cursor, Codex, etc.) to build your entire project task by task.

Launch Update: Recovery + Queue Control#

Recent updates added stronger recovery and queue synchronization paths:

bootspring build backfill (aliases: recover, hydrate, bootstrap)
bootspring build sync and bootspring build sync --replace
explicit stop/resume controls for long-running autonomous loops

`build backfill` Deep Dive#

Use this when an existing project has partial/missing build artifacts (for example missing preseed docs, SEED.md, or planning/TASK_QUEUE.md).

Loading code block...

If you run Bootspring from a source checkout, rebuild compiled runtime files first:

Loading code block...

Then verify command availability:

Loading code block...

Aliases:

Loading code block...

backfill runs this recovery sequence:

Copies canonical docs from planning/*.md into .bootspring/preseed/ when available.
If preseed docs are still incomplete, runs bootspring preseed from-codebase in local/non-LLM mode.
Ensures SEED.md exists (runs bootspring seed synthesize when needed).
If build state already exists, regenerates planning/TASK_QUEUE.md from runtime state so progress is preserved.
If no build state exists, initializes build from recovered docs.

Backfill options:

Option	Description
`--quick`	Skip deep codebase analysis during preseed-from-codebase recovery
`--interactive`	Allow follow-up prompts during recovery
`--no-onboard`	Skip onboard-assisted detection
`--force`	Overwrite/refresh existing artifacts

When to use backfill:

You have partial planning/* docs and need to reconstruct build artifacts.
SEED.md or .bootspring/preseed/* is missing.
You need to recover project continuity without losing current runtime progress.

When not to use backfill:

You only changed planning/TASK_QUEUE.md and just need runtime sync.
Your runtime queue is stale but artifacts are present. Use bootspring build sync --replace first.

After recovery:

Loading code block...

Queue Sync vs Backfill#

Use these commands for different failure modes:

Situation	Command
Edited `planning/TASK_QUEUE.md` and want runtime to match	`bootspring build sync --replace`
Need non-destructive import/merge from queue	`bootspring build sync`
Missing/corrupted preseed + seed + queue artifacts	`bootspring build backfill`
Loop crashed with task already `in_progress`	`bootspring build loop` or `bootspring build resume`

Typical queue refresh flow:

Loading code block...

The Build Loop#

The core workflow is simple:

bootspring build next

This single command:

Marks the next task as in_progress
Shows the task details
Claude/Cursor/Codex implements it
Run bootspring build done when complete
Repeat until MVP is finished

Quick Start#

Method 1: Claude Code (Recommended)#

Open your project in Claude Code and say:

bootspring build next

Claude will:

Read the planning docs
Find the current task in planning/TASK_QUEUE.md
Implement it
Run bootspring build done
Continue to the next task

This creates an autonomous loop that builds your entire MVP.

Method 2: Interactive CLI#

Loading code block...

Shows an interactive menu:

View current task
Start building (spawns AI loop)
Check progress
Skip task

Method 3: Direct Commands#

Loading code block...

Commands#

Command	Description
`bootspring build`	Interactive menu
`bootspring build next`	Mark next task as in_progress
`bootspring build done`	Mark current task complete, auto-queue next
`bootspring build complete`	Alias for `done`
`bootspring build loop`	Autonomous loop with commit/push after each task
`bootspring build all`	Alias for `loop`
`bootspring build status`	Show build progress
`bootspring build pause`	Pause build loop
`bootspring build resume`	Resume paused build
`bootspring build continue`	Alias for `resume`
`bootspring build stop`	Graceful stop after current task
`bootspring build task`	Show current task details
`bootspring build skip`	Skip current task
`bootspring build backfill`	Recover preseed + `SEED.md` + `TASK_QUEUE.md` artifacts
`bootspring build recover`	Alias for `backfill`
`bootspring build hydrate`	Alias for `backfill`
`bootspring build bootstrap`	Alias for `backfill`
`bootspring build plan`	View the full plan
`bootspring build sync`	Sync tasks from `planning/TASK_QUEUE.md` into runtime state
`bootspring build sync --replace`	Replace runtime queue from `planning/TASK_QUEUE.md`
`bootspring build reset`	Reset build state

How It Works#

Planning Folder#

All build state lives in /planning:

planning/
├── MASTER_PLAN.md      # Overall vision and phases
├── TASK_QUEUE.md       # All tasks with acceptance criteria
├── TODO.md             # Checkbox task list
├── CONTEXT.md          # Build context
└── BUILD_STATE.json    # Machine-readable state

Task States#

Tasks flow through these states:

pending → in_progress → completed
                     → skipped

Finding the Current Task#

The AI looks for the task with status: in_progress in:

BUILD_STATE.json (authoritative)
TASK_QUEUE.md (details and acceptance criteria)

Using with AI Assistants#

Claude Code#

The preferred method. Just say:

bootspring build next

Claude reads CLAUDE.md which instructs it to:

Check planning/MASTER_PLAN.md first
Find the in_progress task in planning/TASK_QUEUE.md
Implement following acceptance criteria
Run bootspring build done when complete

Cursor#

Open the project. Cursor reads AGENTS.md which contains the same instructions.

Codex / Other Tools#

All tools that support AGENTS.md will follow the same workflow.

Looping Through Tasks#

The magic happens when the AI naturally continues after each task:

You: "bootspring build next"
Claude: [implements task-001]
Claude: [runs "bootspring build done"]
Bootspring: "✓ Completed task-001. Next: task-002"
Claude: [sees next task, continues implementing]
... (loops until MVP complete)

Loop Mode#

For autonomous building with automatic git commits:

Loading code block...

Features:

Auto-commits after each completed task
Auto-pushes to origin (unless --no-push)
Crash recovery - resumes from in_progress task
Creates descriptive commit messages: feat(task-001): Implement feature...

Flag Reference#

Loop flags:

Flag	Scope	Description
`--no-push`	`build loop`	Commit locally, skip push
`--no-commit`	`build loop`	Disable git commit/push automation

Backfill flags:

Flag	Scope	Description
`--quick`	`build backfill`	Skip deep analysis during preseed recovery
`--interactive`	`build backfill`	Allow follow-up prompts
`--no-onboard`	`build backfill`	Skip onboard-assisted detection
`--force`	`build backfill`	Refresh/overwrite existing artifacts

General flags:

Flag	Scope	Description
`--prompt`	`build task`	Show AI-ready task prompt output

Example Session#

Loading code block...

Then in Claude Code:

> bootspring build next
[Claude reads planning docs, implements the task]
[Claude runs bootspring build done]
[Next task auto-queued]
[Claude continues...]

Progress Tracking#

Check your build progress:

Loading code block...

Best Practices#

Let the AI loop - Don't interrupt. Let it complete multiple tasks.
Check progress periodically - Use bootspring build status
Review completed work - Check git commits between tasks
Skip blockers - Use bootspring build skip if stuck

Git Commits#

When committing during the build loop:

Use conventional commits: feat:, fix:, docs:, refactor:
Keep commits atomic (one task = one commit)
Never add Co-Authored-By or AI attribution to commits
Never commit secrets, API keys, or credentials
Run quality checks before committing

Comparison with Other Tools#

Feature	Bootspring Build	Ralph	Manual
Task extraction from docs	✅	❌	❌
Multi-tool support	✅	Claude only	❌
Planning folder	✅	❌	❌
Natural language	✅	✅	❌
Progress tracking	✅	❌	❌

bootspring seed synthesize - Generate planning folder from preseed docs
bootspring preseed - Create initial project vision
bootspring preseed from-codebase - Recover preseed docs from an existing codebase
bootspring loop - Lower-level loop control