spec-loop

The Spec-Loop Method: Spec-driven planning + autonomous iteration loops for AI-assisted development

A lightweight protocol that combines spec-driven planning with autonomous iteration loops for reliable AI-assisted development with Claude Code.

Quick Start

# Initialize in your project
npx spec-loop init

This creates:

• CLAUDE.md - Agent instructions with the full methodology
• .claude/commands/spec.md - Spec workflow slash commands
• .claude/commands/loop.md - Iteration loop commands
• .claude/settings.json - Hook configuration
• .claude/hooks/check-spec.js - Enforces spec-before-code rule

What You Get

Spec Phase

A context engineering system that forces planning before coding:

• Spec-driven: Can't write code until PROJECT.md is finalized
• Fresh context: Each task runs with full attention, no context rot
• Atomic tasks: Max 2-3 tasks per phase, each completable in one session

Loop Phase

An autonomous iteration loop that keeps trying until success:

• Iteration over perfection: Let the loop refine the work
• Automated verification: Tests, builds, lints after every change
• Self-correction: Analyze failures and adjust approach

Usage

Spec Workflow

# In Claude Code:
/spec init          # Start project definition
/spec plan          # Break current phase into atomic tasks
/spec execute       # Run the plan
/spec status        # Check progress

Loop Execution

# In Claude Code:
/loop "Fix all TypeScript errors until npm run build passes"
/loop "Implement login form, verify with npm test"

Methodology Overview

┌─────────────────────────────────────────────────────────┐
│                    Spec-Loop Flow                        │
├─────────────────────────────────────────────────────────┤
│                                                          │
│  1. DEFINE (Spec)                                       │
│     └── Create PROJECT.md with vision & requirements    │
│                                                          │
│  2. PLAN (Spec)                                         │
│     └── Create ROADMAP.md with phases                   │
│     └── Create PLAN.md with atomic tasks (max 3)        │
│                                                          │
│  3. EXECUTE (Loop)                                      │
│     └── Loop: attempt → verify → fix → repeat           │
│     └── Until: success criteria met                     │
│                                                          │
│  4. ITERATE                                             │
│     └── Update STATE.md                                 │
│     └── Plan next phase                                 │
│     └── Repeat                                          │
│                                                          │
└─────────────────────────────────────────────────────────┘

Document Structure

| Document | Purpose | |----------|---------| | PROJECT.md | Vision, goals, requirements, constraints | | ROADMAP.md | Phases and milestones | | STATE.md | Current progress tracking | | PLAN.md | Active atomic tasks (max 3) | | ISSUES.md | Discovered problems and blockers |

Task Format

Tasks use a structured XML format for clarity:

<task>
  <name>Implement user authentication</name>
  <files>src/auth.ts, src/middleware/auth.ts</files>
  <actions>
    1. Create User interface with email, passwordHash
    2. Add hashPassword and verifyPassword functions
    3. Create authMiddleware for JWT validation
  </actions>
  <verification>npm test -- --grep "auth"</verification>
  <success>All auth tests pass</success>
</task>

Why This Works

Context Engineering (Spec)

Claude's quality degrades as context fills up. The Spec phase prevents this by:

• Breaking work into atomic tasks
• Each task gets fresh, focused context
• No accumulated garbage from previous work

Deterministic Iteration (Loop)

The Loop phase embraces failures as data:

• Predictable failures inform prompt optimization
• Automated verification catches issues immediately
• Loop handles retry logic automatically

Enforced Discipline (Hook)

A pre-tool hook blocks code changes until PROJECT.md exists and is finalized.

Configure enforcement by editing the spec-loop-enforcement line in CLAUDE.md:

| Mode | Behavior | |------|----------| | ask (default) | Block, but allow bypass via .spec-loop-skip file | | block | Hard block, no bypass allowed | | warn | Show warning but proceed | | off | Disable enforcement |

Example in CLAUDE.md:

spec-loop-enforcement: warn

Or create .spec-loop-config:

{ "enforcement": "warn" }

Installation Options

npx (recommended)

npx spec-loop init

Global install

npm install -g spec-loop
spec-loop init

Manual

Copy the templates from this repo directly into your project.

CLI Reference

spec-loop <command> [options]

Commands:
  init          Initialize protocol in current directory
  help          Show help message

Options:
  --force, -f   Overwrite existing files

Influences

This methodology synthesizes ideas from the AI development community, including spec-driven development and autonomous iteration techniques.

Contributing

Contributions welcome! Please read the contributing guidelines first.

License

MIT © Scott