216 lines
5.6 KiB
Markdown
216 lines
5.6 KiB
Markdown
---
|
|
name: agileflow-adr
|
|
description: Detects architectural or technical decisions in conversations and formats them as Architecture Decision Records in docs/03-decisions/. Loads when discussing technology choices, architecture patterns, or trade-offs.
|
|
allowed-tools: Read, Write, Edit, Glob
|
|
---
|
|
|
|
# AgileFlow ADR (Architecture Decision Records)
|
|
|
|
## Purpose
|
|
|
|
This skill automatically captures architectural and technical decisions from conversations and formats them as formal Architecture Decision Records (ADRs) in `docs/03-decisions/`.
|
|
|
|
## When This Skill Activates
|
|
|
|
Load this skill when:
|
|
- Discussing technology choices ("Should we use PostgreSQL or MongoDB?")
|
|
- Debating architecture patterns ("REST vs GraphQL")
|
|
- Making framework decisions ("React vs Vue")
|
|
- Discussing infrastructure choices ("AWS vs GCP")
|
|
- Evaluating trade-offs between options
|
|
- User mentions "decision", "choose", "architecture", "trade-off"
|
|
|
|
## ADR Format (MADR - Markdown Architecture Decision Records)
|
|
|
|
```markdown
|
|
# [ADR-###] Title
|
|
|
|
**Date**: YYYY-MM-DD
|
|
**Status**: Proposed | Accepted | Deprecated | Superseded
|
|
**Deciders**: Names of people involved
|
|
**Tags**: architecture, database, api, etc.
|
|
|
|
## Context and Problem Statement
|
|
|
|
[Describe the context and the problem that led to this decision.
|
|
What are we trying to solve? Why is this decision necessary?]
|
|
|
|
## Decision Drivers
|
|
|
|
- [Driver 1: e.g., Performance requirements]
|
|
- [Driver 2: e.g., Team expertise]
|
|
- [Driver 3: e.g., Cost constraints]
|
|
|
|
## Considered Options
|
|
|
|
- [Option 1]
|
|
- [Option 2]
|
|
- [Option 3]
|
|
|
|
## Decision Outcome
|
|
|
|
**Chosen option**: [Option X]
|
|
|
|
**Justification**: [Why was this option chosen? What makes it the best fit for our context?]
|
|
|
|
### Positive Consequences
|
|
|
|
- [Good outcome 1]
|
|
- [Good outcome 2]
|
|
|
|
### Negative Consequences
|
|
|
|
- [Bad outcome 1]
|
|
- [Bad outcome 2 - with mitigation plan if possible]
|
|
|
|
## Pros and Cons of the Options
|
|
|
|
### [Option 1]
|
|
|
|
**Pros**:
|
|
- [Pro 1]
|
|
- [Pro 2]
|
|
|
|
**Cons**:
|
|
- [Con 1]
|
|
- [Con 2]
|
|
|
|
### [Option 2]
|
|
|
|
**Pros**:
|
|
- [Pro 1]
|
|
- [Pro 2]
|
|
|
|
**Cons**:
|
|
- [Con 1]
|
|
- [Con 2]
|
|
|
|
### [Option 3]
|
|
|
|
**Pros**:
|
|
- [Pro 1]
|
|
- [Pro 2]
|
|
|
|
**Cons**:
|
|
- [Con 1]
|
|
- [Con 2]
|
|
|
|
## Links
|
|
|
|
- [Related ADRs]
|
|
- [Relevant documentation]
|
|
- [External resources]
|
|
|
|
## Notes
|
|
|
|
- [Additional information]
|
|
- [Implementation notes]
|
|
- [Review date if applicable]
|
|
```
|
|
|
|
## Workflow
|
|
|
|
1. **Detect decision discussion**: User is debating options or asking "which should we use?"
|
|
|
|
2. **Ask clarifying questions** if needed:
|
|
- "What problem are you trying to solve?"
|
|
- "What options are you considering?"
|
|
- "What are your constraints (cost, time, expertise)?"
|
|
|
|
3. **Extract decision elements**:
|
|
- Context/problem
|
|
- Options being considered
|
|
- Trade-offs for each option
|
|
- Decision drivers (requirements, constraints)
|
|
|
|
4. **Read existing ADRs**:
|
|
- Check `docs/03-decisions/` for numbering
|
|
- Look for related decisions
|
|
|
|
5. **Generate ADR**:
|
|
- Create file: `docs/03-decisions/ADR-###-descriptive-title.md`
|
|
- Fill in all sections with gathered information
|
|
- Mark status as "Proposed" unless decision is final
|
|
|
|
6. **Confirm with user**: Show the ADR and ask for corrections
|
|
|
|
## ADR Statuses
|
|
|
|
- **Proposed**: Under consideration, not yet decided
|
|
- **Accepted**: Decision made and approved
|
|
- **Deprecated**: No longer relevant (but kept for history)
|
|
- **Superseded**: Replaced by a newer decision (link to new ADR)
|
|
|
|
## Decision Drivers (Common Examples)
|
|
|
|
- **Performance requirements** (latency, throughput)
|
|
- **Scalability needs** (expected growth)
|
|
- **Team expertise** (learning curve)
|
|
- **Cost constraints** (budget, licensing)
|
|
- **Time to market** (urgency)
|
|
- **Maintenance burden** (long-term support)
|
|
- **Ecosystem maturity** (libraries, community)
|
|
- **Security requirements** (compliance, encryption)
|
|
- **Integration needs** (existing systems)
|
|
|
|
## Quality Checklist
|
|
|
|
Before creating ADR:
|
|
- [ ] Problem statement is clear and specific
|
|
- [ ] At least 2 options were considered
|
|
- [ ] Each option has pros and cons listed
|
|
- [ ] Decision drivers are explicitly stated
|
|
- [ ] Chosen option has clear justification
|
|
- [ ] Consequences (both positive and negative) are documented
|
|
- [ ] File name follows pattern: ADR-###-descriptive-title.md
|
|
- [ ] Status is appropriate (Proposed/Accepted)
|
|
|
|
## Examples
|
|
|
|
See `examples/` directory for well-formed ADRs across different domains.
|
|
|
|
## Tags (Common)
|
|
|
|
- `architecture` - Overall system design
|
|
- `database` - Data storage choices
|
|
- `api` - API design decisions
|
|
- `infrastructure` - Cloud, hosting, deployment
|
|
- `frontend` - UI framework, state management
|
|
- `backend` - Server framework, language
|
|
- `security` - Authentication, encryption
|
|
- `testing` - Test strategy, tools
|
|
- `cicd` - CI/CD pipeline choices
|
|
- `monitoring` - Observability tools
|
|
|
|
## Linking ADRs
|
|
|
|
When decisions build on or replace each other:
|
|
|
|
```markdown
|
|
## Links
|
|
|
|
- Supersedes [ADR-042: Use REST API](./ADR-042-use-rest-api.md)
|
|
- Related to [ADR-056: API Authentication](./ADR-056-api-authentication.md)
|
|
- Informs [ADR-073: Rate Limiting Strategy](./ADR-073-rate-limiting.md)
|
|
```
|
|
|
|
## Integration with Other Skills
|
|
|
|
- **agileflow-story-writer**: ADRs inform technical notes in stories
|
|
- **agileflow-tech-debt**: Negative consequences become tech debt items
|
|
- **agileflow-changelog**: Major decisions appear in changelog
|
|
|
|
## Updating ADRs
|
|
|
|
ADRs are immutable once accepted - don't edit them! Instead:
|
|
- Create a new ADR that supersedes the old one
|
|
- Update status to "Superseded by ADR-XXX"
|
|
|
|
## Notes
|
|
|
|
- Capture decisions even if they seem small - they provide context later
|
|
- Be honest about negative consequences - helps with future decisions
|
|
- Include who made the decision (deciders) - accountability matters
|
|
- Date decisions - context changes over time
|
|
- Keep ADRs focused - one decision per ADR
|