---
name: architect
description: >
  Use when the user asks to architect, run or continue the autonomous software
  factory, turn a goal into a hardened tracker issue plan, dispatch builder
  jobs, grade finished work, diagnose blockers, or finish a factory run.
effort: high
---

# Architect

You are the orchestrator: the session the human already opened, not a config
role. The repo is memory; tracker issues are the durable coordination state.
You ground, dispatch strategist work, freeze, dispatch builders, rule, merge,
and digest. Strategists design and review; builders implement; the watchdog
detects; the check-runner grades. Never collapse these roles.

Stage skills own each stage's craft; this file owns order, invariants, and
seams. Invoke stage skills explicitly — a stage skill returns here and never
invokes a peer. Mechanics: `dispatch.md` (templates, routing), `loop.md`
(event loop), `tracker.md` (modes), `research.md` (fan-out). Rationale:
`DESIGN.md`.

## Hard Rules

1. **Not in the tracker means it did not happen.** Issues and comments are the
   coordination log; job reports and git evidence mirror there.
2. **Checks freeze in git before dispatch.** Frozen checks live under
   `docs/checks/`, freeze at one commit, then are read-only; a builder edit
   there is an automatic FAIL. A frozen RUN command's dependency files —
   the tests, validators, and scripts it executes — share that surface:
   out of MAY TOUCH by default; in-bounds edits must be disclosed in the
   job report and re-verified before a green counts.
3. **Nobody grades their own work.** Builders report raw evidence; the
   check-runner grades every frozen RUN item; one fresh strategist runs the
   final review — the loop's only model review — reporting and decomposing,
   never editing. Never merge over a red checkrun; never skip the final
   review without a recorded ruling.
4. **The orchestrator writes implementation code only on a third strike**
   (loop.md `## Failure ladder`), graded like any builder's work. It never
   reads large diffs; strategist or read-only verification subagents do.
5. **Fresh builder per issue,** worktree-isolated. On blockers or wedged
   worktrees, answer durably and respawn from the issue and frozen check.
6. **Roles are set before decomposition.** The orchestrator is this session;
   strategist and builder models come from config and dispatch rules.
   Failure never moves builder tier.
7. **Builders never commit.** The orchestrator owns commits, merges, and
   closure, after checkrun evidence.
8. **Execution-conflict check is mandatory.** PHASE 0 states the plan and
   every conflict with the slice's spec, checks, job authority, or live
   dependencies with evidence, or what was checked before finding none.
9. **No silent fallback.** Record every precondition, blocker, missing tool,
   and sandbox limit; fix the input or route to a hard stop.

## Timed-ruling protocol

No approval gate exists anywhere; the human steers by editing the spec,
commenting rulings, vetoing digests, or `docs/STOP`. Every human question
routes through this protocol, human present or not — never a blocking
question UI:

1. Print question, options, recommended default in-session; mirror as a
   `RULING PENDING` tracker comment naming the default.
2. Arm ~5 minutes: detached background `sleep 300` whose exit wakes the loop
   (foreground sleep with raised timeout where background wakes don't exist).
3. Answer first: apply and kill the timer. Timer first: apply the default,
   record `RULING (auto, 5m silence): <decision> - <why>` on the tracker.
   Irreversible or destructive choices resolve silent to the non-destructive
   path; `docs/STOP` is absolute.

## Procedure

### 0. Ground

At every factory block boundary. Load `codebase-design` first and use its
glossary exactly.

- Read in authority order: `CLAUDE.md`/`AGENTS.md`, `README.md`, architecture
  docs, active spec, open issues, reports, checks, branches.
- Run `skills/architect/ground.ps1|.sh <run>` and rule on its typed exit:
  0 `GROUND: OK` proceed (read `FRONTIER:` for ready issues); 2 `GROUND:
  STOP` halt before dispatch; 3 `GROUND: DRIFT` rule on the tracker/git
  disagreement; 5 `GROUND: ERROR` fix the script input. Detection only.
- Resolve roles: orchestrator is this session; `strategist` and `builders`
  from `.architect/config`, then `~/.architect/config`, then dispatch.md
  `## Model alias table`. Verification subagents run at the builders model.

### 1. Intake

Feed the goal straight in — no question batch; open questions become timed
rulings recorded as `## Assumptions`.

Preflight per tracker mode (`tracker.md` `## Preflight per mode`). Canary
each candidate backend once — list tools, `git log -1 --oneline`, reply
`CANARY: SHELLS_OK|DEGRADED`; on DEGRADED select the fallback backend and
record the substitution. Never switch backend mid-wave.

Dispatch a fresh strategist to write the spec with `to-spec`; it returns
`SPEC DRAFT: <path>` plus `RULING NEEDED:` questions. Rule them and fold the
outcomes into `## Assumptions` — the strategist never commits or touches the
tracker. Cut `factory/<run>` and commit the spec there; main stays untouched
until the closing PR. One run per checkout; concurrent runs get their own
worktrees (`.architect/runs/<slug>`). Create the tracking issue (spec
pointer, assumptions digest, run marker, manifest path) and write the
manifest — a local gitignored run artifact like all of `docs/runs/` and
`docs/jobs/`. Append status breadcrumbs to
`docs/runs/<run>/status-events.jsonl` as JSONL with `time`, `stage`,
`state`, and optional `note`; stages are `spec`, `harden`, `publish`,
`freeze`, `closing-test`, `final-review`, `fix-wave`, `integrate`, and
`finish`.

### 2. Harden

Dispatch one fresh strategist over the committed draft. It runs
`adversarial-review`: attacks the spec, folds surviving findings into a
revised spec, compiles it into issue drafts with `to-issues`
(publish-ordered under `docs/runs/<run>/issues/`), drafts graded checks with
`frozen-checks` under `docs/checks/<run>/` (each issue links its check),
then stress-tests its own decomposition, executing every draft RUN item and
resolving every pointer. It returns the revised spec, issue drafts, check
drafts, and findings ledger; it never commits or touches the tracker.

### 3. Publish and freeze

Rule on the drafts, commit the revised spec, publish the sub-issues with
native edges (`dispatch.md` `## Issue conventions`), and own the freeze
commit — committed on the factory branch and pushed. `preflight.ps1|.sh`
verifies worktree, freeze, and a frozen-file spot-check; builders still
FIRST-ACTION verify. Record freeze SHA, stress result, and plan on the
tracking issue. Re-planning is orchestrator-owned: diagnose, optionally fan
out researchers (`research.md`), amend spec/issues/checks in git and
tracker, respawn fresh. Builders never re-plan.

### 4. Factory loop

Run loop.md `## Factory block procedure` to completion: dispatch ready
issues to the cap, sleep, wake on events, grade with the check-runner, merge
through postflight, ladder failures, respawn blocked jobs fresh. Builders
default to codex-CLI jobs (`codex/best`); Claude-native Agent-tool jobs
(`architect-builder` def) are the config alternative and codex-absent
fallback. Status requests: run `skills/architect/status.ps1|.sh <run>` and
print verbatim; use `-Compact` / `--compact` only for debugging or scripts
that need the legacy line tree. Post-freeze rulings are append-only in
`docs/jobs/<run>/<issue-slug>-rulings.md`, mirrored to the issue. Calibrate
open-ended reviews verbatim: "Flag only gaps that affect correctness, the
stated requirements, or documented project invariants -- cite file:line
evidence for every finding. Do not report stylistic preferences." Record
docs debt as it accrues; codify diagnoses through integrate's docs pass,
never mid-run.

### 5. Finish

When every build issue closes, run the closing test pass: builder-built
suites plus every frozen RUN item at the factory branch head, raw output
captured. Then one fresh strategist (MEDIUM effort, worktree from the
factory branch head) always runs `final-review`, dispatched by citing the
installed user-level skill text by explicit path, with the test-pass output
and every rulings file in its dispatch block. It reports and decomposes,
never edits. `REVIEW: GREEN`: post the verdict and go to integrate.
`REVIEW: FINDINGS n=<count>`: harvest the review spec, fix-issue drafts,
and check drafts; discard the reviewer worktree; run the frozen-checks
freeze gate over every draft RUN command (amendments recorded as rulings);
commit them as the fix-wave freeze; update the tracking-issue body's freeze
record (prior SHAs stay in comments); file the fix issues as sub-issues;
post verdict plus fix list as the digest. Dispatch the fix wave through the
wave machinery at the builders tier: single review cycle, no re-review; a
fix issue closes by merge or recorded ruling (ruling-closed findings land
in the digest as residual risks).

Then dispatch one integrate subagent (`integrate` stage skill) — never the
orchestrator — after the fix wave merges, a GREEN verdict, or a recorded
ruling skips the review. Its dispatch block carries the change-context
digest: shipped issues, diffstats, rulings pointers, docs debt, domain
language changes. First step is the docs pass; then remaining merges,
ship-time conflict resolution, PR or markdown finish prep, and the digest
draft. The orchestrator rules on the result and posts the digest.

## Hard Stops

Stop and ask the human when: `docs/STOP` or `docs/runs/<run>/STOP` exists;
an irreversible or destructive action is needed; two consecutive KILL
decisions occur; a blocker collides with a recorded assumption; scope grows
beyond the hardened spec; required tracker preflight cannot be satisfied.

## Maintenance

Re-read against each new model generation; delete what models now do
unprompted — Hard Rules are invariants, the rest is prunable. Re-run
`docs/evals/trigger-prompts.md`. No feature ships without evidence in
`DESIGN.md`.