build-dark-factory

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Build a dark factory

构建Dark Factory

What the user typed: $ARGUMENTS

Work out the PRD path and the repo path from that line yourself, and do not print a parse you have not checked. The positional split is on whitespace, so anyone who types a sentence ("build a dark factory for my repo at C:\code\thing") gets the first two words as the two paths - three separate test runs opened with
PRD: Build
and
Repo: a
, which is a broken-looking first contact for a parse the skill then quietly recovered from anyway.
So: read the line, find the thing that looks like a
.md
PRD and the thing that looks like a directory, and confirm both back to the user as one sentence before Phase 0. If only one is given, work out from its extension which it is and ask for the other. If the PRD path does not exist, say so and stop - that is Phase 0a, reached early.

A dark factory is a repository where work goes in one end and shipped code comes out the other, and there is no human in between. Work arrives as an issue. Workflows plan it, build it, validate it, and merge it. Deployment carries it to real users. Nobody reviews the diff.

That last sentence is the whole difficulty. Everything else is plumbing.

Build the factory into the user's repo. Do not hand them a design document. Every phase below ends with files committed and something demonstrably working.

用户输入内容： $ARGUMENTS

请自行从输入行中解析PRD路径和仓库路径，且不要输出未经确认的解析结果。 路径按空格分割，因此如果用户输入一句话（例如"build a dark factory for my repo at C:\code\thing"），会将前两个单词识别为两条路径——曾有三次测试运行中，解析结果为
PRD: Build
和
Repo: a
，这是初次解析时的错误，但后续技能会自动修复。
正确做法：读取输入行，识别出类似
.md
格式的PRD文件路径和目录路径，在第0阶段开始前用一句话向用户确认两者。如果只提供了一个路径，根据扩展名判断是PRD还是仓库路径，并询问用户补充另一个。如果PRD路径不存在，直接告知用户并终止流程——这是提前触发的第0a阶段。

Dark Factory是一种无需人工干预的仓库：工作以Issue形式进入仓库，经过工作流规划、构建、验证、合并后，最终输出已部署的代码。整个过程无需人工审核代码差异。

最后这句话正是核心难点所在，其余部分都只是基础架构。

直接在用户的仓库中构建工厂，不要只提供设计文档。 以下每个阶段结束后，都要提交文件并确保功能可运行。

Output discipline - read this before you write a single word to the user

输出规范——在向用户输出任何内容前请仔细阅读

This document is long because it has to be complete. What you SAY is not. A user running this reported the experience as "incredibly frustrating and hard to process, overwhelming to say the least" - and that was the skill working correctly, explaining itself at every step. Reasoning that belongs in a file is noise in a chat window.

Hard budgets. These are not style preferences.

Moment	Budget
Between one question and the next	Nothing. Ask. Do not preface, do not recap the last answer.
Finishing a phase	Two lines. What now exists, and the next question.
Explaining a concept	Only when asked, and then the short version first.
Reporting a file you wrote	One line. Its path and what decides its content.
A command's output	Never paste it. Say the verdict and the number.

Never do these:

Announce a plan for a phase before doing it. Do it, then say what exists.
Restate the user's answer back to them as a paragraph. A picker already showed it.
Explain WHY the skill works this way. That reasoning is in
```
references/
```
, for you, not for them. If they want it they will ask.
Print a table of everything you are about to build.
Summarise at the end of a phase what you said at the start of it.
Paste a file you just wrote. They can open it.

The one thing worth spending words on is a question that carries a real decision, and those go through the question tool, where the words are in the options rather than in a paragraph above them.

A useful test before any message: would this still be true if I deleted it? If the files on disk carry the fact, delete it.

本文档篇幅较长是因为需要覆盖所有细节，但你向用户传达的内容不能这么冗长。曾有用户反馈使用该技能的体验是*“极其令人沮丧、难以理解，信息量过大”*——而这还是技能正常工作、每一步都进行解释的情况。适合写在文件中的逻辑，在聊天窗口中只会成为干扰信息。

严格遵守以下沟通篇幅限制，这不是风格偏好，而是硬性规则。

场景	篇幅限制
两个问题之间	无额外内容。直接提问，不要添加前置说明或复述上一个答案。
完成一个阶段后	两行内容：说明当前已完成的内容，以及下一个问题。
解释概念	仅在用户询问时，且先提供简短版本。
报告已编写的文件	一行内容：说明文件路径和决定其内容的依据。
命令输出	绝不粘贴输出内容，只说明结果和关键数字。

绝对禁止以下行为：

在开始一个阶段前宣布计划。先执行，再说明已完成的内容。
将用户的答案复述成段落形式。用户已通过选择器给出答案，无需重复。
解释技能的设计原因。相关逻辑记录在
```
references/
```
目录下，供你参考，而非向用户展示。如果用户询问，再进行说明。
输出即将构建的所有内容的表格。
在阶段结束时复述阶段开始时的内容。
粘贴刚编写的文件内容。用户可以自行打开查看。

唯一值得花费篇幅的是需要用户做决策的问题，这类问题需通过提问工具呈现，将说明文字放在选项中，而非问题上方的段落里。

发送任何消息前可进行测试：如果删除这段内容，是否会影响信息传达？ 如果磁盘上的文件已经包含相关信息，就删除这段内容。

What this is, and what it is not

本技能的定位

A dark factory is not a different way of coding with AI. It is the way you already code with AI, with the human checkpoints removed.

Whatever process you run today is what goes inside the factory. GitHub Spec Kit, BMAD, a PRP framework, your own plan-then-implement loop, or just a well-worn habit. The steps stay the same. The skills stay the same. The MCP servers, the rules files, the subagents, the commands you already trust: all the same.

One thing changes. Nobody approves the plan, and nobody reads the diff before it ships.

So the job here is not to invent a process. It is to write down the one the user already has, then build the parts that make it safe to walk away from. Ask what their current AI coding workflow looks like early, and encode that, rather than imposing the shape of the example factory.

This skill does not write the PRD. That is deliberate. Producing the top-level plan for a product is the part where almost everyone already has a custom approach worth keeping, and a generic interview would be a downgrade. If the user has no approach yet, point them at the

plan-create-prd

skill in this same repo and come back when they have a file.

Dark Factory并非一种全新的AI编码方式，而是移除人工校验环节后的现有AI编码流程。

你当前使用的任何流程都可以嵌入到工厂中：GitHub Spec Kit、BMAD、PRP框架、你自己的“规划-实现”循环，或是成熟的操作习惯。步骤不变、技能不变、MCP服务器、规则文件、子Agent、你信任的命令——一切都保持原样。

唯一的变化是：无需人工批准规划，也无需人工审核代码差异即可部署。

因此，本技能的任务不是发明新流程，而是记录用户现有的流程，然后构建确保无人值守时安全运行的组件。请尽早询问用户当前的AI编码工作流，并将其固化到工厂中，而非强行套用示例工厂的流程。

本技能不会生成PRD，这是刻意设计的。生成产品顶层规划的环节，几乎所有人都有值得保留的自定义流程，通用的访谈反而会降低效率。如果用户还没有PRD生成流程，请引导他们使用同一仓库中的

plan-create-prd

技能，待生成PRD文件后再返回。

Two things that shape every decision below

指导所有决策的两个核心原则

Cached reads dominate cost by orders of magnitude over output. Context size drives the bill far more than how much the agent writes, which is why the premium model belongs in the planning slot and a cheaper one everywhere else.
Refusing is cheap and building is not. If Phase 0 is borderline, refuse. Building the wrong factory is discovered in month two, and it cannot be patched by a better prompt.

Offer to stop after the guidance layer if the user wants a smaller first commitment. It is useful even if they never turn a cron on.

缓存读取的成本远高于输出成本。上下文大小对费用的影响远大于Agent的输出量，因此应在规划环节使用高级模型，其他环节使用更经济的模型。
拒绝错误需求的成本远低于错误构建的成本。如果第0阶段的可行性存疑，直接拒绝。错误构建的工厂通常在两个月后才会被发现问题，且无法通过优化提示词修复。

如果用户希望先进行小范围尝试，可以提议在完成指导层后暂停。即使不开启定时任务，指导层也具备实用价值。

Before anything else: the three harnesses

前置概念：三种框架

People conflate these and then cannot debug them. Name them once, out loud, early:

Harness	What it is	Who builds it
The agent harness	Claude Code, Codex, Pi - the loop that turns a prompt into edits	Vendor. Not your problem.
The factory harness	how work is planned, implemented, reviewed, gated, merged	`templates/runner/` . Components 1-4, mostly copied.
The validation harness	the tools the agent uses to check its own work as a user would	You, and it is most of the work. Component 5.

The factory harness decides what runs. The validation harness decides whether what ran was worth keeping. Confusing the two is why people build an impressive DAG that ships broken software on schedule.

That distinction is also what decides which parts of this ship as a template:

The factory harness is templatable. The validation harness is not.

The dispatcher, the runner, the gate, the guard, the merge and the state machine are the same in every factory, so they are in

templates/runner/

with their scars intact. What "working" means for this app is the one thing nobody can write in advance, so component 5 is yours - and it is where the real work of this build sits.

人们常混淆这三种框架，导致无法调试。请尽早向用户明确命名：

框架	定义	构建方
Agent框架	Claude Code、Codex、Pi等将提示词转换为代码编辑操作的循环	供应商，无需你处理。
工厂框架	工作的规划、实现、审核、门禁、合并流程	`templates/runner/` ，主要包含组件1-4，可直接复制使用。
验证框架	Agent用于像用户一样检查自身工作的工具	由你构建，这是核心工作，对应组件5。

工厂框架决定运行哪些任务，验证框架决定运行结果是否符合要求。混淆两者会导致构建出看似强大但持续交付错误软件的DAG流程。

这种区分也决定了哪些部分可以作为模板交付：

工厂框架可模板化，验证框架不可模板化。

调度器、执行器、门禁、守卫、合并机制和状态机在所有工厂中都是相同的，因此它们已包含在

templates/runner/

目录中，且保留了过往的优化痕迹。而“软件正常运行”的定义因产品而异，无法提前编写，因此组件5需要你根据具体情况构建——这也是本构建任务的核心工作。

Construction order, and why it is not 1-2-3-4-5

构建顺序及原因

The five components are numbered in anatomy order - the order you explain the machine in. They are not built in that order. Build in this order instead:

Build	Component	Why here
0th	(the PRD)	Not a component. The input. Everything below reads it, and nothing below can be written honestly without it.
1st	Guidance layer (#4)	Markdown, and every other component reads it. The cheapest thing here with the highest leverage.
1.5th	(the walking skeleton)	Greenfield only, and AFTER the guidance layer, not before it - the slice should be built inside the mission's scope, and markdown needs no code to exist. Not a component; deliberately tiny, the thinnest slice that yields one assertable behaviour. Component 5 cannot be written against software that does not exist. See Phase 0c; the danger is building the MVP here rather than a slice.
2nd	Validation harness (#5)	The long pole. Start it before you need it, because you will be wrong about it twice.
3rd	Workflow-driven repo (#1)	Now the workflows have rules to obey and checks to pass.
4th	Deployment (#3)	Close the loop to real users before you make it unattended.
Last	The trigger (#2)	The cron is the switch. It goes on only when 1-4 are proven.

The trigger is built last on purpose. Turning on a scheduler is the moment the repo becomes autonomous. Everything before it can be run by hand and inspected. A factory whose dispatcher was built first is an unsupervised code generator that nobody has ever checked.

State this to the user before starting. It reframes the whole project from "wire up an agent" to "earn the right to walk away."

五个组件的编号是按架构逻辑排序的——即解释系统时的顺序，但实际构建顺序并非1-2-3-4-5。请按以下顺序构建：

构建步骤	组件	原因
第0步	(PRD)	不属于组件，是输入。以下所有内容都依赖PRD，没有PRD就无法如实编写任何内容。
第1步	指导层（组件4）	基于Markdown，所有其他组件都依赖它。这是成本最低、影响力最大的部分。
第1.5步	(最简可运行骨架)	仅适用于全新项目，且需在指导层之后构建——骨架需在任务范围内构建，而Markdown无需代码即可存在。这不属于组件，需尽可能精简，是能产生可验证行为的最薄切片。组件5无法针对不存在的软件编写。详见第0c阶段；需注意避免将MVP作为骨架构建。
第2步	验证框架（组件5）	耗时最长的环节。提前开始构建，因为你很可能会多次调整。
第3步	工作流驱动仓库（组件1）	此时工作流已有规则可遵循、有检查需通过。
第4步	部署机制（组件3）	在实现无人值守前，先完成向真实用户交付的闭环。
最后一步	触发模块（组件2）	定时任务是开关，仅在组件1-4验证通过后再开启。

触发模块最后构建是刻意设计的。开启调度器是仓库实现自主运行的节点，在此之前所有环节都可手动运行并检查。如果先构建调度器，会得到一个无人监管的代码生成器，且从未有人验证过其输出。

在开始构建前，请向用户说明这一点。这会将项目从“连接Agent”重构为“逐步实现无人值守的资格”。

Phase 0. The input, the two ways to refuse, and the greenfield path

第0阶段：输入、两种拒绝场景及全新项目路径

0a. There has to be a PRD

0a. 必须提供PRD

The input to this skill is a PRD: what is being built and why, at the level a product manager writes it. Problem, users, scope, and above all non-goals. Call it a spec, a brief, a product doc, an epic; the name does not matter and the content does.

It deliberately does not contain the tech stack, the architecture, the data model, or the file layout. Those are engineering decisions, they come later, and in a factory they are usually decided on the first real run or already settled by the existing codebase. Asking for them here is how a PRD turns into a spec nobody can change.

When the PRD contains one anyway - and it usually will - treat it as SETTLED, not as scope, and say that you are doing so. Someone who is not an engineer writes down the stack because it is the part they feel confident about; a career-changer's brief will name the framework, the host and a table sketch before it names a single non-goal. Arguing them out of it buys nothing and costs the room.

So: take it as a decision already made, do not put it in

MISSION.md

(it is not scope and the factory must not defend it), and flag it in one line so it is a choice rather than something you quietly assumed. The one thing to check out loud is reachability - a stack that can only be exercised through a rendered page needs the logic split out behind something an E2E can call. See 0c.

Read the PRD at

$prd

in full before asking a single question. Then map it:

The PRD gives you	The factory builds from it
the problem, and why it is worth solving	the framing at the top of `MISSION.md`
who the users are	the person the E2E path is acted out as
MVP scope, the capability areas	what triage is allowed to accept
non-goals	`MISSION.md` out-of-scope-forever, the most load-bearing list in the whole build
success metrics	what the validation harness is ultimately arguing about
open questions, anything marked TBD	a decision to be proposed, not a wall. The factory picks a defensible value, records it, and the merge is held for a human. It escalates only for the short list in `FACTORY_RULES.md` §7.2 - read "open" as "I have not decided", never as "you may not propose"

And be explicit with the user about what the PRD does not give you, because these are exactly what the interview exists to produce:

the E2E happy path, narrated as observable steps
the protected list
the two gates that have to be code rather than prompt
the target autonomy level
the stop button
how work arrives, and where the factory runs

Refuse if there is no PRD. Say why: without a written scope,

MISSION.md

has no out-of-scope list, and without that list every plausible feature request is arguably in scope. The factory will build all of them. That is the single most common way an autonomous repo goes wrong, and it cannot be patched later by a better prompt.

Point at the

plan-create-prd

skill in this repo and stop. Coming back in twenty minutes with a real PRD is the fastest path, not a detour.

本技能的输入是PRD：即产品经理编写的、说明产品构建目标及原因的文档，包含问题、用户群体、范围，尤其是非目标。可以称之为规格说明、 brief、产品文档、史诗；名称不重要，内容才重要。

PRD中刻意不包含技术栈、架构、数据模型或文件布局。这些是工程决策，会在后续环节确定，在工厂中通常由首次实际运行或现有代码库决定。如果在此阶段询问这些内容，会导致PRD变成无法修改的规格说明。

如果PRD中包含这些内容——通常都会包含——请将其视为已确定的决策，而非范围，并告知用户你会这样处理。 非技术人员会写下技术栈，因为这是他们熟悉的部分；转行人员的brief可能会先命名框架、主机和表格草图，再列出非目标。与其说服他们修改，不如接受现状，这不会带来任何好处，反而会浪费沟通时间。

处理方式：将其视为已确定的决策，不要放入

MISSION.md

（这不属于范围，工厂无需维护这些内容），并用一行文字标记，明确这是用户的选择而非你的默认假设。唯一需要公开确认的是可访问性——如果技术栈只能通过渲染页面使用，需将逻辑拆分到E2E测试可调用的接口后。详见0c阶段。

在提问前，请完整读取

$prd

路径下的PRD，然后进行映射：

PRD提供的内容	工厂基于此构建的内容
问题及解决价值	`MISSION.md` 顶部的框架说明
用户群体	E2E路径模拟的用户角色
MVP范围、功能领域	任务分配环节可接受的内容
非目标	`MISSION.md` 中的永久排除范围列表，这是整个构建中最重要的部分
成功指标	验证框架最终需验证的内容
未解决问题、标记为TBD的内容	需要提议的决策，而非障碍。工厂会选择合理的值，记录并暂停合并等待人工确认。仅当问题属于 `FACTORY_RULES.md` 第7.2节中的短列表时才会升级——将“未解决”理解为“我尚未决定”，而非“你不得提议”

请向用户明确说明PRD未提供的内容，这些正是访谈需要获取的信息：

E2E正常路径，以可观察步骤描述
受保护的文件列表
必须以代码实现而非提示词的两个门禁
目标自主化等级
停止按钮
工作的输入方式及工厂运行位置

如果没有PRD，直接拒绝。 说明原因：没有书面范围，

MISSION.md

就没有排除范围列表，而没有该列表，任何看似合理的功能请求都会被视为在范围内，工厂会全部实现。这是自主仓库出错最常见的原因，且无法通过后续优化提示词修复。

引导用户使用同一仓库中的

plan-create-prd

技能，然后终止流程。花20分钟生成真实的PRD是最快的路径，而非绕路。

0b. The repo has to be observable

0b. 仓库必须具备可观察性

Inspect before asking anything. Look for: a test command that runs, a way to start the app, existing CI, whether

gh

is authenticated, whether the repo is public, and whatever AI coding setup already exists (

CLAUDE.md

AGENTS.md

.claude/

.cursor/

, existing skills, commands, MCP config). That last one is the process to encode, and it is usually already sitting there.

Decide which of two repos this is by LOOKING - you have just inspected it. Do not ask. The refusals below are written for one of them and misfire badly on the other, and the difference is visible in the file list:

Brownfield - source files that are not scaffolding. The refusals apply as written.
Greenfield - a PRD, maybe a
```
.gitignore
```
,
```
.claude/
```
, a README, and nothing that runs. Both refusals are then trivially true and neither carries any signal. Go to 0c; do not refuse.

Say which one you concluded and why, in one line, so the user can correct it: "No source files outside docs/ and .claude/, so I am treating this as greenfield." A wrong guess is cheap to fix and asking costs a question you already have the answer to.

Refuse, and say why, when:

There is no way to observe the software working - nothing to start, nothing to invoke, and nothing importable either. Component 5 has nothing to stand on.

This is about software that cannot be observed, not software that does not exist yet. A greenfield repo trips this and the next bullet by definition, and refusing it would be refusing the premise rather than a defect. See 0c.
A library is not this case. The harness ships three drivers -
```
http
```
(a server),
```
cli
```
(a command), and
```
library
```
(no process at all; the E2E imports it and calls it) - and
```
APP_STARTED driver=library
```
means the import succeeded, which is the same claim a server answering makes. This bullet used to open with the words "a library", and a test run against a pure Python library nearly hard-refused a repo the scaffold supports out of the box. Read
```
templates/harness/appproc.py
```
before deciding something is unobservable.
The repo has no CI and no test command at all. Start with a test suite. A dark factory built on zero checks is a machine for merging plausible code.
The user wants the agent to touch auth, payments, or anything with a blast radius they cannot absorb. Those go on the protected list, not into the factory.

Saying no here is cheaper than saying it in month two. If any of these hold, offer the smaller version: build the guidance layer and the harness now, and stop before autonomy.

在提问前先检查仓库：查看是否有可运行的测试命令、启动应用的方式、现有CI、

gh

是否已认证、仓库是否公开，以及已有的AI编码设置（

CLAUDE.md

、

AGENTS.md

、

.claude/

、

.cursor/

、现有技能、命令、MCP配置）。最后一项是需要固化的流程，通常已存在于仓库中。

通过查看文件列表判断仓库类型，不要询问。 以下拒绝场景仅适用于其中一种类型，判断错误会导致拒绝逻辑失效：

存量项目：包含非脚手架的源代码。以下拒绝场景适用。
全新项目：仅有PRD、可能包含
```
.gitignore
```
、
```
.claude/
```
、README，没有可运行的代码。两种拒绝场景的条件都不适用，无需拒绝，直接进入0c阶段。

用一句话向用户说明你的判断及原因，方便用户纠正：例如*“docs/和.claude/之外没有源代码，因此我将其视为全新项目。”* 错误判断的修复成本很低，而询问会浪费一个你已经有答案的问题。

在以下场景中拒绝，并说明原因：

无法观察软件运行状态：无法启动、无法调用、也无法导入。组件5没有基础可依托。

这针对的是无法观察的软件，而非尚未存在的软件。 全新项目按定义会触发此条件及下一个条件，拒绝全新项目会违背前提。详见0c阶段。
库不属于此场景。框架提供三种驱动：
```
http
```
（服务器）、
```
cli
```
（命令行）、
```
library
```
（无进程；E2E测试直接导入调用），
```
APP_STARTED driver=library
```
表示导入成功，这与服务器响应的验证逻辑相同。曾有版本将“库”作为此场景的开头，导致针对纯Python库的测试运行差点错误拒绝了框架支持的仓库。在判断是否可观察前，请先阅读
```
templates/harness/appproc.py
```
。
仓库没有CI且没有任何测试命令：先构建测试套件。基于零检查构建的Dark Factory只是一个合并看似合理代码的机器。
用户希望Agent处理认证、支付或任何影响范围超出其承受能力的内容：这些内容应放入受保护列表，而非纳入工厂。

在此阶段拒绝的成本远低于两个月后再拒绝。如果存在以上任何一种情况，可提议构建简化版本：现在构建指导层和框架，在实现自主运行前暂停。

0c. Greenfield: the walking skeleton, and it is SMALL

0c. 全新项目：最简可运行骨架，必须极小

This is the common case, not the exception. Most people want a dark factory at the start of a project, which is also the best time to build one - the guidance layer is cheapest to write when nothing contradicts it yet, and the sim/presentation split below is free before there is code and expensive afterwards.

Greenfield is not a refusal. But it does mean component 5 has nothing to stand on today, and no ordering of the phases fixes that. Something has to exist first.

这是常见场景，而非例外。 大多数人在项目初期就希望构建Dark Factory，这也是最佳时机——指导层在没有代码冲突时编写成本最低，且以下提到的模拟/展示拆分在没有代码时是免费的，后续再修改成本很高。

全新项目无需拒绝，但意味着组件5目前没有可依托的基础，调整阶段顺序也无法解决此问题，必须先构建一些可运行的内容。

The skeleton is the thinnest vertical slice, NOT the MVP

骨架是最薄的垂直切片，而非MVP

This is where a greenfield build goes wrong, and it goes wrong in the same direction every time: the agent proposes building the core of the product so the harness has something to test, the user agrees because it sounds necessary, and now the interesting, risky work has been done by hand and the factory is left with the leftovers. That inverts the entire point.

Build the smallest slice that produces one observable, assertable behaviour end to end. For a game: one enemy, one hit, one damage number, persisted across a restart. For a service: one endpoint that writes one row and reads it back. For a CLI: one command with one flag that changes one line of output.

The test is not "is this useful" - it is "can an E2E assert something a user would notice?" If yes, stop building and start building the factory. Everything else in the MVP is issues, and the factory building them is the thing you are here for.

State the size explicitly before starting, and say what you are deliberately leaving out: "I am building one horn level, one wave, one damage number and a save file. Not the reward curve, not the elemental interactions, not wave composition - those are issue one, two and three."

全新项目构建最容易出错的地方在于：Agent提议构建产品核心功能，以便框架有测试对象，用户因看似必要而同意，结果有趣且有风险的工作已手动完成，工厂只剩下边角任务。这完全违背了构建工厂的初衷。

构建能产生一个可观察、可验证的端到端行为的最小切片。 例如游戏：一个敌人、一次攻击、一个伤害数值，重启后可持久化。例如服务：一个写入一行数据并读取的接口。例如CLI：一个带一个参数、可修改一行输出的命令。

测试标准不是“是否有用”，而是**“E2E测试能否验证用户会注意到的内容？”** 如果答案是肯定的，停止构建骨架，开始构建工厂。MVP的其余内容都作为Issue，由工厂实现——这才是你在此的目的。

在开始构建前明确说明骨架的大小，以及刻意排除的内容：例如*“我将构建一个关卡、一波敌人、一个伤害数值和存档文件。不包含奖励曲线、元素交互、敌人组合——这些将作为Issue 1、2、3处理。”*

The reachability constraint, decided NOW

可访问性约束，现在确定

The harness reaches software exactly three ways -

http

(a server),

cli

(a command),

library

(imported and called). Read

templates/harness/appproc.py

. A rendered window, a game loop, a canvas, a native UI is none of them.

So on greenfield this stops being an architecture preference and becomes a hard requirement: the logic must live behind a headless, scriptable surface that an E2E can drive. Simulation separate from rendering. Domain separate from view. If the rules only exist inside engine nodes and a render loop, there is nothing to assert and the factory cannot be built at level 3 - not because the skill is limited, but because nothing can check the work.

Say this before any code is written. It is nearly free now and it is a rewrite later.

框架仅通过三种方式访问软件——

http

（服务器）、

cli

（命令行）、

library

（导入调用）。请阅读

templates/harness/appproc.py

。渲染窗口、游戏循环、画布、原生UI都不属于这三种方式。

因此，对于全新项目，这不再是架构偏好，而是硬性要求：逻辑必须在无界面、可脚本化的层之后，以便E2E测试驱动。 模拟与渲染分离，领域与视图分离。如果规则仅存在于引擎节点和渲染循环中，无法进行验证，工厂无法达到3级自主化——这不是技能的限制，而是没有办法检查工作成果。

在编写任何代码前说明这一点。现在处理几乎没有成本，后续再修改则需要重写。

The factory's scope is strictly smaller than the MVP

工厂的范围严格小于MVP

Some MVP items are not machine-validatable and never will be: "combat feels good", "the escalation is visibly and audibly different", "a first-time player understands it". Those are feel, presentation and readability.

Name them out loud, write them into

MISSION.md

and

FACTORY_RULES.md

as permanently human, and be clear that the factory owns the simulation layer rather than the product. That is still a large and valuable surface - usually most of the actual risk - but pretending it is the whole MVP is how you end up with a green factory shipping a game nobody wants to play.

有些MVP内容无法通过机器验证，且永远无法验证：例如*“战斗体验良好”、“升级效果在视觉和听觉上明显不同”、“新用户能理解”*。这些属于体验、展示和可读性范畴。

请明确指出这些内容，将其写入

MISSION.md

和

FACTORY_RULES.md

，标记为永久人工处理，并明确工厂负责模拟层而非整个产品。这仍然是一个庞大且有价值的范围——通常包含大部分实际风险，但假装工厂覆盖整个MVP会导致构建出的工厂交付无人愿意玩的游戏。

Then, in this order - and the fork comes AFTER the interview

接下来的顺序——分支选择在访谈之后

Say the two things above (the skeleton is a slice; the logic has to be reachable) now, in Phase 0, because both change what the user tells you in the interview. Then:

Phase 1, the interview. It is unchanged on greenfield.
Phase 2, the guidance layer. Markdown, needs no code, and every later component reads it - including the skeleton, which should be built inside the mission's scope rather than alongside it. This is also the natural stopping point a greenfield user might want, and putting the skeleton first removes it.
The skeleton, named and sized against the journey from R1.1.
Phase 3 onwards as written.

The fork below is presented after Phase 1, not here. Its recommended option requires you to name the slice and name what you are leaving out, and you cannot do either honestly before R1.1 has told you what the journey is. Asking in Phase 0 gets a decision made on information nobody has yet. Flag in Phase 0 that the choice is coming; put it after the interview.

在第0阶段就说明以上两点（骨架是切片；逻辑必须可访问），因为这两点会影响用户在访谈中的回答。然后按以下顺序执行：

第1阶段，访谈：全新项目的访谈流程不变。
第2阶段，指导层：基于Markdown，无需代码，所有后续组件都依赖它——包括骨架，骨架应在任务范围内构建，而非单独构建。这也是全新项目用户可能希望暂停的自然节点，先构建骨架会移除这个选项。
构建骨架：基于R1.1的用户旅程确定名称和大小。
按文档说明执行第3阶段及后续步骤。

分支选择在第1阶段之后呈现，而非在此。 推荐选项需要你明确切片内容和排除内容，而在获取R1.1的用户旅程前，你无法如实做到这一点。在第0阶段询问会导致用户基于不完整信息做决策。在第0阶段标记后续会有选择，将其放在访谈之后。

The fork, once the interview has given you a journey

访谈获取用户旅程后的分支选择

Three known answers, so this is a question-tool call like every other, and recommend the first:

Build the thin skeleton now, then the factory on it (recommended) - name the slice and name what you are leaving out, so "recommended" cannot be read as "I will build your MVP".
Guidance layer and scaffolds only -
```
MISSION.md
```
,
```
FACTORY_RULES.md
```
,
```
CLAUDE.md
```
, plus
```
runner/
```
and
```
harness/
```
copied in with the contract documented and the assertions left empty. The user builds the skeleton; you resume at component 5. A real option, not a consolation: the
```
MISSION.md
```
/
```
FACTORY_RULES.md
```
pair earns its keep in interactive work whether or not a cron is ever turned on.
Stop - architecture first - when the PRD defers the thing 0c's reachability constraint depends on, and the user would rather settle it before code exists.

有三个已知选项，因此像其他问题一样使用提问工具，并推荐第一个选项：

现在构建极简骨架，然后在其上构建工厂（推荐）——明确切片内容和排除内容，避免“推荐”被误解为“我将构建你的MVP”。
仅构建指导层和脚手架——
```
MISSION.md
```
、
```
FACTORY_RULES.md
```
、
```
CLAUDE.md
```
，以及复制
```
runner/
```
和
```
harness/
```
，记录契约并留空断言。用户构建骨架后，你从组件5继续。这是一个真实选项，而非安慰：即使不开启定时任务，
```
MISSION.md
```
/
```
FACTORY_RULES.md
```
在交互式工作中也有价值。
停止——先确定架构——当PRD推迟了0c阶段可访问性约束依赖的内容，且用户希望在编写代码前先确定架构时选择此选项。

Phase 1. Interview

第1阶段：访谈

Read

references/interview.md

and work through it. It is the whole skill in question form: what each question is actually for, what a good answer sounds like, and which vague answers to push back on.

It is three rounds, not a questionnaire. Round 1 is the three questions below, asked one at a time before anything else. Round 2 is six that only the user can answer. Round 3 is a single message listing every remaining setting with its default already filled in, asking what to change.

Propose defaults; do not interrogate. The protected paths, the poll interval, the concurrency, the stop button, the PR cap, the model routing and the holdout location all have working defaults that ship in

config.sh

and the templates. Asking for them open-ended makes the user do the skill's homework and buries the questions that matter. "I am going to protect these five paths, plus your CI config - anything else?" is a better question than "which files must the agent never touch?", and it cannot be answered wrong by someone who has never built one of these.

The PRD has already answered part of this. Never re-ask what it answers. Read the scope and the non-goals back as a proposal - "so triage accepts anything in these four areas and rejects these six, correct?" - and spend the time on what it left open. Re-asking something the user already wrote down is how an interview loses the room in the first two minutes.

Reflect each answer back as a concrete artifact ("so the merge gate is: X") before moving on.

EVERY QUESTION GOES THROUGH THE QUESTION TOOL.

AskUserQuestion

in Claude Code, or the equivalent elsewhere. Every one, including the open-ended ones. No exceptions, and no prose fallback.

This used to be split - pickers for known options, prose for the open questions - on the argument that offering options for "describe the most valuable thing a user does" replaces the answer with a menu of your guesses. That argument is answered by the tool itself: it always carries an "Other" free-text escape. The user who wants to answer in their own words still can, in one keystroke. The user who would have skimmed a paragraph and said "you pick" now corrects the closest of three concrete candidates, which is the answer you needed and would not have got.

What survives from the old argument is a constraint on the OPTIONS, not on the tool: for an open question, derive them from their PRD and their repo and cite the source. A draft from their own material is their answer played back and they will overwrite it happily; an invented one anchors them onto your guess.

Every Round 2 question asks about something that has ALREADY HAPPENED to them - a bug that escaped, a thing they would drop everything to fix, what they do after a change to convince themselves. Never ask a user to design an artifact. They answer from memory about their own software; turning that into scenarios, defect sets and rules is your job, done silently.

interview.md

carries the exact words and what each becomes.

Two rules apply to every question:

Always carry a recommendation. Exactly one option marked
```
(Recommended)
```
, first, with the reason in its one-line description. Never a blank page. Where a recommendation would be dishonest - a genuine coin-flip - say that in the question rather than inventing confidence.
Offer to explain the hard parts before they answer. Holdout, mutation set, ratchet, independence line, structural gate are obvious only to someone who has built one of these, and a user who does not want to admit they have not heard of a holdout will guess. Add an "Explain this first" option.
```
interview.md
```
has a one-breath explanation for each term - use those words, and do not lecture.

Round 1 - three questions decide the project, so do not let any of them slide:

"Walk me through the single most useful thing someone does with this, from the first click to the thing they end up looking at." That sequence becomes the main path checked on every change. If they cannot describe it, nothing can check it.
"How do you build a feature with AI today?" One open question, not a questionnaire - take what they give you and read
```
CLAUDE.md
```
,
```
AGENTS.md
```
,
```
.claude/
```
and
```
.cursor/
```
for the rest. The workflows should be recognisably their process with the approvals taken out.
"Are you willing to let code reach your users without anyone reading it first?" Then the dial below. Recommend level 3. People often say 5; 5 means the factory writes its own work from the mission, which is a different decision.

阅读

references/interview.md

并完成访谈。该文档以问题形式呈现了整个技能：每个问题的实际目的、好答案的特征，以及如何追问模糊的回答。

访谈分为三轮，而非问卷。 第1轮是以下三个问题，逐个询问，不添加其他内容。第2轮是六个只有用户能回答的问题。第3轮是一条消息，列出所有剩余设置及默认值，询问用户是否需要修改。

提议默认值，而非逐一询问。 受保护路径、轮询间隔、并发数、停止按钮、PR上限、模型路由和保留场景位置都有可运行的默认值，包含在

config.sh

和模板中。开放式询问会让用户完成技能的工作，且会掩盖关键问题。例如“我将保护这五个路径以及你的CI配置——还有其他需要保护的吗？”比“哪些文件Agent绝对不能修改？”更好，且不会让从未构建过此类工厂的用户给出错误答案。

PRD已回答部分问题，不要重复询问。将范围和非目标作为提议反馈给用户——例如*“因此任务分配环节接受这四个领域的内容，拒绝这六个，对吗？”*——并将时间花在PRD未覆盖的内容上。重复询问用户已写下的内容会让访谈在最初两分钟就失去用户的信任。

在进入下一个问题前，将每个答案反馈为具体的工件（例如“因此合并门禁是：X”）。

所有问题都必须通过提问工具提出，例如Claude Code中的

AskUserQuestion

，或其他平台的等效工具。所有问题都必须如此，包括开放式问题。无例外，无 prose 替代方案。

曾有版本将问题分为两类：已知选项使用选择器，开放式问题使用 prose，理由是为“描述用户最有价值的操作”提供选项会用你的猜测替代用户的答案。但工具本身解决了这个问题：工具始终提供“其他”自由文本选项。希望用自己的话回答的用户只需一键选择，而原本可能会跳过段落并说“你选吧”的用户现在会修正最接近的三个具体选项，这正是你需要的答案，且原本无法获取。

旧逻辑的合理之处在于对选项的约束，而非对工具的约束：对于开放式问题，从用户的PRD和仓库中推导选项，并注明来源。基于用户自身材料的草稿是他们答案的回放，他们会乐于修改；而凭空发明的选项会让用户被你的猜测限制。

第2轮的每个问题都询问用户已经经历过的事情——例如逃脱的bug、他们会优先修复的问题、修改后如何确认没问题。永远不要让用户设计工件。他们基于自身软件的记忆回答，将其转化为场景、缺陷集和规则是你的工作，需静默完成。

interview.md

包含每个问题的具体措辞及转化结果。

每个问题都需遵守两个规则：

始终提供推荐选项。恰好有一个选项标记为
```
(推荐)
```
，放在首位，用一行文字说明理由。永远不要提供空白页面。如果无法诚实推荐——例如真正的两难选择——在问题中说明这一点，而非假装自信。
在用户回答前提供解释难点的选项。保留场景、突变集、棘轮机制、独立线、结构门禁等术语仅对构建过此类工厂的人来说是显而易见的，不想承认从未听说过这些术语的用户会猜测。添加“先解释此内容”选项。
```
interview.md
```
包含每个术语的简短解释——使用这些文字，不要长篇大论。

第1轮——三个决定项目走向的问题，不要轻易跳过：

“请带我走一遍用户使用该产品最有价值的操作流程，从第一次点击到最终看到的结果。” 该序列会成为每次变更都要检查的主路径。如果用户无法描述，就无法验证。
“你现在如何用AI构建功能？” 一个开放式问题，而非问卷——记录用户的回答，并从
```
CLAUDE.md
```
、
```
AGENTS.md
```
、
```
.claude/
```
和
```
.cursor/
```
中补充剩余信息。工作流应是用户现有流程移除审批环节后的版本。
“你是否允许代码在无人审核的情况下交付给用户？” 然后展示以下自主化等级表盘。推荐3级。人们常说要5级；5级意味着工厂从任务中自行生成工作，这是一个不同的决策。

The autonomy dial

自主化等级表盘

Level	What is automatic	What you still do
0	workflows exist	run them by hand
1	labelled issue → PR opens	review and merge everything
2	+ validator runs and posts a verdict	merge everything
3	+ validator auto-merges when every structural gate is green	write the issues, cut releases
4	+ it triages its own issues, and a scheduled test files its own bugs	write the important issues
5	+ it writes its own issues from the mission	nothing

Level 3 is the default. Build for it.

It is the first level where code merges without a human reading it, and it is the whole point: a factory that stops at 2 is a code generator with a queue, and the person is still the bottleneck they were trying to remove. Everything difficult in this build exists to earn level 3, so building for anything less means doing the hard part and not using it.

Levels 0 to 2 are stages on the way, not destinations. Ship them in order, prove a lap at each, and keep going to 3. The dial is enforced in

orchestrator.sh

and

factory_doctor

blocks 3 outright until a holdout exists, so "build for 3" cannot turn into "switch on 3" before the evidence is there.

Stop below 3 only when the user has a specific reason - an unmovable review requirement, a blast radius they cannot absorb, a harness they do not yet trust. That is a legitimate choice and it should be their choice, made out loud, rather than the default that happens because nobody raised the dial.

Above 3 is a different question, not a further step: 4 hands over what gets built and 5 hands over what to build. Neither is implied by wanting the merge automated.

等级	自动化内容	仍需人工处理的内容
0	工作流已存在	手动运行工作流
1	标记的Issue → 自动创建PR	审核并合并所有内容
2	+ 验证器运行并发布结果	合并所有内容
3	+ 验证器在所有结构门禁通过时自动合并	编写Issue、发布版本
4	+ 自动分类Issue，定时测试自动提交bug	编写重要Issue
5	+ 从任务中自行生成Issue	无需人工处理

默认目标为3级，按此构建。

这是第一个无需人工审核即可合并代码的等级，也是核心目标：停留在2级的工厂只是带队列的代码生成器，人工仍然是瓶颈，而构建工厂正是为了消除这个瓶颈。本次构建的所有难点都是为了达到3级，因此构建低于3级的工厂意味着做了最难的工作却没有利用它。

0到2级是过渡阶段，而非目标。按顺序交付，在每个等级验证完整循环，然后继续推进到3级。

orchestrator.sh

和

factory_doctor

会在没有保留场景时阻止3级，因此“按3级构建”不会在证据不足时“开启3级”。

仅当用户有具体理由时才停留在3级以下——例如不可动摇的审核要求、无法承受的影响范围、尚未信任的框架。这是合理的选择，应由用户明确做出，而非因无人调整表盘而默认停留在低等级。

3级以上是不同的问题，而非进一步的步骤：4级移交构建内容的决策权，5级移交构建目标的决策权。两者都不是仅希望自动化合并的用户的隐含需求。

Phase 2. The guidance layer (component 4)

第2阶段：指导层（组件4）

Read

references/guidance-layer.md

. Write three files from the templates:

```
MISSION.md
```
- what is being built, and what is deliberately out of scope forever
```
FACTORY_RULES.md
```
- how the agent behaves unsupervised, and the protected list
```
CLAUDE.md
```
/
```
AGENTS.md
```
- the conventions any project has, factory or not (template in
```
templates/CLAUDE.md
```
; if one already exists, split it rather than replacing it)

MISSION.md
is a compression of the PRD, not a new document. Draft it from the PRD directly and show the user the diff in meaning, not just the file. The PRD's non-goals become the out-of-scope list almost verbatim, and anything the interview added on top gets marked as such so it is obvious later which constraints came from the product and which came from making it unattended.

If a conventions file already exists, keep it and pull the factory-only rules out of it rather than writing a new one over the top. That split is usually the single most useful edit this phase makes to an existing repo.

The placement test, for every rule:

Would you write this even with a human doing the work? → conventions file. Does it only exist because nobody is watching? →
FACTORY_RULES.md
. Is it about what the product is and is not? →
MISSION.md
.

The one property that matters: the agent cannot amend the rules it is judged by. All three files go on the protected list, and a PR that touches them is auto-rejected before anything else is evaluated. Enforce this in code, not in a prompt.

Run

scripts/factory_doctor.py --repo <path>

now. It will fail loudly, which is correct - it is a checklist, and this is the start of working through it.

阅读

references/guidance-layer.md

。从模板中编写三个文件：

```
MISSION.md
```
——构建目标，以及永久排除的范围
```
FACTORY_RULES.md
```
——Agent无人值守时的行为规则，以及受保护列表
```
CLAUDE.md
```
/
```
AGENTS.md
```
——项目的通用约定，无论是否使用工厂（模板在
```
templates/CLAUDE.md
```
；如果已存在此类文件，拆分而非替换）

MISSION.md
是PRD的压缩版，而非新文档。直接从PRD草稿，并向用户展示内容差异，而非仅展示文件。PRD的非目标几乎可以直接转化为排除范围列表，访谈添加的内容需标记，以便后续明确哪些约束来自产品，哪些来自无人值守的需求。

如果已存在约定文件，保留它，并从中提取工厂专属规则，而非覆盖。这种拆分通常是本阶段对现有仓库最有用的编辑。

每个规则的放置测试：

即使有人工处理，你也会编写这条规则吗？→ 放入约定文件。这条规则仅因无人值守而存在吗？→ 放入
FACTORY_RULES.md
。这条规则是关于产品是什么或不是什么吗？→ 放入
MISSION.md
。

最重要的特性：Agent不能修改用于评判自身的规则。 三个文件都放入受保护列表，任何修改这些文件的PR都会被自动拒绝，无需其他评估。用代码强制执行，而非仅靠提示词。

现在运行

scripts/factory_doctor.py --repo <path>

。它会报错，这是正常的——它是一个检查清单，这是开始逐步完成检查的起点。

Phase 3. The validation harness (component 5)

第3阶段：验证框架（组件5）

Read

references/validation-harness.md

in full before writing anything. It is the longest reference because this is where factories actually fail. Its opening section is the contract the runner expects - the entrypoint, the markers, the append rule, and the

--quick

subset. Read that even if you skim the rest, because getting the append rule wrong breaks every marker assertion for a reason that looks like your code.

Start from the scaffold, then delete its assertions.

bash

cp -r templates/harness <repo>/harness

templates/harness/

is the plumbing, and only the plumbing. It is not Python-only and not web-only: every command lives in

harness.config.json

, and the driver is

http

cli

library

. Proven on a Python HTTP service, a Node CLI (five config values changed, nothing else) and a Python library.

What it gives you: the step ladder, the markers with counts, the step-namer, the

--quick

subset, and an app-process manager that binds a dynamic port, waits for health and tears down on every path. It runs out of the box.

That split is not a hedge, it is the finding. Two people built this harness from scratch without a scaffold, independently, on different products, and wrote the same file - down to both inventing a "zero tests discovered is not a pass" guard. The plumbing is determined by the marker contract, not by the app.

Every assertion in
e2e.py
is a worked example and all of it should be deleted. The same goes for

.factory/holdout/run.py

and

harness/mutations/defects.json

. Each carries a marker line you delete when the content becomes yours, and

factory_doctor

blocks at level 2+ until you do - because a gate that is green about the template's sample product is worse than no gate at all.

The interview produces all three: R1.1 the journey, R2.5a the composed scenarios the builder cannot read, R2.5b the defects that must be caught. What a user would notice is the part nobody can write for you, it is the answer to R1.1, and it is where the real work sits. The scaffold buys you the plumbing; it does not buy you the assertions.

The short version, which is not a substitute for reading it:

Climb the ladder: static → unit → integration → E2E as the real user → visual judging → holdout scenarios → deterministic gate.
Draw the independence line after integration. Everything below it is inside the agent's optimization loop, so given time it will satisfy whatever you measured rather than the thing you meant. More tests below the line is not the fix.
At least two gates must be code the model cannot talk past. The merge itself, and a positive assertion that the app actually started. Everywhere else a "gate" is a prompt instruction, which is a suggestion with good manners.
Empty is not pass. Assert how many checks ran, not just how many failed. A skipped check returns nothing, and nothing is not a failure.
The validator never learns how the code was written. Only what was asked and what the code does now.

Deliverable: a

validate

entrypoint that a workflow can call, that emits explicit markers, and a merge gate in bash that greps for them.

在编写任何内容前，请完整阅读

references/validation-harness.md

。这是最长的参考文档，因为这是工厂实际失败的常见环节。其开头部分是执行器期望的契约——入口点、标记、追加规则，以及

--quick

子集。即使你略读其余部分，也请阅读这部分，因为追加规则错误会导致标记断言失败，且原因看起来像是你的代码问题。

从脚手架开始，然后删除其中的断言。

bash

cp -r templates/harness <repo>/harness

templates/harness/

是基础架构，且仅包含基础架构。它不仅限于Python或Web项目：所有命令都在

harness.config.json

中，驱动可以是

http

、

cli

或

library

。已在Python HTTP服务、Node CLI（仅修改5个配置值，其余不变）和Python库中验证可行。

它提供的内容：步骤阶梯、带计数的标记、步骤命名器、

--quick

子集，以及绑定动态端口、等待健康检查、每次路径结束后销毁的应用进程管理器。可直接运行。

这种拆分不是权宜之计，而是经验总结。两个人独立从头构建此框架，针对不同产品，最终写出了相同的文件——甚至都发明了“未发现测试用例不算通过”的防护逻辑。基础架构由标记契约决定，而非应用本身。

e2e.py
中的所有断言都是示例，应全部删除。

.factory/holdout/run.py

和

harness/mutations/defects.json

也是如此。每个文件都有标记行，当内容替换为你自己的内容时删除该标记行，且

factory_doctor

在2级及以上会阻止，因为针对模板示例产品的门禁为绿色比没有门禁更糟糕。

访谈会生成所有三个必要内容：R1.1用户旅程、R2.5a构建者无法读取的组合场景、R2.5b必须捕获的缺陷。用户会注意到的内容是无人能替你编写的，这是R1.1的答案，也是核心工作所在。脚手架提供基础架构，但不提供断言。

简短版本（不能替代完整阅读）：

逐步验证：静态检查 → 单元测试 → 集成测试 → 模拟真实用户的E2E测试 → 视觉判断 → 保留场景 → 确定性门禁。
在集成测试后划分独立线。独立线以下的所有内容都在Agent的优化循环内，因此假以时日，Agent会满足你测量的指标，而非你实际期望的结果。增加独立线以下的测试无法解决此问题。
至少两个门禁必须是模型无法绕过的代码。合并操作本身，以及应用实际启动的正向断言。其他地方的“门禁”是提示词指令，只是有礼貌的建议。
空结果不算通过。断言运行的检查数量，而非仅失败数量。跳过的检查返回空结果，空结果不是失败。
验证器永远不会了解代码的编写方式，只了解需求和代码当前的行为。

交付物：工作流可调用的

validate

入口点，能输出明确标记，以及基于bash的合并门禁，通过grep检查标记。

Phase 4. The workflow-driven repo (component 1)

第4阶段：工作流驱动仓库（组件1）

Read

references/automation.md

for the headless contract of each agent and what is in the runner.

Copy the runner; do not write one.

templates/runner/factory/

is a working execution layer - dispatcher, runner, structural gate, protected-path guard, merge, deploy, state machine, seven node prompts. Its

README.md

is the install order.

bash

cp -r templates/runner/factory <repo>/factory
mkdir -p <repo>/.factory/{locks,holdout,runs}

Then three edits, and the third is the real work of this phase:

factory/config.sh
- the agent, the models, and
```
FACTORY_VALIDATE_CMD
```
pointing at the harness from Phase 3. Every project-specific value lives here; if you are editing another script to change a path, that is a bug in
```
config.sh
```
.
factory/guard.py
- the protected list. Seed it, do not just accept what the interview returned.
factory/prompts/*.md
- rewrite these as the user's own process. This is where Phase 1's R1.2 answer lands. If they plan with one skill and implement with another, those are two nodes. If a rules file or an MCP server is loaded at a particular step today, load it at that step here.

The interesting property of a factory is that it runs unattended, not that it works differently. A user who recognises their own workflow in these prompts will trust it and maintain it; one who has to learn a new pipeline will not. The prompts are the personalisation. The plumbing is not - and that is exactly why the plumbing ships as a copy and the prompts ship as a skeleton with the decisions marked.

If the user has a workflow engine they already run (Archon, a YAML DAG, GitHub Actions, an Agent SDK program), the runner is still the reference for what the nodes must do - the fresh-context boundary, the tool allowlists, the holdout deny, the commit step, the gate. Port those properties; do not port the bash.

阅读

references/automation.md

了解每个Agent的无头契约及执行器的内容。

复制执行器，不要从头编写。

templates/runner/factory/

是可运行的执行层——调度器、执行器、结构门禁、受保护路径守卫、合并、部署、状态机、七个节点提示词。其

README.md

包含安装顺序。

bash

cp -r templates/runner/factory <repo>/factory
mkdir -p <repo>/.factory/{locks,holdout,runs}

然后进行三个编辑，第三个是本阶段的核心工作：

factory/config.sh
——Agent、模型，以及指向第3阶段框架的
```
FACTORY_VALIDATE_CMD
```
。所有项目特定值都在此文件中；如果你需要编辑其他脚本修改路径，说明
```
config.sh
```
存在bug。
factory/guard.py
——受保护列表。初始化列表，不要仅接受访谈返回的内容。
factory/prompts/*.md
——将这些重写为用户自己的流程。这是第1阶段R1.2答案的落地之处。如果用户用一个技能规划、另一个技能实现，就设置两个节点。如果现在在特定步骤加载规则文件或MCP服务器，就在此处的对应步骤加载。

工厂的核心特性是无人值守运行，而非工作方式不同。用户在提示词中识别出自己的流程，才会信任并维护它；如果需要学习新的流水线，用户不会接受。提示词是个性化部分，基础架构不是——这正是基础架构作为副本交付，提示词作为带决策标记的骨架交付的原因。

如果用户已有运行的工作流引擎（Archon、YAML DAG、GitHub Actions、Agent SDK程序），执行器仍然是节点必须完成的工作的参考——新鲜上下文边界、工具允许列表、保留场景拒绝、提交步骤、门禁。移植这些特性，而非移植bash代码。

Phase 5. Deployment (component 3)

第5阶段：部署机制（组件3）

Read

references/deployment.md

. It is short and it contains the single trap that silently kills more factories than anything else: GitHub does not trigger workflows on commits made with the default
GITHUB_TOKEN
. The agent commits, the deploy never fires, nothing errors, and nothing tells you.

If the loop does not end at real users, the user has built a PR generator.

阅读

references/deployment.md

。文档很短，但包含一个悄悄毁掉更多工厂的陷阱：GitHub不会对使用默认
GITHUB_TOKEN
提交的代码触发工作流。Agent提交代码后，部署永远不会触发，没有错误提示，也不会告知你问题所在。

如果循环未结束于真实用户，用户只是构建了一个PR生成器。

Phase 6. The trigger (component 2)

第6阶段：触发模块（组件2）

Only now. Read

references/setup.md

in full and the automation reference's dispatcher section.

references/setup.md

is the unglamorous half nobody writes down: prerequisites, cron and systemd and Task Scheduler, the

.gitattributes

line-ending pin,

core.longpaths

PYTHONIOENCODING

, the

git check-ignore

pre-flight, credential expiry, and how to test the stop button on purpose. Every item on it broke a real factory. You can have five perfect components and a machine that has never completed a lap because line endings were rewritten on checkout.

The dial itself is already enforced in the runner:

orchestrator.sh

reads

FACTORY_AUTONOMY

and refuses each action below its level, so raising it is a deliberate act rather than a note in a file.

Say this out loud, because almost everyone arrives with the wrong model: nothing pushes. Filing an issue does not trigger a run. There is no webhook and there is not meant to be one - a scheduler wakes on a timer, reads the state, and dispatches at most one thing. An issue filed at 09:01 waits for the next tick. A push trigger that breaks fails silently and looks exactly like a factory with nothing to do; a poll that breaks is a poll you can see not running.

Install it AFTER the first lap, not here.

install-trigger.sh

refuses below dial 1, and the dial does not leave 0 until Phase 7 has proven a lap by hand - so Phase 6 as numbered cannot be executed in order. Build the trigger's configuration now; run the installer at Phase 7 step 3, when the dial moves. The code is right and this ordering was wrong.

Arm it with the installer rather than by hand, and note that it refuses while the dial is at 0 - a scheduler at level 0 wakes up forever and correctly does nothing, which is how people convince themselves a factory is running when it has never completed a lap:

bash

bash factory/install-trigger.sh --status     # what is armed right now
bash factory/install-trigger.sh --install    # cron, systemd timer, or Task Scheduler
bash factory/install-trigger.sh --remove

Then run

factory_doctor

once more. It now checks whether a scheduler is actually armed, because a fully built factory with nothing scheduled audits identically to a running one.

The dispatcher must be the dumbest, most deterministic thing in the system. Not an LLM deciding what to run - that hallucinates dispatches for work that does not exist. Bash, a fixed priority order, and shared state that lives in something boring (GitHub labels are enough; no database, no message bus).

Fixed priority, and this order is load-bearing:

fix a PR that needs fixing
validate a PR waiting for review
implement the highest-priority accepted issue
triage untriaged issues

Finish in-flight work before starting new work. Backwards, and the factory triages forever while its own PRs rot.

仅在此阶段构建。完整阅读

references/setup.md

及自动化参考文档的调度器部分。

references/setup.md

记录了无人提及的繁琐细节：前置条件、cron和systemd及任务计划程序、

.gitattributes

行尾固定、

core.longpaths

、

PYTHONIOENCODING

、

git check-ignore

预检查、凭证过期，以及如何故意测试停止按钮。其中每个条目都曾导致真实工厂故障。你可能有五个完美的组件，但由于 checkout 时行尾被重写，工厂从未完成一次循环。

自主化等级已在执行器中强制执行：

orchestrator.sh

读取

FACTORY_AUTONOMY

，拒绝低于该等级的操作，因此提升等级是明确的操作，而非文件中的注释。

请大声说明这一点，因为几乎所有人都有错误的认知：没有推送触发。 提交Issue不会触发运行。没有webhook，也不应该有——调度器按定时唤醒，读取状态，最多调度一个任务。09:01提交的Issue会等待下一个定时周期。推送触发故障会静默失败，看起来像工厂无事可做；而轮询故障可以看到轮询未运行。

在第一次循环验证通过后再安装，而非在此阶段。

install-trigger.sh

在等级1以下会拒绝安装，且在第7阶段手动验证循环前，等级不会离开0——因此编号的第6阶段无法按顺序执行。现在构建触发模块的配置；在第7阶段步骤3提升等级时运行安装程序。代码是正确的，只是顺序有误。

使用安装程序配置，注意它在等级0时会拒绝安装——等级0的调度器会永远唤醒但什么都不做，这会让人们误以为工厂在运行，而实际上从未完成一次循环：

bash

bash factory/install-trigger.sh --status     # 查看当前已配置的触发
bash factory/install-trigger.sh --install    # 安装cron、systemd定时器或任务计划程序
bash factory/install-trigger.sh --remove

然后再次运行

factory_doctor

。现在它会检查调度器是否已实际配置，因为完全构建但未配置调度器的工厂与运行中的工厂审核结果相同。

调度器必须是系统中最愚蠢、最具确定性的部分。 不能是LLM决定运行什么——这会导致为不存在的工作生成调度。使用bash、固定优先级顺序，以及存储在简单工具中的共享状态（GitHub标签足够；无需数据库或消息总线）。

固定优先级，以下顺序至关重要：

修复需要修改的PR
验证等待审核的PR
实现最高优先级的已接受Issue
分类未分类的Issue

完成进行中的工作后再开始新工作。 如果顺序颠倒，工厂会永远分类Issue，而自己的PR会停滞。

Phase 7. Prove it, then get to level 3

第7阶段：验证并提升到3级

The target is 3 and the job is not finished until the dial is there. These steps are the evidence that earns it, not a ladder to stop partway up.

Run the walking skeleton by hand: one real issue, all the way to a PR you merge yourself. Do not proceed on a factory that has never completed a lap.
```
python scripts/factory_doctor.py --repo <path> --audit
```
until it is clean. It refuses level 3 while there is no holdout, which is the check that decides whether the rest of this was real. 2b. python scripts/_test_runner.py --repo <path>
and python scripts/_audit_runner.py --repo <path>
. The doctor checks that the repo is set up correctly; these check that the machinery underneath it still works. They are free, they take about two minutes, and a factory that fails them will fail silently - parking work nobody is told about, or re-running a workflow that can only die. Re-run both any time you hand-edit anything under
```
factory/
```
, and before re-arming a factory that has been idle: the runner is copied into a repo and never linked, so a fix upstream has not reached yours.
Raise the dial to 1, then 2, watching one full cycle at each - then raise it to 3. Stopping at 2 leaves a person merging every PR, which is the bottleneck the whole build was for. If the user chooses to stop below 3, write down in
```
FACTORY.md
```
what would have to be true to go further, so it is a decision with a way out of it rather than a dial nobody touched again.
Write
```
FACTORY.md
```
from the template - what was built, at which level it currently runs, and what has to be true before the next notch. Link the PRD it was built from, because when the product changes the mission has to change with it, and the factory will keep faithfully building the old scope until someone notices.

目标是3级，等级未达到3级则任务未完成。 以下步骤是达到3级的证据，而非中途停止的阶梯。

手动运行最简可运行骨架：一个真实Issue，全程执行到你手动合并PR。如果工厂从未完成一次循环，不要继续。
运行
```
python scripts/factory_doctor.py --repo <path> --audit
```
直到结果干净。如果没有保留场景，它会阻止3级，这是验证其余工作是否有效的检查。 2b. 运行
python scripts/_test_runner.py --repo <path>
和
python scripts/_audit_runner.py --repo <path>
。
```
factory_doctor
```
检查仓库配置是否正确；这两个脚本检查底层机制是否仍可运行。它们免费，耗时约两分钟，失败的工厂会静默失败——无人告知的情况下暂停工作，或重复运行只会失败的工作流。每次手动编辑
```
factory/
```
下的内容后，以及重新启用闲置的工厂前，都要重新运行这两个脚本：执行器是复制到仓库中的，而非链接，因此上游修复不会自动同步到已构建的工厂。
将等级提升到1，然后到2，观察每个等级的完整循环——然后提升到3级。停留在2级会让人工合并每个PR，这正是构建工厂要消除的瓶颈。如果用户选择停留在3级以下，在
```
FACTORY.md
```
中记录进一步提升需要满足的条件，使其成为有明确退出路径的决策，而非无人再调整的等级。
从模板编写
```
FACTORY.md
```
——构建内容、当前运行等级，以及提升到下一等级需要满足的条件。链接构建所基于的PRD，因为当产品变更时，任务必须随之变更，否则工厂会继续忠实地构建旧范围，直到有人注意到。

Operating facts - NOT a speech to deliver

运行注意事项——不要向用户复述

Do not recite this section. It reads like an opening briefing and it was being delivered as one, which is six dense paragraphs before the user has done anything. These are facts you need in order to build correctly, and each one belongs at the single moment it becomes actionable - the token bullet when the trigger goes on, the

git check-ignore

bullet when the first committing workflow is written, one line each. If the user asks what they should watch out for, then answer from here, shortest first.

The PRD is now a live document, not a kickoff artifact. In normal development a PRD goes stale and a human quietly compensates. Here nobody compensates: the factory builds the scope it was given until the scope is edited. Changing what the product is means editing
```
MISSION.md
```
, in a human commit, on purpose.
Instrument tokens on day one, before the first unattended run. Not as a warning - as a measurement you will want and cannot reconstruct later. One "fix an issue" run is far more agent sessions than it looks like from the outside, and the only way to know what yours does is to have been recording from the first lap.
Put one premium model in the planning slot and a cheaper one everywhere else. Premium in one of the two slots that matter buys most of the quality of premium in both. Premium in zero slots is what actually costs you.
Leash every editing node to its own diff. A node that can edit without a file scope will grow a six-file PR into eleven and introduce a bug on the way through.
Run
git check-ignore -v
on every config file before the first workflow that commits. A
```
git add -A
```
inside a PR-create step publishes whatever was not ignored, and public means public.
The agent is the interchangeable part. The plumbing is not. Credential expiry, cost cliffs, no default session timeout and sandbox egress are the same problems in every agent, and none of them solve it for you.

不要向用户复述本节内容。 这看起来像是开场简报，曾被作为开场内容发送，导致用户在开始任何操作前就收到六个密集段落。这些是你构建时需要了解的事实，每个事实仅在可操作时提及——例如开启触发时的令牌要点，编写第一个提交工作流时的

git check-ignore

要点，每个要点用一行说明。如果用户询问需要注意什么，再从这里选择最短的内容回答。

PRD现在是实时文档，而非启动工件。 在常规开发中，PRD会过时，人工会悄悄调整。但在此处无人调整：工厂会一直构建给定的范围，直到范围被编辑。变更产品意味着手动编辑
```
MISSION.md
```
。
从第一天开始监控令牌使用，在第一次无人值守运行前。 这不是警告，而是你需要且无法事后重建的测量数据。一次“修复Issue”运行的Agent会话数远多于表面看起来的数量，了解你的工厂的行为的唯一方法是从第一次循环开始记录。
在规划环节使用一个高级模型，其他环节使用更便宜的模型。 在两个关键环节之一使用高级模型，即可获得两个环节都使用高级模型的大部分质量提升。两个环节都不使用高级模型才会真正增加成本。
限制每个编辑节点的文件范围。 没有文件范围限制的节点会将六文件PR扩展到十一文件，并在过程中引入bug。
在第一个提交工作流编写前，对每个配置文件运行
git check-ignore -v
。 PR创建步骤中的
```
git add -A
```
会提交所有未被忽略的内容，而公开仓库中的内容是公开可见的。
Agent是可互换的部分，基础架构不是。 凭证过期、成本悬崖、无默认会话超时和沙箱出口是所有Agent都存在的问题，没有Agent能为你解决这些问题。

Resources

资源

```
references/interview.md
```
: the interview, in three rounds - three questions that decide the project, seven only the user can answer, and one message of defaults to confirm. Marks each question
```
[PICKER]
```
or
```
[PROSE]
```
, carries a recommendation for every one of them, and has a one-breath plain-English line for each piece of jargon. Read in Phase 1.
```
references/guidance-layer.md
```
: the three-file split, the placement test, protected files, and how to write an out-of-scope list that does real work. Read in Phase 2.
```
references/validation-harness.md
```
: the ladder, the independence line, holdout design, structural vs prompted gates, and the failure modes. Read in Phase 3 before writing any check.
```
references/automation.md
```
: headless contracts for eight coding agents, orchestrator options and trade-offs, and the dispatcher rules. Read in Phases 4 and 6.
```
references/deployment.md
```
: deploy strategies, the
```
GITHUB_TOKEN
```
trap, and the GitHub scheduling gotchas. Read in Phase 5.
```
references/setup.md
```
: prerequisites, the platform tax, scheduling, and turning it on. Skim in Phase 0b to refuse early; read in full in Phase 6.
```
templates/
```
:
```
MISSION.md
```
,
```
FACTORY_RULES.md
```
,
```
FACTORY.md
```
. Copy and fill; never ship a template's placeholder text. There is no separate
```
orchestrator.sh
```
or
```
validate-gate.sh
```
sketch any more - they were strictly worse duplicates of the real ones in
```
templates/runner/factory/
```
, and shipping a second definition of the pipeline is the exact failure
```
automation.md
```
warns about. The one nobody runs is the one that drifts.
templates/runner/
: the working execution layer, ~3,000 lines, copied into the repo in Phase 4. Read its
```
README.md
```
for the install order and the list of things that are load-bearing. Its comments record real incidents - a factory rebuilt from the design alone rediscovers every one of them, unattended, in production.
templates/harness/
: the validation harness's plumbing, copied in Phase 3. Runs out of the box; every assertion in it is an example to delete. The factory harness is templatable and so is the harness's plumbing - what is not templatable is what "working" means for this product, and that is the whole of component 5.
```
scripts/factory_doctor.py
```
: deterministic audit of a factory repo - protected files, holdout leaks, gate-is-code, empty-is-not-pass, ignored secrets, autonomy level. Run it in Phases 2 and 7. Never read its source into context; only its output.
```
scripts/_test_factory_doctor.py
```
: the doctor's own tests. Builds a healthy factory, breaks one thing at a time, and requires the doctor to notice. Run it after changing the doctor. A gate that has never failed is a gate nobody has tested, and that applies to this skill's gate too.
scripts/_test_runner.py
: the runner's behaviour suite, and the answer to "is this factory actually sound?" It builds a real git repo with the real
```
factory/
```
in it, stubs the agent and the validator so a full lap is free and deterministic, and then drives the actual shell scripts. Every test is named after the defect it locks.
bash
```
python scripts/_test_runner.py                    # the shipped template
python scripts/_test_runner.py --repo <path>      # a factory somebody BUILT
python scripts/_test_runner.py --mutate           # do the tests catch anything?
```
--repo
is the one to remember. The runner is COPIED into a repo and never linked, so a fix to this template reaches nothing already built, and a hand-edited factory drifts with nothing watching. Run it against a factory before trusting it unattended again.
--mutate
is what keeps the suite honest. It restores each historical defect into a throwaway copy and requires the suite to go RED. A test whose defect can be put back while everything stays green is decoration, and it is named as such. This is the same argument the skill makes about mutation-testing your product, turned on itself - and it has already caught one test here passing for the wrong reason.
scripts/_audit_runner.py
: the structural invariants no behaviour test can express - a knob read by a child process that
```
config.sh
```
never exported, a prompt placeholder the renderer does not substitute, a state nothing dispatches on, an unguarded command that dies before the escalate on the next line.
```
--repo
```
works here too. Where
```
factory_doctor
```
audits YOUR repo, this audits the MACHINERY: its findings are bugs in the factory rather than gaps in your setup, and a correctly configured repo running broken machinery passes every check the doctor has.

Why these two exist. The same four failure shapes kept reappearing in this runner, each found by hand and fixed as a one-off. The reason is the one this skill spends five phases making about your code: there was no harness. ~4,200 lines of runner shipped with nothing that ever executed it, so every fix was a sentence in a document rather than a thing that goes red. If you take one idea from this skill into your own repo, take that one - and notice that it applies to the tools you build as much as to the product they build.

```
references/interview.md
```
：三轮访谈——三个决定项目走向的问题、七个只有用户能回答的问题、一条包含默认值的确认消息。标记每个问题为
```
[PICKER]
```
或
```
[PROSE]
```
，为每个问题提供推荐选项，并为每个术语提供简短的通俗解释。第1阶段阅读。
```
references/guidance-layer.md
```
：三文件拆分、放置测试、受保护文件、如何编写有效的排除范围列表。第2阶段阅读。
```
references/validation-harness.md
```
：验证阶梯、独立线、保留场景设计、结构门禁与提示词门禁、失败模式。第3阶段编写任何检查前阅读。
```
references/automation.md
```
：八个编码Agent的无头契约、编排器选项及权衡、调度器规则。第4和第6阶段阅读。
```
references/deployment.md
```
：部署策略、
```
GITHUB_TOKEN
```
陷阱、GitHub调度注意事项。第5阶段阅读。
```
references/setup.md
```
：前置条件、平台限制、调度配置、开启方法。第0b阶段略读以便提前拒绝；第6阶段完整阅读。
```
templates/
```
：
```
MISSION.md
```
、
```
FACTORY_RULES.md
```
、
```
FACTORY.md
```
。复制并填充；绝不交付模板占位文本。不再单独提供
```
orchestrator.sh
```
或
```
validate-gate.sh
```
草图——它们严格劣于
```
templates/runner/factory/
```
中的真实文件，交付管道的第二个定义正是
```
automation.md
```
警告的失败模式。无人运行的管道会逐渐偏离。
templates/runner/
：可运行的执行层，约3000行，第4阶段复制到仓库中。阅读其
```
README.md
```
了解安装顺序及关键内容。其注释记录了真实事件——仅基于设计重构的工厂会在生产中无人值守地重现每个事件。
templates/harness/
：验证框架的基础架构，第3阶段复制。可直接运行；其中所有断言都是示例，应删除。工厂框架可模板化，框架的基础架构也可模板化——不可模板化的是“正常运行”对该产品的定义，这正是组件5的全部内容。
```
scripts/factory_doctor.py
```
：工厂仓库的确定性审核——受保护文件、保留场景泄露、门禁是否为代码、空结果是否算通过、忽略的密钥、自主化等级。第2和第7阶段运行。无需读取其源代码到上下文；仅关注输出。
```
scripts/_test_factory_doctor.py
```
：
```
factory_doctor
```
的测试套件。构建健康的工厂，每次破坏一个点，要求
```
factory_doctor
```
检测到。修改
```
factory_doctor
```
后运行。从未失败的门禁是未测试的门禁，这也适用于本技能的门禁。
scripts/_test_runner.py
：执行器的行为套件，用于回答“这个工厂是否真正可靠？”。它构建包含真实
```
factory/
```
的真实git仓库， stub Agent和验证器，以便完整循环免费且确定，然后驱动实际的shell脚本。每个测试都以它锁定的缺陷命名。
bash
```
python scripts/_test_runner.py                    # 测试交付的模板
python scripts/_test_runner.py --repo <path>      # 测试已构建的工厂
python scripts/_test_runner.py --mutate           # 测试是否能捕获缺陷？
```
--repo
是需要记住的参数。执行器是复制到仓库中的，而非链接，因此模板的修复不会同步到已构建的工厂，手动编辑的工厂会逐渐偏离。在再次信任无人值守的工厂前，运行此脚本测试。
--mutate
是保持套件可靠的关键。它将每个历史缺陷恢复到临时副本中，要求套件标记为失败。如果缺陷恢复后套件仍为绿色，该测试只是装饰，会被标记为装饰。这正是本技能关于产品变异测试的论点，应用于自身——且已发现一个测试因错误原因通过的情况。
scripts/_audit_runner.py
：行为测试无法表达的结构不变量——子进程读取但
```
config.sh
```
从未导出的旋钮、渲染器未替换的提示词占位符、无调度的状态、下一行升级前就失败的无保护命令。
```
--repo
```
参数也适用。
```
factory_doctor
```
审核你的仓库，此脚本审核机制：其发现是工厂的bug，配置正确但机制损坏的仓库会通过
```
factory_doctor
```
的所有检查。

为什么这两个脚本存在。 此执行器反复出现四种失败模式，每次都是手动发现并作为一次性修复。原因正是本技能用五个阶段说明的关于代码的论点：没有框架。约4200行的执行器交付时没有任何执行它的工具，因此每个修复都只是文档中的一句话，而非会标记为失败的测试。如果你从本技能中带走一个想法应用到自己的仓库，就带走这个想法——请注意，它适用于你构建的工具，也适用于工具构建的产品。