Dark Factory

All agents dispatched via task(agent_type="general-purpose", model="<model-from-config>").

Operating Modes

FULL MODE (default): 6 phases with checkpoints. For new features, projects, complex builds.

EXPRESS MODE: Triggered by "express" keyword OR goal length < <config.factory.express_threshold_words>. Phases: 0 → 3 → 4 → 5 → 6 (Phase 5 runs only when Shadow Score > 0). One checkpoint at delivery. Sealed tests are still generated, but from raw goal text.

Startup Protocol

1. Read configuration: ALWAYS view config.yml first. Treat it as the single source of truth (models, timeouts, thresholds).
2. Determine mode: If user said "express" OR goal length < config.factory.express_threshold_words, set mode=express.
3. Initialize state: Create/update config.isolation.state_file (default .factory/state.json) and SQL tables.
4. Repo signals: Capture a file listing (names only) for stack detection.

Execution Guardrails (Timeouts, Retries, Artifact Limits)

1. Timeouts: If an agent call takes longer than config.factory.agent_timeout_sec, retry up to config.factory.max_retries.
2. Retries: Retries re-dispatch the same role with the same inputs plus a short failure note.
3. Artifact size: If PRD or any artifact exceeds config.safety.max_prd_lines / config.safety.max_artifact_lines, summarize it before passing downstream. Preserve acceptance criteria verbatim where possible.
4. Verbosity: Use config.factory.verbosity to decide how much progress text to print (debug/info/warn/error).

Phase Pipeline — FULL MODE

PHASE 0 — Factory Setup

Automatic. No checkpoint.

1. Generate run ID: run-$(date +%Y%m%d-%H%M%S)
2. Detect git: git rev-parse --git-dir 2>/dev/null
3. If git repo: git worktree add .factory/runs/<run-id> -b <config.isolation.branch_prefix><run-id>
4. If no git: mkdir -p .factory/runs/<run-id> && cd .factory/runs/<run-id> && git init
5. Create sealed dir: mkdir -p <config.isolation.sealed_dir>/<run-id>
6. Initialize SQL:

CREATE TABLE IF NOT EXISTS factory_runs (run_id TEXT PRIMARY KEY, goal TEXT, mode TEXT, started_at TEXT, completed_at TEXT, shadow_score REAL, status TEXT DEFAULT 'running');
CREATE TABLE IF NOT EXISTS phase_results (id INTEGER PRIMARY KEY AUTOINCREMENT, run_id TEXT, phase INTEGER, status TEXT, duration_sec REAL, model_used TEXT, artifacts TEXT);
INSERT INTO factory_runs (run_id, goal, mode, started_at, status) VALUES ('<run-id>', '<goal>', '<mode>', datetime('now'), 'running');

7. Write initial state to <config.isolation.state_file> (default .factory/state.json).
8. Print: 🏭 Factory floor is hot. Run <run-id> initialized.

PHASE 1 — Product Specification

Checkpoint after.

Dispatch Product Manager:

task(agent_type="general-purpose", model="<config.models.product_mgr>", description="Product specification", prompt="
You are the Product Manager for the Dark Factory.
## Mission: Transform the user's goal into a detailed PRD.
## User's Goal: <goal>
## Repo Signals: <file listing only>
## Working Directory: <worktree_path>
## Output: Write PRD.md — overview, user stories, functional/non-functional requirements, acceptance criteria, out-of-scope. Every requirement must be testable.
## Rules: No code, no architecture. WHAT only, never HOW. Max length: <config.safety.max_prd_lines> lines.
")

After: read PRD.md, record in SQL, update state.json (current_phase: 1). Checkpoint: 🏭 Phase 1 complete — Product spec off the line. → ask_user: approve / modify / skip-all / abort

PHASE 2 — Architecture + Seal

Checkpoint after. Two agents in PARALLEL.

2a — QA Sealed (background):

task(agent_type="general-purpose", mode="background", model="<config.models.qa_sealed>", description="Sealed test generation", prompt="
You are the QA Sealed Engineer for the Dark Factory.
## Mission: Write acceptance tests validating PRD requirements. SEALED — implementation team will not see these.
## Input: <PRD.md content>
## Repo Signals: <file listing only>
## Working Directory: <sealed_path>
## Output: Test files covering every acceptance criterion. Match language/framework from PRD or Repo Signals.
## Rules: ONLY test files. No stubs. Validate BEHAVIOR not implementation.
")

2b — Architect (background):

task(agent_type="general-purpose", mode="background", model="<config.models.architect>", description="Architecture design", prompt="
You are the Architect for the Dark Factory.
## Mission: Design system architecture to fulfill the PRD.
## Input: <PRD.md content> + <repo signals — file structure, manifests>
## Working Directory: <worktree_path>
## Output: Write ARCH.md — component diagram, data flow, file structure, key interfaces, tech choices, error handling.
## Rules: No implementation code. Design for testability. Respect repo conventions.
")

After both complete:

1. Hash sealed dir: find <sealed_path> -type f | sort | xargs shasum -a 256 | shasum -a 256
2. Store sealed_hash in state.json. Record both in SQL. Update state (current_phase: 2).
3. Do NOT reveal sealed test contents.

Checkpoint: 🏭 Phase 2 complete — Architecture drafted, tests sealed. 🔒 Hash: sha256:<hash> → ask_user: approve / modify / skip-all / abort

PHASE 3 — Implementation

Checkpoint after.

Dispatch Lead Engineer:

task(agent_type="general-purpose", model="<config.models.lead_eng>", description="Implementation", prompt="
You are the Lead Engineer for the Dark Factory.
## Mission: Implement the system per PRD and Architecture.
## Input: <PRD.md content> + <ARCH.md content>
## Working Directory: <worktree_path>
## Output: All source code + your OWN test suite. Ensure code builds and tests pass.
## Rules: Implement EVERY PRD requirement. Follow ARCH.md file structure. Run tests before finishing. Do NOT look in <config.isolation.sealed_dir>/.
")

After: record in SQL, update state (current_phase: 3). Checkpoint: 🏭 Phase 3 complete — Code off the line. Ready for sealed validation. → ask_user: approve / modify / skip-all / abort

PHASE 4 — Sealed Validation

Checkpoint after.

1. Re-verify sealed hash: recompute the hash from <config.isolation.sealed_dir>/<run-id> and verify it matches sealed_hash in state.json; on mismatch, treat this as sealed tampering, abort the run, and mark SQL status accordingly.
2. Copy sealed tests: cp -r <config.isolation.sealed_dir>/<run-id>/* <worktree_path>/
3. Dispatch QA Validator:

task(agent_type="general-purpose", model="<config.models.qa_validator>", description="Sealed validation", prompt="
You are the QA Validator for the Dark Factory.
## Mission: Run ALL test suites — engineer's open tests AND sealed acceptance tests.
## Working Directory: <worktree_path>
## Output: Write SHADOW-REPORT.md — total tests run/passed/failed. Per failure: test name, expected, actual. Gap score = (failed/total)*100. Last line of response: 'GAP_SCORE: <N>%'
## Rules: Use appropriate test runner. Do NOT modify code or tests. Facts only.
")

4. Parse shadow score. Record in SQL. Update state (current_phase: 4).
5. Delete sealed test copies from the worktree so builders cannot read them later.
6. If shadow score = 0%: skip Phase 5, go to Phase 6.

Checkpoint: 🏭 Phase 4 complete — Sealed envelope opened. Gap score: <X>% → ask_user: approve / modify / skip-all / abort

PHASE 5 — Hardening

No checkpoint. Loops internally.

Each cycle:

1. Extract from SHADOW-REPORT.md: test name + expected + actual ONLY. No test source code.
2. Dispatch Lead Engineer:

task(agent_type="general-purpose", model="<config.models.lead_eng>", description="Hardening cycle N", prompt="
You are the Lead Engineer — Hardening Mode.
## Mission: Fix implementation to pass failing acceptance criteria.
## Failures: <test name, expected, actual — NO test code>
## Working Directory: <worktree_path>
## Rules: Fix SOURCE CODE only. Do NOT modify test files. Re-run own tests for regressions.
")

3. Re-dispatch QA Validator (same as Phase 4).
4. Gap score = 0% → break, proceed to Phase 6.
5. After config.factory.max_hardening_cycles cycles still failing:

🏭 Hardening limit reached. <N> sealed tests still failing.

→ ask_user: continue-hardening / deliver-as-is / abort

continue-hardening: Reset cycle counter to 0 and loop.

PHASE 6 — Delivery

Final checkpoint. ALWAYS shown, even in skip-all mode.

1. Diff summary: cd <worktree_path> && git diff --stat
2. Update SQL: UPDATE factory_runs SET completed_at=datetime('now'), shadow_score=<score>, status='delivered' WHERE run_id='<run-id>'
3. Present delivery report.

→ ask_user: approve / reject

4. On approve (git worktree):

git checkout <original-branch> && git merge <config.isolation.branch_prefix><run-id>
git worktree remove .factory/runs/<run-id> && git branch -D <config.isolation.branch_prefix><run-id>

On approve (temp dir): copy files to original working directory.

On approve (both): Archive artifacts for post-ship evaluation:

mkdir -p <config.outcome_evaluation.archive_dir>/<run-id> && cp PRD.md ARCH.md SHADOW-REPORT.md <config.outcome_evaluation.archive_dir>/<run-id>/

5. On reject: git worktree remove .factory/runs/<run-id> --force && git branch -D <config.isolation.branch_prefix><run-id>
6. Clean up .factory/runs/. Print: 🏭 Factory floor cleared. Run <run-id> complete.

PHASE 7 — Outcome Evaluation (Optional)

Triggered by: dark factory evaluate <run-id> or automatically after N days.

1. Look up run in SQL: SELECT * FROM factory_runs WHERE run_id='<run-id>'
2. Read original PRD.md, SHADOW-REPORT.md from <config.outcome_evaluation.archive_dir>/<run-id>/
3. Dispatch Outcome Evaluator:

task(agent_type="general-purpose", model="<config.models.outcome_evaluator>", description="Outcome evaluation", prompt="
You are the Outcome Evaluator for the Dark Factory.
## Mission: Evaluate whether the delivered build met its PRD success criteria and KPIs.
## Input: <PRD.md content> + <SHADOW-REPORT.md content>
## Working Directory: <current project directory>
## Output: Write OUTCOME-REPORT.md — score each success criterion, measure KPIs, compute outcome score.
## Rules: Run the code. Re-run tests. Evidence-based only. No opinions.
")

4. Record in SQL: UPDATE factory_runs SET outcome_score=<score> WHERE run_id='<run-id>'

Express Mode Pipeline

Express mode is optimized for quick tasks. It still enforces sealed-envelope testing and uses the same hardening loop when there are gaps.

• Phase 0 (setup)
• Start QA Sealed in the background using raw goal text (sealed dir)
• Phase 3 (build from raw goal, no PRD/ARCH)
• Phase 4 (validate by running both suites)
• Phase 5 (hardening loop) when Shadow Score > 0%, otherwise skip directly
• Phase 6 (deliver) with one checkpoint

State Management

Write state.json on EVERY phase transition (path: config.isolation.state_file):

{
  "run_id": "run-20260223-2130",
  "goal": "Build a REST API for task management",
  "mode": "full",
  "current_phase": 3,
  "phases_completed": [0, 1, 2],
  "worktree_path": ".factory/runs/run-20260223-2130",
  "sealed_path": ".factory/sealed/run-20260223-2130",
  "sealed_hash": "sha256:a1b2c3...",
  "artifacts": { "prd": "PRD.md", "arch": "ARCH.md", "gap_report": "SHADOW-REPORT.md" },
  "checkpoints": {
    "1": { "status": "approved", "feedback": null, "decided_at": "2026-02-23T21:35:00Z" },
    "2": { "status": "approved", "feedback": null, "decided_at": "2026-02-23T21:40:00Z" }
  },
  "skip_all": false,
  "started_at": "2026-02-23T21:30:00Z",
  "last_updated": "2026-02-23T21:45:00Z",
  "evaluation_due_at": null
}

"dark factory resume" — Read state.json from most recent run, display progress, re-enter at current_phase.

"dark factory status" — Display state.json without modifying anything.

Checkpoint Protocol

Phase 6 uses only: approve / reject

Agent Dispatch Pattern

Every agent call follows this template:

task(agent_type="general-purpose", model="<config.models.<role>>", description="<phase name>", prompt="
You are the {ROLE} for the Dark Factory.
## Mission: {what to do}
## Input: {PRD / ARCH / goal}
## Repo Signals: {file listing only (optional)}
## Working Directory: {worktree_path or sealed_path}
## Output: {what to produce and where}
## Rules: {constraints for this agent}
")

Rules

1. ALWAYS run phases in order. Express mode has fewer phases, not skipped phases.
2. ALWAYS write state.json after each phase transition.
3. NEVER show sealed test contents to user or building agents during Phases 1-3.
4. ALWAYS present checkpoints via ask_user with exactly 4 choices (approve/modify/skip-all/abort).
5. On abort: clean up worktree immediately (git worktree remove + git branch -D).
6. On modify: re-run current phase with user's feedback appended to the agent prompt.
7. Express mode ALWAYS generates sealed tests from raw goal text (not PRD).
8. Final delivery checkpoint can NEVER be skipped, even in skip-all mode.
9. Track every phase in SQL: INSERT INTO phase_results (run_id, phase, status, duration_sec, model_used, artifacts) VALUES (...).
10. Keep commentary concise — factory metaphors, status updates, not essays.
11. Timeout: if an agent takes longer than config.factory.agent_timeout_sec, retry (max config.factory.max_retries).
12. Safety: enforce config.safety.max_prd_lines and config.safety.max_artifact_lines by summarizing before downstream handoffs.