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

41
skills/acceptance-criteria-generator/SKILL.md Normal file
View File

@@ -0,0 +1,41 @@
# acceptance-criteria-generator
Generate properly-formatted Given/When/Then acceptance criteria.
## Activation Keywords
- "AC", "acceptance criteria", "Given When Then", "given when then", "acceptance", "criteria"
## When to Use
- User is writing acceptance criteria
- Need to format AC in proper Given/When/Then structure
- Ensuring clarity and testability of requirements
## What This Does
Takes user's plain English requirements and converts to structured Given/When/Then format:
- **Given**: Initial state/preconditions
- **When**: User action or trigger
- **Then**: Expected outcome/result
Generates multiple AC items if needed (typically 2-5 per story).
Ensures each criterion is:
- Testable (not vague)
- Independent (doesn't depend on other AC)
- Clear (unambiguous language)
- Measurable (has a clear success/failure)
## Output
Well-formatted acceptance criteria ready to add to story.
## Example Activation
User: "User should be able to log in with email and password, and receive a JWT token"
Skill: Generates:
```
- **Given** a registered user with valid email and password
**When** user POSTs to /api/auth/login with credentials
**Then** they receive a 200 response with JWT token (24h expiration)
- **Given** a user enters wrong password
**When** they attempt login
**Then** they receive 401 Unauthorized and rate limit applied
```

57
skills/adr-template/SKILL.md Normal file
View File

@@ -0,0 +1,57 @@
# adr-template
Generate Architecture Decision Record structure with context/decision/consequences.
## Activation Keywords
- "ADR", "architecture decision", "decision record", "adr template"
## When to Use
- Major architectural decisions made during implementation
- Documenting why a technology/pattern was chosen
- Recording decision trade-offs and alternatives considered
## What This Does
Generates complete ADR structure with:
- **Title**: Clear, concise decision title
- **Status**: Proposed, Accepted, Deprecated, Superseded
- **Context**: Why this decision was needed, what problem does it solve
- **Decision**: What was decided and why
- **Consequences**: Positive outcomes and risks introduced
- **Alternatives**: Other options considered and why rejected
- **Related Stories**: Links to affected user stories
Includes proper YAML frontmatter for integration with status.json.
## Output
Ready-to-use ADR file in docs/03-decisions/adr-XXXX.md format
## Example Activation
User: "We decided to use JWT for authentication instead of sessions"
Skill: Generates:
```
---
adr_id: ADR-0042
title: Use JWT for stateless authentication
status: accepted
date: 2025-10-28
---
## Context
Application needs scalable authentication across microservices.
Session-based auth requires shared state/cache.
## Decision
Adopt JWT (JSON Web Tokens) for stateless authentication.
## Consequences
✅ Benefits: Scalable, distributed, microservice-friendly
❌ Risks: Token revocation requires blacklist, larger payload
## Alternatives Considered
1. Session + Redis: Requires shared state
2. OAuth2: Overkill for internal auth
## Related Stories
- US-0001: User Login API
- US-0002: Password Reset
```

216
skills/agileflow-acceptance-criteria/SKILL.md Normal file
View File

@@ -0,0 +1,216 @@
---
name: agileflow-acceptance-criteria
description: Generates detailed Given/When/Then acceptance criteria when user describes feature behavior or requirements. Enhances user stories with testable scenarios.
allowed-tools: Read, Write, Edit
---
# AgileFlow Acceptance Criteria
## Purpose
This skill automatically generates detailed, testable acceptance criteria in Given/When/Then (Gherkin) format from feature discussions and requirements.
## When This Skill Activates
Load this skill when:
- User describes how a feature should behave
- Discussing user workflows or interactions
- User mentions "acceptance criteria", "test scenarios", "should work like"
- Creating or reviewing user stories
- User describes "when user does X, then Y should happen"
## Given/When/Then Format
```markdown
### AC#: [Criterion Name]
**Given** [initial context or precondition]
**When** [user action or trigger event]
**Then** [expected outcome or system behavior]
```
## Components
### Given (Precondition)
The initial state before the action:
- User's current state
- System state
- Data that exists
- Permissions/roles
Examples:
- "Given I am logged in as an admin"
- "Given the shopping cart contains 3 items"
- "Given I am on the product details page"
- "Given dark mode is enabled"
### When (Action)
The trigger or user action:
- What the user does
- Event that occurs
- API call made
Examples:
- "When I click the 'Add to Cart' button"
- "When I submit the form"
- "When a new message arrives"
- "When the payment fails"
### Then (Outcome)
The expected result:
- What the user sees
- System state changes
- Data modifications
- Error messages
- Notifications
Examples:
- "Then the item is added to my cart"
- "Then I see a success message"
- "Then I am redirected to the dashboard"
- "Then an error message is displayed"
## Workflow
1. **Listen for behavior descriptions**: User explains "when X happens, Y should occur"
2. **Extract scenarios**:
- Identify different paths (happy path, error cases, edge cases)
- Note preconditions for each scenario
- Capture expected outcomes
3. **Generate criteria**:
- Create one AC per distinct scenario
- Use clear, unambiguous language
- Make it testable (observable outcome)
- Include edge cases
4. **Add to story**: If working on a user story, enhance its AC section
## Types of Acceptance Criteria
### Happy Path
```markdown
### AC1: Successful Login
**Given** I am on the login page
**When** I enter valid credentials and click "Login"
**Then** I am redirected to my dashboard
**And** I see a welcome message with my name
```
### Error Handling
```markdown
### AC2: Invalid Password
**Given** I am on the login page
**When** I enter a valid email but incorrect password
**Then** I see an error message "Invalid credentials"
**And** I remain on the login page
**And** the password field is cleared
```
### Edge Cases
```markdown
### AC3: Account Locked After Failed Attempts
**Given** I have failed to login 4 times
**When** I attempt to login with incorrect password again
**Then** my account is locked for 30 minutes
**And** I see a message "Account locked. Try again in 30 minutes"
**And** an email is sent to my registered address
```
### Permission-Based
```markdown
### AC4: Admin-Only Feature Access
**Given** I am logged in as a regular user
**When** I try to access the admin dashboard
**Then** I see a 403 Forbidden error
**And** I am redirected to my user dashboard
```
## Quality Checklist
Good acceptance criteria are:
- [ ] **Specific**: Clearly describes one scenario
- [ ] **Testable**: Can be verified with a test
- [ ] **Independent**: Doesn't depend on order of execution
- [ ] **Unambiguous**: Only one interpretation possible
- [ ] **Complete**: Covers happy path, errors, and edge cases
- [ ] **User-focused**: Written from user's perspective
## Common Patterns
### Form Validation
```markdown
### AC1: Email Format Validation
**Given** I am filling out the registration form
**When** I enter an invalid email format (missing @)
**Then** I see an error "Please enter a valid email address"
**And** the submit button remains disabled
```
### State Transitions
```markdown
### AC2: Order Status Change
**Given** my order status is "Processing"
**When** the warehouse marks it as shipped
**Then** I see the status update to "Shipped"
**And** I receive an email with tracking information
```
### Permissions
```markdown
### AC3: File Edit Permission
**Given** I have "view-only" access to a document
**When** I try to edit the document
**Then** the edit button is disabled
**And** I see a tooltip "You need edit permissions"
```
### Responsive Behavior
```markdown
### AC4: Mobile Menu Toggle
**Given** I am viewing the site on a mobile device (width < 768px)
**When** I tap the menu icon
**Then** the navigation menu slides in from the left
**And** I can navigate to any section
```
## Integration with Other Skills
- **agileflow-story-writer**: Automatically enhances story AC sections
- **agileflow-sprint-planner**: Helps estimate story complexity from AC count
- **agileflow-tech-debt**: Identifies missing test coverage from AC
## Multiple Conditions (And/But)
Use **And** for additional conditions:
```markdown
**Given** I am logged in
**And** I have items in my cart
**When** I click "Checkout"
**Then** I am redirected to payment page
**And** I see my cart summary
**And** I see available payment methods
```
Use **But** for contrasting outcomes:
```markdown
**Given** I am on the search page
**When** I search for "nonexistent product"
**Then** I see "No results found" message
**But** I see suggested categories
**But** the search stays visible for retry
```
## Examples
See `examples/` directory for comprehensive AC sets across different feature types.
## Notes
- Aim for 3-7 acceptance criteria per story
- Too few = incomplete requirements
- Too many = story should be split
- Cover at least one error case per story
- Include accessibility criteria when relevant
- Consider mobile vs desktop differences
- Think about internationalization if applicable

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}

241
skills/agileflow-commit-messages/SKILL.md Normal file
View File

@@ -0,0 +1,241 @@
---
name: agileflow-commit-messages
description: Formats git commit messages following Conventional Commits and respects user's attribution preferences from CLAUDE.md. Loads when creating commits or discussing code changes to commit.
allowed-tools: Read, Bash
---
# agileflow-commit-messages
ROLE & IDENTITY
- Skill ID: COMMIT-MSG
- Specialization: Git commit message formatting with Conventional Commits + attribution policy compliance
- Part of the AgileFlow docs-as-code system
OBJECTIVE
Format git commit messages following Conventional Commits specification while respecting user's Claude Code attribution preferences from CLAUDE.md. Ensure commits are clear, concise, and follow project conventions for type, scope, and footer formatting.
INPUTS
- User request to commit changes
- Files staged for commit (from git status)
- Change descriptions or diff context
- CLAUDE.md (optional) - Attribution policy
FIRST ACTION
**Deterministic boot sequence**:
1. Check if CLAUDE.md exists: `[ -f CLAUDE.md ] && echo "Found" || echo "Not found"`
2. If found, read attribution policy: `grep -A 20 "Git Commit Attribution Policy" CLAUDE.md`
3. Scan git status: `git status --short` to understand scope of changes
4. Check for staged changes: `git diff --cached --stat`
PROACTIVE KNOWLEDGE LOADING
**Before generating commit message:**
- Read CLAUDE.md for attribution policy (CRITICAL - respect user preference)
- Read .git/config for repo context (if available)
- Scan staged files to determine commit type and scope
- Check recent commit history: `git log --oneline -5` to match style
**Attribution Policy Detection**:
- IF `grep -q "DO NOT ADD AI ATTRIBUTION" CLAUDE.md` → No attribution
- ELSE → Add default attribution footer
WORKFLOW
1. **Analyze staged changes**:
- Run `git diff --cached --stat` to see files
- Determine primary change type (feat, fix, refactor, etc.)
- Identify affected scope (api, ui, auth, db, config, etc.)
2. **Check attribution policy** (CRITICAL):
- Read CLAUDE.md for "Git Commit Attribution Policy"
- IF "DO NOT ADD AI ATTRIBUTION" found → skip footer
- ELSE → prepare attribution footer
3. **Format commit message** following Conventional Commits:
```
<type>(<scope>): <subject>
<body>
<footer>
```
- **Type**: feat, fix, docs, style, refactor, perf, test, chore, ci, revert
- **Scope** (optional): api, ui, auth, db, config, etc.
- **Subject**: Imperative mood, lowercase, <50 chars, no period
- **Body** (optional): Explain WHAT and WHY (not HOW), wrap at 72 chars
- **Footer**: Issue refs (Closes #123), breaking changes, attribution
4. **Add attribution footer** (if policy allows):
```
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
```
5. **Show commit message** to user for approval (diff-first pattern)
6. **Execute commit** after YES confirmation:
```bash
git commit -m "$(cat <<'EOF'
<formatted message>
EOF
)"
```
RELATED COMMANDS
- `/AgileFlow:setup` - Creates CLAUDE.md with attribution policy during setup
- `/AgileFlow:ai-code-review` - Use before committing to verify quality
- `/AgileFlow:generate-changelog` - Parses commit messages for changelog generation
- `/AgileFlow:status STORY=... STATUS=in-review` - Update story status after commit
**When to use slash commands**:
- After committing code changes → `/AgileFlow:status` to update story
- After completing story → `/AgileFlow:generate-changelog` for release notes
OUTPUTS
- Formatted commit message (shown to user for approval)
- Git commit executed (if user says YES)
- Commit SHA (from git output)
HANDOFFS
**AgileFlow Coordination** (optional - if working within AgileFlow system):
- DOES NOT update docs/09-agents/status.json directly (commit is atomic)
- DOES NOT append to bus/log.jsonl (commits don't trigger coordination)
- **Story lifecycle**: Commits typically happen during `in-progress` phase
- **After commit**: Dev agent should update status.json to `in-review` if story complete
**Security Note**: NEVER commit secrets to git
- Check for .env, credentials.json, tokens, API keys
- Warn user if sensitive files are staged
- Suggest adding to .gitignore instead
QUALITY CHECKLIST
Before suggesting commit message:
- [ ] Type is appropriate (feat/fix/refactor/docs/chore/etc.)
- [ ] Subject is imperative mood ("add" not "added" or "adds")
- [ ] Subject is lowercase, <50 chars, no period at end
- [ ] Body explains WHY (not just WHAT), wrapped at 72 chars
- [ ] Footer includes issue references if applicable (Closes #123)
- [ ] **Attribution policy checked in CLAUDE.md** (CRITICAL)
- [ ] No secrets in staged files (.env, tokens, credentials)
- [ ] Breaking changes marked with `!` and `BREAKING CHANGE:` footer
## Conventional Commits Format
### Types
- **feat**: New feature
- **fix**: Bug fix
- **docs**: Documentation only changes
- **style**: Code style (formatting, missing semicolons, whitespace)
- **refactor**: Code refactor (neither fixes bug nor adds feature)
- **perf**: Performance improvements
- **test**: Adding/modifying tests
- **chore**: Build process, dependencies, tooling
- **ci**: CI/CD configuration changes
- **revert**: Reverts a previous commit
### Scope (Optional)
- `(api)`, `(ui)`, `(auth)`, `(db)`, `(config)`, etc.
- Can be omitted if change affects multiple areas
### Subject Rules
- Imperative mood: "add feature" not "added feature" or "adds feature"
- No capitalization of first letter
- No period at the end
- Max 50 characters
- Clear and concise
### Body (Optional but Recommended)
- Explain WHAT changed and WHY (not HOW - code shows that)
- Wrap at 72 characters per line
- Separate from subject with blank line
- Use bullet points for multiple changes
### Footer (Optional)
- **Breaking changes**: `BREAKING CHANGE: description`
- **Issue references**: `Closes #123`, `Fixes #456`
- **Attribution**: Add if CLAUDE.md allows (see attribution policy)
## Attribution Examples
**WITH attribution** (default if no policy):
```
feat(auth): add two-factor authentication
Implemented TOTP-based 2FA with QR code generation
for enhanced user account security.
Closes #234
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
```
**WITHOUT attribution** (if CLAUDE.md says "DO NOT ADD AI ATTRIBUTION"):
```
feat(auth): add two-factor authentication
Implemented TOTP-based 2FA with QR code generation
for enhanced user account security.
Closes #234
```
## Multi-File Commits
For commits affecting multiple files:
- Choose the most significant type (feat > fix > refactor > chore)
- Use scope that represents the feature/module
- List key changes in body as bullet points
Example:
```
feat(user-profile): add profile editing and avatar upload
- Implemented profile form with validation
- Added avatar upload with image cropping
- Created API endpoints for profile updates
- Added unit tests for profile service
Closes #123, #124
```
## Breaking Changes
When introducing breaking changes, use `!` and `BREAKING CHANGE:`:
```
feat(api)!: change authentication endpoint structure
BREAKING CHANGE: The /auth/login endpoint now returns a different
response format. Clients must update to handle the new structure.
Old: { token: "..." }
New: { accessToken: "...", refreshToken: "...", expiresIn: 3600 }
Migration guide: docs/migrations/auth-response-v2.md
```
## Revert Commits
```
revert: feat(auth): add two-factor authentication
This reverts commit abc1234def5678.
Reason: 2FA implementation caused login failures for users with
certain browser configurations. Reverting to investigate and fix.
```
## Integration with Other Skills
- **agileflow-changelog**: Commit messages inform changelog entries
- **agileflow-story-writer**: Reference story IDs in commits (Closes STORY-042)
- **agileflow-adr-writer**: Link ADRs in footer (Refs: ADR-0005)
## Notes
- **ALWAYS** check CLAUDE.md first before formatting commit message
- Respect user preferences - attribution is a sensitive topic
- If unsure about type, ask the user
- For large commits, suggest breaking into smaller logical commits
- Include context in body - future developers will thank you
- Keep line lengths: subject <50 chars, body <72 chars

168
skills/agileflow-commit-messages/reference/bad-examples.md Normal file
View File

@@ -0,0 +1,168 @@
# Bad Commit Message Examples (and How to Fix Them)
## ❌ Too Vague
```
fix: fix bug
```
**Problem**: Doesn't explain what bug was fixed
**Better**:
```
fix(auth): prevent session timeout during active use
Fixed bug where user sessions expired after 30 minutes
even during active usage. Now sessions extend while user
is interacting with the application.
Fixes #456
```
## ❌ Wrong Tense
```
feat: added dark mode
```
**Problem**: Should be imperative mood ("add" not "added")
**Better**:
```
feat(ui): add dark mode toggle
Implemented dark mode with localStorage persistence
and system preference detection.
Closes #789
```
## ❌ Subject Too Long
```
feat: add a new user profile editing feature that allows users to update their name, email, and profile picture
```
**Problem**: Subject exceeds 50 characters, should be concise
**Better**:
```
feat(profile): add user profile editing
Users can now update their name, email, and profile
picture from the settings page. Changes are validated
server-side and saved to the database.
Closes #123
```
## ❌ No Type
```
update README
```
**Problem**: Missing type prefix
**Better**:
```
docs(readme): add API authentication examples
Added code examples showing how to authenticate API
requests using JWT tokens.
```
## ❌ Multiple Unrelated Changes
```
feat: add login and fix cart bug and update dependencies
```
**Problem**: Should be 3 separate commits
**Better**: Split into:
```
feat(auth): add user login functionality
```
```
fix(cart): resolve item duplication issue
```
```
chore(deps): update npm packages to latest versions
```
## ❌ Description of HOW Instead of WHY
```
fix: changed if statement to switch statement
```
**Problem**: Describes implementation detail, not the reason
**Better**:
```
refactor(validation): simplify input validation logic
Replaced nested if statements with switch statement
for better readability and easier maintenance. No
functional changes.
```
## ❌ Capitalized Subject
```
feat: Add Dark Mode Support
```
**Problem**: Subject should be lowercase
**Better**:
```
feat(ui): add dark mode support
```
## ❌ Period at End of Subject
```
fix: resolve login timeout issue.
```
**Problem**: Subject shouldn't end with period
**Better**:
```
fix(auth): resolve login timeout issue
Increased session timeout from 15 to 30 minutes to
prevent premature logouts during form filling.
Fixes #567
```
## ❌ No Context
```
fix: it works now
```
**Problem**: Completely uninformative
**Better**:
```
fix(payment): resolve Stripe webhook signature validation
Fixed HMAC signature verification by using raw request
body instead of parsed JSON. Webhooks now process correctly.
Fixes #890
```
## ❌ Missing Issue Reference
```
feat: add two-factor authentication
Implemented TOTP-based 2FA with QR code generation.
```
**Problem**: Should reference the issue/story
**Better**:
```
feat(auth): add two-factor authentication
Implemented TOTP-based 2FA with QR code generation
for enhanced account security.
Closes #234, STORY-042
```

120
skills/agileflow-commit-messages/reference/good-examples.md Normal file
View File

@@ -0,0 +1,120 @@
# Good Commit Message Examples
## Simple Feature Addition
```
feat(auth): add password reset via email
Users can now request a password reset link sent to their
registered email address. The link expires after 1 hour.
Closes #456
```
## Bug Fix with Context
```
fix(cart): prevent duplicate items in shopping cart
Fixed race condition where clicking "Add to Cart" rapidly
could add the same item multiple times. Added debouncing
and server-side validation.
Fixes #789
```
## Refactoring with Explanation
```
refactor(api): extract authentication middleware
Moved authentication logic from individual route handlers
into reusable middleware. This reduces code duplication
and makes auth logic easier to maintain and test.
No behavioral changes.
```
## Breaking Change
```
feat(api)!: migrate to v2 response format
BREAKING CHANGE: All API endpoints now return data wrapped
in a standardized envelope format.
Before: { id: 1, name: "..." }
After: { data: { id: 1, name: "..." }, meta: { version: 2 } }
Migration guide: docs/api-v2-migration.md
Closes #234
```
## Multiple Related Changes
```
feat(profile): add profile editing and avatar upload
- Implemented profile form with field validation
- Added avatar upload with client-side image cropping
- Created PUT /api/users/:id endpoint
- Added error handling for file size limits
- Wrote unit tests for profile update logic
Closes #123, #124
```
## Documentation
```
docs(readme): add installation instructions for Docker
Added step-by-step guide for running the application
in Docker containers, including environment variable
configuration and volume mounting.
```
## Performance Improvement
```
perf(db): add index on user email column
Query performance for user lookup by email improved from
~500ms to ~5ms. Added composite index on (email, status)
for common query patterns.
```
## Dependency Update
```
chore(deps): upgrade React to v18.2
Updated React and React DOM to latest stable version.
Migrated deprecated lifecycle methods in UserProfile
and Dashboard components.
Tested with full E2E suite - all tests passing.
```
## CI/CD Change
```
ci(github): add automated dependency updates
Configured Dependabot to create PRs for npm package
updates weekly. Auto-merge enabled for patch updates
that pass all tests.
```
## Revert
```
revert: feat(payments): add Stripe integration
This reverts commit abc123def456.
Stripe webhook validation is failing in production.
Reverting to investigate HMAC signature verification
before re-deploying.
```

15
skills/agileflow-commit-messages/scripts/check-attribution.sh Executable file
View File

@@ -0,0 +1,15 @@
#!/bin/bash
# check-attribution.sh
# Determines if Claude Code attribution should be added to git commits
# Returns "yes" if attribution should be added, "no" if it should not
if [ -f CLAUDE.md ]; then
if grep -q "DO NOT ADD AI ATTRIBUTION" CLAUDE.md; then
echo "no"
else
echo "yes"
fi
else
# Default to adding attribution if no CLAUDE.md exists
echo "yes"
fi

242
skills/agileflow-epic-planner/SKILL.md Normal file
View File

@@ -0,0 +1,242 @@
---
name: agileflow-epic-planner
description: Breaks down large features into properly-scoped epics with milestones and story groupings. Loads when user describes major features or initiatives.
allowed-tools: Read, Write, Edit, Glob
---
# AgileFlow Epic Planner
## Purpose
This skill automatically structures large features or initiatives into epics, breaking them down into logical story groupings and milestones.
## When This Skill Activates
Load this skill when:
- User describes a large feature spanning multiple sprints
- Discussing a major initiative or project
- User says "we need to build...", "big feature", "multi-month project"
- Feature seems too large to be a single story (>13 story points)
- User mentions "epic", "initiative", "theme"
## Epic Format
```markdown
# [EPIC-###] Title
**Status**: PLANNING | ACTIVE | ON_HOLD | COMPLETED
**Owner**: Product Owner / Team Lead
**Start Date**: YYYY-MM-DD
**Target Completion**: YYYY-MM-DD
**Priority**: P0 | P1 | P2 | P3
**Business Value**: High | Medium | Low
## Problem Statement
[What problem does this epic solve? Why is it important?]
## Goals and Objectives
- [Goal 1: Specific, measurable outcome]
- [Goal 2: Business or user metric to improve]
- [Goal 3: Strategic alignment]
## Success Metrics
- [Metric 1: e.g., 20% increase in user engagement]
- [Metric 2: e.g., Reduce support tickets by 30%]
- [Metric 3: e.g., 95% user satisfaction on feature]
## User Stories
### Milestone 1: [Name] (Target: YYYY-MM-DD)
- [ ] [STORY-###: Title](../06-stories/STORY-###-title.md) - 5 pts
- [ ] [STORY-###: Title](../06-stories/STORY-###-title.md) - 8 pts
- [ ] [STORY-###: Title](../06-stories/STORY-###-title.md) - 3 pts
**Total: 16 story points**
### Milestone 2: [Name] (Target: YYYY-MM-DD)
- [ ] [STORY-###: Title](../06-stories/STORY-###-title.md) - 5 pts
- [ ] [STORY-###: Title](../06-stories/STORY-###-title.md) - 8 pts
**Total: 13 story points**
## Dependencies
- [Dependency 1: What needs to be done first]
- [Dependency 2: External team dependencies]
- [Dependency 3: Technical prerequisites]
## Risks and Assumptions
**Risks**:
- [Risk 1: What could go wrong]
- [Risk 2: Mitigation plan]
**Assumptions**:
- [Assumption 1: What we're assuming is true]
- [Assumption 2: Needs validation]
## Out of Scope
- [What we're explicitly NOT doing in this epic]
- [Features deferred to future epics]
## Progress Tracking
**Overall Progress**: X / Y stories completed (Z%)
**Last Updated**: YYYY-MM-DD
```
## Workflow
1. **Detect large feature**: User describes something too big for a single story
2. **Ask clarifying questions**:
- "What's the main problem you're solving?"
- "Who are the users?"
- "What's the timeline/urgency?"
- "What defines success?"
3. **Break down into logical chunks**:
- Identify milestones (MVP, Phase 2, Polish)
- Group related functionality
- Ensure each milestone delivers value
4. **Create epic structure**:
- Read existing epics for numbering
- Write epic file in `docs/05-epics/`
- Outline stories (create skeleton, defer details)
5. **Estimate effort**:
- Rough story point estimates
- Calculate milestone totals
- Suggest timeline based on team velocity
## Epic vs Story
### This Should Be an Epic If:
- Takes more than 1-2 sprints (>13 story points total)
- Involves multiple team members or subteams
- Has distinct phases or milestones
- Requires coordination across different areas (UI, API, DevOps)
- Has significant business impact or strategic value
### This Should Be a Story If:
- Can be completed in one sprint
- Single developer can own it
- Clear, specific acceptance criteria
- One or two related tasks
## Milestone Planning
### Milestone 1: MVP (Minimum Viable Product)
- Core functionality only
- Simplest path to value
- No edge cases or polish
- Goal: Validate approach
### Milestone 2: Feature Complete
- All planned functionality
- Edge cases handled
- Error handling
- Goal: Production-ready core
### Milestone 3: Polish & Optimization
- Performance improvements
- UX enhancements
- Accessibility
- Goal: Delightful experience
## Epic Size Guidelines
- **Small Epic**: 15-30 story points (1-2 sprints)
- **Medium Epic**: 30-60 story points (2-4 sprints)
- **Large Epic**: 60-100 story points (4-6 sprints)
- **Initiative**: >100 story points (multiple epics)
If epic exceeds 100 points, break into multiple epics.
## Quality Checklist
Before creating epic:
- [ ] Problem statement is clear and specific
- [ ] Goals are measurable
- [ ] Success metrics defined
- [ ] At least 2 milestones planned
- [ ] Stories grouped logically
- [ ] Dependencies identified
- [ ] Risks acknowledged with mitigations
- [ ] Out-of-scope explicitly stated
## Examples
See `templates/epic-template.md` for standard format.
## Dependencies
### Types of Dependencies:
- **Technical**: Infrastructure, APIs, services
- **Team**: Other teams' work
- **External**: Third-party integrations
- **Sequential**: Story X must complete before Story Y
### Documenting Dependencies:
```markdown
## Dependencies
- **EPIC-042 Authentication System**: Must complete before we can add user-specific features
- **Design Team**: Finalized mockups needed before Milestone 2
- **External API**: Stripe integration account setup required
```
## Risk Management
### Common Risks:
- **Scope creep**: Clearly define out-of-scope items
- **Technical unknowns**: Spike stories for research
- **Resource constraints**: Buffer time in estimates
- **Dependency delays**: Identify critical path early
### Risk Format:
```markdown
**Risks**:
- **Risk**: Integration with legacy system may be complex
**Impact**: High (could delay Milestone 2 by 2 weeks)
**Mitigation**: Allocate spike story to investigate (5 pts)
**Owner**: Backend Lead
```
## Integration with Other Skills
- **agileflow-story-writer**: Creates individual stories for the epic
- **agileflow-sprint-planner**: Assigns stories to sprints
- **agileflow-adr**: Links architectural decisions made during epic
## Progress Tracking
Update epic as stories complete:
```markdown
## Progress Tracking
**Overall Progress**: 8 / 12 stories completed (67%)
**Story Points**: 45 / 65 completed (69%)
**Last Updated**: 2025-01-20
**Milestone 1**: ✅ Complete (16 / 16 points)
**Milestone 2**: 🔄 In Progress (15 / 25 points)
**Milestone 3**: ⏳ Not Started (0 / 24 points)
**Burndown**:
- Sprint 1: 16 points (completed Milestone 1)
- Sprint 2: 14 points (partial Milestone 2)
- Sprint 3: 15 points (target: finish Milestone 2)
```
## Notes
- Epics are living documents - update as you learn
- Don't over-plan - detail emerges during execution
- Review epic scope at sprint planning
- Celebrate milestone completions
- Link to ADRs for major technical decisions

304
skills/agileflow-retro-facilitator/SKILL.md Normal file
View File

@@ -0,0 +1,304 @@
---
name: agileflow-retro-facilitator
description: Structures retrospective discussions using Start/Stop/Continue format with action items and accountability. Loads during retrospective conversations or sprint reviews.
allowed-tools: Read, Write, Edit
---
# AgileFlow Retro Facilitator
## Purpose
This skill facilitates sprint retrospectives by structuring feedback, identifying actionable improvements, and tracking action items across sprints.
## When This Skill Activates
Load this skill when:
- User mentions "retrospective", "retro", "sprint review"
- Discussing what went well/poorly in a sprint
- User says "let's reflect on..." or "how can we improve..."
- Gathering team feedback
- User mentions "lessons learned", "process improvements"
## Retro Format (Start/Stop/Continue)
```markdown
# Sprint [Number] Retrospective
**Date**: YYYY-MM-DD
**Facilitator**: [Name]
**Attendees**: [Team members present]
**Sprint Duration**: [Start] - [End]
## Sprint Metrics
- **Committed**: X story points
- **Completed**: Y story points
- **Velocity**: Z%
- **Stories Done**: A / B
- **Bugs Found**: C
- **Blockers**: D
## What Went Well ✅
- [Positive 1: Specific thing that worked]
- [Positive 2: Team success]
- [Positive 3: Process improvement]
## What Didn't Go Well ❌
- [Challenge 1: Specific problem]
- [Challenge 2: Blocker or delay]
- [Challenge 3: Process issue]
## Start (New Practices) 🟢
- **[Practice 1]**
- Why: [Reasoning]
- Owner: [Who will drive this]
- Success metric: [How we'll measure]
## Stop (Remove Practices) 🔴
- **[Practice 1]**
- Why it's not working: [Reasoning]
- Alternative: [What we'll do instead]
## Continue (Keep Doing) 🟡
- **[Practice 1]**
- Why it's working: [Reasoning]
- How to maintain: [Keep it going]
## Action Items
- [ ] **[Action 1]** - @Owner - Due: [Date]
- Success criteria: [How we know it's done]
- [ ] **[Action 2]** - @Owner - Due: [Date]
- Success criteria: [How we know it's done]
## Previous Action Items Review
- [✅] **[Completed Action]** - Implemented, improved X by Y%
- [🔄] **[In Progress Action]** - Still working on it, 60% done
- [❌] **[Not Done Action]** - Blocked by Z, rolling to next sprint
## Key Insights
1. [Insight 1: Pattern or learning]
2. [Insight 2: Team dynamic observation]
3. [Insight 3: Process discovery]
## Next Retrospective
**Date**: [Next retro date]
**Focus Areas**: [Specific topics to revisit]
```
## Workflow
1. **Set the Stage**:
- Review sprint metrics (velocity, completion rate)
- Check previous action items
2. **Gather Feedback**:
- What went well?
- What didn't go well?
- What should we start doing?
- What should we stop doing?
- What should we continue doing?
3. **Identify Patterns**:
- Group similar feedback
- Find root causes
- Spot recurring themes
4. **Create Action Items**:
- Specific, actionable steps
- Assign owners
- Set due dates
- Define success criteria
5. **Document and Share**:
- Save in `docs/08-project/retros/`
- Share with team
- Add action items to backlog if needed
## Retro Formats (Choose Based on Context)
### 1. Start/Stop/Continue (Standard)
Best for: Regular sprint retros
### 2. Glad/Sad/Mad
Best for: Emotional topics, team dynamics
```markdown
## Glad 😊
- [Things that made us happy]
## Sad 😔
- [Things that disappointed us]
## Mad 😡
- [Things that frustrated us]
```
### 3. 4Ls (Liked, Learned, Lacked, Longed For)
Best for: Learning-focused retros
```markdown
## Liked 👍
- [What we enjoyed]
## Learned 💡
- [New knowledge or skills]
## Lacked ⚠️
- [What was missing]
## Longed For 🌟
- [What we wish we had]
```
### 4. Sailboat (Wind, Anchor, Rocks, Island)
Best for: Visual teams, long-term goals
```markdown
## Wind ⛵ (What pushes us forward)
- [Helpful forces]
## Anchor ⚓ (What slows us down)
- [Obstacles]
## Rocks 🪨 (What could sink us)
- [Risks]
## Island 🏝️ (Our goal)
- [Where we want to be]
```
## Good vs Bad Feedback
### Good (Specific, Actionable):
```markdown
✅ "Daily standups ran long (20+ min) because we discussed implementation details.
Consider moving technical discussions to separate sessions."
✅ "Code reviews were faster this sprint (avg 4 hours vs 24 hours last sprint)
thanks to smaller PR sizes. Let's keep PRs under 300 lines."
✅ "Unclear acceptance criteria on STORY-042 led to 3 days of rework.
We should refine stories more thoroughly during planning."
```
### Bad (Vague, Blame-Oriented):
```markdown
❌ "Meetings were bad"
❌ "Bob didn't do his job"
❌ "Everything was terrible"
❌ "Process is broken"
```
## Action Item Quality
### SMART Action Items:
- **S**pecific: Clear what needs to be done
- **M**easurable: Can verify it's complete
- **A**ssignable: Has an owner
- **R**elevant: Addresses the issue
- **T**ime-bound: Has a deadline
### Example:
```markdown
✅ Good:
- [ ] **Create PR size guideline** - @TechLead - Due: Before next sprint
- Success: Document written, shared with team, added to CLAUDE.md
- Metric: 80% of PRs under 300 lines
❌ Bad:
- [ ] Fix code reviews
```
## Metrics to Track
### Sprint Health:
- Velocity trend (increasing, stable, decreasing?)
- Commitment accuracy (completed vs committed)
- Bug count (increasing, decreasing?)
- Blocker frequency
### Team Health:
- Meeting effectiveness
- Communication quality
- Collaboration level
- Work-life balance
### Process Health:
- Cycle time (story start to done)
- Code review turnaround
- Deployment frequency
- Incident count
## Common Themes to Watch For
### Positive Patterns:
- 🟢 Consistent velocity
- 🟢 Low bug count
- 🟢 Fast code reviews
- 🟢 Clear requirements
- 🟢 Good collaboration
### Warning Signs:
- 🔴 Declining velocity
- 🔴 Recurring blockers
- 🔴 Communication issues
- 🔴 Scope creep
- 🔴 Burnout indicators
## Integration with Other Skills
- **agileflow-sprint-planner**: Retro insights inform next sprint planning
- **agileflow-tech-debt**: Identifies tech debt to address
- **agileflow-story-writer**: Improves story writing process
## Facilitator Tips
### Do:
- ✅ Create safe space for honest feedback
- ✅ Focus on process, not people
- ✅ Time-box discussions (5-10 min per topic)
- ✅ Ensure everyone participates
- ✅ End on positive note
- ✅ Follow up on action items
### Don't:
- ❌ Blame individuals
- ❌ Let discussions run too long
- ❌ Skip retros ("too busy")
- ❌ Create action items without owners
- ❌ Ignore previous action items
## Remote Retro Adaptations
For distributed teams:
- Use anonymous feedback tools (Retrium, Metro Retro)
- Give time for async reflection before meeting
- Use polls/voting for prioritization
- Record session for absent team members
- Use collaborative docs for brainstorming
## Frequency Guidelines
- **Every sprint**: Standard retros (60-90 min)
- **Major milestones**: Extended retros (2-3 hours)
- **Quarterly**: Big-picture retros (process, tools, culture)
- **Post-incident**: Blameless postmortems (as needed)
## Notes
- Retros are for the team, not management reporting
- Psychological safety is critical for honest feedback
- Action items should be small and achievable
- Track action item completion rate (target: >80%)
- Vary retro format to keep it fresh
- Celebrate wins, don't just focus on problems

245
skills/agileflow-sprint-planner/SKILL.md Normal file
View File

@@ -0,0 +1,245 @@
---
name: agileflow-sprint-planner
description: Helps plan sprints by grouping stories, calculating capacity, identifying risks, and creating sprint goals. Loads when discussing sprint planning or iteration planning.
allowed-tools: Read, Write, Edit, Glob, Bash
---
# AgileFlow Sprint Planner
## Purpose
This skill assists with sprint planning by analyzing available stories, team capacity, dependencies, and creating balanced sprint plans.
## When This Skill Activates
Load this skill when:
- User mentions "sprint planning", "iteration planning"
- Discussing what to work on next sprint
- User asks "what should we work on?"
- Calculating team capacity or velocity
- User mentions "sprint goal", "sprint commitment"
## Sprint Plan Format
```markdown
# Sprint [Number]: [Sprint Goal]
**Duration**: [Start Date] - [End Date] (2 weeks)
**Team Capacity**: X story points
**Sprint Goal**: [1-2 sentence description of what we aim to achieve]
## Committed Stories
### High Priority (P0/P1)
- [ ] [STORY-###: Title](link) - X pts - @Owner
- [ ] [STORY-###: Title](link) - X pts - @Owner
### Medium Priority (P2)
- [ ] [STORY-###: Title](link) - X pts - @Owner
### Stretch Goals (if capacity allows)
- [ ] [STORY-###: Title](link) - X pts - @Owner
**Total Committed**: X story points
**Total with Stretch**: Y story points
## Capacity Breakdown
| Team Member | Availability | Capacity (pts) | Assigned (pts) |
|-------------|--------------|----------------|----------------|
| Alice | 10 days | 15 | 13 |
| Bob | 8 days (PTO) | 12 | 11 |
| Carol | 10 days | 15 | 14 |
| **Total** | 28 days | **42** | **38** |
## Dependencies & Blockers
- [Dependency 1: What needs to happen]
- [Blocker 1: Known issue]
## Risks
- [Risk 1: What might go wrong]
- [Risk 2: Mitigation plan]
## Sprint Schedule
- **Day 1 (Mon)**: Sprint Planning
- **Day 3 (Wed)**: Mid-sprint check-in
- **Day 8 (Wed)**: Feature freeze / Code review
- **Day 10 (Fri)**: Sprint Review & Retro
## Definition of Done
- [ ] Code reviewed and approved
- [ ] Tests written and passing (unit + integration)
- [ ] Documentation updated
- [ ] Deployed to staging
- [ ] Acceptance criteria validated
- [ ] No open bugs
```
## Workflow
1. **Gather Information**:
- Read backlog stories from `docs/06-stories/`
- Check team capacity (PTO, holidays, meetings)
- Review last sprint's velocity
2. **Calculate Capacity**:
- Team members × days available × points per day
- Account for:
- PTO/vacation
- Holidays
- Meetings/ceremonies (10-20% overhead)
- Ongoing support work
3. **Select Stories**:
- Start with highest priority (P0, P1)
- Consider dependencies
- Balance work across team members
- Group related stories
- Add stretch goals (20% buffer)
4. **Define Sprint Goal**:
- One clear, achievable objective
- Aligns with epic/milestone
- Measurable outcome
5. **Validate Plan**:
- Check for blockers/dependencies
- Ensure balanced workload
- Verify stories are ready (well-defined AC)
## Capacity Calculation
### Basic Formula:
```
Capacity = Team Members × Available Days × Points per Day
```
### Example:
- 3 developers
- 10 working days per person
- ~1.5 story points per day average
- Capacity = 3 × 10 × 1.5 = **45 story points**
### Adjustments:
- **Meetings overhead**: -15% (6.75 pts)
- **Code reviews**: -10% (4.5 pts)
- **Bug fixes**: -10% (4.5 pts)
- **Realistic capacity**: ~30 story points
## Velocity Tracking
```markdown
## Historical Velocity
| Sprint | Committed | Completed | Velocity |
|--------|-----------|-----------|----------|
| 12 | 40 | 38 | 95% |
| 11 | 35 | 35 | 100% |
| 10 | 42 | 30 | 71% |
| 9 | 38 | 40 | 105% |
| **Avg**| **38.75** | **35.75** | **92%** |
**Recommended commitment**: 36-40 story points
```
## Sprint Goal Guidelines
### Good Sprint Goals:
- ✅ "Complete user authentication (login, signup, password reset)"
- ✅ "Launch MVP of dark mode feature"
- ✅ "Improve search performance to <100ms"
- ✅ "Integrate Stripe payment processing"
### Bad Sprint Goals:
- ❌ "Complete as many stories as possible" (not specific)
- ❌ "Fix bugs" (too vague)
- ❌ "Work on 10 different features" (no focus)
## Story Selection Strategy
### Priority-Based:
1. **P0 (Critical)**: Blockers, security fixes, production bugs
2. **P1 (High)**: Planned features, important improvements
3. **P2 (Medium)**: Nice-to-haves, enhancements
4. **P3 (Low)**: Tech debt, cleanup, future work
### Dependency-Based:
- Group stories that depend on each other
- Complete prerequisites first
- Avoid half-done features
### Skill-Based:
- Match stories to team member expertise
- Allow learning opportunities
- Pair complex tasks
### Balance:
- Mix of UI, API, infrastructure work
- Mix of large and small stories
- Include testing and documentation
## Risk Identification
### Common Risks:
- **Underestimated complexity**: Add buffer or spike story
- **External dependencies**: Identify early, create fallback plan
- **Unclear requirements**: Refine stories before sprint starts
- **Team availability**: Plan for reduced capacity
- **Technical unknowns**: Add research/investigation time
### Risk Matrix:
```markdown
| Risk | Probability | Impact | Mitigation |
|------|-------------|--------|------------|
| API changes | High | High | Coordinate with team early |
| PTO overlap | Medium | Medium | Reduce commitment by 20% |
```
## Quality Checklist
Before finalizing sprint plan:
- [ ] Sprint goal is clear and achievable
- [ ] Stories sum to realistic capacity (80-90% of max)
- [ ] All stories have defined acceptance criteria
- [ ] Dependencies identified and resolved
- [ ] Work balanced across team members
- [ ] Stretch goals identified (10-20% extra)
- [ ] Blockers documented with mitigation plans
- [ ] Team has reviewed and committed
## Integration with Other Skills
- **agileflow-story-writer**: Ensures stories are well-formed
- **agileflow-epic-planner**: Pulls stories from epic milestones
- **agileflow-retro-facilitator**: Uses retro insights for planning
## Mid-Sprint Adjustments
If scope changes mid-sprint:
```markdown
## Mid-Sprint Adjustments (Day 5)
**Added**:
- [STORY-###: Critical Bug Fix](link) - 5 pts (replaces STORY-089)
**Removed**:
- [STORY-089: Feature Polish](link) - 5 pts (moved to next sprint)
**Reason**: Production bug requires immediate attention
**Impact**: Sprint goal remains achievable
```
## Notes
- Sprint planning should take ~2 hours for 2-week sprint
- Don't overcommit - better to under-promise and over-deliver
- Review velocity trends, not just last sprint
- Team capacity varies - account for real availability
- Leave 10-20% buffer for unknowns
- Pair estimation with multiple team members
- Re-estimate stories that seem unclear during planning

227
skills/agileflow-story-writer/SKILL.md Normal file
View File

@@ -0,0 +1,227 @@
---
name: agileflow-story-writer
description: Automatically formats user requirements and feature discussions into proper user stories with acceptance criteria following AgileFlow templates. Loads when user describes features, requirements, or tasks to implement.
allowed-tools: Read, Write, Edit, Glob
---
# agileflow-story-writer
ROLE & IDENTITY
- Skill ID: STORY-WRITER
- Specialization: User story formatting from feature discussions with acceptance criteria
- Part of the AgileFlow docs-as-code system
OBJECTIVE
Convert user feature descriptions and requirements into properly formatted AgileFlow user stories with acceptance criteria, owner assignment, priority, and estimates. Ensure stories are ready for dev agent pickup by following Definition of Ready (AC exists, test stub created, status=ready).
INPUTS
- User feature description or requirement discussion
- Existing stories in docs/06-stories/ (for numbering)
- Epic context (if story is part of epic)
- Story template from templates/story-template.md
- Project conventions from CLAUDE.md (optional)
FIRST ACTION
**Deterministic boot sequence**:
1. Check if docs/06-stories/ exists: `[ -d docs/06-stories ] && echo "Found" || echo "Not found"`
2. If found, count existing stories: `ls docs/06-stories/US-*.md 2>/dev/null | wc -l`
3. Read story template: `cat templates/story-template.md`
4. Check status.json for epic context: `jq '.stories | to_entries[] | select(.value.status == "ready")' docs/09-agents/status.json`
PROACTIVE KNOWLEDGE LOADING
**Before generating story**:
- Read templates/story-template.md for current story structure
- List docs/06-stories/ to determine next story number (US-####)
- Read docs/09-agents/status.json to check if story is part of an epic
- Read CLAUDE.md for project-specific story conventions (if exists)
- Scan recent stories to match team's AC writing style
**Owner Determination**:
- **AG-UI**: Frontend components, styling, user interactions, accessibility
- **AG-API**: Backend services, APIs, data models, business logic
- **AG-CI**: CI/CD pipelines, testing infrastructure, quality gates
- **AG-DEVOPS**: Infrastructure, deployment, monitoring, automation
WORKFLOW
1. **Extract user story components**:
- **Who** (user type): As a [user type]
- **What** (capability): I want to [action/capability]
- **Why** (benefit): So that [benefit/value]
2. **Determine metadata**:
- **Owner**: Based on work type (AG-UI, AG-API, AG-CI, AG-DEVOPS)
- **Priority**: P0 (Critical) | P1 (High) | P2 (Medium) | P3 (Low)
- **Estimate**: 1,2,3,5,8,13 story points (Fibonacci)
- **Epic**: Link if part of larger epic
3. **Generate acceptance criteria** (2-5 criteria):
- Format: **Given** [context] **When** [action] **Then** [outcome]
- Make specific and testable
- Cover happy path + edge cases
4. **Create story file**:
- Path: `docs/06-stories/US-####-descriptive-name.md`
- Follow template structure from templates/story-template.md
- Include: frontmatter, description, AC, technical notes, testing strategy
5. **Show diff** and wait for YES/NO confirmation (diff-first pattern)
6. **After YES**:
- Write story file
- Update docs/06-stories/README.md index
- Update docs/09-agents/status.json with new story entry (status: ready)
- Create test stub at docs/07-testing/test-cases/US-####.md
RELATED COMMANDS
- `/AgileFlow:epic` - Creates epics that contain stories (use when feature is large)
- `/AgileFlow:status STORY=... STATUS=...` - Update story status after creation
- `/AgileFlow:story-validate US-####` - Validate story completeness before dev agent pickup
- `/AgileFlow:adr-new` - Document architectural decisions referenced in story
- `/AgileFlow:chatgpt MODE=research TOPIC=...` - Research technical approach before writing story
**When to use slash commands**:
- After creating story → `/AgileFlow:story-validate` to ensure Definition of Ready
- Large feature → `/AgileFlow:epic` instead of single story
- Architectural decision needed → `/AgileFlow:adr-new` to document choice
OUTPUTS
- User story file at `docs/06-stories/US-####-descriptive-name.md`
- Updated `docs/06-stories/README.md` index
- Updated `docs/09-agents/status.json` with new story entry
- Test stub at `docs/07-testing/test-cases/US-####.md`
HANDOFFS
**AgileFlow Coordination** (if working within AgileFlow system):
- Updates docs/09-agents/status.json with new story:
```json
{
"US-0042": {
"title": "User Login Form",
"owner": "AG-UI",
"status": "ready",
"priority": "P1",
"estimate": "5",
"epic": "EP-0001",
"created": "2025-10-30T10:00:00Z"
}
}
```
- May append bus message if part of epic coordination:
```jsonl
{"ts":"2025-10-30T10:00:00Z","from":"STORY-WRITER","type":"status","story":"US-0042","text":"New story created, ready for AG-UI pickup"}
```
- Creates test stub in docs/07-testing/test-cases/ (Definition of Ready requirement)
- Dev agents (AG-UI, AG-API, AG-CI, AG-DEVOPS) will pick up stories with status=ready
**Story Lifecycle**:
- Story created → status=ready (if Definition of Ready met)
- Dev agent picks up → status=in-progress
- Implementation complete → status=in-review
- PR merged → status=done
QUALITY CHECKLIST
Before creating story file, verify:
- [ ] User story follows "As a...I want...So that..." format
- [ ] At least 2 acceptance criteria with Given/When/Then
- [ ] Owner is appropriate for work type (AG-UI/AG-API/AG-CI/AG-DEVOPS)
- [ ] Priority reflects urgency and impact (P0-P3)
- [ ] Estimate is in Fibonacci sequence (1,2,3,5,8,13)
- [ ] File name matches pattern: US-####-descriptive-name.md
- [ ] Technical notes capture implementation details and dependencies
- [ ] Definition of Done is comprehensive
- [ ] Story will be added to status.json with status=ready
- [ ] Test stub will be created at docs/07-testing/test-cases/US-####.md
## Story Point Estimation Guide
- **1 point**: Trivial change (update text, fix typo, config tweak)
- **2 points**: Simple feature (add form field, new button, basic validation)
- **3 points**: Small feature (basic CRUD endpoint, simple component)
- **5 points**: Medium feature (authentication flow, data model with relations)
- **8 points**: Large feature (payment integration, complex UI workflow)
- **13 points**: Very large (consider splitting into multiple stories or epic)
## Priority Guidelines
- **P0 (Critical)**: Blocking users, security issues, data loss, production outage
- **P1 (High)**: Major features, important fixes, user-facing improvements
- **P2 (Medium)**: Nice-to-have features, minor improvements, enhancements
- **P3 (Low)**: Tech debt, cleanup, future enhancements, optimizations
## User Story Format Reference
```markdown
---
story_id: US-0042
epic: EP-0001
title: User Login Form
owner: AG-UI
status: ready
estimate: 5
priority: P1
created: 2025-10-30
updated: 2025-10-30
dependencies: [US-0040]
---
## Description
As a user,
I want to log in with my email and password,
So that I can access my account and personalized features.
## Acceptance Criteria
### AC1: Successful Login
**Given** a registered user with valid credentials
**When** user enters email "user@example.com" and password "ValidPass123!"
**Then** user is redirected to dashboard with welcome message (HTTP 200)
### AC2: Invalid Credentials
**Given** user enters incorrect password
**When** user submits login form
**Then** error message "Invalid email or password" is displayed (HTTP 401)
### AC3: Input Validation
**Given** user submits empty email field
**When** user clicks "Login" button
**Then** validation error "Email is required" is shown
## Technical Notes
- Use JWT authentication with 24h expiration
- Store tokens in httpOnly cookies
- Implement rate limiting (5 attempts per 15 minutes)
- Hash passwords with bcrypt (cost factor 12)
## Testing Strategy
- Unit tests for form validation logic
- Integration tests for authentication flow
- E2E test for full login journey
- Test stub: docs/07-testing/test-cases/US-0042.md
## Definition of Done
- [ ] Code implemented and reviewed
- [ ] Tests written and passing
- [ ] Documentation updated
- [ ] Deployed to staging
- [ ] Acceptance criteria validated
```
## Notes
- If user is vague, ask clarifying questions before generating story
- Always increment story number based on existing stories in docs/06-stories/
- Update docs/06-stories/README.md index after creating story
- If story is >13 points, suggest breaking into multiple stories or creating an epic
- Follow "diff-first; YES/NO" pattern - show story before writing file
- Create test stub to satisfy Definition of Ready (required for status=ready)

63
skills/agileflow-story-writer/examples/good-story-example.md Normal file
View File

@@ -0,0 +1,63 @@
# [STORY-042] Add Dark Mode Toggle to Settings
**Owner**: AG-UI
**Status**: TODO
**Epic**: [EPIC-005] User Experience Improvements
**Priority**: P2
**Estimate**: 5 story points
## User Story
As a user who works at night,
I want to toggle dark mode in the settings,
So that I can reduce eye strain and improve readability in low-light conditions.
## Acceptance Criteria
### AC1: Settings Toggle Available
**Given** I am on the settings page
**When** I navigate to the "Appearance" section
**Then** I should see a dark mode toggle switch
### AC2: Theme Switches Immediately
**Given** I am viewing the app in light mode
**When** I toggle dark mode on
**Then** the entire UI should switch to dark theme within 200ms
### AC3: Preference Persists
**Given** I have enabled dark mode
**When** I close and reopen the application
**Then** dark mode should still be active
### AC4: System Preference Detection
**Given** I have not set a preference
**When** the app loads for the first time
**Then** it should default to my system's dark mode preference
## Technical Notes
- Use CSS custom properties for theme colors
- Store preference in localStorage: `theme: 'light' | 'dark' | 'system'`
- Listen to `prefers-color-scheme` media query for system default
- Ensure all components support both themes
- Add transition animations for smooth mode switching
## Testing Strategy
- Test theme switching in all major browsers (Chrome, Firefox, Safari)
- Verify localStorage persistence across sessions
- Test system preference detection on different OS
- Validate WCAG contrast ratios in dark mode
- Test with keyboard navigation (accessibility)
## Definition of Done
- [ ] Dark mode toggle implemented in settings UI
- [ ] Theme preference stored in localStorage
- [ ] All components styled for dark mode
- [ ] System preference detection working
- [ ] Unit tests for theme switching logic
- [ ] E2E tests for toggle interaction
- [ ] Documentation updated with theme implementation details
- [ ] Deployed to staging and tested
- [ ] Accessibility audit passed (WCAG AA)

44
skills/agileflow-story-writer/templates/story-template.md Normal file
View File

@@ -0,0 +1,44 @@
# [STORY-###] {Title}
**Owner**: {AG-UI | AG-API | AG-CI | AG-DEVOPS}
**Status**: TODO
**Epic**: {Link to epic if applicable}
**Priority**: {P0 | P1 | P2 | P3}
**Estimate**: {1-13 story points}
## User Story
As a {user type},
I want to {action/capability},
So that {benefit/value}.
## Acceptance Criteria
### AC1: {Criterion Name}
**Given** {initial context/state}
**When** {action/trigger}
**Then** {expected outcome}
### AC2: {Another Criterion}
**Given** {context}
**When** {action}
**Then** {outcome}
## Technical Notes
- {Implementation details}
- {Dependencies}
- {Risks/Considerations}
## Testing Strategy
- {How to test this story}
- {Edge cases to verify}
## Definition of Done
- [ ] Code implemented and reviewed
- [ ] Tests written and passing
- [ ] Documentation updated
- [ ] Deployed to staging
- [ ] Acceptance criteria validated

426
skills/agileflow-tech-debt/SKILL.md Normal file
View File

@@ -0,0 +1,426 @@
---
name: agileflow-tech-debt
description: Identifies and tracks technical debt items with impact/effort matrix and prioritization. Loads when discussing code quality, refactoring, or long-term maintenance.
allowed-tools: Read, Write, Edit, Glob
---
# agileflow-tech-debt
ROLE & IDENTITY
- Skill ID: TECH-DEBT
- Specialization: Technical debt identification, tracking, and prioritization with impact/effort scoring
- Part of the AgileFlow docs-as-code system
OBJECTIVE
Identify, document, prioritize, and track technical debt using impact/effort matrix and priority scoring. Ensure debt is visible, measured, and addressed systematically without accumulating to the point of slowing down development.
INPUTS
- User mentions of code quality, refactoring, maintenance issues ("tech debt", "needs cleanup", "messy code")
- Existing tech debt inventory at docs/08-quality/tech-debt.md
- Codebase analysis (complexity, duplication, test coverage)
- Team pain points from retrospectives
- Developer complaints about specific code areas
FIRST ACTION
**Deterministic boot sequence**:
1. Check if docs/08-quality/tech-debt.md exists: `[ -f docs/08-quality/tech-debt.md ] && echo "Found" || echo "Not found"`
2. If found, read existing tech debt inventory to understand current state
3. Count current items by priority: `grep -c "## High Priority" docs/08-quality/tech-debt.md`
4. Calculate total estimated effort from existing items
5. Identify last TD-### ID to determine next number
PROACTIVE KNOWLEDGE LOADING
**Before documenting tech debt**:
- Read docs/08-quality/tech-debt.md for existing debt items and numbering
- Check docs/09-agents/bus/log.jsonl for recent tech debt mentions from agents
- Read docs/03-decisions/ for architectural constraints that may affect solutions
- Scan docs/09-agents/retro/ for retrospective notes mentioning quality issues
- Review recent code review comments for patterns indicating tech debt
**Tech Debt Classification Knowledge**:
- **Code Quality**: Duplicate code, complex logic, poor naming, missing docs, inconsistent patterns
- **Performance**: Slow queries, N+1 problems, inefficient algorithms, missing caching, large bundles
- **Security**: Outdated dependencies, vulnerable packages, missing auth, insufficient validation
- **Maintainability**: Tightly coupled code, missing tests, unclear architecture, hard to deploy
- **Testing**: Low coverage, flaky tests, slow suite, missing integration/E2E tests
WORKFLOW
1. **Identify tech debt** from user description, code analysis, or pain points:
- What specific code/system is problematic?
- Why is this debt (not just "messy" but concrete issues)?
- What pain does it cause (slows features, causes bugs, blocks scaling)?
2. **Classify type**:
- Code Quality | Performance | Security | Maintainability | Testing
- Use most specific type (e.g., "Performance" not just "Code Quality")
3. **Assess dimensions** (1-5 scale):
- **Impact**: How much does this hurt us? (1=Low, 3=Medium, 5=High)
- **Urgency**: How soon must we fix? (1=Low, 3=Medium, 5=High)
- **Effort**: How hard to fix? (1=Low <1 sprint, 3=Medium 1-2 sprints, 5=High >2 sprints)
4. **Calculate Priority Score**:
- Formula: `Priority = (Impact × Urgency) / Effort`
- Example: High impact (5), High urgency (5), Low effort (1) → (5 × 5) / 1 = **25** (Critical)
- Example: Medium impact (3), Medium urgency (3), Low effort (1) → (3 × 3) / 1 = **9** (High)
- Example: Low impact (1), Low urgency (1), High effort (5) → (1 × 1) / 5 = **0.2** (Low)
5. **Determine priority tier**:
- **Score >10**: 🔴 High Priority (DO NOW)
- **Score 3-10**: 🟡 Medium Priority (PLAN)
- **Score <3**: 🟢 Low Priority (LATER)
6. **Create tech debt item**:
- ID: TD-### (next sequential number)
- Include: Problem, Impact, Proposed Solution, Estimated Effort, Priority Score, Status
- Format following template (see Tech Debt Item Template below)
7. **Update docs/08-quality/tech-debt.md** (diff-first, YES/NO):
- Add item under appropriate priority tier
- Update metrics section (total items, total effort, net change)
- Update "Last Updated" timestamp
8. **Suggest actions**:
- **High priority (score >10)**: Suggest creating story via `/AgileFlow:story`
- **Major refactoring**: Suggest documenting decision via `/AgileFlow:adr-new`
- **Blocking features**: Suggest updating status.json with blocked stories
- **Quarterly review**: Update tech debt health metrics
RELATED COMMANDS
- `/AgileFlow:adr-new` - Document major refactoring decisions (architecture changes)
- `/AgileFlow:story` - Convert high-priority debt to actionable stories (score >10)
- `/AgileFlow:retro` - Retrospectives surface new tech debt (use to capture pain points)
- `/AgileFlow:sprint` - Allocate 10-20% sprint capacity for debt reduction
- `/AgileFlow:ai-code-review` - Identify tech debt during code reviews
- `/AgileFlow:chatgpt MODE=research TOPIC=...` - Research refactoring approaches
**When to use slash commands**:
- After documenting high-priority debt → `/AgileFlow:story` to schedule work
- For major architectural refactoring → `/AgileFlow:adr-new` to document decision
- Quarterly tech debt review → `/AgileFlow:sprint` to allocate capacity
- During retros → `/AgileFlow:retro` to capture new debt items
OUTPUTS
- Tech debt item at docs/08-quality/tech-debt.md with:
- TD-### ID and descriptive title
- Impact/Urgency/Effort scores (1-5 scale)
- Priority score calculation
- Priority tier assignment (High 🔴, Medium 🟡, Low 🟢)
- Problem description, impact, proposed solution
- Estimated effort (story points or time)
- Owner and status
- Updated tech debt metrics (total items, total effort, net change)
- Optional: Story created for high-priority debt (via `/AgileFlow:story`)
HANDOFFS
**AgileFlow Coordination** (if working within AgileFlow system):
- **High-priority debt (score >10)**: Suggest creating story in docs/06-stories/ via `/AgileFlow:story`
- Story gets added to status.json with owner (AG-REFACTOR or relevant agent)
- Example bus message: `{"ts":"2025-10-30T10:00:00Z","from":"TECH-DEBT","type":"status","story":"US-0078","text":"High-priority tech debt TD-042 converted to story, assigned to AG-REFACTOR"}`
- **Major refactoring**: Document architectural decision via `/AgileFlow:adr-new` in docs/03-decisions/
- **Debt blocking features**: If tech debt blocks story, update status.json:
- Blocked story status → `blocked`
- Add dependency: `"dependencies": ["TD-042"]`
- **Quarterly metrics**: Include tech debt health in stakeholder updates
- **Security debt**: Coordinate with AG-SECURITY agent for vulnerability remediation
**Tech Debt Lifecycle**:
- Identified → docs/08-quality/tech-debt.md (status: Identified)
- High priority → Convert to story (status: Planned, appears in status.json)
- Assigned → Dev agent picks up (status: In Progress)
- Resolved → Marked complete (status: Resolved, moved to "Resolved Tech Debt" section)
**Security Note**: Security-related tech debt (outdated deps, vulnerabilities) should be prioritized immediately and coordinated with AG-SECURITY agent.
QUALITY CHECKLIST
Before creating tech debt item, verify:
- [ ] Problem clearly described (specific code/system, not vague "messy")
- [ ] Impact explained with concrete pain points (not just "it's messy")
- [ ] Proposed solution is specific and actionable
- [ ] Effort estimated realistically (story points or time)
- [ ] Priority score calculated: (Impact × Urgency) / Effort
- [ ] Type assigned (Code Quality/Performance/Security/Maintainability/Testing)
- [ ] Owner or responsible team identified
- [ ] Status set (Identified/Planned/In Progress/Resolved)
- [ ] TD-### ID is next sequential number
- [ ] Item added under correct priority tier (🔴/🟡/🟢)
## Prioritization Framework
### Priority Score Formula
```
Priority = (Impact × Urgency) / Effort
Impact: 1 (Low), 3 (Medium), 5 (High)
Urgency: 1 (Low), 3 (Medium), 5 (High)
Effort: 1 (Low <1 sprint), 3 (Medium 1-2 sprints), 5 (High >2 sprints)
```
### Scoring Examples
```
TD-042: (3 × 3) / 1 = 9 → High Priority (duplicate code, easy fix)
TD-067: (5 × 5) / 1 = 25 → Critical Priority (slow query, add index)
TD-089: (1 × 1) / 5 = 0.2 → Low Priority (minor cleanup, major refactor)
```
### Priority Tiers
- **🔴 High Priority (score >10)**: DO NOW - High impact, low-medium effort, blocks features
- **🟡 Medium Priority (score 3-10)**: PLAN - Mixed impact/effort, include in sprint planning
- **🟢 Low Priority (score <3)**: LATER - Low impact or high effort, address opportunistically
## Impact/Effort Matrix
```
High Impact, │ TD-012 │ TD-045 │ │
Low Effort │ DO NOW │ DO NOW │ │
├────────┼────────┼────────┤
High Impact, │ TD-023 │ TD-067 │ │
Med Effort │ PLAN │ PLAN │ │
├────────┼────────┼────────┤
Low Impact, │ TD-089 │ TD-091 │ TD-003 │
Any Effort │ LATER │ LATER │ NEVER │
└────────┴────────┴────────┘
Low Medium High
EFFORT
```
## Types of Tech Debt
### Code Quality
- Duplicate code across multiple files
- Complex/nested logic (high cyclomatic complexity)
- Poor naming (unclear variables/functions)
- Missing documentation
- Inconsistent patterns
**Example**:
```markdown
### [TD-042] Extract Duplicate User Validation Logic
**Impact**: 3 (Medium) - Code duplicated across 8 files
**Urgency**: 3 (Medium) - Causes bugs when logic diverges
**Effort**: 1 (Low) - ~3 hours to extract into utility module
**Priority Score**: (3 × 3) / 1 = **9** (High Priority)
**Type**: Code Quality
**Problem**:
User validation logic (email format, password strength) is copy-pasted
in 8 different files. Changes require updating all 8 locations.
**Impact**:
- Bug fixes take longer (must update multiple places)
- Inconsistent behavior across modules
- New developers confused by duplicated code
**Proposed Solution**:
- Extract to `utils/userValidation.ts`
- Replace all 8 instances with utility calls
- Add unit tests for validation logic
**Estimated Effort**: 3 story points
```
### Performance
- Slow database queries (missing indexes)
- N+1 query problems
- Inefficient algorithms (O(n²) when O(n log n) possible)
- Missing caching
- Large bundle sizes
**Example**:
```markdown
### [TD-067] Add Database Index on User Email Column
**Impact**: 5 (High) - Every login query does full table scan
**Urgency**: 5 (High) - Affects all users, slows login
**Effort**: 1 (Low) - 10 minutes to add index
**Priority Score**: (5 × 5) / 1 = **25** (Critical Priority)
**Type**: Performance
**Problem**:
User lookup by email takes ~500ms for 100K users due to missing index.
**Impact**:
- Slow login experience (500ms → should be <10ms)
- Database CPU at 80% during peak hours
- Cannot scale to 1M+ users
**Proposed Solution**:
- Add index: `CREATE INDEX idx_users_email ON users(email)`
- Test with production data copy
- Deploy during low-traffic window
**Estimated Effort**: 1 story point
```
### Security
- Outdated dependencies (known vulnerabilities)
- Vulnerable packages (CVE warnings)
- Missing authentication checks
- Insufficient input validation
- Exposed secrets in code
### Maintainability
- Tightly coupled code (hard to test)
- Missing tests (low coverage)
- Unclear architecture (no docs)
- Hard to deploy (manual steps)
- Configuration complexity
### Testing
- Low test coverage (<80%)
- Flaky tests (intermittent failures)
- Slow test suite (>10 min for unit tests)
- Missing integration tests
- No E2E tests for critical flows
## When to Address Tech Debt
### Continuous (Every Sprint)
- Allocate 10-20% of sprint capacity for debt reduction
- Pay interest as you go (fix small items immediately)
- Boy Scout Rule: Leave code cleaner than you found it
### Scheduled (Quarterly)
- Tech debt sprint (full sprint dedicated to quality)
- Major refactoring initiatives
- Architecture improvements
### Opportunistic
- While working on nearby code (touch it, improve it)
- When adding related features
- During bug fixes in affected areas
### Strategic
- Before major new features (clean foundation)
- When debt blocks progress (unblock development)
- When quality metrics decline (coverage drops, bugs increase)
## Tech Debt Metrics
Track these over time in docs/08-quality/tech-debt.md:
```markdown
## Tech Debt Health (Q4 2025)
**Total Items**: 24 (🔴 6 High, 🟡 11 Medium, 🟢 7 Low)
**Total Estimated Effort**: 156 story points
**Resolved This Quarter**: 8 items (42 story points)
**New This Quarter**: 5 items (18 story points)
**Net Change**: -3 items (-24 points) ✅ Improving
**Top Contributors**:
- Legacy authentication module: 6 items (45 points)
- Missing test coverage: 5 items (30 points)
- Outdated dependencies: 4 items (20 points)
**Blockers**:
- TD-012 blocks 3 planned features (US-0045, US-0046, US-0047)
- TD-045 causes 60% of production bugs
```
## Tech Debt Item Template
```markdown
### [TD-###] Descriptive Title
**Impact**: 1-5 (Low/Medium/High) - What hurts?
**Urgency**: 1-5 (Low/Medium/High) - How soon?
**Effort**: 1-5 (Low <1 sprint / Medium 1-2 sprints / High >2 sprints)
**Priority Score**: (Impact × Urgency) / Effort = X.X
**Type**: Code Quality | Performance | Security | Maintainability | Testing
**Created**: YYYY-MM-DD
**Owner**: Team/Person responsible
**Status**: Identified | Planned | In Progress | Resolved
**Problem**:
[What's wrong? Be specific, not vague. "Duplicate validation in 8 files" not "messy code"]
**Impact**:
- [How does this hurt us? Specific pain points]
- [What can't we do because of this?]
- [Quantify if possible: "500ms query", "60% of bugs", "8 duplicated files"]
**Proposed Solution**:
- [What should we do to address this? Specific steps]
- [What tools/patterns to use?]
**Estimated Effort**: X story points / Y hours / Z sprints
```
## Preventing Tech Debt
### Best Practices
- ✅ Code reviews catch issues early (require reviews before merge)
- ✅ Automated testing prevents regressions (80%+ coverage)
- ✅ Regular refactoring (Boy Scout Rule: leave cleaner than you found)
- ✅ Document intentional decisions (ADRs for architecture choices)
- ✅ Allocate time for quality work (10-20% sprint capacity)
- ✅ Monitor metrics (coverage, complexity, performance, bundle size)
### Warning Signs
- 🔴 Slowing velocity (stories taking longer each sprint)
- 🔴 Increasing bug rate (more bugs per feature)
- 🔴 Developers avoiding certain code ("don't touch that module")
- 🔴 "It's too scary to touch" comments
- 🔴 Long PR review times (complex changes, unclear code)
- 🔴 New developer onboarding difficulty
## Debt vs Investment
Not all "ugly code" is tech debt. Distinguish between debt and intentional trade-offs:
### Tech Debt (Should Fix)
- Code that slows us down
- Blocks new features
- Causes bugs frequently
- Hampers developer onboarding
### Intentional Trade-offs (OK to Keep)
- Prototype/POC code (if clearly labeled and isolated)
- Code that works and won't change (stable, low-risk)
- Third-party library quirks (external constraints)
- Platform limitations (can't be fixed by us)
**Document intentional trade-offs as ADRs via `/AgileFlow:adr-new`, not tech debt.**
## Communication Templates
### To Stakeholders
```markdown
"We have $156k in tech debt (156 story points × $1k/point).
Paying down high-priority items would:
- Reduce bug rate by 40% (TD-045 causes 60% of bugs)
- Speed up feature development by 25% (TD-012 blocks 3 features)
- Improve developer satisfaction (less time fighting code)
Proposal: Dedicate one sprint to high-impact, low-effort items (TD-012, TD-042, TD-067).
Expected ROI: 25 story points effort → unlocks 78 story points of features."
```
### To Team
```markdown
"Let's tackle TD-042 this sprint. It's blocking 3 upcoming features
and should only take 3 points. Who wants to own it?"
```
## Notes
- Track tech debt, don't let it hide (visibility is key)
- Make it visible (dashboard, metrics, regular reviews)
- Allocate consistent capacity (10-20% per sprint, not "when we have time")
- Celebrate debt reduction (recognize quality improvements)
- Prevent new debt through code review (catch issues before merge)
- Balance new features with quality (don't just ship, ship sustainably)
- Tech debt is not failure - it's reality of software development (manage it, don't ignore it)
- Use priority scoring to make objective decisions (not just "feels messy")

60
skills/api-documentation-generator/SKILL.md Normal file
View File

@@ -0,0 +1,60 @@
# api-documentation-generator
Generate OpenAPI/Swagger snippets with proper schemas.
## Activation Keywords
- "API doc", "OpenAPI", "Swagger", "endpoint docs", "endpoint documentation"
## When to Use
- Documenting REST API endpoints
- Creating OpenAPI/Swagger specifications
- Need endpoint documentation with request/response examples
## What This Does
Generates OpenAPI 3.0 specification snippets including:
- **Endpoint path and method** (GET, POST, etc.)
- **Summary and description**
- **Request body** with schema and examples
- **Response schemas** (success and error cases)
- **Parameters** (query, path, header)
- **Authentication** requirements
- **Status codes** and descriptions
Coordinates with agileflow-documentation agent for full API docs.
## Output
OpenAPI YAML/JSON snippet ready for integration into spec
## Example Activation
User: "Document POST /api/auth/login endpoint"
Skill: Generates:
```yaml
/api/auth/login:
post:
summary: User login with email and password
tags: [Authentication]
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
email:
type: string
format: email
password:
type: string
responses:
'200':
description: Login successful
content:
application/json:
schema:
type: object
properties:
token:
type: string
'401':
description: Invalid credentials
```

50
skills/changelog-entry/SKILL.md Normal file
View File

@@ -0,0 +1,50 @@
# changelog-entry
Generate Keep a Changelog format entries.
## Activation Keywords
- "changelog", "release notes", "version notes", "changelog entry"
## When to Use
- Creating release notes for new version
- Documenting changes for changelog
- Preparing version announcement
## What This Does
Generates changelog entries in Keep a Changelog format:
- **Version header** with date (YYYY-MM-DD)
- **Categories**: Added, Changed, Fixed, Improved, Deprecated, Removed, Security
- **Detailed descriptions** of each change
- **Breaking changes** clearly marked
- **Links to related issues/PRs**
- **Migration guides** for breaking changes
Can auto-extract changes from commit messages if provided.
## Output
Ready-to-add section for CHANGELOG.md
## Example Activation
User: "Version 2.18.0 - Added 8 new agents"
Skill: Generates:
```markdown
## [2.18.0] - 2025-10-28
### Added
- **Documentation Agent** - Technical docs, API documentation, user guides
- **Monitoring Agent** - Observability, logging, metrics, alerting
- **Compliance Agent** - GDPR, HIPAA, SOC2 compliance
- **Design Agent** - Design systems, component specs
- **Accessibility Agent** - WCAG compliance, a11y testing
- **Analytics Agent** - Event tracking, product analytics
- **Data Migration Agent** - Zero-downtime migrations
- **QA Agent** - Test strategy, release gates
### Changed
- Expanded agent ecosystem from 17 to 25 agents
- Improved agent coverage for enterprise features
### Improved
- Added comprehensive monitoring and compliance support
- Enhanced quality assurance gates
```

45
skills/commit-message-formatter/SKILL.md Normal file
View File

@@ -0,0 +1,45 @@
# commit-message-formatter
Generate conventional commit messages with detailed descriptions.
## Activation Keywords
- "commit", "git commit", "conventional commit", "commit message"
## When to Use
- User is about to commit code changes
- Need to format commit in conventional commits style
- Writing clear, searchable commit messages
## What This Does
Generates properly-formatted commit messages following Conventional Commits standard:
- Type: feat, fix, chore, docs, style, refactor, perf, test
- Scope: module or component affected
- Subject: concise description (imperative mood, <50 chars)
- Body: detailed explanation of change (wrapped at 72 chars)
- Footer: references to issues, breaking changes, co-authorship
Automatically includes:
- Claude Code co-authorship footer
- Link to related story/issue if mentioned
- Breaking change notation if applicable
## Output
Ready-to-use commit message for `git commit -m`
## Example Activation
User: "I implemented user login endpoint with JWT auth and rate limiting"
Skill: Generates:
```
feat(auth): implement JWT-based user login endpoint
Implemented POST /api/auth/login endpoint with:
- Email/password validation
- JWT token generation (24h expiration)
- Rate limiting (5 attempts per 15 minutes)
- Proper error handling and logging
Matches acceptance criteria from US-0001.
🤖 Generated with Claude Code
Co-Authored-By: Claude <noreply@anthropic.com>
```

79
skills/deployment-guide-generator/SKILL.md Normal file
View File

@@ -0,0 +1,79 @@
# deployment-guide-generator
Generate deployment guides with rollback procedures.
## Activation Keywords
- "deployment", "release guide", "deploy steps", "deployment procedure"
## When to Use
- Preparing to deploy a feature
- Creating release runbook
- Documenting deployment steps
## What This Does
Generates deployment guide including:
- **Pre-deployment checklist** (tests passing, staging verified)
- **Deployment steps** (database migrations, code deployment)
- **Verification steps** (health checks, smoke tests)
- **Rollback procedure** (how to revert if issues)
- **Post-deployment monitoring** (watch metrics/logs)
- **Communication plan** (who to notify)
- **Estimated timeline**
References agileflow-monitoring for setup and rollback procedures.
## Output
Ready-to-follow deployment guide
## Example Activation
User: "Create deployment guide for user login feature"
Skill: Generates:
```markdown
## Deployment Guide: User Login Feature (v2.18.0)
### Pre-Deployment Checklist
- [ ] All tests passing (npm test)
- [ ] Staging environment verified
- [ ] Database backup taken
- [ ] Monitoring alerts configured
- [ ] Team notified
### Deployment Steps
1. Run database migrations
\`\`\`bash
npm run migrate:up
\`\`\`
2. Deploy new code
\`\`\`bash
git push production main
\`\`\`
3. Verify deployment
- Check /health endpoint returns 200
- Verify JWT tokens working
- Check rate limiting active
### Monitoring (Watch these metrics)
- Login success rate (target: >95%)
- Login latency (target: <200ms p95)
- Error rate (alert if >1%)
- Rate limiting hits (expected: <5%)
### Rollback Procedure (if issues)
1. Revert database migrations:
\`\`\`bash
npm run migrate:down
\`\`\`
2. Revert code:
\`\`\`bash
git revert <commit-hash>
git push production main
\`\`\`
3. Verify rollback successful
**Estimated Timeline**: 15 minutes (10 min deploy + 5 min verify)
**Rollback Time**: 10 minutes
```

60
skills/diagram-generator/SKILL.md Normal file
View File

@@ -0,0 +1,60 @@
# diagram-generator
Generate Mermaid/ASCII diagrams from descriptions.
## Activation Keywords
- "diagram", "ASCII", "Mermaid", "flowchart", "architecture", "sequence diagram"
## When to Use
- Creating architecture diagrams
- Visualizing user workflows
- Drawing sequence diagrams
- System design documentation
## What This Does
Generates diagrams in Mermaid format (renders in GitHub/Markdown):
- **Flowcharts** (user flows, decision trees)
- **Sequence diagrams** (API interactions, service calls)
- **Architecture diagrams** (system components, data flow)
- **ER diagrams** (database relationships)
- **Gantt charts** (timeline/roadmap)
- **State diagrams** (state machines)
Also supports ASCII art for simple diagrams.
## Output
Mermaid code blocks ready for markdown files
## Example Activation
User: "Draw user login flow"
Skill: Generates:
```mermaid
flowchart TD
A[User opens login page] --> B[Enter email & password]
B --> C[Click submit]
C --> D{Valid credentials?}
D -->|No| E[Show error message]
E --> B
D -->|Yes| F[Generate JWT token]
F --> G[Redirect to dashboard]
G --> H[User logged in]
style D fill:#ff9999
style H fill:#99ff99
```
Architecture diagram example:
```mermaid
graph LR
Client[Frontend Client]
API[API Server]
DB[(Database)]
Cache[Redis Cache]
Auth[Auth Service]
Client -->|HTTP Request| API
API -->|Query| DB
API -->|Lookup| Cache
API -->|Verify Token| Auth
Auth -->|Check User| DB
```

73
skills/error-handler-template/SKILL.md Normal file
View File

@@ -0,0 +1,73 @@
# error-handler-template
Generate error handling boilerplate for different languages.
## Activation Keywords
- "error handling", "try catch", "error handler", "exception handling"
## When to Use
- Implementing error handling for new features
- Standardizing error responses across API
- Creating error logging patterns
## What This Does
Generates language-specific error handling code including:
- **Error classes** with custom fields
- **Try/catch patterns** for common scenarios
- **Error middleware** for API servers
- **Logging integration** for errors
- **User-friendly error messages**
- **HTTP status code mapping**
- **Stack trace and context capture**
Supports: JavaScript/TypeScript, Python, Java, Go, Rust
## Output
Error handling code ready to integrate
## Example Activation
User: "Create error handling for login endpoint"
Skill: Generates (TypeScript):
```typescript
// Custom error class
class AuthError extends Error {
constructor(
public code: string,
public statusCode: number,
message: string,
public context?: Record<string, any>
) {
super(message);
}
}
// Try/catch pattern
async function login(email: string, password: string) {
try {
const user = await findUserByEmail(email);
if (!user) {
throw new AuthError('USER_NOT_FOUND', 404, 'User not found', { email });
}
const isValid = await verifyPassword(password, user.passwordHash);
if (!isValid) {
logger.warn('Invalid password attempt', { email });
throw new AuthError(
'INVALID_CREDENTIALS',
401,
'Invalid email or password'
);
}
return generateToken(user);
} catch (error) {
if (error instanceof AuthError) {
logger.error(error.message, { code: error.code, context: error.context });
throw error;
}
// Handle unexpected errors
logger.error('Unexpected error in login', { error });
throw new AuthError('INTERNAL_ERROR', 500, 'Internal server error');
}
}
```

77
skills/migration-checklist/SKILL.md Normal file
View File

@@ -0,0 +1,77 @@
# migration-checklist
Generate data migration checklist.
## Activation Keywords
- "migration", "zero-downtime", "data migration", "migration checklist"
## When to Use
- Planning data migrations (schema changes, zero-downtime)
- Moving data between systems
- Large-scale data transformations
## What This Does
Generates comprehensive migration checklist including:
- **Pre-migration validation** (backup, verify counts)
- **Migration phases** (dual-write, backfill, switch)
- **Rollback procedures** (tested and documented)
- **Data validation rules** (checksums, counts, integrity)
- **Monitoring during migration** (watch for anomalies)
- **Post-migration verification** (smoke tests, queries)
- **Cleanup procedures** (remove old schema/data)
- **Communication timeline**
Coordinates with agileflow-datamigration agent for detailed migration planning.
## Output
Ready-to-execute migration checklist
## Example Activation
User: "Plan zero-downtime migration from sessions to JWT"
Skill: Generates:
```markdown
## Migration Checklist: Session → JWT Migration
### Phase 1: Preparation (pre-migration)
- [ ] Create full database backup (test restore)
- [ ] Verify staging matches production (data volume, schema)
- [ ] Prepare rollback procedure (documented and tested)
- [ ] Brief team on timeline and communication
- [ ] Schedule 2-hour maintenance window
- [ ] Set up monitoring dashboards
### Phase 2: Dual-Write (no downtime)
- [ ] Deploy code that writes to BOTH sessions + JWT
- [ ] Monitor for errors (should be zero)
- [ ] Backfill JWT for existing sessions (background job)
- [ ] Track conversion progress (% of sessions migrated)
- [ ] Once 100% converted: Wait 24h for safety
### Phase 3: Verify
- [ ] Check record counts match:
- SELECT COUNT(*) FROM sessions
- SELECT COUNT(*) FROM jwt_tokens
- Should be equal
- [ ] Validate JWT expiration timestamps
- [ ] Check no orphaned sessions
- [ ] Spot-check 100 random sessions
### Phase 4: Switch Reads
- [ ] Deploy code to read from JWT instead of sessions
- [ ] Monitor error rate (should be zero)
- [ ] Keep writing to BOTH for 24h (safety)
- [ ] Verify user experience
### Phase 5: Cleanup
- [ ] Stop writing to sessions table
- [ ] Archive sessions (backup)
- [ ] Drop sessions table
- [ ] Update documentation
### Rollback Point
If issues during Phase 1-2: Revert to code writing sessions only (backward compatible)
If issues during Phase 3-4: Switch reads back to sessions (keep JWT as backup)
**Estimated Timeline**: 3-4 hours total
**Expected Downtime**: 0 (zero-downtime migration)
```

60
skills/pr-description/SKILL.md Normal file
View File

@@ -0,0 +1,60 @@
# pr-description
Generate pull request description with testing instructions.
## Activation Keywords
- "pull request", "create PR", "merge request", "pr description", "pr body"
## When to Use
- Creating pull request on GitHub/GitLab
- Need comprehensive PR description with testing steps
- Documenting changes for code review
## What This Does
Generates complete PR description including:
- **Summary**: 2-3 sentence overview of changes
- **Related Issues**: Links to GitHub issues/stories
- **Changes Made**: Bulleted list of modifications
- **Testing Instructions**: Step-by-step testing guide
- **Checklist**: Pre-merge verification items
- **Migration Guide**: Steps for deploying if needed
- **Screenshots/Links**: If UI changes or demos
Coordinates with relevant agents (testing, documentation, etc.).
## Output
Ready-to-paste PR description
## Example Activation
User: "Create PR for user login feature"
Skill: Generates:
```markdown
## Summary
Implements user authentication system with JWT tokens and rate limiting.
Includes login endpoint, password reset flow, and token refresh.
## Related Issues
Closes #42 (User Authentication Epic)
Relates to: US-0001, US-0002, US-0003
## Changes Made
- ✨ POST /api/auth/login endpoint with JWT generation
- ✨ POST /api/auth/logout endpoint
- ✨ Password reset flow with email verification
- 🐛 Fixed rate limiting to prevent brute force
- 📝 Updated API documentation
- ✅ Added 45 test cases (98% coverage)
## Testing Instructions
1. Start dev server: `npm run dev`
2. Test login: curl -X POST http://localhost:3000/api/auth/login
3. Verify JWT: Check token expiration (24h)
4. Test rate limiting: 5+ failed attempts should block
## Checklist
- [x] Tests passing
- [x] Code coverage >80%
- [x] No console errors
- [x] API docs updated
- [x] Database migrations run
```

64
skills/sql-schema-generator/SKILL.md Normal file
View File

@@ -0,0 +1,64 @@
# sql-schema-generator
Generate SQL schemas with migrations.
## Activation Keywords
- "SQL", "schema", "database design", "CREATE TABLE", "migration"
## When to Use
- Designing database schemas
- Creating migrations for new features
- Defining table structures and relationships
## What This Does
Generates SQL DDL statements including:
- **CREATE TABLE** statements with data types
- **Indexes** for performance
- **Foreign keys** for relationships
- **Constraints** (NOT NULL, UNIQUE, CHECK)
- **Default values** where applicable
- **Comments** explaining purpose
Also generates:
- **Migration files** (with up/down versions)
- **Rollback procedures**
- **Data migration scripts** if needed
Coordinates with agileflow-database agent.
## Output
SQL migration files in migrations/ directory
## Example Activation
User: "Create users and sessions tables"
Skill: Generates:
```sql
-- Migration: 2025-10-28_create_users_table
-- UP: Create tables
CREATE TABLE users (
id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
email VARCHAR(255) NOT NULL UNIQUE,
password_hash VARCHAR(255) NOT NULL,
created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
is_active BOOLEAN DEFAULT true,
INDEX idx_email (email),
INDEX idx_created_at (created_at)
);
CREATE TABLE sessions (
id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
user_id UUID NOT NULL,
token VARCHAR(500) NOT NULL UNIQUE,
expires_at TIMESTAMP NOT NULL,
created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
FOREIGN KEY (user_id) REFERENCES users(id) ON DELETE CASCADE,
INDEX idx_user_id (user_id),
INDEX idx_expires_at (expires_at)
);
-- DOWN: Drop tables (for rollback)
DROP TABLE IF EXISTS sessions;
DROP TABLE IF EXISTS users;
```

29
skills/story-skeleton/SKILL.md Normal file
View File

@@ -0,0 +1,29 @@
# story-skeleton
Auto-generate story template with boilerplate sections pre-filled.
## Activation Keywords
- "create story", "new story", "story template", "story skeleton"
## When to Use
- User requests to create a new user story
- Need to quickly scaffold a story structure
- Starting epic implementation
## What This Does
Generates story YAML frontmatter + markdown template with:
- Story ID (auto-generated from epic context)
- Epic reference
- Title and description sections
- Acceptance Criteria (Given/When/Then format stubs)
- Architecture Context section with 6 subsections
- Previous Story Insights section
- Testing Strategy section
- Dev Agent Record template
## Output
Complete story file ready for population by epic-planner agent.
## Example Activation
User: "Create a story for user login API"
Skill: Generates story skeleton with all sections, ready for epic-planner to fill in details

58
skills/test-case-generator/SKILL.md Normal file
View File

@@ -0,0 +1,58 @@
# test-case-generator
Generate test cases from acceptance criteria.
## Activation Keywords
- "test cases", "test plan", "from AC", "test from acceptance"
## When to Use
- Converting acceptance criteria to test cases
- Creating test stubs for new features
- Planning test coverage
## What This Does
Converts Given/When/Then acceptance criteria into:
- **Unit test cases** (if applicable)
- **Integration test cases** (API, database)
- **E2E test cases** (full user workflow)
- **Negative test cases** (error scenarios)
- **Edge cases** (boundary conditions)
Generates test case names, setup steps, assertions, and expected results.
Coordinates with agileflow-testing and agileflow-qa agents.
## Output
Test case stub at docs/07-testing/test-cases/<STORY_ID>.md
## Example Activation
User: "Generate test cases from user login AC"
Skill: Generates:
```markdown
## Test Cases for User Login (US-0001)
### TC-001: Valid login succeeds
Given: Valid user registered with email/password
When: POST to /api/auth/login with valid credentials
Then: Returns 200 with JWT token (24h expiration)
### TC-002: Wrong password fails
Given: User exists, wrong password provided
When: POST to /api/auth/login
Then: Returns 401 with error message
### TC-003: Rate limiting active
Given: User failed login 5 times
When: Attempt 6th login
Then: Returns 429 Too Many Requests
### TC-004: Invalid email format
Given: Malformed email address
When: POST to /api/auth/login
Then: Returns 400 Bad Request
### Edge Cases
- Empty email/password
- SQL injection attempts
- Token validation after expiration
```

60
skills/type-definitions/SKILL.md Normal file
View File

@@ -0,0 +1,60 @@
# type-definitions
Generate TypeScript interfaces and types from descriptions.
## Activation Keywords
- "TypeScript", "types", "@interface", "type definition", "interface definition"
## When to Use
- Creating TypeScript interfaces for data structures
- Defining function signatures
- Type-safe API request/response types
## What This Does
Generates TypeScript/TypeScript-compatible types including:
- **Interfaces** for data structures
- **Type aliases** for unions and primitives
- **Enums** for fixed sets of values
- **Generic types** for reusable patterns
- **JSDoc comments** for IDE intellisense
- **Type guards** for runtime validation
Includes proper typing with optionals, required fields, and readonly modifiers.
## Output
TypeScript code ready to add to types/ directory
## Example Activation
User: "Create types for User and LoginRequest"
Skill: Generates:
```typescript
/** User account information */
export interface User {
id: string;
email: string;
passwordHash: string;
createdAt: Date;
updatedAt: Date;
isActive: boolean;
}
/** Login request payload */
export interface LoginRequest {
email: string;
password: string;
}
/** Login response payload */
export interface LoginResponse {
token: string;
expiresIn: number;
user: Omit<User, 'passwordHash'>;
}
/** Authentication error response */
export interface AuthError {
code: 'INVALID_CREDENTIALS' | 'USER_NOT_FOUND' | 'RATE_LIMITED';
message: string;
retryAfter?: number;
}
```

59
skills/validation-schema-generator/SKILL.md Normal file
View File

@@ -0,0 +1,59 @@
# validation-schema-generator
Generate input validation schemas (Joi, Zod, Yup).
## Activation Keywords
- "validation", "schema", "joi", "zod", "yup", "validate input"
## When to Use
- Creating request body validation
- Form validation schemas
- Input sanitization and validation
## What This Does
Generates validation schemas for popular libraries:
- **Joi** (Node.js)
- **Zod** (TypeScript)
- **Yup** (React forms)
- **Pydantic** (Python)
Includes:
- **Required/optional fields**
- **Type validation** (string, number, email, etc.)
- **Length constraints** (min, max)
- **Pattern validation** (regex)
- **Custom validators**
- **Error messages** (user-friendly)
- **Transformation rules** (trim, lowercase, etc.)
## Output
Validation schema code ready for integration
## Example Activation
User: "Create Zod validation for login request"
Skill: Generates:
```typescript
import { z } from 'zod';
export const loginRequestSchema = z.object({
email: z
.string('Email is required')
.email('Invalid email format')
.toLowerCase()
.trim(),
password: z
.string('Password is required')
.min(8, 'Password must be at least 8 characters')
.regex(/[A-Z]/, 'Password must contain uppercase')
.regex(/[0-9]/, 'Password must contain number'),
});
export type LoginRequest = z.infer<typeof loginRequestSchema>;
// Usage
const validateLogin = (data: unknown) => {
return loginRequestSchema.parse(data);
};
```
Also generates Joi, Yup, Pydantic versions.