loop-factory

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

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.

Loop Factory 将“让Agent构建某事物”转化为一条可视化的流水线。每个任务都是一份Markdown 规范（spec）。规范所在的文件夹代表它的状态。Agent负责实现和验证，但从不决定要构建什么。

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

统领一切的规则：自动化实现与验证，而非产品决策。如果规范缺少某项决策，记录下未解决的问题——不要自行设定产品方向。

通过输入

/loop-factory

按需调用此技能（单次手动执行），或让定时任务自动触发——详见自主模式。

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.

在仓库中设置Loop Factory（安装CLI、运行
```
init
```
命令）。
从inbox中选取规范并分派给Claude Code或Codex。
根据验收标准实现规范。
审核已完成的工作并归档已通过的规范。
将实现过程中的经验反馈到动态规范/文档中。

Setup (first time in a repo)

首次在仓库中设置

The

loop-factory

CLI is the state engine. Install it once, then scaffold any git repo:

bash

undefined

loop-factory

CLI是状态引擎。只需安装一次，即可为任意Git仓库搭建环境：

bash

undefined

get the CLI (clone the source repo, install editable)

获取CLI（克隆源码仓库，以可编辑模式安装）

git clone https://github.com/JuliusBrussee/Loop-Factory.git python3 -m pip install -e ./Loop-Factory

scaffold the factory/ folders in your target project

在目标项目中搭建factory/文件夹

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

cd your-project loop-factory init loop-factory doctor # 确认git与Agent CLI已连接


除Python 3.10+外无其他运行时依赖。如果已在Loop-Factory仓库内，可跳过安装步骤，直接运行 `python3 bin/loop-factory <command>`。完整安装说明、Agent-CLI配置，以及如何复制原生Agent适配器：**[references/install.md](references/install.md)**。

The loop

工作循环

Inspect the queue. Run
```
loop-factory scan
```
to see inbox and active specs.
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.
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
```
.
Implement. Build only the acceptance criteria. Match existing code style. Stay scoped.
Verify. Run every command listed in the spec's
```
verification:
```
frontmatter. Capture the output as evidence.
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.
Archive accepted work.
bash
```
loop-factory archive <spec-id> --accepted
```
```
--accepted
```
is required on purpose — nothing leaves
```
active/
```
without a confirmed pass.
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
```

检查队列。运行
```
loop-factory scan
```
查看inbox和active中的规范。
先审查新规范。在分派新规范前，逐个问题质询（谁拥有决策权、哪些内容超出范围、风险最高的假设、最小可行版本）。将答案记录在
```
# Grill Gate
```
部分。模糊的规范会产出模糊的代码。
分派任务。生成实现提示并将规范移至
```
active/
```
：
bash
```
loop-factory dispatch --agent claude --limit 1 --stage
```
此命令会将提示写入
```
factory/prompts/
```
，并将运行记录写入
```
factory/runs/
```
。除非添加
```
--execute
```
参数，否则不会运行AI。
实现规范。仅围绕验收标准构建。匹配现有代码风格，严格控制范围。
验证成果。运行规范
```
verification:
```
前置元数据中列出的所有命令，捕获输出作为证据。
审核工作。生成审核提示并对照标准检查代码差异：
bash
```
loop-factory review <spec-id> --agent claude
```
通过 → 归档。失败 → 将规范留在
```
active/
```
中等待再次处理。
归档已通过的工作。
bash
```
loop-factory archive <spec-id> --accepted
```
```
--accepted
```
参数是必填项——未确认通过的内容不能离开
```
active/
```
。
反馈经验。如果构建功能改变了系统实际运行方式，将这些内容同步回规范/文档，但不得改变产品意图：
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:

Scan
```
factory/specs/inbox/
```
.
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.
For each ready spec: stage → implement against acceptance criteria → run verification.
Stop at the review gate. Leave built specs in
```
active/
```
. Do not archive — acceptance stays a human decision.
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.
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.

运行单次独立循环，无需人工干预即可处理完inbox中的任务。当用户调用时提及“autonomous”/“drain the inbox”、通过定时任务触发，或通过

/loop

重复触发（如

/loop 30m /loop-factory

）时激活此模式。

单次循环的具体流程：

扫描
```
factory/specs/inbox/
```
。
仅筛选就绪的规范。当规范的grill gate完成时（前置元数据中
```
grill: completed
```
，或
```
# Grill Gate
```
部分已填写完整），视为就绪。跳过未就绪的规范并记录为“需要审查”。绝不能自主执行审查：grill gate需要人工答复，自行编造答复等同于决定产品方向。
对每个就绪的规范：预准备 → 对照验收标准实现 → 运行验证。
在审核关卡处停止。将已构建的规范留在
```
active/
```
中。不得归档——验收必须由人工决定。
如果验证失败，将规范留在
```
active/
```
中，并在
```
factory/runs/
```
中添加备注。不得循环重试或放宽标准使其通过。
生成报告：已构建、已跳过（需审查）、验证失败——然后停止。

这样能保持边界清晰：循环是不知疲倦的构建者，而非沉默的决策者。

两种定期触发方式：

/loop
（本地，推荐用于活跃工作） ——
```
/loop 30m /loop-factory
```
会按指定间隔针对本地工作区重新运行此技能。已构建的规范会存入
```
active/
```
；无需git推送或PR。仅在Claude Code会话开启时运行。
Cron（云端，无人值守） —— 定时任务，无论是否在线都会运行（最小间隔1小时），并以Pull Request的形式返回工作成果。

以上两种方式及安全配置，详见 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.

bash

loop-factory scan                              # 列出inbox和active中的规范
loop-factory dispatch --agent <claude|codex> --stage   # 生成提示并移至active
loop-factory review <spec-id> --agent <claude|codex>   # 生成审核提示
loop-factory archive <spec-id> --accepted      # 归档已通过的规范
loop-factory backprop --agent <claude|codex>   # 将文档/规范与代码同步
loop-factory doctor                            # 检查设置健康状态

可在任何命令中将

--agent claude

替换为

--agent codex

——循环流程完全相同。默认行为是写入提示文件；仅当本地已安装

codex

claude

CLI且用户要求实时执行时，才添加

--execute

参数。完整参数说明：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.

规范是包含前置元数据（

id

、

title

、

agent

、

risk

、

verification

）的Markdown文件，正文涵盖背景、验收标准、约束条件和审核说明。验收标准是契约——Agent需据此构建，审核者需据此检查，因此需确保其具体且可测试。格式、示例及grill gate问题：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.

只有人工或明确的CLI命令能将规范从
```
inbox
```
移至
```
active
```
。
只有通过审核的规范能从
```
active
```
移至
```
archive
```
。
审核失败的规范会留在
```
active
```
中——不会被删除或自动重新分派。
反馈操作可更新规范/文档，但绝不能自行改变产品意图。
```
factory/prompts/
```
、
```
factory/runs/
```
和
```
factory/reviews/
```
下的生成文件是工件和审计线索——可查看，但不能视为事实来源。规范才是事实来源。

Working with subagents

与子Agent协作

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.

当隔离有助于工作时，可将不同阶段交给专门的子Agent处理，而非在同一上下文中完成所有工作：

规范实现者：为单个active规范编写代码，
规范审核者（上下文隔离）：判断代码差异，
规范反馈者：将经验整合回规范/文档。

当工作是连续的、涉及相同文件或风险较高时，使用单个Agent。仅当规范相互独立或审核需保持上下文隔离时，才拆分给多个Agent处理。