---
name: factory
description: Use when the user says "factory", wants an autonomous plan/build/test/quality run, or asks about factory decisions/stop/reconcile. Global `factory` CLI, works from any repo — the only executor for autonomous work.
---

# factory

Audience: AI coding agents first. Imperative, BLUF.

Global software factory: one-line request in → autonomous ADW (AI Developer Workflow) plans/builds/tests on a branch, traces to global SQLite, surfaces decisions in the Inbox, blocks until answered. Core lives in overdeck (`modules/harness/factory/`), deployed clone serves the CLI — NEVER copy it per-repo.

## The request can be a sentence or a document

A path argument resolves to that file's **contents** (`adw_modules/utils.py` `resolve_prompt`), so an authored plan document IS the request:

```bash
factory adw_plan_build_test_quality docs/plans/2026-08-08-auth-rework.md
```

The factory's own planner decomposes whatever it is handed — it writes `<context_handoff_dir>/plan.md`, copies it to `specs/<adw_id>_<slug>.md`, and the builder reads those. An authored doc is therefore a request spec, never a task graph.

## Run

From inside the target repo (or `--repo PATH`):

```bash
factory plan "add a health endpoint"          # plan only
factory plan_build "add a health endpoint"    # plan + implement
factory plan_build_test "…"                   # + tests
factory plan_build_test_quality "…"           # + quality pass
factory build "…"   # implement from existing spec
factory prompt "summarize this repo"          # one-shot, no code changes
factory scout "where is auth handled?"        # codebase Q&A
factory document "…"
```

- Config resolution: `--config` → `<repo>/.factory/sssf.config.yaml` → overdeck default. Models are GPT-5.6 luna/sol/terra ONLY — NEVER 5.5.
- Blocks in foreground until done or waiting on a human decision. No resume — re-launching starts a new `adw_id`. Long runs → background via QuietContext execute `background:true` (Bash `run_in_background` is deny-gated).
- Global state: `~/.local/state/overdeck/factory/sssf.db` (+ `data/`). All repos, one DB.

## Human decisions (HITL)

Planner emits a decision ONLY at a genuine owner fork (product taste/scope/cost). Run blocks until answered; answer durably resumes the SAME run.

- See pending: Inbox at `http://127.0.0.1:31337` (kind `decision`), or `factory decisions [--adw ID] [--json]`.
- Answer: click the Inbox action, or `factory answer <decision_id> --choice VALUE` (`--text TEXT` for free-text).
- Canceling: `factory stop <adw_id>` cancels the wait cleanly.

## Control

```bash
factory stop <adw_id>     # kill run's processes, fail session, cancel pending decisions
factory reconcile         # mark dead sessions failed, clean stale process rows
```

## Observe

- Deck: `http://127.0.0.1:31337/factory` — runs, phases, tokens, cost.
- Systray: factory dot shows live runs + repo.
- Trace events: `sssf.db` tables `sessions`/`events`/`decisions` (readonly queries OK; NEVER write).

## Do NOT

- Do NOT edit `modules/harness/factory/**` to make a run pass — `adw_modules/permissions.py` bars every agent from it, because an agent must not edit the machinery that judges its own work.
- Do NOT edit `sssf.db` by hand; use `factory stop` / `factory reconcile` / `factory answer`.