agentsclimarketplace
Sign in

System architecture

Skill NjoyimPeguy/augments/plugins/augments/skills/system-architecture

Use after the requirements are set, when a non-trivial system needs designing before it's built — components, boundaries, data flow, and the seams that keep it testable. Skip for a small feature; its structure lives in the plan.From its SKILL.md

Install
npx -y skills add NjoyimPeguy/augments --skill system-architecture

Assembled from the repository path, not quoted from the project. Check it against their README if it does not work.

One thing to look at

  • 1 stars1 stars. Stars are a popularity signal and not a quality one, but at this level it is likely that nobody has read this closely except its author, and you would be relying on your own review.

SKILL.md

2.7 KB, 548 tokens by cl100k_base, as published. Nobody here has run it

System Architecture

Design the shape of the solution before anyone builds it: what the pieces are, how they fit, and where the seams go. Aim for deep modules, not a sprawl of shallow ones.

When to use

  • You have approved requirements and the work is non-trivial — a new subsystem, several components, real integration.
  • Skip for a small feature; its structure lives in writing-plans' interface map, not a separate design.

Procedure

  1. Components and boundaries. Name each module by what it does and what it deliberately doesn't. A module earns its place if removing it would spread its complexity across the callers; if complexity merely relocates, it's shallow — merge it.
  2. Data flow. Trace the request/response and event paths end to end. Each should be followable from entry to effect.
  3. External services. Map every third party (payments, mail, realtime, storage). For each, state the testability strategy: how you trace the data path through it, and how you behave — and test — when it's unavailable.
  4. Seams. Put boundaries where you'd swap an implementation, and inject across them. Don't add a port for a hypothetical seam — two real adapters justify one; one doesn't.
  5. Decide the load-bearing choices deliberately. For each significant, hard-to-reverse structural decision, weigh the real options and record the result as an ADR — architecture-decisions owns how to weigh them.
  6. Name things in the domain's language, not generic "service / manager / handler". The vocabulary is itself a design decision.
  7. Write the architecture section of the shared design document .augments/designs/{{YYYY-MM-DD}}-{{topic}}.md (the standard designs location; another path only if the user has set one).

Common mistakes

  • Shallow modules — an interface as wide as the implementation behind it.
  • Untested external-service paths — "it'll work in prod" is not a design.
  • Designing for hypothetical futures (a port with one adapter, "for extensibility").
  • Generic vocabulary that hides the domain.

For a high-stakes design, once the document is compiled, dispatch references/design-review.md — a fresh subagent that checks the whole design before anyone builds against it.

The module-design terms used here (deep module, seam, adapter, leverage) are defined once in refactor-architecture's references/vocabulary.md — both skills use them with the same meaning.

What ships with it: 1 file

3.1 KB alongside SKILL.md

references/

Gives 0 of the 12 instructions most architecture codebase skills give in 548 tokens

Counted across 811 of the 1,134 authors here whose files we hold, read 2026-08-07

  • Ask the user which candidate to explorein 45 of 811, across 15 files
  • Apply the deletion test to suspected shallow modulesin 43 of 811, across 15 files
  • Read any relevant architecture decision records firstin 31 of 811, across 8 files
  • Use exact glossary terms in every suggestionin 30 of 811, across 10 files
  • Accept dependencies instead of creating themin 24 of 811, across 5 files
  • Include before and after visualisations for each candidatein 24 of 811, across 5 files
  • Read the domain glossary before exploringin 24 of 811, across 6 files
  • Return results instead of producing side effectsin 23 of 811, across 4 files
  • Explore the codebase for shallow modules and frictionin 23 of 811, across 3 files
  • Introduce seams only where things varyin 22 of 811, across 3 files
  • Reduce the number of methodsin 21 of 811, across 2 files
  • Design deep modules with small interfacesin 21 of 811, across 3 files

Said here and by no other author read

  • Define what each module does and excludes
  • Merge modules that merely relocate complexity
  • State testability strategy for every external service
  • Place boundaries where implementations swap
  • Require two real adapters to justify one port
  • Record hard-to-reverse structural decisions as ADRs

Grouped from the skills themselves: near-identical wordings counted once, and counted by distinct author, so one author publishing three of these counts once. Length counted with cl100k_base; the agent that loads this file may tokenize it differently.

Keep looking

Skills are one crate of 326,736. Ordering is by how many stacks a row turns up in, so the top of any crate is what has actually been picked rather than what has the most stars.