architect
Skill1 starsChanged 3 days agoMITView on GitHub
Use when the user invokes `$architect`, usually because they are unclear about what to build or how it should be shaped. Works out the requirement, traces the system and who is affected, and designs before any code. Also surveys existing code for deepening opportunities. Stops with an agreed design for `$full-stop` or `$full-send`.
186 other projects use a version of this, 63 of them edited.
Adopted by
Most recently taken up by
- akshay-diwadkar/first-four-hourstheir own version, first seen Nov 16, 2026
- fworks-tech/agenthoodtheir own version, first seen Nov 16, 2026
- shiwenbin1617/pstackedited, first seen Nov 16, 2026
- jdonohoo/vern-bottheir own version, first seen Nov 15, 2026
- backnotprop/pstackedited, first seen Nov 15, 2026
- JeffKarling/Anviltheir own version, first seen Nov 15, 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 versions186 projects use a version of this.
Word for word · 0
None found.
Edited · 63
- backnotprop/pstack★ 4.2k56% same
- moeru-ai/xsai★ 66755% same
- jtaroreh/agystack★ 12853% same
- uzairansaruzi/p3-stack★ 12658% same
- dsebban/skills★ 7149% same
- overextended/skills★ 2250% same
- painhardcore/pstack★ 2257% same
- creedants/pstack-t3★ 1844% same
- mariusflorescu/pstack-t3★ 1351% same
- Scino/fstack★ 1355% same
53 more not listed
Wrote their own version · 123
- Yeachan-Heo/oh-my-claudecode★ 41ksame name
- Yeachan-Heo/oh-my-claude-sisyphus★ 41ksame name
- pascalorg/editor★ 26ksame name
- agenticnotetaking/arscontexta★ 3.5ksame name
- jsmastery-pro/skills★ 1.4ksame name
- SethGammon/Citadel★ 927same name
- DanMcInerney/architect-loop★ 626same name
- Hainrixz/the-architect★ 562same name
- Trevoke/org-gtd.el★ 485same name
- nagi-studio/skills★ 470same name
113 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 repository22 other files it gives its agents.
- analyze-logsSkill
- build-audit-logsSkill
- cloudflareSkill
- code-reviewSkill
- design-engineeringSkill
- diagnosing-bugsSkill
- full-sendSkill
- full-stopSkill
- ghSkill
- grillingSkill
- impeccableSkill
- improve-animationsSkill
- interrogateSkill
- no-use-effectSkill
- prSkill
- retroSkill
- t3-toolsSkill
- triageSkill
- unslopSkill
- vitestSkill
- wait-whatSkill
- writing-for-agentsSkill
The file
We split this skill into the rules it gives an agent
9 rules. 0 are common, 7 are distinctive, and 2 are very specific to this project.
0
Common
Most of the 174 edited versions we read keep these.
7
Distinctive
This author's own choices. Worth a look.
2
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 53
If the human pushes back on the shape (in a checkpoint or after the fact), treat that as Phase A evidence.
- Distinctive: line 63
If implementation keeps producing friction the sketch can't absorb, throw the sketch out.
- Distinctive: line 74
Use judgment. A few edge cases don't condemn an architecture.
- Distinctive: line 93
Use these terms exactly: don't substitute "component," "service," "API," or "boundary." Consistent language is the whole point.
- Distinctive: line 135
When designing an interface, ask:
- Distinctive: line 210
If the user named a direction (a module, a subsystem, a pain point), take it, and skip the inference below.
- Very specific: line 213
Read the project's domain glossary (GLOSSARY.md) and any ADRs in the area you're touching first.
- Distinctive: line 248
Do NOT propose interfaces yet.
- Very specific: line 257
Sharpening a fuzzy term during the conversation?: Update GLOSSARY.md right there.
“Common” is measured: kept by at least 6 in 10 of the 174 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
Design before implementing. Sketch types, function signatures, class shapes, and module boundaries with not implemented bodies and pseudocode. Synthesize across multiple model perspectives, then fill in code against the chosen sketch. If implementation proves the sketch wrong, throw it out and redesign.
Start
Open a todolist with one entry per phase before starting.
- Ground
- Sketch
- Agree
- Implement
- Scrap
Phase A: Ground the problem
Build a real mental model of every system the new code touches. Trace the real code: entry points, data flow, state, and who owns what, with file:line references.
Naming a file isn't grounding. Produce the traced model. If the design redefines ownership or layering, also read the git history and PRs for the existing shape so the rationale becomes a constraint, not a guess.
Skip Phase A only when the work is genuinely greenfield with no surrounding system to integrate.
Then work out who this touches: use the Blast radius mode of the interrogate skill on the planned change. Its findings are constraints on the sketch.
Phase B: Sketch
Start at least two independent sub-agents, on different model families when available, with the design-sketch task and the Phase A findings. Pass references/runner-prompt.md as each one's prompt. If you cannot start them, produce the candidates yourself. Each candidate produces a design package shaped per references/rationale-template.md.
In T3 Code, pick the runners from the user's favourites, the strongest ones from at least two families (the t3-tools skill has the steps). Elsewhere, use distinct high-capability models the harness exposes. If you cannot select a model per subagent, run the candidates from independent contexts instead.
Design it twice. Require at least two structurally distinct candidates before synthesis, even when the first looks sufficient. Whole-shape alternatives, not point fixes inside one shape.
Screen every candidate against references/design-red-flags.md before synthesis. Reject or revise shallow modules, information leakage, temporal decomposition, and pass-through methods.
Compare viable candidates on interface depth. Prefer the design that hides more complexity behind a smaller, simpler public surface. A rich interface can keep call chains short by concentrating capability instead of scattering it across layers.
Combine the candidates into one design package. The synthesis decision populates the rationale's "Synthesis decision" section.
Phase C: Agree
The user invoked $architect: they are here because something is unclear, so stay with them. Use the grilling skill on anything about what to build before you sketch, and again on any open question the sketch raises. Show the synthesized design, the impact findings, and your recommendation, then stop before implementing. Tell them $full-stop or $full-send will build it from this design. Skip Phase D unless they ask you to continue.
$full-stop or $full-send sent you here: nobody is watching. Make the decisions yourself, record them, and continue.
The synthesis can ship as its own commit either way. Planned and scoped breakage during fill-in is fine. For adversarial pressure on the design before implementing, run the interrogate skill on the synthesized sketch.
If the human pushes back on the shape (in a checkpoint or after the fact), treat that as Phase A evidence. Re-ground and re-run Phase B before writing more code.
Phase D: Implement against the sketch
Replace not implemented bodies with code, pseudocode with logic. The synthesized sketch is the contract.
Deviations from the sketch are signal worth surfacing, not friction to absorb silently. If a function needs a parameter the sketch didn't anticipate, ask whether the sketch was wrong, the requirement was missed, or the implementation is overreaching.
Phase E: Scrap when the architecture is wrong
If implementation keeps producing friction the sketch can't absorb, throw the sketch out. Don't bolt fixes onto a wrong design.
The signal is a pattern, not single instances. Tells:
- The same shape of workaround appearing repeatedly across unrelated code.
- Multiple unrelated edge cases that all need special-case branches.
- Types that need escape hatches (
any, casts, optional fields always set in practice) to compile. - The "we need a lock" reflex when the sketch said the state wasn't shared.
- Callers having to know the abstraction's internal rules to use it.
- Two or more independent Phase D deviations of the same shape across the implementation.
Use judgment. A few edge cases don't condemn an architecture. Some problems are legitimately complex. Complexity in the data is not complexity in the design.
When you scrap:
- Trace what's been built, the same way as Phase A.
- Redesign as if the new constraints had been day-one assumptions.
- Subtract before adding. The new sketch should be smaller than the old one before it grows.
- Return to Phase B and sketch again.
Outputs
The caller's usage is written first and the type sketch derived from it. One file with new types and signatures for small changes. Module map plus type definitions for larger work. The rationale ships alongside, shaped per references/rationale-template.md, including the usage sketch and the synthesis decision.
Vocabulary
Design deep modules: a lot of behaviour behind a small interface, placed at a clean seam, testable through that interface. Use this language and these principles wherever code is being designed or restructured. The aim is leverage for callers, locality for maintainers, and testability for everyone.
Glossary
Use these terms exactly: don't substitute "component," "service," "API," or "boundary." Consistent language is the whole point.
Module: anything with an interface and an implementation. Deliberately scale-agnostic: a function, class, package, or tier-spanning slice. Avoid: unit, component, service.
Interface: everything a caller must know to use the module correctly: the type signature, but also invariants, ordering constraints, error modes, required configuration, and performance characteristics. Avoid: API, signature (too narrow, they refer only to the type-level surface).
Implementation: what's inside a module, its body of code. Distinct from Adapter: a thing can be a small adapter with a large implementation (a Postgres repo) or a large adapter with a small implementation (an in-memory fake). Reach for "adapter" when the seam is the topic; "implementation" otherwise.
Depth: leverage at the interface. The amount of behaviour a caller (or test) can exercise per unit of interface they have to learn. A module is deep when a large amount of behaviour sits behind a small interface, shallow when the interface is nearly as complex as the implementation.
Seam (Michael Feathers): a place where you can alter behaviour without editing in that place; the location at which a module's interface lives. Where to put the seam is its own design decision, distinct from what goes behind it. Avoid: boundary (overloaded with DDD's bounded context).
Adapter: a concrete thing that satisfies an interface at a seam. Describes role (what slot it fills), not substance (what's inside).
Leverage: what callers get from depth. More capability per unit of interface they learn. One implementation pays back across N call sites and M tests.
Locality: what maintainers get from depth. Change, bugs, knowledge, and verification concentrate in one place rather than spreading across callers. Fix once, fixed everywhere.
Deep vs shallow
Deep module = small interface + lots of implementation:
┌─────────────────────┐
│ Small Interface │ ← Few methods, simple params
├─────────────────────┤
│ │
│ Deep Implementation│ ← Complex logic hidden
│ │
└─────────────────────┘Shallow module = large interface + little implementation (avoid):
┌─────────────────────────────────┐
│ Large Interface │ ← Many methods, complex params
├─────────────────────────────────┤
│ Thin Implementation │ ← Just passes through
└─────────────────────────────────┘When designing an interface, ask:
- Can I reduce the number of methods?
- Can I simplify the parameters?
- Can I hide more complexity inside?
Principles
- Depth is a property of the interface, not the implementation. A deep module can be internally composed of small, mockable, swappable parts; they just aren't part of the interface. A module can have internal seams (private to its implementation, used by its own tests) as well as the external seam at its interface.
- The deletion test. Imagine deleting the module. If complexity vanishes, it was a pass-through. If complexity reappears across N callers, it was earning its keep.
- The interface is the test surface. Callers and tests cross the same seam. If you want to test past the interface, the module is probably the wrong shape.
- One adapter means a hypothetical seam. Two adapters means a real one. Don't introduce a seam unless something actually varies across it.
Designing for testability
Good interfaces make testing natural:
Accept dependencies, don't create them.
// Testable function processOrder(order, paymentGateway) {} // Hard to test function processOrder(order) { const gateway = new StripeGateway(); }Return results, don't produce side effects.
// Testable function calculateDiscount(cart): Discount {} // Hard to test function applyDiscount(cart): void { cart.total -= discount; }- Small surface area. Fewer methods = fewer tests needed. Fewer params = simpler test setup.
Relationships
- A Module has exactly one Interface (the surface it presents to callers and tests).
- Depth is a property of a Module, measured against its Interface.
- A Seam is where a Module's Interface lives.
- An Adapter sits at a Seam and satisfies the Interface.
- Depth produces Leverage for callers and Locality for maintainers.
Rejected framings
- Depth as ratio of implementation-lines to interface-lines (Ousterhout): rewards padding the implementation. We use depth-as-leverage instead.
- "Interface" as the TypeScript
interfacekeyword or a class's public methods: too narrow: interface here includes every fact a caller must know. - "Boundary": overloaded with DDD's bounded context. Say seam or interface.
Going deeper
- Deepening a cluster given its dependencies, see DEEPENING.md: dependency categories, seam discipline, and replace-don't-layer testing.
- Exploring alternative interfaces, see DESIGN-IT-TWICE.md: spin up parallel sub-agents to design the interface several radically different ways, then compare on depth, locality, and seam placement.
Survey existing code
Surface architectural friction and propose deepening opportunities: refactors that turn shallow modules into deep ones. The aim is testability and AI-navigability.
This survey is informed by the project's domain model and built on the Vocabulary section above:
- Use the Vocabulary section for the architecture terms (module, interface, depth, seam, adapter, leverage, locality) and its principles (the deletion test, "the interface is the test surface", "one adapter = hypothetical seam, two = real"). Use these terms exactly in every suggestion, and don't drift into "component," "service," "API," or "boundary."
- The domain language in
GLOSSARY.mdgives names to good seams; ADRs indocs/adr/(or the repo's own ADR location, per its docs) record decisions this survey should not re-litigate.
1. Explore
Scope before you scan: YAGNI. Deepening a module pays off by making future changes to it easier, so put extra weight on the parts of the codebase that have recently changed. Decide where to look before you look:
- If the user named a direction (a module, a subsystem, a pain point), take it, and skip the inference below.
- Otherwise, walk back a good stretch of the commit history (
git log --oneline) to find the codebase's hot spots, the files and areas that keep coming up, and let those paths pull your attention first. If the changes are scattered with no clear hot spot, widen the net.
Read the project's domain glossary (GLOSSARY.md) and any ADRs in the area you're touching first.
Then spawn a sub-agent to walk the codebase. Don't follow rigid heuristics; explore organically and note where you experience friction:
- Where does understanding one concept require bouncing between many small modules?
- Where are modules shallow, with an interface nearly as complex as the implementation?
- Where have pure functions been extracted just for testability, but the real bugs hide in how they're called (no locality)?
- Where do tightly-coupled modules leak across their seams?
- Which parts of the codebase are untested, or hard to test through their current interface?
Apply the deletion test to anything you suspect is shallow: would deleting it concentrate complexity, or just move it? A "yes, concentrates" is the signal you want.
2. Present candidates as an HTML report
Write a self-contained HTML file to the OS temp directory so nothing lands in the repo. Resolve the temp dir from $TMPDIR, falling back to /tmp (or %TEMP% on Windows), and write to <tmpdir>/architecture-review-<timestamp>.html so each run gets a fresh file. Open it for the user (xdg-open <path> on Linux, open <path> on macOS, start <path> on Windows) and tell them the absolute path.
The report uses Tailwind via CDN for layout and styling, and Mermaid via CDN for diagrams where a graph/flow/sequence reliably communicates the structure. Mix Mermaid with hand-crafted CSS/SVG visuals: use Mermaid when relationships are graph-shaped (call graphs, dependencies, sequences), and hand-built divs/SVG when you want something more editorial (mass diagrams, cross-sections, collapse animations). Each candidate gets a before/after visualisation. Be visual.
For each candidate, render a card with:
- Files: which files/modules are involved
- Problem: why the current architecture is causing friction
- Solution: plain English description of what would change
- Benefits: explained in terms of locality and leverage, and how tests would improve
- Before / After diagram: side-by-side, custom-drawn, illustrating the shallowness and the deepening
- Recommendation strength: one of
Strong,Worth exploring,Speculative, rendered as a badge
End the report with a Top recommendation section: which candidate you'd tackle first and why.
Use GLOSSARY.md vocabulary for the domain, and the Vocabulary section above for the architecture. If GLOSSARY.md defines "Order," talk about "the Order intake module," not "the FooBarHandler," and not "the Order service."
ADR conflicts: if a candidate contradicts an existing ADR, only surface it when the friction is real enough to warrant revisiting the ADR. Mark it clearly in the card (e.g. a warning callout: "contradicts ADR-0007, but worth reopening because…"). Don't list every theoretical refactor an ADR forbids.
See HTML-REPORT.md for the full HTML scaffold, diagram patterns, and styling guidance.
Do NOT propose interfaces yet. After the file is written, ask the user: "Which of these would you like to explore?"
3. Grilling loop
Once the user picks a candidate, call the Skill tool with "grilling" to walk the decision tree with them: constraints, dependencies, the shape of the deepened module, what sits behind the seam, what tests survive.
Side effects happen inline as decisions crystallize. The grilling skill's domain model section keeps the domain model current as you go:
- Naming a deepened module after a concept not in
GLOSSARY.md? Add the term toGLOSSARY.md. Create the file lazily if it doesn't exist. - Sharpening a fuzzy term during the conversation? Update
GLOSSARY.mdright there. - User rejects the candidate with a load-bearing reason? Offer an ADR, framed as: "Want me to record this as an ADR so future architecture reviews don't re-suggest it?" Only offer when the reason would actually be needed by a future explorer to avoid re-suggesting the same thing; skip ephemeral reasons ("not worth it right now") and self-evident ones.
- Want to explore alternative interfaces for the deepened module? Use the design-it-twice parallel sub-agent pattern in DESIGN-IT-TWICE.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.

