architecture-planning
Create detailed architecture plans with decision records and risk assessments. Use when planning significant features or system changes.
Best use case
architecture-planning is best used when you need a repeatable AI agent workflow instead of a one-off prompt.
Create detailed architecture plans with decision records and risk assessments. Use when planning significant features or system changes.
Teams using architecture-planning should expect a more consistent output, faster repeated execution, less prompt rewriting.
When to use this skill
- You want a reusable workflow that can be run more than once with consistent structure.
When not to use this skill
- You only need a quick one-off answer and do not need a reusable workflow.
- You cannot install or maintain the underlying files, dependencies, or repository context.
Installation
Claude Code / Cursor / Codex
Manual Installation
- Download SKILL.md from GitHub
- Place it in
.claude/skills/architecture-planning/SKILL.mdinside your project - Restart your AI agent — it will auto-discover the skill
How architecture-planning Compares
| Feature / Agent | architecture-planning | Standard Approach |
|---|---|---|
| Platform Support | Not specified | Limited / Varies |
| Context Awareness | High | Baseline |
| Installation Complexity | Unknown | N/A |
Frequently Asked Questions
What does this skill do?
Create detailed architecture plans with decision records and risk assessments. Use when planning significant features or system changes.
Where can I find the source code?
You can find the source code on GitHub using the link provided at the top of the page.
SKILL.md Source
# Architecture Planning Skill
## Purpose
Produce consistent, thorough architecture documentation for system design.
## When to Use
- Planning significant feature implementations
- Making technology or pattern decisions
- Designing new modules or services
- Before major refactoring efforts
- System integration planning
## Templates
### Main Templates
- [templates/architecture-doc.md](templates/architecture-doc.md) - Full architecture document
- [templates/decision-record.md](templates/decision-record.md) - ADR (Architecture Decision Record) format
- [templates/risk-assessment.md](templates/risk-assessment.md) - Risk matrix template
### Pattern Library
Reference established architectural patterns:
- [patterns/microservices.md](patterns/microservices.md) - Microservices architecture
- [patterns/monolith.md](patterns/monolith.md) - Monolithic architecture
- [patterns/serverless.md](patterns/serverless.md) - Serverless architecture
## Decision Framework
### When to Create an ADR
Create a formal Architecture Decision Record when:
- Choosing between technologies (database, framework, library)
- Selecting architectural patterns (monolith vs microservice)
- Defining integration approaches (sync vs async)
- Making security model changes
- Decisions that are hard to reverse
### ADR Format (Lightweight)
```markdown
# ADR-[N]: [Title]
**Status:** Proposed | Accepted | Deprecated | Superseded
**Date:** [YYYY-MM-DD]
## Context
[Why is this decision needed? What's the situation?]
## Decision
[What was decided?]
## Consequences
[What follows from this decision?]
```
## Risk Assessment Matrix
Use this matrix to categorize risks:
| Probability ↓ / Impact → | Low | Medium | High |
|---------------------------|-----|--------|------|
| **High** | Medium | High | Critical |
| **Medium** | Low | Medium | High |
| **Low** | Low | Low | Medium |
### Risk Categories
- **Technical**: Technology limitations, complexity, performance
- **Timeline**: Schedule impacts, dependencies
- **Integration**: External system dependencies, API changes
- **Security**: Vulnerabilities, compliance requirements
- **Operational**: Deployment, monitoring, maintenance
## Architecture Document Sections
### Required Sections
1. **Overview** - High-level description
2. **Design Decisions** - Key choices with rationale
3. **Component Design** - Responsibilities and interfaces
4. **Risk Assessment** - Identified risks and mitigations
### Optional Sections (as needed)
- Data Flow diagrams
- Integration Points
- Security Considerations
- Performance Requirements
- Migration Strategy
## Quality Checklist
Before finalizing an architecture document:
- [ ] All major decisions documented with options considered
- [ ] Rationale provided for each decision
- [ ] Trade-offs explicitly stated
- [ ] Risks identified with mitigation strategies
- [ ] Aligns with existing codebase patterns (from research)
- [ ] Integration points clearly defined
- [ ] Component responsibilities are clear and non-overlapping
- [ ] Security implications considered
- [ ] Performance requirements addressed
## Output Location
Save architecture documents to: `docs/plans/architecture-{session}.md`
Save ADRs to: `docs/plans/adr-{number}-{title}.md`
## Integration with Workflow
1. **Research phase** provides codebase context and patterns
2. **Questioning phase** provides validated requirements
3. **Architecture planning** creates design documents (this skill)
4. **Task breakdown** converts architecture to executable tasks
5. **Implementation** follows the approved planRelated Skills
backend-architecture
Design and implement scalable backend infrastructure, microservices, and system architecture patterns.
astro-architecture
Technical architecture for Astro lead generation websites. Use when setting up new projects, configuring build tools, or establishing project foundations. For images use astro-images skill. For SEO use astro-seo skill.
assessing-architecture-quality
Use when assessing codebase architecture and you feel pressure to soften critique, lead with strengths, or frame problems diplomatically - provides evidence-based critical assessment resisting relationship and economic pressures
architecture
Comprehensive system architecture design and implementation workflow that orchestrates expert analysis, technical decision-making, and architectural pattern selection using the integrated toolset. Handles everything from initial system analysis to implementation-ready technical specifications.
architecture-workshop
Framework for designing new architectural mechanisms when existing patterns don't fit
architecture-validator
Validate hexagonal architecture (Domain, Application, Infrastructure, Presentation). Use when creating new files in src/, reorganizing code, or when the user requests architecture validation.
architecture-validation
Dynamically validate codebase compliance with architectural decisions and constraints
architecture-to-json
Guide for extracting architectural diagrams, flowcharts, and sequence diagrams into a structured JSON format. Use this skill when you need to transform a visual or textual description of a system architecture or workflow into a clear, structured JSON representation.
architecture-tech-lead
This skill should be used when the user asks to 'review my architecture', 'improve testability', 'refactor for testing', 'reduce mocking in tests', 'too many mocks', 'extract pure functions', 'functional core imperative shell', 'design a feature', 'evaluate approaches', 'make code more testable', 'domain modeling', 'DDD design', 'bounded contexts', 'too much coupling', or needs architectural validation for Java/Spring Boot or TypeScript/Next.js codebases. Use for design decisions, not implementation.
architecture-synthesis
Generate a reference architecture specification from analyzed frameworks. Use when (1) designing a new agent framework based on prior art, (2) defining core primitives (Message, State, Tool types), (3) specifying interface protocols, (4) creating execution loop pseudocode, or (5) producing architecture diagrams and implementation roadmaps.
architecture-strategist
Use this agent when analyzing code changes from an architectural perspective, evaluating system design decisions, or ensuring changes align with established architectural patterns. Triggers on requests like "architecture review", "design evaluation", "system architecture analysis".
architecture-status
Reports on the health and state of architecture documentation (counts of ADRs, reviews, activity levels, documentation gaps). Use when the user asks "What's our architecture status?", "Show architecture documentation", "How many ADRs do we have?", "What decisions are documented?", "Architecture health check", or wants an overview/summary of documentation state. Do NOT use for listing team members (use list-members), creating new documents (use create-adr), or conducting reviews (use architecture-review or specialist-review).