arch-crew: a plugin for deciding (and auditing) architecture

There's a failure mode I keep hitting, in my own work and in other people's. You reach for an architecture, a pattern, or an agent framework because it's the thing you've heard of, not because the problem actually needs it. The result is a microservice that wanted to be a function, a FactoryProviderStrategy wrapping a one-line if, or a ReAct loop burning tokens on a task a single prompt would have handled.

arch-crew is three Claude Code skills that push the other way: recommend the least architecture that meets the requirement, and name the cost of every step up.

What it is

Three skills. Each one first works out where you are: starting fresh (greenfield) or working in code that already exists (refactoring). From there it either runs a short selection interview or reviews what you have against a catalog.

• decide-architecture — structure, topology, data, overlays. Compose a stack, or audit the one you've already got.
• design-patterns — GoF and Python-idiomatic patterns. Which one fits, and often the answer is "a plain function."
• agentic-patterns — design or assess an LLM-agent system layer by layer, starting from the least autonomy that does the job.

The through-line in all three: do less, and know what each "more" costs you.

When you'd reach for it

A few situations it was built for:

• You're reaching for Clean Architecture on reflex. Onion, Hexagonal, and Ports-and-Adapters are real tools, but a three-endpoint CRUD service pays their abstraction tax for nothing. The architecture wizard asks what actually drives change in your code before it names a topology. It's just as happy to land you on a modular monolith with vertical slices as on anything fancier; the default isn't the layered diagram everyone draws, it's whatever your change rate justifies. The data question is now its own taxonomy that splits four things people flatten into one — where data lives, how it's refined, how it's processed, and who owns it — so "we have data" composes into a specific platform instead of a hand-wave.
• You've got spaghetti and have to fix it. Refactoring is where the pain lives, and where the wrong move costs weeks. Point the refactoring mode at the mess and it reads the code, finds the seams, and hands you targeted moves rather than a rewrite or a lecture. It tells you which boundary is worth the pain and which is just cargo-culting someone else's diagram.
• You're writing Python and not sure which pattern applies. Half the GoF catalog dissolves in a language with first-class functions, closures, and dataclasses. The design-patterns wizard walks you to the pattern that fits and its Pythonic form, including when the honest answer is that you don't need a pattern at all. It now has a whole section for the patterns people routinely confuse — Chain of Responsibility vs Decorator, Strategy vs Policy — and grounds the choice in the design principles behind the catalog rather than treating it as a checklist.
• Not every agent needs to be ReAct. A single well-prompted call beats a workflow, a fixed pipeline beats a loop, and a loop beats a swarm, right up until the task genuinely needs the rung above. The agentic wizard starts at the bottom of that ladder and climbs only when you make the case. Its autonomy gate now cuts both ways: it still pushes you down toward the least autonomy that works, but it also catches the opposite mistake — the case where a real iterative loop (agentic RAG that decides what to retrieve and re-queries on weak evidence) gets waved off as "just preprocessing" when it's genuinely an agent.

Where it came from

Before any of this was a plugin, it was three long HTML pages I'd built to think through these decisions for myself: clickable decision trees I kept open in a tab. The skills are those references distilled into a workflow, and the wizards below are those same pages, re-skinned to live here.

Two ways to use it

1. Click through a tree yourself. Open a wizard, answer the questions, and walk out the other side with a recommendation you can argue with. No install, nothing to set up.
2. Less sure? Let the skill interview you. Install the plugin in Claude Code and just describe your decision. The right skill triggers, asks what it needs, and composes an answer against your actual code.

/plugin marketplace add AdamKrysztopa/architectural-decisions
/plugin install arch-crew

Repo: github.com/AdamKrysztopa/architectural-decisions

The three wizards

• Software Architecture Patterns
• Agentic System Patterns
• Design Patterns (GoF / Pythonic)