Your AI agent writes code. Quantum-Loop makes sure it writes the right code.

A Claude Code plugin that turns a one-line feature description into verified, reviewed, autonomously-implemented code -- through structured specs, dependency-aware execution, parallel worktree agents, and mandatory verification gates that prevent AI agents from cutting corners.

Named after Loop Quantum Gravity: spacetime is built from discrete, verified loops. So is your codebase.

AI coding agents are fast. They're also confidently wrong. They skip tests, ignore specs, claim "it should work" without checking, and produce code that drifts from requirements with each iteration.

Quantum-Loop solves this with three principles:

1. Structured specs before code -- No implementation until requirements are formal, granular, and machine-verifiable
2. Dependency-aware execution -- Stories execute from a DAG, not a flat list. Failures don't cascade into unrelated work
3. No claims without evidence -- The Iron Law: every "it works" requires fresh command output proving it

/quantum-loop:ql-brainstorm → /quantum-loop:ql-spec → /quantum-loop:ql-plan → /quantum-loop:ql-execute
         │                        │                     │                      │
      Socratic               9-section            quantum.json          Autonomous loop
      dialogue                 PRD                with DAG               with gates
         │                        │                     │                      │
         ▼                        ▼                     ▼                      ▼
      design.md              prd-*.md            Stories with          Verified, reviewed,
      (approved)            (verifiable           2-5 min tasks         committed code
                             criteria)

Each phase produces an artifact consumed by the next. Skip a phase and the next one catches it. The execution loop runs until every story passes both review gates -- or tells you exactly why it can't.

Option 1: Plugin marketplace (requires Claude Code >= 1.0.33)

# In Claude Code:
/plugin marketplace add andyzengmath/quantum-loop
/plugin install quantum-loop@quantum-loop

Option 2: Local plugin flag (any version)

git clone https://github.com/andyzengmath/quantum-loop.git
claude --plugin-dir ./quantum-loop

Option 3: Manual config (if the above don't work)

Clone the repo, then edit three files in ~/.claude/:

1. Add quantum-loop to an existing marketplace's .claude-plugin/marketplace.json:

   {
     "name": "quantum-loop",
     "source": { "source": "url", "url": "https://github.com/andyzengmath/quantum-loop.git" },
     "description": "Spec-driven autonomous development loop",
     "version": "0.2.2",
     "strict": true
   }

2. Add to plugins/installed_plugins.json:

   "quantum-loop@<marketplace-name>": [{
     "scope": "user",
     "installPath": "/path/to/quantum-loop",
     "version": "0.2.2",
     "installedAt": "2026-02-18T00:00:00.000Z",
     "lastUpdated": "2026-02-18T00:00:00.000Z"
   }]

3. Add to settings.json under enabledPlugins:

   "quantum-loop@<marketplace-name>": true

After any install method, restart Claude Code. Commands use the quantum-loop: prefix (e.g., /quantum-loop:ql-brainstorm) or the short form (/ql-brainstorm).

# Step 1: Explore the idea (Socratic Q&A, 2-3 approaches, section-by-section approval)
/quantum-loop:ql-brainstorm Add a task priority system with filtering

# Step 2: Generate formal spec (5-8 lettered questions, respond "1A, 2C, 3B")
/quantum-loop:ql-spec

# Step 3: Create execution plan (dependency DAG, granular tasks, verification commands)
/quantum-loop:ql-plan

# Step 4a: Execute interactively (auto-detects parallelism)
/quantum-loop:ql-execute

# Step 4b: Or run autonomously -- sequential (one story at a time)
./quantum-loop.sh --max-iterations 20

# Step 4c: Or run autonomously -- parallel (independent stories run concurrently)
./quantum-loop.sh --parallel --max-parallel 4 --max-iterations 20

# Step 4d: Windows autonomous (native PowerShell, no bash required)
.\quantum-loop.ps1 -MaxIterations 20 -SkipPermissions

Quantum-Loop builds on Ralph's autonomous loop architecture and adds: DAG-based dependencies, parallel worktree execution, 5-state story tracking, two-stage review gates, structured retry/failure logs, and an in-process orchestrator agent.

Quantum-Loop takes Superpowers' verification discipline (Iron Law, anti-rationalization guards, two-stage review) and adds: machine-readable state (quantum.json), DAG-driven execution, cross-session persistence, parallel execution, and autonomous overnight runs.

Stories execute based on a dependency graph. A database schema story runs before the API story that reads from it, which runs before the UI story that displays it. Independent stories don't block each other.

US-001 (schema) ──→ US-002 (UI) ──→ US-004 (integration)
                ──→ US-003 (API) ──↗

If US-002 fails, US-003 still executes (it only depends on US-001).

When multiple stories have all dependencies satisfied, Quantum-Loop runs them concurrently in isolated git worktrees:

Wave 1:  US-001 (schema)   ─── worktree ─── [PASSED] ── merge
         US-005 (config)   ─── worktree ─── [PASSED] ── merge

Wave 2:  US-002 (UI)       ─── worktree ─── [PASSED] ── merge    (unblocked by US-001)
         US-003 (API)      ─── worktree ─── [FAILED] ── retry    (unblocked by US-001)

Wave 3:  US-003 (API)      ─── worktree ─── [PASSED] ── merge    (retry succeeded)
         US-004 (tests)    ─── worktree ─── [PASSED] ── merge    (unblocked by US-002 + US-003)

How it works:

1. The orchestrator queries the DAG for all stories with satisfied dependencies
2. Each story gets an isolated git worktree (.ql-wt/<story-id>/)
3. A fresh Claude Code agent is spawned per worktree with the story ID in its prompt
4. Agents implement the story, commit their changes (git add -A && git commit), then signal completion
5. The orchestrator verifies changes are committed (safety commit if agent forgot), then merges the worktree branch into the feature branch
6. The DAG is re-queried after every completion to spawn newly unblocked stories
7. On merge conflict or failure, the story is retried in the next wave

Agents are fully isolated: each works in its own worktree directory. Only the orchestrator reads/writes quantum.json. Agents must commit before signaling — the orchestrator includes a safety commit as a fallback, but uncommitted work in a removed worktree is lost. Agents that timeout (default 15 min) or crash are killed, their stories marked failed, and worktrees cleaned up.

Two execution modes:

Without --parallel or with only one executable story, execution remains sequential -- full backward compatibility.

pending ──→ in_progress ──→ passed
                │
                ▼
             failed ──→ (retry) ──→ in_progress
                │
                ▼ (retries exhausted)
             blocked

Implementation complete
        │
        ▼
  Stage 1: Spec Compliance ──── FAIL → fix → re-review
        │
      PASS
        │
        ▼
  Stage 2: Code Quality ─────── FAIL → fix → re-review
        │
      PASS
        │
        ▼
     Commit
        │
        ▼
  Stage 3: Cross-Story Integration ── (after dependency chain completes)
        │                               Traces call chains, type consistency,
      PASS                              dead code, import resolution (LSP preferred)
        │
        ▼
     COMPLETE

Stage 2 never runs if Stage 1 fails. Code that doesn't match the spec is waste -- no matter how well-written.

NO COMPLETION CLAIMS WITHOUT FRESH VERIFICATION EVIDENCE.

The verification skill catches hedging language ("should work", "probably passes"), stale evidence ("passed earlier"), and partial checks ("linter passed so it's fine"). Every claim needs a fresh command run with full output.

Every skill includes a table of excuses AI agents use to skip steps, paired with rebuttals:

The machine-readable state file that survives across sessions:

{
  "project": "MyApp",
  "branchName": "ql/task-priority",
  "stories": [
    {
      "id": "US-001",
      "title": "Add priority field to database",
      "status": "passed",
      "dependsOn": [],
      "tasks": [
        { "id": "T-001", "title": "Write migration test", "testFirst": true, "status": "passed" },
        { "id": "T-002", "title": "Create migration", "testFirst": false, "status": "passed" }
      ],
      "review": {
        "specCompliance": { "status": "passed" },
        "codeQuality": { "status": "passed" }
      },
      "retries": { "attempts": 0, "maxAttempts": 3 }
    }
  ],
  "progress": [...],
  "codebasePatterns": ["Use IF NOT EXISTS for migrations"]
}

See quantum.json.example for the full schema with 3 stories and 10 tasks.

quantum-loop/
├── skills/
│   ├── ql-brainstorm/    # Socratic design exploration
│   ├── ql-spec/          # PRD generation
│   ├── ql-plan/          # quantum.json creation
│   ├── ql-execute/       # Thin dispatcher -> orchestrator agent
│   ├── ql-verify/        # Iron Law verification
│   └── ql-review/        # Two-stage code review
├── agents/
│   ├── orchestrator      # Execution lifecycle manager (DAG, dispatch, review, commit)
│   ├── implementer       # TDD implementation per story
│   ├── spec-reviewer     # Acceptance criteria check
│   └── quality-reviewer  # Code quality check
├── lib/                  # Shell libraries for parallel orchestration
│   ├── common.sh         # Shared validation utilities
│   ├── dag-query.sh      # DAG query + cycle detection
│   ├── worktree.sh       # Git worktree lifecycle (create/remove/list)
│   ├── spawn.sh          # Agent spawning (autonomous mode)
│   ├── monitor.sh        # Agent polling, signal detection, merge-on-pass
│   ├── json-atomic.sh    # Atomic quantum.json writes (tmp + mv)
│   └── crash-recovery.sh # Orphaned worktree cleanup on startup
├── tests/                # Shell test suites (110 tests)
│   ├── test_dag_query.sh
│   ├── test_worktree.sh
│   ├── test_spawn.sh
│   ├── test_monitor_merge.sh
│   ├── test_timeout.sh
│   ├── test_json_atomic.sh
│   └── test_crash_recovery.sh
├── quantum-loop.sh       # Autonomous bash loop (sequential + parallel)
└── CLAUDE.md             # Agent template (parallel-aware)

Two runner scripts (different purposes):

The root script is used internally by the plugin. For your projects, download the templates version:

curl -sO https://raw.githubusercontent.com/andyzengmath/quantum-loop/main/templates/quantum-loop.sh && chmod +x quantum-loop.sh

Sequential mode (default):

1. Reads quantum.json state
2. Selects next story from dependency DAG (jq query)
3. Spawns fresh Claude Code instance with CLAUDE.md
4. Processes completion signals (<quantum>STORY_PASSED</quantum>, etc.)
5. Handles retries and cascade blocking
6. Exits: 0 (all passed), 1 (blocked), 2 (max iterations)

Parallel mode (--parallel):

1. Recovers orphaned worktrees from any interrupted previous run
2. Queries DAG for all independently executable stories
3. Creates isolated git worktree per story (.ql-wt/<story-id>/)
4. Spawns background claude --print process per worktree (up to --max-parallel)
5. Monitors agents: polls for signals, enforces 15-min timeout, detects crashes
6. On pass: safety-commits any uncommitted changes, merges worktree branch into feature branch, re-queries DAG, spawns newly unblocked stories
7. On failure/timeout/crash: marks story failed, cleans up worktree, retries next wave
8. Exits: 0 (all passed), 1 (blocked), 2 (max iterations)

./quantum-loop.sh [OPTIONS]

Options:
  --max-iterations N   Maximum iterations before stopping (default: 20)
  --max-retries N      Max retry attempts per story (default: 3)
  --tool TOOL          AI tool: "claude" (default) or "amp"
  --parallel           Enable parallel execution of independent stories
  --max-parallel N     Max concurrent agents in parallel mode (default: 4)
  --help               Show help message

If a parallel run is interrupted (Ctrl+C, power loss, etc.), the next run automatically:

• Detects orphaned worktrees listed in execution.activeWorktrees
• Removes them with git worktree remove --force
• Resets affected story statuses from in_progress back to pending
• Logs: "Recovered N orphaned worktrees from interrupted parallel execution"

Three options for Windows, in order of recommendation:

Option 1: /ql-execute (interactive, recommended)

# In Claude Code:
/quantum-loop:ql-execute

Invokes the orchestrator agent inside Claude Code with full tool access and native worktree isolation for parallel execution. Most reliable option.

Option 2: quantum-loop.ps1 (autonomous overnight, native PowerShell)

.\quantum-loop.ps1 -MaxIterations 20 -SkipPermissions
.\quantum-loop.ps1 -MaxIterations 50 -SkipPermissions -Model "claude-sonnet-4-5-20250514"

Native PowerShell sequential loop -- no bash, no WSL, no Git Bash. Spawns fresh claude --print per story. Requires jq installed. Sequential only (no parallel).

Option 3: WSL2 + quantum-loop.sh (autonomous overnight, full feature set)

# In WSL2 Ubuntu:
wsl
cd /mnt/c/Users/you/project
./quantum-loop.sh --parallel --max-parallel 4 --max-iterations 20

Full feature set including parallel mode. WSL2 setup guide. Requires jq and claude CLI installed inside WSL2.

The bash script's parallel mode (--parallel) is not recommended with Git Bash on Windows due to OneDrive file locking and background process management issues. Use WSL2 or the PowerShell script instead.

Quantum-Loop stands on the shoulders of two pioneering Claude Code plugins:

• Ralph by snarktank -- The autonomous agent loop architecture, PRD-to-JSON pipeline, fresh-context-per-iteration design, and story-sizing discipline that makes autonomous execution possible.
• Superpowers by Jesse Vincent -- The Iron Law of verification, anti-rationalization engineering, two-stage review, Socratic brainstorming, and the radical idea that AI agents need guardrails against their own tendencies.

Issues and PRs welcome. If you find a new way AI agents rationalize skipping steps, add it to the anti-rationalization tables.

MIT