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 turns ad-hoc requests to an agent into a visible, spec-driven assembly line. Each coding task lives as a markdown spec, and the folder the spec sits in (inbox, active, or archive) is its state. Agents such as Claude Code or Codex implement and verify the work but never decide what to build; the governing rule is to automate implementation and verification, not product decisions. When a spec is missing a decision, the loop records the open question rather than inventing product direction.
The backbone is the dependency-free loop-factory CLI (Python 3.10+), a state engine that owns transitions and generates prompts. After installing it and running init to scaffold factory folders, the loop runs: scan the queue, grill new specs by interrogating assumptions and recording answers in a grill gate, dispatch a spec (which writes an implementation prompt and a run manifest and optionally stages or executes the agent), implement only the acceptance criteria, verify by running the commands in the spec's frontmatter, review the diff against criteria, then archive accepted work (the --accepted flag is mandatory so nothing leaves active without a confirmed pass), and finally backpropagate implementation learnings into specs and docs. An autonomous mode drains the inbox unattended via /loop locally or a scheduled cron returning work as a pull request, protected by a safety contract: only build grilled specs, never archive (human acceptance is required), and never answer grill questions itself. Reference files cover install, commands, autonomous mode, and spec authoring, and optional native adapters wire the rules into Claude Code and Codex. Setup documents installing agent CLIs via official installer scripts and an optional GitHub Action review that uses a repository API-key secret.
It targets developers and teams who want repeatable, reviewable agent-driven coding work with an auditable trail of prompts, runs, and reviews. Typical use cases include scaffolding the loop into a repo, dispatching specs to an agent, and running reviewed autonomous passes.
The CLI needs Python 3.10 or newer and a git repository, with no other runtime dependencies. To actually execute agents (rather than just write prompt files) you install the Claude Code and/or Codex CLIs; the optional GitHub Action review needs an OPENAI_API_KEY repository secret.
Each task is a markdown spec, and the folder it lives in is its state: inbox (not started), active (being built), or archive (accepted). The CLI moves specs between these via dispatch --stage and archive --accepted, keeping run manifests and review records as an audit trail.
It is bounded by a three-rule safety contract: only build specs whose grill gate is complete, never archive (acceptance stays a human gate), and never answer grill questions itself since that would be deciding product direction. Local /loop passes stay in the working tree; cron passes return work as a pull request.
Not by default. Dispatch and review only write prompt files and manifests unless you add the --execute flag, which runs the local agent CLI. This keeps the state engine and prompt generation separate from actually invoking an AI.
You clone the Loop-Factory repo and pip install it editable, or run it directly from a checkout with python3 bin/loop-factory. The agent CLIs are installed separately via their official installer scripts or package managers.
Quick Setup:
.claude/skills/Repository
juliusbrussee/skills