loop-factory

Loop Factory

Loop Factory 将“让 Agent 来构建某个东西”变成一条可见的流水线。每项任务都是一个 Markdown 规格。规格所在的文件夹就是它的状态。Agent 负责实现和验证；它们绝不决定要构建什么。

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

支配一切的一条规则是：自动化实现和验证，而非产品决策。 如果规格缺少某项决策，就记录这个待解决问题——不要擅自决定产品方向。

按需输入 /loop-factory 来调用此技能（手动执行一次），或让 cron 无人值守地触发它——请参阅自主模式。

何时使用此技能

• 在仓库中设置 Loop Factory（安装 CLI、运行 init）。
• 从收件箱中选取规格，并将其分派给 Claude Code 或 Codex。
• 根据验收标准实现规格。
• 审查已完成的工作，并归档已验收的规格。
• 将实现过程中学到的经验反向更新到持续维护的规格/文档中。

设置（首次在仓库中使用）

loop-factory CLI 是状态引擎。安装一次后，即可在任意 git 仓库中搭建脚手架：

# 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

除 Python 3.10+ 外，无其他运行时依赖。如果你已在 Loop-Factory 仓库中，可以跳过安装，直接运行 python3 bin/loop-factory <command>。完整的安装说明、Agent CLI 设置方法，以及如何复制原生 Agent 适配器，请参阅：references/install.md。

工作循环

1. 检查队列。 运行 loop-factory scan，查看收件箱和活动规格。
2. 先细问新规格。 分派新的规格前，逐个提出问题，深入确认细节（谁负责这项决策、哪些内容不在范围内、风险最大的假设是什么、可接受的最小版本是什么）。在 # Grill Gate 部分下记录答案。模糊的规格只会产出模糊的代码。
3. 分派。 生成实现提示词，并将规格移至 active/：

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

   这会将提示词写入 factory/prompts/，并将运行记录写入 factory/runs/。除非添加 --execute，否则不会运行 AI。
4. 实现。 仅实现验收标准。遵循现有代码风格。严格限定范围。
5. 验证。 运行规格 verification: frontmatter 中列出的所有命令。将输出作为证据留存。
6. 审查。 生成审查提示词，并根据标准检查差异：

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

   通过 → 归档。未通过 → 将规格留在 active/，以便再次处理。
7. 归档已验收的工作。

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

   必须使用 --accepted——这是有意为之：未经确认通过，任何内容都不能离开 active/。
8. 反向更新。 如果构建此功能改变了系统的实际工作方式，就将这些变化同步回规格/文档，但不要改变产品意图：

   loop-factory backprop --agent claude
   

自主模式

运行一次独立完整的流程，在无人参与的情况下清空收件箱。当通过“autonomous” / “drain the inbox”调用、由计划的 cron 触发，或通过 /loop（例如 /loop 30m /loop-factory）反复运行时，就会启动此流程。

一次流程严格执行以下操作：

1. 扫描 factory/specs/inbox/。
2. 仅筛选已准备就绪的规格。 当 grill gate 已完成时，规格即为就绪状态——frontmatter 中有 grill: completed，或 # Grill Gate 部分已填写完整。跳过其他所有规格，并将其记录为“needs grilling”。绝不自主进行 grill：grill gate 需要人类回答，擅自编造答案就等于自行决定产品方向。
3. 对每个就绪的规格：暂存 → 按验收标准实现 → 运行验证。
4. 在审查关卡处停止。 将已构建的规格留在 active/ 中。不要归档——是否验收由人类决定。
5. 如果验证失败，将规格留在 active/ 中，并在 factory/runs/ 中添加备注。不要循环重试，也不要降低标准以使其通过。
6. 报告：已构建、已跳过（需要 grill）、验证失败——然后停止。

这能守住边界：循环是勤勉的构建者，绝不是悄无声息的决策者。

有两种方式可定期启动此流程：

• /loop（本地，推荐用于进行中的工作） — /loop 30m /loop-factory 会按指定间隔，针对本地工作树重新运行此技能。已构建的规格会放入 active/；无需 git push 或 PR。仅在 Claude Code 会话处于打开状态时运行。
• Cron（云端，无人值守） — 无论你是否在线都会运行的计划例程（最短间隔为 1 小时），并通过拉取请求交付工作。

这两种方式以及安全选项都列在 references/autonomous.md 中。

核心命令

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

可将任何位置的 --agent claude 替换为 --agent codex——循环流程完全相同。默认行为是写入提示词文件；仅当本地已安装 codex/claude CLI 且用户要求实际执行时，才添加 --execute。完整的标志参考：references/commands.md。

编写规格

规格是带有 frontmatter（id、title、agent、risk、verification）的 Markdown 文档，正文涵盖背景、验收标准、约束和审查备注。验收标准就是契约——Agent 会据此构建，审查者会据此检查，因此要确保其具体且可测试。格式、示例和 grill-gate 问题：references/spec-authoring.md。

边界

• 只有人类或明确的 CLI 命令才能将规格从 inbox 移至 active。
• 只有通过验收的审查才能将规格从 active 移至 archive。
• 审查失败时，规格仍留在 active 中——不会被删除或悄无声息地重新派发。
• Backprop 可以更新规格/文档，但绝不能自行更改产品意图。
• factory/prompts/、factory/runs/ 和 factory/reviews/ 下生成的文件都是产物和审计记录——可以阅读，但不要将其视为事实来源。规格才是事实来源。

与子 Agent 协作

需要隔离时，可将各阶段交给专用子 Agent，而不是在同一个上下文中完成所有工作：

• spec-implementer：为一个 active 规格编写代码；
• spec-reviewer（上下文隔离）：评判差异内容；
• spec-backpropagator：将经验总结回填到规格/文档中。

当工作按顺序进行、涉及相同文件或风险较高时，使用一个 Agent。仅当规格彼此独立，或审查需要保持上下文隔离时，才分派给多个 Agent。