From solo-sdlc
Design the system architecture from an approved PRD. Use this skill in Phase 3 of every feature, AFTER PRD is approved and BEFORE writing any code. Triggers on requests for system design, architecture, design doc, "how to build this", tech choices, or component design. Produces a design doc with C4 diagrams, ADRs, and a solutioning gate check.
How this skill is triggered — by the user, by Claude, or both
Slash command
/solo-sdlc:architectureThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
After `docs/specs/<feature>/prd.md` is approved. This is Phase 3.
After docs/specs/<feature>/prd.md is approved. This is Phase 3.
docs/specs/<feature>/brief.mddocs/specs/<feature>/prd.mddocs/specs/<feature>/glossary.md (if exists)docs/architecture/adr/ (review prior decisions to avoid contradictions)Before recommending any library, fetch its current docs via Context7. Do not rely on training-data knowledge for libraries that change fast.
If the brief mentions multiple bounded contexts or complex business rules, run the ddd-modeling skill first to identify aggregates, entities, value objects, and bounded contexts.
Write docs/architecture/<feature>/design.md:
# <Feature> - Architecture Design
## 1. Context (C4 Level 1)
What this system does, who uses it, what external systems it talks to.
## 2. Containers (C4 Level 2)
Each deployable unit: web app, API, worker, DB, cache, queue.
| Container | Tech | Responsibility | Dependencies |
|---|---|---|---|
| ... | ... | ... | ... |
## 3. Components (C4 Level 3, for the most complex container)
Internal modules of the main service.
## 4. Data Architecture
- Primary store: <DB and why>
- Schema overview: <key tables/collections, relationships>
- Migration strategy: <how schema evolves>
- Data lifecycle: <retention, archival, deletion>
## 5. API Contracts
- External APIs exposed: <list with versioning approach>
- External APIs consumed: <list with fallback strategies>
- Internal contracts: <message formats, RPC schemas>
## 6. Cross-Cutting Concerns
### Authentication
<method, libraries, session handling>
### Authorization
<RBAC/ABAC model, enforcement points>
### Observability
- Logs: <structured format, fields, destination>
- Metrics: <names, labels, alerts>
- Traces: <propagation strategy>
### Error Handling
<global strategy: retries, circuit breakers, fallbacks>
### Configuration & Secrets
<source: env vars, vault, k8s secrets>
## 7. Deployment Architecture
- Environment topology
- CI/CD pipeline outline
- Rollback strategy
## 8. Performance & Scale
Map each NFR-Performance target to specific design choice that delivers it.
## 9. Security Threat Model
- Top 3-5 threats
- Mitigations per threat
- Residual risk acknowledged
## 10. Architecture Decision Records (ADRs)
List ADRs created for this design. Each ADR is a separate file:
`docs/architecture/adr/NNNN-decision-name.md`
## 11. Open Risks & Recommendations
(MANDATORY)
- Choices made under uncertainty
- Things that should be load-tested before launch
- Patterns that may not scale to 10x current targets
- Library choices that may be wrong but are fastest now
For every meaningful technical choice, create an ADR using adr-writer skill. Examples of decisions worth an ADR:
Score 0-100:
| Criterion | Points |
|---|---|
| Every FR maps to one or more design components | 20 |
| Every NFR has a specific technical solution | 20 |
| External dependencies all have fallback strategies | 15 |
| Security threat model is concrete | 15 |
| Performance design matches targets with sizing math | 15 |
| ADRs exist for all major choices | 10 |
| Open risks are <5 and acknowledged | 5 |
< 80 = revise before proceeding to implementation.
Tell user: design ready, gate score X/100. Next phase: implementation, starting with the first slice in the user stories.
Bad architecture doc: "We will use microservices and Kubernetes for scalability."
Good architecture doc:
The order processing path runs as a single Go service with Kafka for async work. We chose Kafka over RabbitMQ for ADR-0008 reasons. Order events are partitioned by customer ID to preserve order within customer. Expected throughput: 1k orders/sec, partitioned across 16 partitions = 60 orders/sec/partition, well under our measured 500 orders/sec/partition single-consumer baseline.
After publishing the design, always include:
npx claudepluginhub shakhovskiya-create/shakhoff-claude-marketplace --plugin solo-sdlcProvides behavioral guidelines to reduce common LLM coding mistakes, focusing on simplicity, surgical changes, assumption surfacing, and verifiable success criteria.
Searches, retrieves, and installs Agent Skills from prompts.chat registry using MCP tools like search_skills and get_skill. Activates for finding skills, browsing catalogs, or extending Claude.