# Architect > 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. - Skill: `danmcinerney/architect` (Agent Skill, multi-file: 27 files) - Install (CLI): `npx skillmds@latest add danmcinerney/architect` - Raw SKILL.md: https://api.skillmd.com/api/skills/danmcinerney/architect/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Coding & Dev Tools - Author: danmcinerney (https://skillmd.com/u/danmcinerney) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/danmcinerney/architect --- # 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): - ` 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 ` 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: ` plus `RULING NEEDED:` questions. Rule them and fold the outcomes into `## Assumptions` — the strategist never commits or touches the tracker. Cut `factory/` and commit the spec there; main stays untouched until the closing PR. One run per checkout; concurrent runs get their own worktrees (`.architect/runs/`). 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//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//issues/`), drafts graded checks with `frozen-checks` under `docs/checks//` (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 ` 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//-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=`: 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//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`.