zhongwei/gh-xloxn69-agileflow
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Initial commit

Browse Source
This commit is contained in:
Zhongwei Li
2025-11-30 09:07:10 +08:00
commit 169a5fc5cd
99 changed files with 25560 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

215
skills/agileflow-adr/SKILL.md Normal file
View File

@@ -0,0 +1,215 @@
---
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

122
skills/agileflow-adr/examples/database-choice-example.md Normal file
View File

@@ -0,0 +1,122 @@
# [ADR-012] Use PostgreSQL for Primary Database
**Date**: 2025-01-15
**Status**: Accepted
**Deciders**: Tech Lead, Backend Team, DevOps
**Tags**: database, architecture, backend
## Context and Problem Statement
Our application needs a primary database to store user data, transactions, and analytics. We need to choose a database that supports complex queries, transactions, and can scale with our growing user base (currently 10K users, expecting 100K+ within 6 months).
## Decision Drivers
- **Strong ACID compliance** - Financial transactions require data integrity
- **Complex query support** - Analytics require joins and aggregations
- **Team expertise** - Team has SQL experience but limited NoSQL experience
- **Cost** - Must fit within infrastructure budget (~$200/month)
- **Scalability** - Need to handle 10x growth over 6 months
- **Operational overhead** - Limited DevOps resources for maintenance
## Considered Options
- PostgreSQL
- MongoDB
- MySQL
## Decision Outcome
**Chosen option**: PostgreSQL
**Justification**: PostgreSQL offers the best balance of ACID compliance, query flexibility, and team expertise. While MongoDB could handle our document-like user profiles well, the financial transaction requirements demand strong consistency guarantees. PostgreSQL's JSON support gives us flexibility for semi-structured data without sacrificing transactional integrity.
### Positive Consequences
- Strong ACID guarantees protect financial data
- Team can leverage existing SQL knowledge immediately
- Rich ecosystem of tools (pg Admin, extensions, ORMs)
- JSON/JSONB support provides flexibility for evolving schemas
- Excellent performance for our expected load (<1M rows initially)
- Free and open source - no licensing costs
- Proven scalability path (read replicas, partitioning, Citus extension)
### Negative Consequences
- Vertical scaling limits eventually require sharding strategy
- Less flexible schema changes compared to schema-less databases
- Requires careful query optimization for complex analytics
- Team needs to learn PostgreSQL-specific features (JSONB, window functions)
## Pros and Cons of the Options
### PostgreSQL
**Pros**:
- ✅ Strong ACID compliance with serializable isolation
- ✅ Excellent support for complex queries (JOINs, CTEs, window functions)
- ✅ JSONB for flexible semi-structured data
- ✅ Rich extension ecosystem (PostGIS, pg_trgm, etc.)
- ✅ Free and open source
- ✅ Battle-tested at scale (Instagram, Spotify, GitHub use it)
- ✅ Team has SQL experience
**Cons**:
- ❌ Vertical scaling limits (~10M rows before needing partitioning)
- ❌ Schema migrations require downtime for large tables
- ❌ Write performance lower than NoSQL for high-throughput scenarios
- ❌ Replication complexity for multi-region deployment
### MongoDB
**Pros**:
- ✅ Flexible schema for rapidly evolving data models
- ✅ Horizontal scaling built-in (sharding)
- ✅ Fast writes for high-throughput scenarios
- ✅ Good for document-oriented data (user profiles, products)
- ✅ Built-in replication and failover
**Cons**:
- ❌ Weaker consistency guarantees (eventual consistency by default)
- ❌ Limited transaction support (only multi-document ACID since v4.0)
- ❌ Team has no MongoDB experience (3-6 month learning curve)
- ❌ More expensive managed hosting (~$400/month vs $200 for PostgreSQL)
- ❌ Complex queries less efficient (no JOINs)
- ❌ Analytics require aggregation pipeline (steep learning curve)
### MySQL
**Pros**:
- ✅ Strong ACID compliance
- ✅ Widely used and well-documented
- ✅ Team has SQL experience
- ✅ Good performance for read-heavy workloads
- ✅ Free and open source
**Cons**:
- ❌ Weaker JSON support compared to PostgreSQL
- ❌ Less feature-rich (no CTEs until v8.0, weaker window functions)
- ❌ Replication can be complex (binlog issues)
- ❌ Extension ecosystem less rich than PostgreSQL
- ❌ Oracle ownership concerns (licensing changes)
## Links
- [PostgreSQL JSON Support](https://www.postgresql.org/docs/current/datatype-json.html)
- [Scalability Guide](docs/architecture/postgres-scaling.md)
- [Database Schema Design](docs/architecture/schema-design.md)
- Related: [ADR-013: Use Prisma ORM](./ADR-013-use-prisma-orm.md)
## Notes
- **Migration path**: If we hit PostgreSQL scaling limits (>10M users), we'll evaluate:
1. Citus extension for horizontal scaling
2. Read replicas for read-heavy queries
3. Vertical scaling to larger instances
- **Review date**: 2025-06-15 (6 months) - Assess if decision still holds with actual usage data
- **Monitoring**: Set up alerts for:
- Query performance degradation
- Table size growth
- Replication lag
- Connection pool exhaustion

69
skills/agileflow-adr/templates/adr-template.md Normal file
View File

@@ -0,0 +1,69 @@
# [ADR-###] {Title}
**Date**: {YYYY-MM-DD}
**Status**: {Proposed | Accepted | Deprecated | Superseded}
**Deciders**: {Names}
**Tags**: {tag1, tag2}
## Context and Problem Statement
{Describe the context and problem}
## Decision Drivers
- {Driver 1}
- {Driver 2}
- {Driver 3}
## Considered Options
- {Option 1}
- {Option 2}
- {Option 3}
## Decision Outcome
**Chosen option**: {Option X}
**Justification**: {Why this option}
### Positive Consequences
- {Good outcome 1}
- {Good outcome 2}
### Negative Consequences
- {Bad outcome 1}
- {Bad outcome 2}
## 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}
## Links
- {Related ADRs}
- {Documentation}
## Notes
- {Additional information}