Quantum-Loop

*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.

The Problem

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

How It Works

/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.

Self-modifying execution

Quantum-loop is self-modifying: each release ships a bundle that often modifies the very orchestrator, agent, and skill prompts the orchestrator itself uses to run. Because every dogfood run executes against the previous release's prompt semantics (the code already on the branch when the orchestrator was invoked), this release's wires only apply to runs starting after the bundle merges to master.

A concrete example. v0.6.4 added the pre-impl-review CSV-persistence wires (metrics/pre-impl-review-findings.csv). The v0.6.4 dogfood ran on the v0.6.3 master HEAD that did not yet have those wires, so its CSV was empty by design — not a regression. v0.6.5's first run is the first to populate the CSV. If you arrive at this codebase fresh, see an empty metrics/ directory after install, and run --audit, the WARN row for pre-impl-review-coverage is the expected first-run state, not a bug.

This generalizes. When a v0.X.Y release adds a new wire (a new gate, a new step, a new audit), the release's own dogfood cannot exercise that wire — only subsequent releases can. Plan accordingly when reading a release's PIPELINE_REPORT: the metrics it captures are the metrics the previous release wired. See idea-stage/PIPELINE_REPORT_v5.md for the v0.6.4 retrospective that first surfaced this caveat.

Quick Start

Install

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.3.3",
     "strict": true
   }

1. Add to plugins/installed_plugins.json:

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

1. 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).

Run

# 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 4b (alt): Run with a different coding agent
./quantum-loop.sh --tool codex --max-iterations 20
./quantum-loop.sh --tool gemini --max-iterations 10

# 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.ps1 -Tool codex -MaxIterations 20

Supported Runners

Quantum-loop can orchestrate any terminal-based coding agent CLI via JSON manifest files. Switch runners with --tool <name>.

Tiers: Guaranteed = zero-regression CI gate. Tested = CI-verified. Experimental = community-contributed.

Adding a Custom Runner

Drop a JSON file in runners/ following the schema in schemas/runner.schema.json:

# Validate your manifest
bash schemas/validate.sh runners/my-runner.json

The manifest defines how the CLI is invoked (flag, positional, or stdin delivery), which instruction file it reads, and whether it needs preamble injection or heuristic signal fallback.

What Makes It Different

vs. Plain AI Coding

vs. Ralph

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.

vs. Superpowers

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.

The Six Skills

Key Concepts

Dependency DAG

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).

Parallel Execution

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. File-conflict filtering removes stories that share file paths with higher-priority stories in the same wave — preventing merge conflicts from parallel edits to the same file
3. Each story gets an isolated git worktree (.ql-wt/<story-id>/)
4. A fresh Claude Code agent is spawned per worktree with the story ID in its prompt
5. Agents implement the story, commit their changes (git add -A && git commit), then signal completion
6. The orchestrator runs an inline review gate (spec compliance + code quality) after each merge
7. The DAG is re-queried after every completion to spawn newly unblocked stories
8. On merge conflict or failure, the story is retried in the next wave
9. After all stories pass, a full-feature code review examines the entire branch diff for cross-story consistency

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.

Worktree nesting prevention: If an agent is spawned inside a worktree (e.g., during mid-wave dispatch), _resolve_repo_root() resolves the path to the top-level repository root, preventing .ql-wt/ directories from nesting inside each other. On Windows with long OneDrive paths, worktrees automatically fall back to a shorter temp-directory location.

Python project isolation: Parallel worktrees share a single Python interpreter. Agents use PYTHONPATH injection instead of pip install -e . to avoid editable-install race conditions where one agent's install overwrites another's.

Two execution modes:

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

5-State Story Tracking

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

Two-Stage Review Gate

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.

The Iron Law

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.

Cross-Story Contracts

When parallel agents share values (secret key names, env vars, API routes, type definitions), a contracts section in quantum.json ensures consistency:

"contracts": {
  "secret_keys": { "openai": { "value": "openai-api-key", "pattern": "^[a-z][a-z0-9-]*$" } }
}

Implementers must use exact contract values. If they disagree, they halt and propose changes (propose-and-wait) rather than silently deviating.

Stale Story Detection

Stories stuck in_progress are automatically detected and retried. The caller writes a startedAt timestamp before dispatching each agent. If now - startedAt > staleThresholdMinutes (default 20, CLI-overridable), the story is reset to failed and retried. Implemented in all execution paths: orchestrator agent, quantum-loop.sh, quantum-loop.ps1, and templates/quantum-loop.sh.

Execution Observations

After every run, an observations document is auto-generated to docs/post-mortems/ with failure summaries, recurring patterns, and raw data. Optionally filed as a GitHub issue (with user confirmation) to feed improvements back into the pipeline.

Anti-Rationalization Engineering

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

quantum.json

The machine-readable state file that survives across sessions:

{
  "project": "MyApp",
  "branchName": "ql/task-priority",
  "coverageThreshold": 80,
  "staleThresholdMinutes": 20,
  "contracts": {
    "secret_keys": { "openai": { "value": "openai-api-key" } },
    "shared_types": { "priority": { "value": "Priority" } }
  },
  "stories": [
    {
      "id": "US-001",
      "title": "Add priority field to database",
      "status": "passed",
      "startedAt": null,
      "dependsOn": [],
      "tasks": [
        { "id": "T-001", "title": "Write migration test", "testFirst": true, "status": "passed" },
        { "id": "T-002", "title": "Create migration", "testFirst": false, "status": "passed",
          "wiring_verification": { "file": "models/task.py", "must_contain": ["priority"] } },
        { "id": "T-003", "title": "Create PriorityBadge", "testFirst": true, "status": "passed",
          "consumedBy": ["US-003"] }
      ],
      "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.

Architecture

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 + file-conflict filtering
│   ├── 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)
│   ├── init-guard.sh     # Environment detection and preflight checks
│   ├── resilience.sh     # WIP commits, squash-on-merge, crash recovery
│   ├── merge-semantic.sh # AST-aware 3-way merge (ts-morph, libcst, diff3)
│   ├── merge-strategy.sh # Category-based merge conflict resolution
│   ├── materialize.sh    # Contract type materialization
│   ├── barrel-regen.sh   # Barrel/index file regeneration
│   ├── known-failures.sh # Test failure tracking across waves
│   └── dep-manifest.sh   # Dependency manifest protection
├── tests/                # Shell test suites (800+ 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
│   ├── test_init_guard.sh
│   ├── test_resilience.sh
│   ├── test_merge_semantic.sh
│   ├── test_merge_strategy.sh
│   ├── test_materialize.sh
│   ├── test_stale_detection.sh
│   ├── test_started_at.sh
│   ├── test_final_sweep.sh
│   └── test_observations.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, filters out file conflicts
3. Creates isolated git worktree per story (.ql-wt/<story-id>/, or /tmp fallback on long paths)
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)

CLI Reference

./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

Crash Recovery

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"

Windows Users

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.

Acknowledgments

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

• [Ralph](https://github.com/snarktank/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](https://github.com/obra/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.

Contributing

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

License

MIT