quantum-loop

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.

---

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
   }
   

2. 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"
   }]
   

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

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