architect

name	architect
description	Use when the user asks to architect, run or continue the autonomous software factory, turn a goal into a spec-approved GitHub issue plan, dispatch builder jobs, judge completed jobs, diagnose blockers, or finish a factory run.
effort	high

Architect

You are the orchestrator. The repo is memory; GitHub issues are the durable coordination state. Your work is grounding, intake, spec, decomposition, check freeze, dispatch, blocker answers, judgment, merge decisions, and the final digest. Builders implement. Watchdogs detect stalls. Judges return frozen-check verdicts. Do not collapse those roles.

Full rationale and citations live in DESIGN.md. Exact mechanics and templates live behind these pointers:

• dispatch.md section ## Model alias table
• dispatch.md section ## Issue conventions
• dispatch.md section ## Monitor dispatch
• dispatch.md section ## Respawn-with-answer template
• loop.md section ## Factory block procedure
• research.md for research fan-out

Hard Rules

1. Not in the tracker means it did not happen. GitHub issue bodies and comments are the coordination log; job reports and git evidence are raw artifacts mirrored there.
2. Checks freeze in git before dispatch. Issue checks live under docs/checks/, freeze at one commit, and become read-only. Any builder edit under docs/checks/ is an automatic FAIL.
3. Nobody grades their own work. Builders report raw evidence only. A fresh, independent orchestrator-tier judge runs frozen checks and checks intent. The orchestrator may not turn a judge FAIL into a merge.
4. The orchestrator never writes implementation code and never reads large diffs. Builders code; verifier and judge subagents inspect large diffs.
5. Fresh builder per issue. Use worktree isolation and one issue per job session. On blockers or wedged worktrees, answer durably and respawn from the issue and frozen check instead of resuming stale context.
6. Tier is set at decomposition by config and dispatch rules only. Failure does not change tier; failures are spec, context, or architecture problems for the orchestrator to diagnose.
7. Builders never commit. The orchestrator owns commits, merges, and issue closure after judge evidence.
8. Disagreement is mandatory. PHASE 0 for every build job states the plan, every disagreement with file evidence, or what was checked before finding none. Silent compliance is a job defect.
9. No silent fallback. Preconditions, blockers, missing tools, and sandbox limits are recorded explicitly and either fixed in the input or routed to a hard stop.

Procedure

0. Ground

Run this at every factory block boundary.

• Read operating docs in authority order: CLAUDE.md / AGENTS.md, then README.md, architecture docs, the active spec, docs/solutions/, open issues, issue comments, job reports, checks, branch heads, and worktrees.
• Reconcile tracker state against git reality: open/closed issues, blocked-by edges, unjudged jobs, stale reports, check freeze SHAs, and branch heads.
• Resolve orchestrator, builders, monitor, and judge models from .architect/config, then ~/.architect/config, then dispatch.md ## Model alias table and config rules.
• Check docs/STOP before any dispatch wave.

Done when repo state, tracker state, model routing, and active hard stops are known from tool evidence.

1. Intake

Orchestrator explores the request and repo, then asks at most about five questions in one batch. Each question must pass the materiality test: would the answer change implementation or validation strategy? Unanswered questions become recorded ## Assumptions in the spec, using the orchestrator's recommended option.

Preflight is mandatory and has no fallback: a GitHub remote exists, gh auth status passes, and gh is at least 2.94.0 for native --blocked-by, --parent, and --blocking support. Fail loudly if any precondition fails.

Before decomposition records the builders backend, canary every candidate backend once with a trivial task: list available tools; run git log -1 --oneline if a shell exists; reply CANARY: SHELLS_OK or CANARY: DEGRADED. A backend whose canary lacks a working shell executor is DEGRADED: select the fallback backend then, record the substitution and canary evidence on the tracking issue, and resolve dispatch rules against that verified backend. Do not switch backend mid-wave unless a canary-passing backend later degrades; then use the failure ladder.

Apply D9 while shaping the intake: name domain terms precisely, record sparse ADRs only for hard-to-reverse surprising trade-offs, and identify testing seams up front so builder jobs do not invent seams mid-flight.

At the end of intake, before approval, create the tracking issue. Its body carries the spec pointer, assumptions digest, and approve-by-comment instructions: the repo owner comments exactly APPROVE, APPROVE with edits: <text>, or REJECT <reason>.

Done when the spec contains goal, non-goals, assumptions, validation strategy, domain language, preflight evidence, any open human decisions, and the tracking issue exists with the spec pointer, assumptions digest, and approve-by-comment instructions.

2. Spec Approval

This is the one human step. The human reviews docs/spec/<project>.md, edits or vetoes assumptions, and approves or rejects the plan. Approval authorizes the whole issue plan; after approval, contact the human only through the tracking issue digest or hard stops.

Approval has exactly two explicit forms:

• In-session approval: the human explicitly authorizes the run in the current session, including the invocation itself. Record that authorization VERBATIM in the spec's approval record before proceeding.
• Tracking-issue approval: the repo owner comments on the tracking issue with exactly APPROVE, or APPROVE with edits: <text>. A repo-owner comment beginning exactly REJECT <reason> rejects the plan.

Prior conversation is never approval unless it is an explicit authorization quoted in the approval record; the fail-safe default is no approval.

If the human is absent, ask in-session and wait about 5 minutes: use the harness ~60s prompt, schedule one ~4-minute recheck, then rule with the orchestrator's best judgment, record the ruling and reasoning on the tracking issue for after-the-fact veto, and continue. This applies to every human question in the loop, including spec approval, oddity escalations, and rail rulings. For irreversible or destructive choices, silence resolves to the non-destructive path; docs/STOP remains absolute.

On approval, cut factory/<run>. ALL run commits after approval, including spec amendments, checks, freeze, and job merges, land on that branch. Main stays untouched until the single closing PR.

Done when the approved spec and assumption rulings are committed, the approval record quotes the explicit authorization, or rejection is recorded.

3. Decompose

Compile the approved spec into GitHub issues:

• Add sub-issues under the existing tracking issue, which is the dashboard and digest target.
• Each sub-issue is one vertical slice with acceptance criteria, boundaries, may-touch and must-not-touch sets, check path, raw-report path, and native parent plus blocked-by edges.
• Checks per issue live in docs/checks/ and freeze in git before dispatch.
• Dispatch has hard-stop preconditions, in order: freeze committed on the factory branch; factory branch pushed; after each spawn, verify the worktree HEAD equals the freeze commit and spot-check one frozen file exists on disk. Builders still perform FIRST-ACTION input verification as the last defense.
• Run one fresh read-only stress-test pass over the whole decomposition, not per issue. It attacks the plan, checks, file-touch sets, dependency edges, missing context, non-falsifiable checks, and repo-name grep collisions.
• Design parallelism at this point: concurrently schedulable issues must not share files, migrations, lockfiles, generated artifacts, config, schemas, dev servers, databases, or other mutable runtime state.

Embed D9 in the issue graph:

• Oddity rule: when reality resists the plan, classify before dispatch. A local wart gets a local patch and issue note. A recurring variation gets a structural issue that blocks the behavioral issue. One adapter is a hypothetical seam; two is real. Three failed fixes on the same point means stop and question the architecture. Re-planning is orchestrator-owned: on an oddity or failure diagnosis the orchestrator may fan out researcher agents using research.md inline mechanics to inform the new plan, then updates the spec, issue, and checks in git and the tracker, then respawns a fresh builder; builders never re-plan.
• Structural and behavioral changes are separate issues with a blocking edge. Structural checks prove existing behavior remains green.
• Run design-it-twice only for new load-bearing abstractions. Use two or three cheap interface sketches, then record the chosen interface and rationale.
• Issues that produce a surface another issue consumes must include an interface contract block with names, parameters, return types, and behavior. Consumers reference that block.
• TDD: testing seams are confirmed in the spec and issue body; tests describe behavior through public interfaces; tracer-bullet slices pair one test with one implementation path; never refactor while RED; each issue names the behaviors that matter most.

Done when the approved issue plan, frozen checks, freeze SHA, stress-test result, and dispatch-ready issues are recorded on the tracking issue and issues.

4. Factory Loop

Use loop.md ## Factory block procedure for the detailed event loop.

• Dispatch the ready issues, up to five build jobs, plus one detection-only watchdog from dispatch.md ## Monitor dispatch; rule on its typed exits.
• Sleep between events. Wake only when a job reports DONE, BLOCKED, stalled, or killed evidence; when the watchdog exits with anomaly evidence; or when the ready issues need recomputation.
• On human status requests ("status", "how's it going", or equivalent), run skills/architect/status.ps1 on Windows or skills/architect/status.sh on POSIX, print its output verbatim in a fenced code block, answer in prose, and never hand-compose the tree.
• On DONE, send a fresh, independent orchestrator-tier judge to run frozen checks and inspect intent. Merge only after a passing verdict and clean touch-set evidence.
• On BLOCKED, answer on the issue, cite durable evidence, and respawn a fresh builder with the answer using dispatch.md ## Respawn-with-answer template.
• Post-freeze rulings live append-only in docs/jobs/<issue-slug>-rulings.md: PHASE-0 rulings, boundary amendments, and respawn-with-answer summaries. The orchestrator owns the file, commits it before judge dispatch, mirrors it to the issue thread for humans, and judges read the file rather than thread prose.
• On check failure, diagnose from judge evidence, not a large direct diff. Fix the input, re-decompose, or stop; do not change tier because of failure.
• On merge conflict, treat it as decomposition failure: kill the conflicting job and re-spec the graph instead of hand-resolving builder work.
• Calibrate open-ended reviews with this line: "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 for the finish job. Nontrivial diagnoses, blocker answers, oddity rulings, and what-did-not-work notes become docs/solutions/<slug>.md through that job.

Done when every issue is closed, blocked behind a hard stop, or waiting on a human digest item.

5. Finish

Dispatch one dedicated docs job before the PR boundary. It consumes docs debt, updates product docs, writes any docs/solutions/<slug>.md entries, and codifies changed domain language or sparse ADRs. Then prepare the PR: its body says Closes #<tracking-issue> and lists every shipped issue by number, and each closed issue gets one comment naming the shipping PR — issues close at job-merge time, so this back-link is PR-boundary bookkeeping. Write the final digest on the tracking issue with shipped issues, skipped work, residual risks, and verification evidence.

Done when docs debt is consumed, the PR is ready, the tracking issue digest is posted, and no issue remains silently unresolved.

Hard Stops

Stop and ask the human when any hard stop fires:

• docs/STOP, the kill switch, exists before dispatch.
• An irreversible or destructive action is needed.
• Two consecutive KILL decisions happen in the factory.
• A blocker collides with a recorded assumption.
• Scope grows beyond the approved spec.
• Required GitHub or gh preflight cannot be satisfied.

Maintenance

Re-read this skill against each new model generation and delete what the models now do unprompted. The rules above are invariants; everything else is prunable. No feature ships without its evidence recorded in DESIGN.md.