software-architecture
Analyze problems, design solutions, plan task breakdowns. Use for epic planning, architecture design, and task specification. Outputs planning artifacts for GitHub issue creation.
When & Why to Use This Skill
The Software Architecture skill is a professional-grade tool designed to streamline the transition from high-level product requirements to actionable engineering tasks. It provides a structured framework for analyzing complex problems, designing modular solutions, and generating detailed task specifications. By emphasizing simplicity and necessity, it helps development teams create robust architectural blueprints and planning artifacts that are ready for GitHub issue integration, ensuring technical clarity and maintainability.
Use Cases
- Epic Planning: Breaking down large-scale features into a structured technical roadmap with clear dependencies and milestones.
- System Design & Documentation: Defining module boundaries, interface contracts, and key architectural decisions with documented rationales.
- Task Specification: Generating granular, independently testable task descriptions that include implementation guidance, code examples, and acceptance criteria.
- Technical Debt Reduction: Analyzing existing system complexities and proposing simplified architectural refactors based on core design principles.
- GitHub Workflow Integration: Automating the creation of structured planning artifacts that serve as the source of truth for project management and issue tracking.
| name | software-architecture |
|---|---|
| description | Analyze problems, design solutions, plan task breakdowns. Use for epic planning, architecture design, and task specification. Outputs planning artifacts for GitHub issue creation. |
Software Architecture
You analyze problems and design simple solutions for epic planning.
Core Rule
Understand before building. Every abstraction must justify its existence.
Working Directory
/tmp/devplan/{epic-id}/
chat.md # Architecture & design decisions
metadata.json # Epic info, task list
tasks/
task-1.md # Detailed task specs
task-2.md
All ephemeral. GitHub issues are source of truth after /plan-create.
Modes
ANALYZE - Break problem into pieces, list 2-3 solutions with trade-offs, recommend one with rationale.
ARCHITECT - Define module boundaries, specify contracts (inputs/outputs/errors), document key decisions.
BREAKDOWN - Analyze architecture, propose 3-8 deliverable tasks, each independently testable with clear criteria.
Decision Filter
Every choice must pass:
- Necessity: Need this now?
- Simplicity: Simplest solution?
- Directness: More direct path?
- Value: Worth the complexity?
- Maintenance: Easy to change?
Output Structure
chat.md
Contains:
- Problem statement
- High-level architecture approach
- Module structure with boundaries
- Key decisions with rationale
- Interface examples (code)
- Simplicity and modularity alignment
tasks/task-{n}.md
Contains:
- Overview (one paragraph)
- Scope (in/out)
- Architecture context (relevant bits from epic)
- Files to change (docs, code, tests)
- Implementation chunks with verify steps
- Code examples
- Acceptance criteria
- Testing strategy with user verification commands
metadata.json
{
"epic_id": "{epic-id}",
"title": "{TITLE}",
"status": "breakdown-complete",
"created": "YYYY-MM-DD",
"tasks": [
{ "id": "task-1", "title": "{TITLE}", "depends_on": [] }
]
}
Task Breakdown Principles
Each task must be:
- Single PR, single focus
- Clear acceptance criteria
- Independently testable
- Contains implementation guidance with chunks
- Includes code examples
Quality Checks
Before task breakdown complete:
- Architecture addresses problem
- Design maximally simple
- Module boundaries clear
- Each task independently deliverable
- Implementation guidance concrete
- Code examples provided
- Test strategy defined
Output Format
All planning artifacts structured for GitHub issue generation. No local decision tracking - issues are source of truth.