---
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:
```bash
# 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/`:
```bash
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:
```bash
loop-factory review <spec-id> --agent claude
```
Pass → archive. Fail → leave the spec in `active/` for another pass.
7. **Archive accepted work.**
```bash
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:
```bash
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
```bash
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 <claude|codex> # sync docs/specs with code
loop-factory doctor # health-check setup
```
Swap `--agent claude` for `--agent codex` anywhere — the loop is identical. Default behavior writes prompt files; add `--execute` only when the local `codex`/`claude` CLI is installed and the user asked for live execution. Full flag reference: **[references/commands.md](references/commands.md)**.
## Writing specs
A spec is markdown with frontmatter (`id`, `title`, `agent`, `risk`, `verification`) and a body covering Context, Acceptance Criteria, Constraints, and Review Notes. The acceptance criteria are the contract — they're what the agent builds toward and what the reviewer checks against, so make them concrete and testable. Format, examples, and the grill-gate questions: **[references/spec-authoring.md](references/spec-authoring.md)**.
## Boundaries
- Only a human or an explicit CLI command moves a spec from `inbox` to `active`.
- Only an accepted review moves a spec from `active` to `archive`.
- A failed review leaves the spec `active` — it does not get deleted or silently re-dispatched.
- Backprop may update specs/docs but must never change product intent on its own.
- Generated files under `factory/prompts/`, `factory/runs/`, and `factory/reviews/` are artifacts and audit trail — read them, don't treat them as source of truth. The spec is the source of truth.
## Working with subagents
When isolation helps, hand stages to dedicated subagents instead of doing everything in one context:
- a **spec-implementer** to write the code for one active spec,
- a **spec-reviewer** (context-isolated) to judge the diff,
- a **spec-backpropagator** to fold learnings back into specs/docs.
Use one agent when work is sequential, touches the same files, or is high-risk. Fan out to multiple only when specs are independent or review should stay context-isolated.
