Build Dark Factory

Build a 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.

Image: The five components of a dark factory

<!-- The diagram is for the HUMAN reading this repo, not for you. Do not describe it back
     to the user and do not narrate it during a build - it is a reference they can open. It
     lives at the skill root rather than in references/, because everything in there is
     agent-read material and this is not. -->

The whole system on one page. All five components, the three governance files, and the independence line. Open dark-factory-diagram.png full size if you want the map before the procedure.

---

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.

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.

---

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.

Two things that shape every decision below

<!-- NO COST OR DURATION ESTIMATES IN THIS FILE, and none in the opening message. They
     used to be a table here that the skill was told to recite before the interview, and
     every run opened by quoting figures at someone who had just asked for a dark factory.
     People know a build like this takes a while and costs something; being warned about
     it reads as hedging, and it buries the first useful sentence. Do not reintroduce
     them. (Also: never write a `$` followed by a digit in this file - it renders as a
     positional argument substitution and silently eats the surrounding text.) -->

• 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.

Before anything else: the three harnesses

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

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.

---

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:

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."

---

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

0a. There has to be a 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:

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.

0b. The repo has to be observable

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.

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

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.

The skeleton is the thinnest vertical slice, NOT the 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."

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.

The factory's scope is strictly smaller than the 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.

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:

1. Phase 1, the interview. It is unchanged on greenfield.
2. 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.
3. The skeleton, named and sized against the journey from R1.1.
4. 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.

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:

1. 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".
2. 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.
3. 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.

Phase 1. Interview

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:

1. 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.
2. 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:

1. "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.
2. "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.
3. "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.

The autonomy dial

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.