/loop-factory

name: loop-factory
description: Run a spec-driven agent loop where coding tasks live as markdown specs that move through inbox → active → archive, get implemented by Claude Code or Codex, and pass a review gate before they count as done. Use when the user mentions "loop factory", a "spec-driven loop", an "agent factory", wants repeatable/reviewable agent work, or when a repo has a factory/specs/inbox or factory/specs/active directory. Also covers installing and scaffolding the loop-factory CLI into a project.

Loop Factory

Loop Factory turns "ask an agent to build something" into a visible assembly line. Each task is a markdown **spec**. The folder the spec lives in *is* its state. Agents implement and verify; they never decide what to build.

   📥 inbox/          🔧 active/           📦 archive/
   tasks not      ──► task an agent    ──► finished work,
   started yet        is building now      reviewed + accepted

The one rule that governs everything: **automate implementation and verification, not product decisions.** If a spec is missing a decision, record the open question — do not invent product direction.

Invoke this skill on demand by typing `/loop-factory` (one manual pass), or let a cron fire it unattended — see [Autonomous mode](#autonomous-mode-cron).

When to use this skill

• Setting up Loop Factory in a repo (installing the CLI, running `init`).
• Picking a spec out of the inbox and dispatching it to Claude Code or Codex.
• Implementing a spec against its acceptance criteria.
• Reviewing finished work and archiving accepted specs.
• Backpropagating implementation learnings into the living specs/docs.

Setup (first time in a repo)

The `loop-factory` CLI is the state engine. Install it once, then scaffold any git repo:

# get the CLI (clone the source repo, install editable)
git clone https://github.com/JuliusBrussee/Loop-Factory.git
python3 -m pip install -e ./Loop-Factory

# scaffold the factory/ folders in your target project
cd your-project
loop-factory init
loop-factory doctor      # confirm git + agent CLIs are wired up

No runtime dependencies beyond Python 3.10+. If you are already inside the Loop-Factory repo, you can skip the install and run `python3 bin/loop-factory <command>` directly. Full install notes, agent-CLI setup, and how to copy the native agent adapters: **[references/install.md](references/install.md)**.

The loop

1. **Inspect the queue.** Run `loop-factory scan` to see inbox and active specs. 2. **Grill new specs first.** Before dispatching a fresh spec, interrogate it one question at a time (who owns this decision, what's out of scope, riskiest assumption, smallest acceptable version). Record answers under a `# Grill Gate` section. A vague spec produces vague code. 3. **Dispatch.** Generate the implementation prompt and move the spec to `active/`:

   loop-factory dispatch --agent claude --limit 1 --stage

This writes a prompt to `factory/prompts/` and a run record to `factory/runs/`. It does **not** run the AI unless you add `--execute`. 4. **Implement.** Build *only* the acceptance criteria. Match existing code style. Stay scoped. 5. **Verify.** Run every command listed in the spec's `verification:` frontmatter. Capture the output as evidence. 6. **Review.** Generate a review prompt and check the diff against the criteria:

   loop-factory review <spec-id> --agent claude

Pass → archive. Fail → leave the spec in `active/` for another pass. 7. **Archive accepted work.**

   loop-factory archive <spec-id> --accepted

`--accepted` is required on purpose — nothing leaves `active/` without a confirmed pass. 8. **Backpropagate.** If building the feature changed how the system actually works, sync that back into specs/docs without changing product intent:

   loop-factory backprop --agent claude

Autonomous mode

Run a single self-contained pass that drains the inbox with no human present. Trigger it when invoked with "autonomous" / "drain the inbox", by a scheduled cron, or repeatedly by `/loop` (e.g. `/loop 30m /loop-factory`).

A pass does exactly this:

1. **Scan** `factory/specs/inbox/`. 2. **Filter to ready specs only.** A spec is ready when its grill gate is complete — `grill: completed` in frontmatter, or a filled-in `# Grill Gate` section. Skip anything else and log it as "needs grilling." Never grill autonomously: the grill gate needs human answers, and inventing them would be deciding product direction. 3. For each ready spec: **stage → implement against acceptance criteria → run verification.** 4. **Stop at the review gate.** Leave built specs in `active/`. Do **not** archive — acceptance stays a human decision. 5. If verification fails, leave the spec in `active/` with a note in `factory/runs/`. Do not retry in a loop or weaken the criteria to make it pass. 6. **Report**: built, skipped (needs grilling), failed-verification — and stop.

This keeps the boundary intact: the loop is a tireless *builder*, never a silent *decider*.

Two ways to fire it on a recurring basis:

• **`/loop` (local, recommended for active work)** — `/loop 30m /loop-factory` re-runs this skill on any interval against your local working tree. Built specs land in `active/`; no git push or PR needed. Only runs while a Claude Code session is open.
• **Cron (cloud, unattended)** — a scheduled routine that runs whether or not you're online (minimum 1-hour interval) and returns work as a pull request.

Both, plus the safety knobs, are in **[references/autonomous.md](references/autonomous.md)**.

Core commands

loop-factory scan                              # list inbox + active specs
loop-factory dispatch --agent <claude|codex> --stage   # prompt + move to active
loop-factory review <spec-id> --agent <claude|codex>   # generate review prompt
loop-factory archive <spec-id> --accepted      # archive a passed spec
loop-factory backprop --agent <claud