architect
Skill15 starsChanged 4 months agoApache-2.0View on GitHub
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.
188 other projects use a version of this, 1 of them edited.
Adopted by
Most recently taken up by
- GoBeromsu/craft-skillstheir own version, first seen Nov 16, 2026
- gfunc/skillstheir own version, first seen Nov 16, 2026
- akshay-diwadkar/first-four-hourstheir own version, first seen Nov 16, 2026
- RIJUDEVx/agent-skillstheir own version, first seen Nov 16, 2026
- fworks-tech/agenthoodtheir own version, first seen Nov 16, 2026
- shiwenbin1617/pstacktheir own version, first seen Nov 16, 2026
Used with
Projects with it also use ecosystem-reference, fractal-delegation and 10 more.
Other files people use alongside this one.
Files found in the same public projects as a version of this one, more often than they turn up anywhere else. Each project counts once, large collections count for less, and this file's own repository is left out.
naman10parikhSkillecosystem-reference
Quick-access directory of Claude Code ecosystem repos, skills, plugins, MCPs, and patterns. Use when improving the harness.
Also in 5 projects that use this
naman10parikhSkillfractal-delegation
Also in 5 projects that use this
tristanphvnSkillketchup-video
Catch the user up like /keel:ketchup, with a short silent video of slides for what happened and the waiting calls as text under it. Use for /keel:ketchup-video.
Also in 14 projects that use this
jaydubya818Skillfigure-it-out
Use when novel or multi-phase work needs an auditable workflow and no narrower playbook fits.
Also in 55 projects that use this
ianclearySkillprinciple-explain-the-number
Apply before you trust, report, or act on a number you measured: a speedup, a regression, a throughput, a latency, or an eval result. Find what limits it, and rule out that it measured something other than the work you think.
Also in 29 projects that use this
eryzerzSkillmake-bot-ui
Use when building a custom UI (page, dashboard, buttons) that should wake a Grok Bot over a webhook, when the user must provide a webhook sender key, or when exposing that UI on Tailscale.
Also in 20 projects that use this
- +6 more from naman10parikh
Other versions188 projects use a version of this.
Word for word · 0
None found.
Edited · 1
- DanMcInerney/architect-loop★ 62610% same
Wrote their own version · 187
- Yeachan-Heo/oh-my-claudecode★ 41ksame name
- Yeachan-Heo/oh-my-claude-sisyphus★ 41ksame name
- pascalorg/editor★ 26ksame name
- backnotprop/pstack★ 4.2ksame name
- agenticnotetaking/arscontexta★ 3.5ksame name
- jsmastery-pro/skills★ 1.4ksame name
- SethGammon/Citadel★ 927same name
- moeru-ai/xsai★ 667same name
- Hainrixz/the-architect★ 562same name
- Trevoke/org-gtd.el★ 485same name
177 more not listed
How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.
In this repository8 other files it gives its agents.
- AGENTS.mdAGENTS.md
- CLAUDE.mdCLAUDE.md
- llms.txtllms.txt
- architect-researchSkill
- code-standardsSkill
- parler-reviewSkill
- validate-marketSkill
- write-blogSkill
The file
We split this skill into the rules it gives an agent
11 rules. 0 are common, 7 are distinctive, and 4 are very specific to this project.
0
Common
Most of the 176 edited versions we read keep these.
7
Distinctive
This author's own choices. Worth a look.
4
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 41
Fresh builder per issue: Use worktree isolation and one issue per job session.
- Distinctive: line 60
Run this at every factory block boundary.
- Very specific: line 62
Read operating docs in authority order: CLAUDE.md / AGENTS.md, then README.md, architecture docs, the active spec, docs/solutions/, open …
- Very specific: line 70
Check docs/STOP before any dispatch wave.
- Very specific: line 87
Before decomposition records the builders backend, canary every candidate backend once with a trivial task: list available tools.
- Distinctive: line 128
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 …
- Distinctive: line 146
Add sub-issues under the existing tracking issue, which is the dashboard and digest target.
- Distinctive: line 156
Run one fresh read-only stress-test pass over the whole decomposition, not per issue.
- Distinctive: line 176
Run design-it-twice only for new load-bearing abstractions.
- Very specific: line 192
Use loop.md ## Factory block procedure for the detailed event loop.
- Distinctive: line 243
Stop and ask the human when any hard stop fires:
“Common” is measured: kept by at least 6 in 10 of the 176 edited versions of this file we could read. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
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.mdfor research fan-out
Hard Rules
- 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.
- Checks freeze in git before dispatch. Issue checks live under
docs/checks/, freeze at one commit, and become read-only. Any builder edit underdocs/checks/is an automatic FAIL. - 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.
- The orchestrator never writes implementation code and never reads large diffs. Builders code; verifier and judge subagents inspect large diffs.
- 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.
- 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.
- Builders never commit. The orchestrator owns commits, merges, and issue closure after judge evidence.
- 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.
- 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, thenREADME.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, thendispatch.md## Model alias tableand config rules. - Check
docs/STOPbefore 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, orAPPROVE with edits: <text>. A repo-owner comment beginning exactlyREJECT <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.mdinline 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.ps1on Windows orskills/architect/status.shon 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>.mdthrough 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
ghpreflight 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.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

