From arch-crew
Use when choosing or assessing software architecture — picking a structure/topology for a new system, or reviewing whether an existing codebase's architecture fits. Triggers on questions like 'how should I structure this service', 'should this be microservices or a monolith', 'is our layering right', 'we're adding events/CQRS/a queue — does it fit', or any greenfield architecture decision or architecture-focused code review. Branches automatically: greenfield → a short selection interview that composes a stack; existing code → a review against the pattern catalog with targeted moves. Reach for this even when the user hasn't named a specific pattern.
How this skill is triggered — by the user, by Claude, or both
Slash command
/arch-crew:decide-architectureThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
Architecture is not one list with a single winner — it is **several axes that compose**: how code
Architecture is not one list with a single winner — it is several axes that compose: how code is structured inside a deployable, how processes split and talk, how data is refined, plus overlays. A real system picks one per axis that applies and skips the rest. The job of this skill is to make those picks deliberately, and — crucially — to recommend the least architecture that meets the requirement. Every axis you add buys capability at the price of operational complexity; each one must earn its place. Over-architecting a thin CRUD app is as much a failure as under-architecting a system that genuinely needs microservices.
The knowledge lives in two references you read on demand, so this file stays a workflow:
references/decision-tree.md — the greenfield selection interview (the questions, in order).references/catalog.md — every pattern: when to reach for it, its cost, and the review cue
(what it looks like in code, and the smell that says "introduce this").Everything branches on one question: greenfield or refactoring? Are we choosing an architecture for something new, or assessing/evolving code that already exists?
Usually the request makes it obvious ("I'm starting a new payments service" = greenfield; "is our monolith's layering right?" = refactoring). If it's genuinely ambiguous, ask — one short question. Don't ask if there's a clear signal (a repo to read, a named existing system → refactoring; a blank slate or "I'm about to build" → greenfield).
If the user is building an agentic / LLM system (an agent that reasons, calls tools, and acts),
that's a different axis set — say so and hand off to the agentic-patterns skill, which owns that
decision tree. This skill covers regular software systems.
Read references/decision-tree.md and walk it.
references/catalog.md so every recommendation carries
its trade-off, not just a name.Output — a "Your stack" summary the user can act on:
## Your architecture stack
| Axis | Pick | Why it fits | Cost to accept |
|------|------|-------------|----------------|
| Structure | <pattern> | <one line> | <one line> |
| Topology | <pattern> | ... | ... |
| ...only the axes that apply... |
**Also consider:** <contextual notes>
**The least-architecture check:** <one or two sentences confirming nothing here is speculative —
or flagging any axis the user could defer until a real forcing function appears.>
Here the deliverable is an honest assessment, not a fantasy redesign. The bias is toward the smallest change that removes real pain — never a rewrite unless the evidence demands it.
references/catalog.md to read the code's intent.
Not every system maps to every axis — a CLI tool, a library, a static frontend, or a
scientific script may have no meaningful Topology or Data axis. Mark those n/a instead of
forcing a label; the catalog cues lean toward request-serving backends, so down-scale them for
other shapes. And before counting files, separate product code from content/fixtures/vendored
deps so size doesn't mislead you.Output — a review the user can prioritise:
## Architecture review
**Current shape:** Structure: <…> · Topology: <…> · Data: <…> · UI: <…>
### Findings
1. **<smell / mismatch>** — <where, with file refs> · Impact: <the real pain> ·
Move: <pattern to introduce> (`catalog` ref) · First step: <smallest safe change> · Cost: <…>
2. ...
**Leave alone:** <parts that are fine as-is — say so explicitly, so the user doesn't over-correct.>
A clean bill of health is a valid result. If the architecture is already right-sized for what the system is, say so plainly and keep the report short — name the current shape, confirm it fits, list nothing-to-do. Inventing findings to look thorough is itself a failure mode; a well-sized small app needs no refactor, and the most useful thing you can tell its author is "leave it."
A decision that lives only in a chat transcript is lost. Persist it.
Greenfield → an ADR. After presenting the stack, write docs/adr/NNNN-short-title.md (lowercase
words joined by hyphens, e.g. 0001-modular-monolith-with-hexagonal-core.md) — a 4-digit number,
one past the highest existing ADR in docs/adr/ (else 0001). Create docs/adr/ if absent. Use
this MADR-style template:
# NNNN. <decision title, e.g. "Adopt a modular monolith with a hexagonal core">
- Status: Accepted
- Date: <YYYY-MM-DD>
- Deciders: <the user / team, if known>
## Context
<the forces from the interview — what's being built, and the load / team / domain facts that drove
each axis. This is *why*, not just what.>
## Decision
<the composed stack: the axis · pick · why table you just presented>
## Consequences
<the cost accepted for each pick, the contextual notes triggered (gateway/mesh/stability/…), and
the least-architecture caveat: which axes were deferred and the concrete signal that would reopen
them.>
Refactoring → a review report. Write the review to docs/architecture-review-<YYYY-MM-DD>.md
(create docs/ if absent — Current shape + Findings + Leave-alone; short if the system is sound).
If a finding is a direction the user commits to, offer to capture that one as its own ADR too.
Write the file and report its path. Ask first only if the repo layout is unclear or the user is clearly still just exploring options rather than deciding.
Naming the trade-off for every pick is deliberate: an architecture recommendation without its cost is just fashion, and fashion is how teams end up with distributed monoliths and CQRS on a CRUD app. The greenfield/refactoring split matters because the two situations have opposite risks — greenfield tempts you to add patterns "for later"; legacy tempts you to rewrite. Both are resisted by the same principle: change the architecture only as fast as a real requirement forces it.
npx claudepluginhub adamkrysztopa/architectural-decisions --plugin arch-crewProvides UI/UX resources: 50+ styles, color palettes, font pairings, guidelines, charts for web/mobile across React, Next.js, Vue, Svelte, Tailwind, React Native, Flutter. Aids planning, building, reviewing interfaces.
Fetches up-to-date documentation from Context7 for libraries and frameworks like React, Next.js, Prisma. Use for setup questions, API references, and code examples.