solo-spec-loop

Solo Spec Loop

One file, one loop, one gate. Stops AI agents from sprinting ahead of you.

What it is

A workflow for solo founders using AI to build:

explore → slice → approve → build → learn

Lives in one file per project: .specs/next.md.

The problem

You ask an AI for a small feature. You get a folder tree, an ADR forest, and 800 lines of code for something nobody designed. Reviewing it is slower than writing it yourself.

Solo Spec Loop forces a checkpoint: the agent can't touch source until you've explicitly approved a small, vertical slice with a runnable acceptance check.

Claude Code

/plugin marketplace add agjs/solo-spec-loop
/plugin install solo-spec-loop
/reload-plugins

/solo-spec-loop:spec init
/solo-spec-loop:spec explore <idea>
/solo-spec-loop:spec slice
/solo-spec-loop:spec approve
/solo-spec-loop:spec build

Clash with another marketplace? /plugin install solo-spec-loop@agjs-solo-spec-loop

Want /spec instead? Copy commands/spec.md into this project’s .claude/commands/spec.md.

Other tools

Cursor: install from this repo (.cursor-plugin/).

Anything else (Codex, Gemini, Aider, Copilot, plain ChatGPT): copy templates/next.md to .specs/next.md, paste rules/spec-loop.mdc into your AGENTS.md. Optionally wire hooks/solo_spec_gate.py into a pre-write hook if your tool has one.

Vendoring into a starter template

This repo is project-agnostic by design. Starter templates that want the loop on a git clone (no marketplace fetch, no pip install) can vendor the artifacts directly. BoringStack does this — tools/spec-loop/ is a verbatim copy plus a bun run spec:init script that wires .specs/next.md, the slash command, and PreToolUse hooks for both Claude Code and Cursor in one shot. A BoringStack-flavored variant of templates/next.md (with monorepo-aware acceptance examples) ships as templates/next.boringstack.md.

If you're vendoring into a TypeScript / bun project, the solo_spec_gate.py script can also be ported to TypeScript without changing the loop's semantics — see BoringStack's tools/spec-loop/hooks/gate.ts for a parity-tested reference implementation.

What's in the repo

hooks/solo_spec_gate.py    the portable gate (~160 lines stdlib Python)
templates/next.md          the spec template
commands/spec.md           slash command (Claude Code: `/solo-spec-loop:spec …`)
rules/spec-loop.mdc        Cursor always-apply rule
skills/solo-spec/          Claude Code skill
tests/                     stdlib-only tests for the gate

Tests

python3 tests/test_solo_spec_gate.py

What this is not

Not Spec Kit. Not GSD. Not OpenSpec. No constitution, no per-feature folders, no multi-agent orchestration. If you want any of that, pick one of those.

License

MIT.