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.

---

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
   }
   

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