Spur is an opinionated, "Go Horse" approach to AI agent orchestration.

Most agents fail because they are over-engineered: bloated prompts, useless interactive sessions, and terrible task decomposition. Spur strips all that away. It forces a rigid, sequential execution loop that treats your project as a series of atomic "beats".

The problem it solves: AI coding agents drift. They forget the plan, get lost in recursive "thinking" loops, and fail to break down complex projects into executable steps.

Spur fixes this by:

1. Aggressive Context Rooting: Injecting a high-fidelity PLAN.MD into every task instance.
2. Atomic Decomposition: Converting your problem into small, manageable chunks—not 50-step epics.
3. Hard-Stop Orchestration: No hanging, no "question locks," no infinite retries. Just execution.

The Spur Loop

Problem → Identify → Lean PLAN.MD → Slice into Tasks
                                          │
                      ┌───────────────────┘
                      ▼
              ┌──────────────┐
              │   TASK N     │
              │      ↓       │
              │  VALIDATE    │
              │      ↓       │
              │  PASS?       │
              │  ↙    ↘      │
              │ YES    NO    │
              │  ↓      ↓   │
              │ SPUR   RETRY │
              │  ↓   (max 3) │
              │ CONFIRM  ↓   │
              │  ↓    HALT   │
              │ NEXT TASK    │
              └──────────────┘

One agent, one task, immediate validation. Hard limits.

Quick Start

git clone https://github.com/yourname/spur.git
cd spur
bun install

# Set your agent (claude/opencode)
export SPUR_AGENT=claude

# Just go.
spur go "Build a REST API for a todo app with SQLite and JWT auth"

Spur will:

1. Identify the core requirements.
2. Forge the PLAN.MD (The Context Root).
3. Slice the project into logical, atomic tasks.
4. Hammer through them one by one.

Commands

| Command | Action | |---------|--------| | spur go "<problem>" | Run the full pipeline. | | spur plan | Create PLAN.MD + slice tasks. | | spur run | Execute next atomic task. | | spur status | Current project health. | | spur retry <id> | Reset and force retry. | | spur skip <id> | Skip and move on. |

Why Spur? (The Go Horse Philosophy)

1. No "Question Locks"

AI agents love to pause and ask "Is this okay?". We don't have time for that.

• We close stdin.
• We use strict environment flags (CI=1, TERM=dumb).
• We timeout the process. If it hangs, it dies. We don't wait.

2. The Context Root (PLAN.MD)

Most tools feed the agent the entire history of the chat, creating "context pollution." Spur feeds the agent the minimum viable context (The Context Root) + the specific task. No history, no drift.

3. Atomic Tasks

If a tool takes 10 minutes to generate a file, it's not a task; it's a failure. Spur forces the agent to break work down into chunks that can be finished in minutes.

Architecture

Spur is built to be a simple, filesystem-backed state machine.

your-project/
├── .spur/
│   ├── state.json     # Project state & current task
│   └── plan.md        # The Truth (Context Root)
└── src/               # The code

| Component | Responsibility | |-----------|----------------| | engine | The Spur Loop. Identify → Slice → Execute. | | context | Strips bloated prompts to keep agent focused. | | agent | Manages process lifecycle (spawn/kill/timeout). | | state | Filesystem persistence. Syncs state after every success. |

License

MIT