Super Architecture

One skill, three axes. Call it once. It works out the job, then loads only the style and stack guides that job needs, plus the shared core principles.

New style, stack or job: add one folder or file and one row in styles/README.md or the matching table below. Nothing else changes.

Step 0: detect the job and the context

Do this first and do not announce it.

1. Is there code? If yes, run node scripts/arch-scan.mjs detect <dir> and read its evidence, then open two or three files on the main request path. Never name a style from folder names alone; confirm the dependency direction from imports.
2. Is it greenfield? Gather only what is missing: team size and experience, business-rule complexity, stack, how often infrastructure changes, number of entry points (HTTP, CLI, queue, gRPC), test requirements, deployable shape (one process or many), traffic pattern.
3. Pick the job from the table, state it in one line, and load its guide.

Jobs

For a standalone ADR request, use write-adr. When an architecture selection also needs a decision record, pass the chosen option and evidence to write-adr. When write-adr invoked this skill for an unresolved choice, return the recommendation and evidence to it; do not call it again from this pass.

Common chains: greenfield is select, build, document. Legacy is detect, evaluate, migrate, then verify. Review is detect, then evaluate with a short report.

Styles

Two independent axes. Pick one in-process structure, add domain-driven only when the business has a language to model, and pick a deployable shape when the unit of deploy matters. Full catalog with grouping: styles/README.md.

Styles combine. A typical modern service is hexagonal or vertical-slice at the top level, with CQRS inside the slices that need it, inside a modular monolith or a single process. Each guide has a "Combines with" section.

Stacks

Core principles

Load the matching file when a job needs more than the summary here.

Rules that hold in every style

1. Follow the project first. Detect before prescribing. Do not rewrite a working structure to match a favorite pattern; move one slice at a time.
2. Right-size. Use the simplest structure that keeps the rules intact. Upgrade when a measurable pain appears, not in anticipation.
3. Dependencies point inward. The inside defines the abstractions it needs; the outside implements them.
4. The core knows no framework. Domain and use-case code import no web, ORM, queue or SDK types. Adapters stay thin. One composition root wires everything.
5. Name business intent. PlaceOrder, not updateOrder. Folders should show what the system does before they show what it is built with.
6. One aggregate per transaction. Inside an aggregate, consistency is immediate. Between aggregates, use IDs and events.
7. Abstract only where it pays. A port needs volatility, a test seam or a team boundary. Share code only after two real consumers prove identical meaning.
8. Make claims checkable. Back structure with scan output, architecture tests and diagrams derived from the code, each with file paths.
9. Record the decision with its trade-off through write-adr when requested or required by repository convention.
10. Verify before claiming. Use the verify gate: run the scan and tests, read the output, then say what holds.

Output by job

Detect returns a style, a confidence, evidence with paths, deviations and violation candidates. Select returns one recommendation, its reasons, what would change it, and an ADR. Build returns the structure and code plus the check that proves the boundaries hold. Evaluate returns a scored report and a prioritized roadmap. Migrate returns phases, a rollback path and the first slice. Document returns diagrams and records grounded in paths.

Related skills

• codebase-learner: you need facts about the current system first.
• super-tech-blueprint: the style is chosen and the stack is not.
• challenge-me: stress-test the choice before you commit to it.
• safe-refactor: move an existing codebase toward the chosen style, one safe step at a time.
• super-nodejs: build the chosen style in a Node service.

Done when

• The job, style and stack were named, and only the guides they need were opened.
• Recommendations fit the detected project, or state why they deviate.
• Dependency direction was checked with scripts/arch-scan.mjs check or an architecture test, and the result was read.
• Any decision is recorded with its trade-off, and any claim names the file it came from.