agentleFS
RIJUDEVxRIJUDEVx/agent-skills/architect/SKILL.md

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

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.
  • naman10parikhSkill

    ecosystem-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

  • naman10parikhSkill

    fractal-delegation

    Also in 5 projects that use this

  • tristanphvnSkill

    ketchup-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

  • jaydubya818Skill

    figure-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

  • ianclearySkill

    principle-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

  • eryzerzSkill

    make-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

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
  1. Distinctive:

    If the human pushes back on the shape (in a checkpoint or after the fact), treat that as Phase A evidence.

    line 53
  2. Distinctive:

    If implementation keeps producing friction the sketch can't absorb, throw the sketch out.

    line 63
  3. Distinctive:

    Use judgment. A few edge cases don't condemn an architecture.

    line 74
  4. Distinctive:

    Use these terms exactly: don't substitute "component," "service," "API," or "boundary." Consistent language is the whole point.

    line 93
  5. Distinctive:

    When designing an interface, ask:

    line 135
  6. Distinctive:

    If the user named a direction (a module, a subsystem, a pain point), take it, and skip the inference below.

    line 210
  7. Very specific:

    Read the project's domain glossary (GLOSSARY.md) and any ADRs in the area you're touching first.

    line 213
  8. Distinctive:

    Do NOT propose interfaces yet.

    line 248
  9. Very specific:

    Sharpening a fuzzy term during the conversation?: Update GLOSSARY.md right there.

    line 257

“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.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

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.

  1. Ground
  2. Sketch
  3. Agree
  4. Implement
  5. 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:

  1. Trace what's been built, the same way as Phase A.
  2. Redesign as if the new constraints had been day-one assumptions.
  3. Subtract before adding. The new sketch should be smaller than the old one before it grows.
  4. 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:

  1. Accept dependencies, don't create them.

    // Testable
    function processOrder(order, paymentGateway) {}
    
    // Hard to test
    function processOrder(order) {
      const gateway = new StripeGateway();
    }
  2. Return results, don't produce side effects.

    // Testable
    function calculateDiscount(cart): Discount {}
    
    // Hard to test
    function applyDiscount(cart): void {
      cart.total -= discount;
    }
  3. 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 interface keyword 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.md gives names to good seams; ADRs in docs/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 to GLOSSARY.md. Create the file lazily if it doesn't exist.
  • Sharpening a fuzzy term during the conversation? Update GLOSSARY.md right 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.

Download now (ZIP)

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
What did you use it for? e.g. Reviewing pull requests in a Rails app

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.