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

22
commands/adr.md Normal file
View File

@@ -0,0 +1,22 @@
---
description: adr-new
allowed-tools: Bash, Read, Edit, Write, Glob, Grep
---
# adr-new
Create a new Architecture Decision Record.
## Prompt
ROLE: ADR Writer
INPUTS
NUMBER=<4-digit> TITLE=<Decision Title>
CONTEXT=<short context> DECISION=<choice>
CONSEQUENCES=<trade-offs> LINKS=<optional bullets>
ACTION
Create docs/03-decisions/adr-<NUMBER>-<slug>.md from adr-template.md (date=now; status=Accepted unless specified).
Diff-first; YES/NO.

23
commands/agent.md Normal file
View File

@@ -0,0 +1,23 @@
---
description: agent-new
allowed-tools: Bash, Read, Edit, Write, Glob, Grep
---
# agent-new
Onboard a new agent with profile and system prompt.
## Prompt
ROLE: Agent Onboarder
INPUTS
AGENT_ID=<AG-UI|AG-API|AG-CI or custom> ROLE=<role>
TOOLS=[list] SCOPE=<directories & story tags>
ACTIONS
1) Create docs/02-practices/prompts/agents/agent-<AGENT_ID>.md from agent-profile-template.md including a strict "System Prompt (contract)" (scope boundaries, commit/branch rules, tests, status/bus updates).
2) Update docs/09-agents/roster.yaml (create if missing) mapping id→role/tools/scope.
3) Print a persona snippet to paste as that terminal's system prompt.
Diff-first; YES/NO.

34
commands/assign.md Normal file
View File

@@ -0,0 +1,34 @@
---
description: assign
allowed-tools: Bash, Read, Edit, Write, Glob, Grep
---
# assign
Assign or reassign a story to an owner with status update.
## Prompt
ROLE: Assigner
INPUTS
STORY=<US-ID> NEW_OWNER=<id> NEW_STATUS=ready|in-progress|blocked|in-review|done NOTE=<short text>
ACTIONS
1) Update story frontmatter (owner,status,updated) in docs/06-stories/**/<STORY>*.
2) Merge docs/09-agents/status.json (owner,status,last_update).
**CRITICAL**: Always use jq or Edit tool for JSON operations.
3) **Validate JSON after update**:
```bash
# Validate status.json after modification
if ! jq empty docs/09-agents/status.json 2>/dev/null; then
echo "❌ ERROR: status.json is now invalid JSON!"
echo "Run: bash scripts/validate-json.sh docs/09-agents/status.json"
exit 1
fi
```
4) Append bus/log.jsonl "assign" line.
**JSON Safety**: Always use jq or Edit tool (never echo/cat > status.json). Validate after modifications.
Preview changes; YES/NO.

347
commands/auto.md Normal file
View File

@@ -0,0 +1,347 @@
---
description: auto-story
allowed-tools: Bash, Read, Edit, Write, Glob, Grep
---
# auto-story
Automatically generate user stories from product artifacts like PRDs, mockups, or API docs.
## Prompt
ROLE: Story Generator
OBJECTIVE
Parse product documentation and generate actionable user stories with acceptance criteria.
INPUTS
- SOURCE=<file path or URL> (required: PRD, mockup, API spec, etc.)
- EPIC=<EP_ID> (optional: associate stories with existing epic)
- OWNER=<AG_ID> (optional: default owner for stories)
- AUTO_CREATE=yes|no (default: no, show preview first)
SUPPORTED SOURCES
### 1. Product Requirements Document (PRD)
Formats: .md, .docx, .pdf, .txt
Parse for:
- User personas
- Feature descriptions
- Success criteria
- Edge cases
- Non-functional requirements
### 2. UI Mockups/Designs
Formats: Figma URL, .png/.jpg (with OCR), design spec .md
Extract:
- Screens and components
- User interactions
- Navigation flows
- Form fields and validation
### 3. API Documentation
Formats: OpenAPI/Swagger JSON, .md
Extract:
- Endpoints (method + path)
- Request/response schemas
- Authentication requirements
- Error cases
### 4. User Flow Diagrams
Formats: Mermaid .mmd, PlantUML, .png (with OCR)
Extract:
- Steps in user journey
- Decision points
- Alternative paths
PARSING WORKFLOW
1. Read source file/URL
2. Identify document type
3. Extract features/requirements
4. Group related requirements
5. Generate stories with AC
6. Show preview (diff-first)
7. Create files (if approved)
EXAMPLE: PRD → Stories
**Input PRD**:
```markdown
# User Authentication Feature
## Overview
Allow users to register, log in, and manage their accounts.
## Requirements
- Users can register with email and password
- Email verification required before login
- Users can log in with verified email
- Users can reset forgotten password via email
- Session expires after 24 hours
- Support OAuth login with Google and GitHub
## Non-functional
- Login must complete in <500ms
- Password must be hashed with bcrypt
- Rate limit: 5 login attempts per minute
```
**Generated Stories**:
```markdown
---
story_id: US-0050
epic: EP-0010
title: User registration with email verification
owner: AG-API
status: ready
estimate: 1.5d
dependencies: []
---
# US-0050: User registration with email verification
## Description
As a new user, I want to register with my email and password so that I can create an account.
## Acceptance Criteria
- **Given** I am on the registration page
**When** I enter a valid email and password (min 8 chars, 1 uppercase, 1 number)
**Then** my account is created and a verification email is sent
- **Given** I receive the verification email
**When** I click the verification link
**Then** my email is marked as verified and I can log in
- **Given** I try to log in with an unverified email
**When** I submit credentials
**Then** I see an error: "Please verify your email first"
## Technical Notes
- Password hashing: bcrypt with 12 rounds
- Verification token: UUID v4, expires after 24 hours
- Email service: Use existing EmailService
## Testing Strategy
- Unit tests for registration logic
- Integration test for verification flow
- Security test: reject weak passwords
---
# US-0051: User login with session management
[Similar structure...]
---
# US-0052: Password reset flow
[Similar structure...]
---
# US-0053: OAuth login (Google)
[Similar structure...]
---
# US-0054: Rate limiting for login attempts
[Similar structure...]
```
EXAMPLE: API Spec → Stories
**Input OpenAPI**:
```yaml
paths:
/api/users:
post:
summary: Create user
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
name: { type: string }
email: { type: string, format: email }
responses:
201: { description: User created }
400: { description: Invalid input }
```
**Generated Story**:
```markdown
---
story_id: US-0060
title: Implement POST /api/users endpoint
owner: AG-API
estimate: 0.5d
---
# US-0060: Implement POST /api/users endpoint
## Acceptance Criteria
- **Given** a valid request body with name and email
**When** POST /api/users is called
**Then** a user is created and returns 201 with user object
- **Given** an invalid email format
**When** POST /api/users is called
**Then** returns 400 with error: "Invalid email format"
- **Given** a missing required field
**When** POST /api/users is called
**Then** returns 400 with error: "Field 'name' is required"
## Technical Notes
- Validate email format using regex or validator library
- Check for duplicate email (return 409 Conflict)
```
EXAMPLE: Mockup → Stories
**Input**: Screenshot of login form
**OCR/Analysis**:
- Text input: Email
- Text input: Password (masked)
- Checkbox: Remember me
- Button: Log In
- Link: Forgot password?
- Link: Sign up
**Generated Stories**:
```markdown
US-0070: Build login form UI component
US-0071: Implement "Remember me" functionality
US-0072: Create "Forgot password" flow
US-0073: Add "Sign up" registration link
```
STORY GENERATION RULES
### Good Story Characteristics (INVEST)
- **Independent**: Can be completed without dependencies
- **Negotiable**: Details can be adjusted
- **Valuable**: Delivers user-facing value
- **Estimable**: Can be sized (0.5-2 days)
- **Small**: Completable in 1 sprint
- **Testable**: Has clear acceptance criteria
### Acceptance Criteria Format
Always use Given/When/Then:
```markdown
- **Given** [precondition/context]
**When** [action/trigger]
**Then** [expected outcome]
```
### Estimates
- 0.5d: Simple CRUD, basic UI component
- 1d: Standard feature with validation and tests
- 1.5d: Complex logic or integration
- 2d: Significant refactor or architecture change
> If estimate >2d, suggest breaking into smaller stories
STORY GROUPING
Related stories are grouped into epics:
```
PRD: "User Authentication Feature"
→ Epic: EP-0010 "User Authentication"
→ US-0050: Registration
→ US-0051: Login
→ US-0052: Password reset
→ US-0053: OAuth (Google)
→ US-0054: OAuth (GitHub)
→ US-0055: Rate limiting
→ US-0056: Session management
```
OUTPUT PREVIEW
Before creating, show summary:
```markdown
# Story Generation Preview
**Source**: docs/requirements/auth-prd.md
**Epic**: EP-0010 (User Authentication)
**Stories to Create**: 7
## Summary
1. US-0050: User registration (1.5d, AG-API)
2. US-0051: User login (1d, AG-API)
3. US-0052: Password reset (1d, AG-API)
4. US-0053: OAuth Google (1.5d, AG-API)
5. US-0054: OAuth GitHub (1.5d, AG-API)
6. US-0055: Rate limiting (0.5d, AG-CI)
7. US-0056: Session management (1d, AG-API)
**Total Estimate**: 8.5 days
**Owners**: AG-API (6), AG-CI (1)
---
Preview of US-0050:
[Show first story in full]
---
Create these stories? (YES/NO)
```
ACTIONS (after approval)
1. Create epic (if EPIC not provided):
- docs/05-epics/EP-XXXX.md
2. Create stories:
- docs/06-stories/EP-XXXX/US-XXXX-<slug>.md (one per story)
3. Create test stubs:
- docs/07-testing/test-cases/US-XXXX.md (one per story)
4. Update status.json:
- Add all stories with status=ready
5. Append to bus:
- {"type":"assign","story":"US-XXXX","owner":"AG-API"} for each
INTEGRATION
- Link back to source: Add "Source: <path or URL>" in story frontmatter
- Update source doc with story IDs (if editable markdown)
- Suggest running /AgileFlow:readme-sync on docs/06-stories/
LIMITATIONS & WARNINGS
- **Review Generated Stories**: AI may misinterpret requirements
- **Add Context**: Stories may need technical details added manually
- **Dependencies**: Manually add dependencies between stories
- **Estimates**: Validate estimates based on team velocity
RULES
- Always preview before creating
- Generate 3-8 stories per epic (break down further if needed)
- Every story gets test stub
- Use consistent ID numbering
- Link stories to source document
- Diff-first, YES/NO for all file operations
OUTPUT
- Story generation preview
- Epic file (if created)
- Story files (multiple)
- Test stub files (multiple)
- Updated status.json

1024
commands/babysit.md Normal file
View File

File diff suppressed because it is too large Load Diff

343
commands/blockers.md Normal file
View File

@@ -0,0 +1,343 @@
---
description: blockers
allowed-tools: Bash, Read, Edit, Write, Glob, Grep
---
# blockers
Comprehensive blocker tracking, resolution suggestions, and cross-agent coordination (leverages v2.7.0 AG-API unblocking capabilities).
## Prompt
ROLE: Blocker Analyst & Resolution Coordinator
OBJECTIVE
Extract, categorize, and prioritize all blockers across the AgileFlow system. Leverage v2.7.0's cross-agent coordination where AG-API actively searches for blocked AG-UI stories. Provide actionable resolution suggestions with links to relevant ADRs and research.
INPUTS (all optional)
- AGENT=<agent-id> — Filter by specific agent (e.g., AG-UI, AG-API)
- SHOW_RESOLVED=true — Include recently resolved blockers (last 7 days)
- DETAILED=true — Show extended details (dependencies, research links, ADRs)
KNOWLEDGE LOADING (run first, silently)
Read in order:
1. docs/09-agents/status.json — Current story statuses and blockers
2. docs/09-agents/bus/log.jsonl — Recent unblock/blocked messages (last 50 lines)
3. docs/06-stories/**/US-*.md — Story details for blocked stories
4. docs/03-decisions/adr-*.md — Index all ADRs for resolution suggestions
5. docs/10-research/*.md — Index research notes for blocker context
6. docs/05-epics/*.md — Epic context for blocked stories
BLOCKER EXTRACTION
## 1. Direct Blockers (status="blocked")
```bash
# Extract all blocked stories
jq -r '.stories | to_entries[] | select(.value.status=="blocked") |
"\(.key)|\(.value.owner)|\(.value.blocked_by // "Not specified")|\(.value.last_update)|\(.value.epic // "none")"' \
docs/09-agents/status.json
```
## 2. Dependency Blockers (stories waiting on dependencies)
```bash
# Find stories blocked by dependencies
jq -r '.stories | to_entries[] | select(.value.deps) |
"\(.key)|\(.value.owner)|\(.value.deps | join(","))|\(.value.status)"' \
docs/09-agents/status.json | while IFS='|' read story owner deps status; do
# Check each dependency
IFS=',' read -ra DEP_ARRAY <<< "$deps"
for dep in "${DEP_ARRAY[@]}"; do
dep_status=$(jq -r ".stories[\"$dep\"].status" docs/09-agents/status.json 2>/dev/null)
# If dependency is not done, this is a blocker
if [ "$dep_status" != "done" ]; then
dep_owner=$(jq -r ".stories[\"$dep\"].owner" docs/09-agents/status.json 2>/dev/null)
echo "$story is waiting on $dep (owned by $dep_owner, status: $dep_status)"
fi
done
done
```
## 3. WIP Capacity Blockers (agents at WIP limit)
```bash
# Find agents at WIP limit (2 in-progress stories)
jq -r '.stories | to_entries[] | select(.value.status=="in-progress") |
"\(.value.owner)|\(.key)"' docs/09-agents/status.json | \
awk -F'|' '{count[$1]++; stories[$1]=stories[$1] $2 " "}
END {for (agent in count) if (count[agent] >= 2)
print agent " at WIP limit (" count[agent] "/2): " stories[agent]}'
# Cross-reference with ready stories waiting for these agents
```
## 4. Stale Blockers (blocked >14 days)
```bash
fourteen_days_ago=$(date -u -d '14 days ago' +%Y-%m-%dT%H:%M:%S 2>/dev/null || date -u -v-14d +%Y-%m-%dT%H:%M:%S 2>/dev/null)
jq -r --arg cutoff "$fourteen_days_ago" '.stories | to_entries[] |
select(.value.status=="blocked") |
select(.value.last_update < $cutoff) |
"\(.key)|\(.value.owner)|\(.value.last_update)|\(.value.blocked_by // \"Unknown\")"' \
docs/09-agents/status.json
```
BLOCKER CATEGORIZATION
Group blockers by type:
1. **Technical** — Missing APIs, infrastructure, dependencies not done
2. **Coordination** — Waiting on other agents, handoff needed
3. **Clarification** — Requirements unclear, acceptance criteria incomplete
4. **External** — Third-party service, approval, access needed
5. **Capacity** — Agent at WIP limit, no bandwidth
6. **Research** — Need investigation before proceeding
Assign category based on:
- `blocked_by` text content (keywords: "API", "waiting", "unclear", "need", "WIP")
- Bus messages (type: "blocked", text analysis)
- Story dependency chain
RESOLUTION SUGGESTIONS
For each blocker, provide:
### Technical Blockers
- Check if dependent story is in-progress
- Estimate completion time (based on story estimate and elapsed time)
- Suggest interim workarounds (mock data, feature flags)
- Link to relevant ADRs (search for technology/component keywords)
### Coordination Blockers (v2.7.0 Focus)
- **AG-API Unblocking Status**: Check bus/log.jsonl for AG-API messages about unblocking AG-UI stories
```bash
# Find AG-API unblock messages for AG-UI stories
grep '"from":"AG-API"' docs/09-agents/bus/log.jsonl | grep '"type":"unblock"' | tail -n 10
```
- Show AG-API progress on implementing endpoints that AG-UI is waiting for
- Suggest handoff if different agent better suited
- Identify if blocker is due to missing communication (no bus messages)
### Clarification Blockers
- Check story file for incomplete AC
- Suggest questions to ask (based on epic goals)
- Link to related research or ADRs
- Recommend creating spike story for investigation
### External Blockers
- Identify who/what is blocking (from blocked_by text)
- Suggest escalation path
- Recommend documenting assumptions to proceed in parallel
### Capacity Blockers
- Show agent's current in-progress stories
- Suggest redistributing to other agents
- Estimate when bandwidth will free up
### Research Blockers
- Search docs/10-research/ for related topics
- Check for stale research (>90 days) that might need updating
- Suggest running /AgileFlow:chatgpt MODE=research for specific topic
- Link to ADRs that might have context
CROSS-AGENT COORDINATION ANALYSIS (v2.7.0)
Specifically analyze AG-API ↔ AG-UI coordination:
```bash
# Find AG-UI stories blocked waiting for AG-API endpoints
jq -r '.stories | to_entries[] |
select(.value.owner=="AG-UI") |
select(.value.status=="blocked") |
select(.value.blocked_by | contains("API") or contains("endpoint") or contains("backend")) |
"\(.key)|\(.value.blocked_by)"' docs/09-agents/status.json
# For each, check if AG-API has started work
# Look for AG-API stories that might unblock these
jq -r '.stories | to_entries[] |
select(.value.owner=="AG-API") |
select(.value.status=="in-progress" or .value.status=="in-review") |
"\(.key)|\(.value.summary)"' docs/09-agents/status.json
```
Show:
- Which AG-UI stories are blocked waiting for AG-API
- Which AG-API stories are in progress that will unblock AG-UI
- Estimated unblock timeline (based on AG-API story estimates)
- Recent AG-API unblock messages from bus
ADR & RESEARCH LINKING
For each blocker:
1. **Extract keywords** from blocked_by text and story title
2. **Search ADRs**: `grep -i <keywords> docs/03-decisions/adr-*.md`
3. **Search research**: `grep -i <keywords> docs/10-research/*.md`
4. **Link relevant documents** in output (path + brief context)
Example:
```
US-0042 blocked by "Need authentication middleware decision"
→ Related ADR: docs/03-decisions/adr-005-auth-strategy.md
→ Related Research: docs/10-research/20251015-auth-comparison.md
```
RECENTLY RESOLVED BLOCKERS (if SHOW_RESOLVED=true)
```bash
# Find unblock messages in last 7 days
seven_days_ago=$(date -u -d '7 days ago' +%Y-%m-%dT%H:%M:%S 2>/dev/null || date -u -v-7d +%Y-%m-%dT%H:%M:%S 2>/dev/null)
grep '"type":"unblock"' docs/09-agents/bus/log.jsonl | while read -r line; do
ts=$(echo "$line" | jq -r '.ts')
# Compare timestamp
if [[ "$ts" > "$seven_days_ago" ]]; then
story=$(echo "$line" | jq -r '.story')
from=$(echo "$line" | jq -r '.from')
text=$(echo "$line" | jq -r '.text')
echo "✅ $ts - $from unblocked $story: $text"
fi
done
```
OUTPUT FORMAT
```
🚧 Blocker Dashboard
====================
Generated: <timestamp>
Filter: <agent filter if applied, else "All agents">
📊 SUMMARY
----------
Total Active Blockers: X
- Technical: X
- Coordination: X
- Clarification: X
- External: X
- Capacity: X
- Research: X
Critical (>14 days): X
Cross-Agent Blockers: X (AG-UI ↔ AG-API coordination)
🔴 CRITICAL BLOCKERS (>14 days)
-------------------------------
[Story ID] [Owner] [Type] [Blocked Since]
<description>
Resolution: <suggested action>
Related: <ADR/research links>
---
⚠️ ACTIVE BLOCKERS
-------------------
### Technical Blockers (X)
US-0042 | AG-UI | Blocked: Missing login API endpoint
Status: Blocked for 5 days
Epic: EP-0010 (Authentication System)
Dependencies: US-0038 (AG-API, in-progress, est. 1d remaining)
💡 Resolution:
- US-0038 is 70% complete (based on elapsed time vs estimate)
- Estimated unblock: Tomorrow
- Workaround: Use mock auth data for UI development
- AG-API is actively working on this (last update: 2h ago)
📚 Related:
- ADR: docs/03-decisions/adr-005-auth-strategy.md
- Research: docs/10-research/20251015-jwt-vs-session.md
---
### Coordination Blockers (X)
[v2.7.0 AG-API Unblocking Status]
AG-API is actively unblocking 2 AG-UI stories:
✅ US-0038 (POST /auth/login) - 70% complete, unblocks US-0042
🔄 US-0041 (GET /user/profile) - 30% complete, unblocks US-0045
Recent AG-API unblock activity:
- 2h ago: "POST /auth/login endpoint complete, ready for integration"
- 5h ago: "Started work on user profile endpoint"
---
### Clarification Blockers (X)
US-0051 | AG-DEVOPS | Blocked: Unclear deployment target
Status: Blocked for 3 days
Epic: EP-0012 (CI/CD Pipeline)
💡 Resolution:
- Story AC incomplete (missing "Then" clause)
- Suggest questions:
1. Which platform? (Vercel, AWS, Docker)
2. What's the target environment? (staging, production, both)
3. Who approves production deploys?
- Related: Epic EP-0012 mentions "cloud-native" but no specifics
📚 Related:
- Research: docs/10-research/20251010-deployment-comparison.md (90 days old, may be stale)
- Suggest: /AgileFlow:chatgpt MODE=research TOPIC="Modern deployment platforms 2025"
---
💪 CAPACITY BLOCKERS
--------------------
AG-API at WIP limit (2/2):
- US-0038 (in-progress, 70% complete)
- US-0041 (in-progress, 30% complete)
Ready stories waiting for AG-API: 3
- US-0055 (Epic: EP-0011, est: 1d)
- US-0060 (Epic: EP-0013, est: 2d)
- US-0062 (Epic: EP-0010, est: 0.5d)
💡 Suggestion: Wait for US-0038 to complete (est. tomorrow), then pick up US-0062 (smallest)
---
✅ RECENTLY RESOLVED (last 7 days)
----------------------------------
[if SHOW_RESOLVED=true]
2025-10-21 14:30 - AG-API unblocked US-0042: "POST /auth/login endpoint complete"
2025-10-20 09:15 - AG-UI unblocked US-0033: "Design system tokens extracted"
2025-10-19 16:45 - AG-CI unblocked US-0028: "Test environment configured"
---
🎯 PRIORITIZED ACTIONS
----------------------
1. [High] Resolve US-0051 clarification blocker (3 days old, blocking epic)
2. [High] Complete US-0038 (70% done, unblocks AG-UI's US-0042)
3. [Medium] Review stale research for US-0051 (deployment comparison is 90 days old)
4. [Low] Redistribute AG-API backlog when capacity opens
Next Commands:
- /AgileFlow:status STORY=US-0051 STATUS=ready NOTE="Clarified deployment target: Vercel"
- /AgileFlow:chatgpt MODE=research TOPIC="Modern deployment platforms 2025"
- /AgileFlow:validate-system (check for other inconsistencies)
- /AgileFlow:board (visualize current state)
```
RULES
- Always show both blocker stats and resolution suggestions
- Prioritize critical (>14 days) blockers first
- Highlight v2.7.0 cross-agent coordination (AG-API unblocking AG-UI)
- Link ADRs and research when relevant keywords match
- Suggest specific next commands to resolve blockers
- Read-only operation (no modifications to status.json)
- Group by blocker type for clarity
- Show estimated unblock times based on in-progress dependencies
FOLLOW-UP INTEGRATION
After displaying blockers, ask:
"Would you like me to update any blocker statuses or create resolution stories?"
If yes, suggest:
- `/AgileFlow:status STORY=<id> STATUS=ready` for resolved blockers
- `/story-new` for creating unblocking stories
- `/handoff` for reassigning capacity-blocked stories
- `/adr-new` for architectural blockers needing decisions

241
commands/board.md Normal file
View File

@@ -0,0 +1,241 @@
---
description: board
allowed-tools: Bash, Read, Edit, Write, Glob, Grep
---
# board
Generate a visual kanban board from current story statuses.
## Prompt
ROLE: Board Visualizer
OBJECTIVE
Create a visual kanban board showing stories organized by status with color coding, WIP limits, and quick stats.
INPUTS (optional)
- EPIC=<EP_ID> (filter by specific epic)
- OWNER=<agent_id> (filter by owner)
- FORMAT=ascii|markdown|html (default: ascii)
- GROUP_BY=status|owner|epic (default: status)
DATA SOURCE
Read docs/09-agents/status.json to get all current story statuses.
BOARD LAYOUT (ASCII Format)
```
╔══════════════════════════════════════════════════════════════════════════════╗
║ AGILEFLOW KANBAN BOARD ║
║ Updated: 2025-10-17 14:30 ║
╠══════════════════════════════════════════════════════════════════════════════╣
║ 📊 Summary: 15 stories | 3 ready | 4 in-progress | 2 in-review | 6 done ║
║ ⚠️ WIP Limit: 2/agent (AG-UI: 2/2 ⚠️, AG-API: 1/2 ✓, AG-CI: 0/2 ✓) ║
╚══════════════════════════════════════════════════════════════════════════════╝
┌─────────────────┬─────────────────┬─────────────────┬─────────────────┐
│ 📋 READY (3) │ 🔄 IN PROGRESS │ 👀 IN REVIEW │ ✅ DONE (6) │
│ WIP: - │ (4) WIP: 4/6 │ (2) WIP: - │ WIP: - │
├─────────────────┼─────────────────┼─────────────────┼─────────────────┤
│ │ │ │ │
│ 🟢 US-0042 │ 🟡 US-0038 │ 🔵 US-0035 │ ⚪ US-0030 │
│ Login form UI │ OAuth flow │ Password reset │ User registration│
│ AG-UI · 1d │ AG-API · 1.5d │ AG-API · 1d │ AG-API · 1d │
│ EP-0010 │ EP-0010 │ EP-0010 │ EP-0010 │
│ │ │ │ │
│ 🟢 US-0043 │ 🟡 US-0039 │ 🔵 US-0036 │ ⚪ US-0031 │
│ Profile page │ Session mgmt │ Email verify │ Login endpoint │
│ AG-UI · 1.5d │ AG-API · 1d │ AG-CI · 0.5d │ AG-API · 1d │
│ EP-0011 │ EP-0010 │ EP-0010 │ EP-0010 │
│ │ │ │ │
│ 🟢 US-0044 │ 🟡 US-0040 │ │ ⚪ US-0032 │
│ Dashboard │ Rate limiting │ │ JWT generation │
│ AG-UI · 2d │ AG-CI · 0.5d │ │ AG-API · 0.5d │
│ EP-0011 │ EP-0010 │ │ EP-0010 │
│ │ │ │ │
│ │ 🟡 US-0041 ⚠️ │ │ ⚪ US-0033 │
│ │ BLOCKED │ │ DB schema │
│ │ Payment API │ │ AG-API · 0.5d │
│ │ AG-API · 2d │ │ EP-0010 │
│ │ Dep: US-0035 │ │ │
│ │ │ │ ⚪ US-0034 │
│ │ │ │ Token refresh │
│ │ │ │ AG-API · 1d │
│ │ │ │ EP-0010 │
│ │ │ │ │
│ │ │ │ ⚪ US-0037 │
│ │ │ │ CI setup │
│ │ │ │ AG-CI · 1d │
│ │ │ │ EP-0010 │
└─────────────────┴─────────────────┴─────────────────┴─────────────────┘
Legend:
🟢 Priority: High 🟡 Priority: Medium 🔵 Priority: Low ⚪ Completed
⚠️ Blocked/WIP limit exceeded
```
COLOR CODING
Use emoji/symbols for visual distinction:
- 🟢 Green: High priority or ready to start
- 🟡 Yellow: In progress or medium priority
- 🔵 Blue: In review or low priority
- ⚪ White: Done
- 🔴 Red: Blocked
- ⚠️ Warning: WIP limit exceeded or blockers
MARKDOWN TABLE FORMAT
```markdown
## AgileFlow Board (2025-10-17 14:30)
**Summary**: 15 stories | 3 ready | 4 in-progress | 2 in-review | 6 done
| Ready | In Progress | In Review | Done |
|-------|-------------|-----------|------|
| **US-0042** 🟢<br>Login form UI<br>AG-UI · 1d<br>EP-0010 | **US-0038** 🟡<br>OAuth flow<br>AG-API · 1.5d<br>EP-0010 | **US-0035** 🔵<br>Password reset<br>AG-API · 1d<br>EP-0010 | **US-0030** ✅<br>User registration<br>AG-API · 1d<br>EP-0010 |
| **US-0043** 🟢<br>Profile page<br>AG-UI · 1.5d<br>EP-0011 | **US-0039** 🟡<br>Session mgmt<br>AG-API · 1d<br>EP-0010 | **US-0036** 🔵<br>Email verify<br>AG-CI · 0.5d<br>EP-0010 | **US-0031** ✅<br>Login endpoint<br>AG-API · 1d<br>EP-0010 |
| ... | ... | | ... |
### WIP Limits
- AG-UI: 2/2 ⚠️ (at limit)
- AG-API: 1/2 ✓
- AG-CI: 0/2 ✓
### Blockers
- US-0041 blocked by US-0035 (in review)
```
HTML FORMAT (for export)
```html
<!DOCTYPE html>
<html>
<head>
<style>
.board { display: flex; gap: 20px; padding: 20px; }
.column { flex: 1; background: #f5f5f5; border-radius: 8px; padding: 15px; }
.card { background: white; padding: 12px; margin: 10px 0; border-radius: 4px; box-shadow: 0 2px 4px rgba(0,0,0,0.1); }
.ready { border-left: 4px solid #4caf50; }
.in-progress { border-left: 4px solid #ff9800; }
.in-review { border-left: 4px solid #2196f3; }
.done { border-left: 4px solid #9e9e9e; }
.blocked { border: 2px solid #f44336; }
</style>
</head>
<body>
<h1>AgileFlow Kanban Board</h1>
<div class="board">
<div class="column">
<h2>📋 Ready (3)</h2>
<div class="card ready">
<strong>US-0042</strong><br>
Login form UI<br>
<small>AG-UI · 1d · EP-0010</small>
</div>
<!-- More cards -->
</div>
<!-- More columns -->
</div>
</body>
</html>
```
GROUP BY OWNER
```
╔══════════════════════════════════════════════════════════════════════════════╗
║ AGILEFLOW BOARD (Grouped by Owner) ║
╚══════════════════════════════════════════════════════════════════════════════╝
┌─────────────────┬─────────────────┬─────────────────┐
│ 🎨 AG-UI (5) │ 🔧 AG-API (8) │ ⚙️ AG-CI (2) │
│ WIP: 2/2 ⚠️ │ WIP: 1/2 ✓ │ WIP: 0/2 ✓ │
├─────────────────┼─────────────────┼─────────────────┤
│ │ │ │
│ 🟡 US-0038 │ 🟡 US-0039 │ ✅ US-0037 │
│ IN PROGRESS │ IN PROGRESS │ DONE │
│ Login form │ Session mgmt │ CI setup │
│ │ │ │
│ 🟡 US-0040 │ 🔵 US-0035 │ 🔵 US-0036 │
│ IN PROGRESS │ IN REVIEW │ IN REVIEW │
│ Profile page │ Password reset │ Email verify │
│ │ │ │
│ 🟢 US-0042 │ 🟢 US-0043 │ │
│ READY │ READY │ │
│ Dashboard │ Payment API │ │
└─────────────────┴─────────────────┴─────────────────┘
```
STATISTICS
Include helpful stats:
```
📊 Board Statistics
Throughput:
- Stories completed this week: 6
- Avg completion time: 2.3 days
- Velocity: 8.5 points/week
Status Distribution:
- Ready: 3 (20%)
- In Progress: 4 (27%)
- In Review: 2 (13%)
- Done: 6 (40%)
By Owner:
- AG-UI: 5 stories (2 in progress)
- AG-API: 8 stories (1 in progress)
- AG-CI: 2 stories (0 in progress)
Blockers:
- 1 story blocked (US-0041 waiting on US-0035)
Warnings:
- AG-UI at WIP limit (2/2)
- US-0050 stale (no updates in 7 days)
```
ACTIONS (after showing board)
1. Ask: "Would you like to:"
- Export to file? (board-YYYYMMDD.md or .html)
- Update a story status?
- View details for a specific story?
- Filter by epic/owner?
2. Suggest actions based on board state:
- "AG-UI is at WIP limit. Consider completing US-0038 before starting new work."
- "US-0041 is blocked. Can we unblock it by reviewing US-0035?"
- "3 stories ready. Which should we prioritize?"
INTEGRATION
- Save board snapshot to docs/08-project/boards/board-<YYYYMMDD>.md
- Track board states over time for velocity analysis
- Optionally update /AgileFlow:velocity with latest data
WORKFLOW
1. Read docs/09-agents/status.json
2. Parse stories by status
3. Apply filters (epic, owner) if specified
4. Calculate WIP limits and warnings
5. Render board in requested format
6. Show statistics
7. Suggest actions
RULES
- Never modify status.json (read-only visualization)
- Highlight blockers and WIP violations prominently
- Keep ASCII board width ≤80 chars for terminal viewing
- Update timestamp on every render
- Sort stories by priority within columns
OUTPUT
- Rendered kanban board (ASCII/markdown/HTML)
- Statistics summary
- Action suggestions
- Optional: saved snapshot file

321
commands/changelog.md Normal file
View File

@@ -0,0 +1,321 @@
---
description: generate-changelog
allowed-tools: Bash, Read, Edit, Write, Glob, Grep
---
# generate-changelog
Automatically generate changelog from PR titles, commits, and tags.
## Prompt
ROLE: Changelog Generator
OBJECTIVE
Create or update CHANGELOG.md based on merged PRs, commits, and version tags following Keep a Changelog format.
INPUTS (optional)
- VERSION=<version number> (e.g., 1.2.0) (default: auto-detect from latest tag)
- SINCE=<tag or commit> (default: last version tag)
- FORMAT=keepachangelog|simple|github (default: keepachangelog)
- AUTO_COMMIT=yes|no (default: no, ask first)
CHANGELOG FORMAT
Follow [Keep a Changelog](https://keepachangelog.com/en/1.0.0/) standard:
```markdown
# Changelog
All notable changes to this project will be documented in this file.
The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
## [Unreleased]
## [1.2.0] - 2025-10-16
### Added
- New feature X for users to do Y (#123)
- Support for Z configuration (#125)
### Changed
- Improved performance of A by 40% (#124)
- Updated B to use new API (#126)
### Deprecated
- Old method C will be removed in v2.0 (#127)
### Removed
- Unused dependency D (#128)
### Fixed
- Bug where E caused F (#129)
- Crash when G is null (#130)
### Security
- Patched XSS vulnerability in H (#131)
## [1.1.0] - 2025-09-15
[...]
```
DATA COLLECTION
### 1. Get Version Info
```bash
# Get latest tag
git describe --tags --abbrev=0
# If no VERSION provided, suggest next version based on changes:
# - Major (2.0.0): Breaking changes
# - Minor (1.X.0): New features (Added)
# - Patch (1.1.X): Bug fixes only (Fixed)
```
### 2. Get Commits Since Last Release
```bash
git log <SINCE>..HEAD --oneline --no-merges
```
### 3. Get Merged PRs (if using GitHub)
```bash
gh pr list --state merged --base main --json number,title,mergedAt,labels
```
### 4. Parse Conventional Commits
Recognize commit prefixes:
- `feat:` or `feat(scope):` → **Added**
- `fix:` or `fix(scope):` → **Fixed**
- `docs:` → (skip or **Documentation**)
- `style:` → (skip)
- `refactor:` → **Changed**
- `perf:` → **Changed** (note performance improvement)
- `test:` → (skip)
- `chore:` → (skip unless important)
- `BREAKING CHANGE:` or exclamation mark → **Changed** (breaking) + note
- `security:` → **Security**
CATEGORIZATION
### Auto-Categorize Commits
```
commit: feat(auth): add OAuth2 support (#123)
→ Added: OAuth2 authentication support (#123)
commit: fix(api): handle null user in login endpoint (#124)
→ Fixed: Crash when user is null in login endpoint (#124)
commit: perf(db): optimize user query with index (#125)
→ Changed: Improved user query performance by 50% (#125)
commit: feat(ui)!: redesign dashboard layout (#126)
→ Changed: **BREAKING** Redesigned dashboard layout (#126)
```
### Manual Review
If commit messages are unclear, suggest manual categorization:
```
Unclear commits (need categorization):
- "update stuff" (abc123)
- "fix things" (def456)
Please categorize:
1. Added / Changed / Fixed / Security? update stuff
→ [User inputs: Changed]
2. Added / Changed / Fixed / Security? fix things
→ [User inputs: Fixed]
```
BREAKING CHANGES
Detect breaking changes:
- Commit with exclamation mark after type: `feat!: new API`
- Commit with `BREAKING CHANGE:` footer
- PR label: `breaking-change`
Highlight prominently:
```markdown
### Changed
- ⚠️ **BREAKING**: Redesigned API endpoints. See migration guide. (#126)
- ...
```
VERSION SUGGESTION
Based on changes:
```
Changes detected:
- 3 Added (feat:)
- 5 Fixed (fix:)
- 1 BREAKING (feat!:)
Suggested version: 2.0.0 (MAJOR - breaking change)
Current version: 1.5.2
Accept suggested version? (YES/NO/CUSTOM)
```
CHANGELOG GENERATION
### New Changelog (if doesn't exist)
Create CHANGELOG.md with:
- Header (Keep a Changelog notice)
- `[Unreleased]` section (empty)
- `[VERSION]` section with all changes
- Footer links
### Update Existing Changelog
1. Read existing CHANGELOG.md
2. Find `## [Unreleased]` section
3. Move unreleased items to new `[VERSION]` section
4. Add new changes to `[VERSION]` section
5. Clear `[Unreleased]` section
6. Update footer links
EXAMPLE OUTPUT
```markdown
# Changelog
All notable changes to this project will be documented in this file.
## [Unreleased]
## [2.0.0] - 2025-10-16
### Added
- OAuth2 authentication support for Google and GitHub providers (#123)
- User profile settings page with avatar upload (#135)
- Dark mode toggle in user preferences (#137)
### Changed
- ⚠️ **BREAKING**: Redesigned API endpoints to RESTful structure. See [migration guide](docs/migration-v2.md). (#126)
- Improved user query performance by 50% with database indexing (#125)
- Updated UI component library from v3 to v4 (#138)
### Fixed
- Crash when user object is null in login endpoint (#124)
- Memory leak in WebSocket connection handler (#139)
- Incorrect timezone display in activity logs (#140)
### Security
- Patched XSS vulnerability in comment rendering (#131)
- Updated dependencies with known CVEs (#141)
## [1.5.2] - 2025-09-15
[Previous release...]
---
[unreleased]: https://github.com/user/repo/compare/v2.0.0...HEAD
[2.0.0]: https://github.com/user/repo/compare/v1.5.2...v2.0.0
[1.5.2]: https://github.com/user/repo/compare/v1.5.1...v1.5.2
```
WORKFLOW
1. Detect current version and changes since last release
2. Parse commits/PRs and categorize
3. Suggest next version number
4. Generate changelog entry preview (diff-first)
5. Ask: "Update CHANGELOG.md? (YES/NO)"
6. If YES:
- Update CHANGELOG.md
- Optionally commit:
```bash
git add CHANGELOG.md
git commit -m "chore(release): update CHANGELOG for v${VERSION}"
```
7. Optionally create release:
- Git tag: `git tag -a v${VERSION} -m "Release v${VERSION}"`
- GitHub release: `gh release create v${VERSION} --notes-file CHANGELOG-${VERSION}.md`
INTEGRATION
### CI Automation
Suggest adding to release workflow:
```yaml
name: Release
on:
workflow_dispatch:
inputs:
version:
description: 'Version number (e.g., 1.2.0)'
required: true
jobs:
release:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
with:
fetch-depth: 0 # Get all tags
- name: Generate changelog
run: npx claude-code /AgileFlow:generate-changelog VERSION=${{ github.event.inputs.version }}
- name: Commit changelog
run: |
git config user.name "github-actions"
git config user.email "actions@github.com"
git add CHANGELOG.md
git commit -m "chore(release): update CHANGELOG for v${{ github.event.inputs.version }}"
- name: Create tag
run: git tag -a v${{ github.event.inputs.version }} -m "Release v${{ github.event.inputs.version }}"
- name: Push changes
run: |
git push origin main
git push origin v${{ github.event.inputs.version }}
- name: Create GitHub release
run: gh release create v${{ github.event.inputs.version }} --generate-notes
env:
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
```
### Story Integration
Create story after release:
```
US-XXXX: Post-release tasks for v${VERSION}
- [ ] Announce release (blog, social media)
- [ ] Update documentation
- [ ] Monitor error tracking for new issues
```
CUSTOMIZATION
Read project-specific settings from `.agileflow/changelog-config.json`:
```json
{
"categories": {
"feat": "Added",
"fix": "Fixed",
"perf": "Changed",
"docs": "Documentation"
},
"excludeLabels": ["wip", "draft"],
"includeAuthors": true,
"groupByScope": true
}
```
RULES
- Follow Keep a Changelog format strictly
- Include PR/issue numbers for traceability
- Highlight breaking changes prominently
- Use consistent verb tense (past tense)
- Group similar changes together
- Never remove old changelog entries
- Diff-first, YES/NO before updating
- Suggest semantic version based on changes
OUTPUT
- Version suggestion
- Changelog entry preview
- Updated CHANGELOG.md (if approved)
- Optional: Git tag and release creation

125
commands/chatgpt.md Normal file
View File

@@ -0,0 +1,125 @@
---
description: chatgpt
allowed-tools: Bash, Read, Edit, Write, Glob, Grep
---
# chatgpt
Generate, export, or manage the ChatGPT context brief.
## Prompt
ROLE: ChatGPT Context Manager
INPUTS (optional)
- MODE=full|export|note|research (default: full)
- NOTE=<text> (required if MODE=note)
- TOPIC=<text> (required if MODE=research)
---
## MODE=full (default)
Create/refresh docs/chatgpt.md with managed sections.
### Objective
Generate comprehensive ChatGPT context brief with:
- What we're building • Current focus • Feature map • Tech/tooling summary
- Key decisions (ADRs) • Architecture snapshot • Testing & CI
- Recent progress (last 10 bus messages) • Risks • Next steps
### Sources
If present: status.json, bus/log.jsonl, epics/stories, ADRs, practices, architecture, roadmap/backlog/risks, research index, project manifests, CI, CHANGELOG.
### Rules
- Update only managed sections
- Preserve user-written content
- Diff-first; YES/NO before changes
---
## MODE=export
Export a concise ChatGPT context excerpt.
### Task
Read docs/chatgpt.md and output only:
- Last updated • What we're building • Current focus
- Tech/tooling summary • Key decisions (ADRs)
- Feature map (one line per epic) • Next steps
### Constraints
- LIMIT ≤ 300 lines
- No file writes
- End with "Paste this excerpt into ChatGPT to load context."
---
## MODE=note
Append a timestamped note to the ChatGPT context file.
### Input
NOTE=<1–5 line note>
### Action
Append under "Notes for ChatGPT" section with ISO timestamp.
Create section if missing.
### Rules
Diff-first; YES/NO before changes.
---
## MODE=research
Build a comprehensive research prompt for ChatGPT.
### Input
- TOPIC=<free text> (required)
- DETAILS=<constraints/deadlines> (optional)
### Sources
chatgpt.md; status.json; epics/stories; ADRs; project manifests; CI config.
### Output
A SINGLE code block prompt for ChatGPT that requests:
- TL;DR; Step-by-step plan w/ file paths; minimal runnable snippets
- Config/keys; error handling; analytics hooks
- Tests (unit/integration/e2e); manual checklist
- Security/privacy checklist
- ADR draft (options, decision, consequences)
- Story breakdown (3–6 stories + AC bullets)
- Rollback plan; Risks & gotchas
- PR body template
- Sourcing rules (official docs/repos; cite title/URL/date)
- Final "Paste back to Claude" checklist
### Rules
No file writes. Copy-paste ready.
---
## Usage Examples
```bash
# Generate/refresh full context brief (default)
/AgileFlow:chatgpt
/AgileFlow:chatgpt MODE=full
# Export concise excerpt for pasting
/AgileFlow:chatgpt MODE=export
# Add a quick note
/AgileFlow:chatgpt MODE=note NOTE="User reported auth bug in production"
# Build research prompt
/AgileFlow:chatgpt MODE=research TOPIC="Implement OAuth 2.0 with Google"
/AgileFlow:chatgpt MODE=research TOPIC="Add Stripe payments" DETAILS="Launch by end of sprint"
```
---
## Output
Depending on MODE:
- **full**: Updated docs/chatgpt.md (after YES confirmation)
- **export**: Text output ready to paste into ChatGPT
- **note**: Appended note to docs/chatgpt.md (after YES confirmation)
- **research**: Research prompt in code block

24
commands/ci.md Normal file
View File

@@ -0,0 +1,24 @@
---
description: ci-setup
allowed-tools: Bash, Read, Edit, Write, Glob, Grep
---
# ci-setup
Bootstrap minimal CI workflow and CODEOWNERS.
## Prompt
ROLE: CI Bootstrapper
INPUT
OWNERS=<@handles>
ACTIONS
1) Create .github/workflows/ci.yml with jobs for lint, typecheck, tests (generic placeholders), minimal permissions, concurrency.
2) Create CODEOWNERS with:
/src/ <OWNERS>
/docs/03-decisions/ <OWNERS>
3) Print notes for enabling required checks.
Diff-first; YES/NO.

270
commands/compress.md Normal file
View File

@@ -0,0 +1,270 @@
---
description: Compress status.json by removing verbose fields and keeping only tracking metadata
---
# compress
Reduce status.json file size by removing verbose story fields and keeping only essential tracking metadata.
## Purpose
**Problem**: status.json exceeds 25000 tokens, causing agents to fail with "file content exceeds maximum allowed tokens"
**Solution**: Strip verbose fields (description, architectureContext, devAgentRecord, etc.) from status.json while preserving full story details in `docs/06-stories/` markdown files.
**Result**: Lightweight tracking index that agents can read + full story content in dedicated files.
## What Gets Removed
The script removes these verbose fields from status.json:
- `description` - Story description and context
- `acceptanceCriteria` - AC bullet points
- `architectureContext` - Architecture details (6 subsections)
- `technicalNotes` - Implementation hints
- `testingStrategy` - Test approach
- `devAgentRecord` - Implementation notes (6 subsections)
- `previousStoryInsights` - Lessons from previous story
- Any other large text fields
## What Gets Kept
Only essential tracking metadata remains:
- `story_id` - Story identifier
- `epic` - Parent epic
- `title` - Story title
- `owner` - Assigned agent
- `status` - Current status (ready/in-progress/blocked/done)
- `estimate` - Time estimate
- `created` / `updated` / `completed_at` - Timestamps
- `dependencies` - Dependent story IDs
- `branch` - Git branch
- `summary` - Short summary
- `last_update` - Last modification message
- `assigned_at` - Assignment timestamp
## Workflow
When user runs `/AgileFlow:compress`:
1. **Validate Environment**:
- Check if `docs/09-agents/status.json` exists
- Validate JSON syntax with `jq empty`
- Check if `jq` is installed
2. **Show Before Stats**:
```
📊 Before Compression:
Stories: 145
Size: 384KB
Lines: 12,847
```
3. **Create Backup**:
- Copy status.json to status.json.backup
- Preserve original in case rollback needed
4. **Compress Stories**:
- For each story in status.json:
- Extract ONLY the essential tracking fields listed above
- Discard all verbose content fields
- Update `updated` timestamp to now
5. **Write Compressed File**:
- Overwrite status.json with compressed version
- Pretty-print JSON with `jq '.'`
6. **Show After Stats**:
```
✅ Compression complete!
📊 After Compression:
Stories: 145 (unchanged)
Size: 384KB → 42KB
Lines: 12,847 → 1,203
Saved: 89% (342KB)
✅ Estimated tokens: ~10,500 (safely under 25000 limit)
```
7. **Show Status Summary**:
```
📋 Status Summary:
ready: 23 stories
in-progress: 8 stories
blocked: 2 stories
done: 112 stories
```
8. **Provide Guidance**:
- Note: Full story details remain in `docs/06-stories/`
- Agents should read story markdown files for implementation
- status.json is now a lightweight tracking index
## When to Use
**Run compression when**:
- status.json exceeds 25000 tokens
- Agents fail with "file content exceeds maximum allowed tokens"
- status.json is slow to read/parse
- After major epic completion (many stories with verbose records)
**Combine with archival**:
1. First run archival to move old completed stories: `/AgileFlow:compress` → runs `bash scripts/archive-completed-stories.sh`
2. If still too large, run compression: `/AgileFlow:compress` → runs `bash scripts/compress-status.sh`
3. Result: status.json under 25000 tokens
## Safety
**Backups**:
- Original saved to `status.json.backup`
- Restore anytime: `cp docs/09-agents/status.json.backup docs/09-agents/status.json`
**No Data Loss**:
- Full story content remains in `docs/06-stories/EP-XXXX/US-XXXX-*.md` files
- Only status.json tracking index is compressed
- Story markdown files are NOT modified
**Reversible**:
- Can restore from backup if needed
- Can re-populate verbose fields by reading story markdown files
## Implementation
```bash
bash scripts/compress-status.sh
```
## Related Commands
- `/AgileFlow:status` - View current story statuses
- `/AgileFlow:validate` - Validate AgileFlow system health
## Example Output
```
🗜️ AgileFlow Status Compression
Purpose: Strip verbose fields from status.json
Target: Keep only essential tracking metadata
💾 Backup created: docs/09-agents/status.json.backup
📊 Before Compression:
Stories: 145
Size: 384KB
Lines: 12,847
✅ Compression complete!
📊 After Compression:
Stories: 145 (unchanged)
Size: 384KB → 42KB
Lines: 12,847 → 1,203
Saved: 89% (342KB)
🗑️ Removed Fields (stored in story markdown files):
• description
• acceptanceCriteria
• architectureContext
• technicalNotes
• testingStrategy
• devAgentRecord
• previousStoryInsights
• And any other verbose fields
📝 Note: Full story details remain in docs/06-stories/ markdown files
Agents should read story files for implementation details
status.json is now a lightweight tracking index
✅ Estimated tokens: ~10,500 (safely under 25000 limit)
📋 Status Summary:
ready: 23 stories
in-progress: 8 stories
blocked: 2 stories
done: 112 stories
💾 To restore original: cp docs/09-agents/status.json.backup docs/09-agents/status.json
```
## Technical Notes
**Token Estimation**:
- Rough formula: tokens ≈ bytes / 4
- Target: < 100KB for status.json (≈ 25000 tokens)
- After compression: typical 80-90% reduction
**Why This Works**:
- status.json should be a lightweight **tracking index**, not a content store
- Full story content belongs in markdown files
- Agents read status.json for "what to work on" (metadata)
- Agents read story markdown files for "how to build it" (implementation details)
**Separation of Concerns**:
- **status.json** = lightweight tracking (which stories, who owns, what status)
- **docs/06-stories/** = full story content (AC, architecture, implementation)
- **docs/09-agents/status-archive.json** = historical completed stories
## Prompt
You are the Status Compression assistant for AgileFlow.
**Your job**:
**Step 1: Ensure compression script exists**
```bash
# Check if compression script exists in user's project
if [ ! -f scripts/compress-status.sh ]; then
echo "📦 Compression script not found - deploying from plugin..."
# Copy from AgileFlow plugin
cp ~/.claude-code/plugins/AgileFlow/scripts/compress-status.sh scripts/compress-status.sh
# Make executable
chmod +x scripts/compress-status.sh
echo "✅ Deployed compression script: scripts/compress-status.sh"
fi
```
**Step 2: Run compression**
```bash
bash scripts/compress-status.sh
```
**Step 3: Verify and advise**
1. Show output to user
2. Verify estimated tokens < 25000
3. If still too large, suggest archival with shorter threshold
**Safety checks**:
- Verify backup created before compression
- Validate JSON syntax after compression
- Calculate and show token estimate
- Remind user full story content preserved in markdown files
**Example execution**:
```bash
cd /path/to/user/project
# Auto-deploy script if missing (v2.20.1+)
if [ ! -f scripts/compress-status.sh ]; then
cp ~/.claude-code/plugins/AgileFlow/scripts/compress-status.sh scripts/compress-status.sh
chmod +x scripts/compress-status.sh
fi
# Run compression
bash scripts/compress-status.sh
```
**If compression isn't enough**:
```bash
# Combine with aggressive archival
bash scripts/archive-completed-stories.sh 3 # Archive stories >3 days old
bash scripts/compress-status.sh # Then compress remaining
```
**Always**:
- Show clear before/after stats
- Calculate savings percentage
- Verify token estimate
- Confirm agents can now read status.json

268
commands/debt.md Normal file
View File

@@ -0,0 +1,268 @@
---
description: tech-debt
allowed-tools: Bash, Read, Edit, Write, Glob, Grep
---
# tech-debt
Track and visualize technical debt across the codebase.
## Prompt
ROLE: Technical Debt Tracker
OBJECTIVE
Identify, categorize, and prioritize technical debt to guide refactoring efforts.
INPUTS (optional)
- SCAN=full|quick (default: quick - only flagged areas)
- OUTPUT=report|stories|both (default: report)
- THRESHOLD=high|medium|low (default: medium - minimum severity to report)
DEBT DETECTION
### 1. Code Quality Signals
Scan for common debt indicators:
- TODO/FIXME/HACK comments
- Long functions (>50 lines)
- High cyclomatic complexity (>10)
- Duplicated code blocks (copy-paste)
- Large files (>500 lines)
- Deep nesting (>4 levels)
- God objects (classes with >10 methods)
- Low test coverage (<70%)
### 2. Story Tags
Search docs/06-stories/ for:
- Stories tagged `tech-debt: true`
- Stories with status=blocked by debt
- Stories with "refactor" or "cleanup" in title
### 3. ADR Analysis
Check docs/03-decisions/ for:
- ADRs with status=Deprecated (implementations may still exist)
- ADRs with documented "negative consequences"
- ADRs noting "temporary solution"
### 4. Git History
Analyze:
- Files with high churn (frequently modified)
- Files with many authors (ownership unclear)
- Old branches not merged (potential context loss)
### 5. Linter/Analyzer Output
Parse output from:
- ESLint, TSLint, Pylint
- SonarQube, CodeClimate
- Code coverage reports
CATEGORIZATION
Group debt by type:
- **Architecture**: Wrong abstractions, tight coupling, missing patterns
- **Code Quality**: Duplication, complexity, inconsistent style
- **Documentation**: Missing, outdated, or incomplete docs
- **Testing**: Low coverage, flaky tests, missing E2E
- **Security**: Outdated dependencies, exposed secrets, weak auth
- **Performance**: N+1 queries, memory leaks, slow operations
- **Dependencies**: Outdated packages, unmaintained libraries
SCORING
Each debt item gets a score (0-100):
- **Severity**: Low (1-3), Medium (4-6), High (7-9), Critical (10)
- **Scope**: How many files affected (1-10 scale)
- **Pain**: Developer frustration (1-10 scale)
Score = Severity × Scope × Pain / 10
DEBT REPORT
```markdown
# Technical Debt Report
**Generated**: <ISO timestamp>
**Total Debt Items**: 42
**Critical**: 3 | **High**: 12 | **Medium**: 18 | **Low**: 9
---
## Critical Debt (Score >80)
### 1. Auth service tightly coupled to database layer
**Type**: Architecture
**Score**: 87
**Impact**: Blocks US-0055 (Add OAuth), US-0061 (Add 2FA)
**Files**: src/services/auth.ts (287 lines, complexity 18)
**ADR**: ADR-0003 recommends service layer separation (not implemented)
**Estimate**: 3-5 days to refactor
**Stories**:
- Create epic: EP-0010 "Refactor auth architecture"
- Stories: Separate concerns, add interface, migrate callers
---
### 2. Missing integration tests for payment flow
**Type**: Testing
**Score**: 85
**Impact**: High risk for regressions, blocking production deploy
**Files**: src/api/payments/*.ts (12 files, 0% integration coverage)
**Last incident**: 2025-09-15 (payment bug in production)
**Estimate**: 2-3 days
**Stories**:
- US-XXXX: Write integration tests for payment flow
---
### 3. Unmaintained dependency: old-oauth-lib (3 years outdated)
**Type**: Security
**Score**: 82
**Impact**: 2 known CVEs, blocks security audit
**Files**: 8 files import this library
**ADR**: ADR-0012 marked this for replacement (6 months ago)
**Estimate**: 1-2 days to migrate to modern-oauth-lib
**Stories**:
- US-XXXX: Migrate from old-oauth-lib to modern-oauth-lib
---
## High Debt (Score 60-80)
[12 items...]
---
## Summary by Category
| Category | Count | Avg Score | Estimated Effort |
|----------|-------|-----------|------------------|
| Architecture | 8 | 72 | 15 days |
| Code Quality | 15 | 58 | 8 days |
| Testing | 10 | 65 | 12 days |
| Security | 3 | 78 | 5 days |
| Performance | 4 | 61 | 6 days |
| Documentation | 2 | 45 | 2 days |
**Total Estimated Effort**: 48 days
---
## Trend Analysis
Debt added this sprint: +5 items
Debt resolved this sprint: -2 items
Net change: +3 items ⚠️
---
## Recommendations
1. **Immediate** (Critical): Address auth refactor and payment tests
2. **This Sprint**: Tackle 3 high-severity items (choose by ROI)
3. **Next Sprint**: Reserve 20% capacity for debt reduction
4. **Ongoing**: Require tests for all new code (enforce in CI)
---
## Debt Heatmap
Most problematic files:
- src/services/auth.ts: 3 debt items (arch, complexity, coupling)
- src/api/payments/process.ts: 2 debt items (no tests, deprecated API)
- src/utils/legacy.ts: 2 debt items (duplication, no docs)
```
ACTIONS (after user review)
1. Ask: "Generate stories for critical debt? (YES/NO)"
2. If YES:
- Create epic: "EP-XXXX: Technical Debt Reduction"
- Create stories for top 5 critical items
- Use templates with AC focused on "before/after" state
3. Ask: "Save report to docs/08-project/? (YES/NO)"
4. If YES:
- Save to docs/08-project/tech-debt-<YYYYMMDD>.md
- Update docs/08-project/README.md with link
5. Suggest adding to roadmap:
- Reserve 10-20% of each sprint for debt reduction
- Add debt review to retrospectives
INTEGRATION
### Story Template for Debt
```markdown
---
story_id: US-XXXX
title: Refactor auth service to separate concerns
type: tech-debt
debt_score: 87
estimate: 3d
---
## Context
Auth service is tightly coupled to database layer, blocking OAuth integration.
## Current State (Before)
- auth.ts contains DB queries, business logic, and HTTP handling
- 287 lines, complexity 18
- Hard to test, hard to extend
## Desired State (After)
- Clear separation: AuthService, AuthRepository, AuthController
- Each <100 lines, complexity <8
- 80%+ test coverage
- Enables US-0055 (OAuth)
## Acceptance Criteria
- [ ] AuthRepository handles all DB operations
- [ ] AuthService contains only business logic
- [ ] AuthController handles only HTTP/routing
- [ ] Tests cover each layer independently
- [ ] All existing auth tests still pass
- [ ] No breaking changes to API
## References
- ADR-0003: Service layer separation
- Blocked stories: US-0055, US-0061
```
### Dashboard Integration
Suggest creating a simple dashboard:
```
docs/08-project/debt-dashboard.md
# Debt Dashboard (Updated Weekly)
## Trend
Week 42: 42 items (↑ from 39)
Week 41: 39 items (↓ from 43)
## Critical Items: 3
[List with links to stories]
## This Sprint Goal
Reduce critical debt from 3 → 1
```
AUTOMATION
Suggest adding to CI (weekly):
```yaml
- cron: '0 0 * * 1' # Monday
- name: Technical debt scan
run: npx claude-code /AgileFlow:tech-debt SCAN=full OUTPUT=report
```
RULES
- Never auto-create stories without approval
- Be honest about estimates (err on high side)
- Link debt items to blocked stories when possible
- Prioritize debt that blocks future work
- Celebrate debt reduction in retrospectives
OUTPUT
- Technical debt report (markdown)
- Optional: Stories for top debt items
- Optional: Trend analysis
- Recommendations for debt reduction

529
commands/deploy.md Normal file
View File

@@ -0,0 +1,529 @@
---
description: setup-deployment
allowed-tools: Bash, Read, Edit, Write, Glob, Grep
---
# setup-deployment
Automatically set up deployment pipeline for the project.
## Prompt
ROLE: Deployment Pipeline Configurator
OBJECTIVE
Detect project type and configure CI/CD deployment to appropriate platform with environment management.
INPUTS (optional)
- PLATFORM=auto|vercel|netlify|heroku|aws|gcp|docker|eas (default: auto-detect)
- ENV=staging|production|both (default: both)
- AUTO_DEPLOY=yes|no (default: no, manual trigger)
PROJECT DETECTION
Analyze project to determine deployment needs:
### Static Sites
- **Indicators**: No backend, HTML/CSS/JS, React/Vue/Angular SPA
- **Platforms**: Vercel, Netlify, GitHub Pages, Cloudflare Pages
- **Recommended**: Vercel (for React/Next.js), Netlify (for general static)
### Full-Stack Web Apps
- **Indicators**: Node.js server, Express/Fastify/Next.js API routes
- **Platforms**: Vercel (Next.js), Heroku, Railway, Fly.io, AWS (ECS/Lambda)
- **Recommended**: Vercel (Next.js), Railway (Docker)
### Mobile Apps (React Native / Expo)
- **Indicators**: expo config, react-native
- **Platforms**: EAS Build, App Center
- **Recommended**: EAS (Expo Application Services)
### Containers
- **Indicators**: Dockerfile present
- **Platforms**: Docker Hub, AWS ECR, GCP Artifact Registry, Fly.io
- **Recommended**: Fly.io (easy Docker deploy)
### Serverless Functions
- **Indicators**: Lambda functions, API Gateway config
- **Platforms**: AWS Lambda, Vercel Functions, Netlify Functions
- **Recommended**: Vercel Functions (for Next.js), AWS SAM
DEPLOYMENT CONFIGURATIONS
### Vercel (Next.js / Static)
Create `vercel.json`:
```json
{
"buildCommand": "npm run build",
"outputDirectory": "dist",
"framework": "nextjs",
"env": {
"DATABASE_URL": "@database-url-staging",
"API_KEY": "@api-key"
},
"build": {
"env": {
"NEXT_PUBLIC_API_URL": "https://api.example.com"
}
}
}
```
GitHub Actions:
```yaml
name: Deploy to Vercel
on:
push:
branches: [main]
pull_request:
branches: [main]
jobs:
deploy:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- name: Deploy to Vercel
uses: amondnet/vercel-action@v25
with:
vercel-token: ${{ secrets.VERCEL_TOKEN }}
vercel-org-id: ${{ secrets.VERCEL_ORG_ID }}
vercel-project-id: ${{ secrets.VERCEL_PROJECT_ID }}
vercel-args: '--prod'
```
---
### Netlify (Static Sites)
Create `netlify.toml`:
```toml
[build]
command = "npm run build"
publish = "dist"
[build.environment]
NODE_VERSION = "20"
[[redirects]]
from = "/*"
to = "/index.html"
status = 200
[context.production.environment]
API_URL = "https://api.example.com"
[context.staging.environment]
API_URL = "https://staging-api.example.com"
```
---
### Heroku (Node.js)
Create `Procfile`:
```
web: npm start
```
Create `app.json`:
```json
{
"name": "my-app",
"description": "My application",
"buildpacks": [
{
"url": "heroku/nodejs"
}
],
"env": {
"NODE_ENV": {
"value": "production"
},
"DATABASE_URL": {
"description": "PostgreSQL connection string",
"required": true
}
}
}
```
GitHub Actions:
```yaml
name: Deploy to Heroku
on:
push:
branches: [main]
jobs:
deploy:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- name: Deploy to Heroku
uses: akhileshns/heroku-deploy@v3.13.15
with:
heroku_api_key: ${{ secrets.HEROKU_API_KEY }}
heroku_app_name: "my-app-production"
heroku_email: "deploy@example.com"
```
---
### Docker (Fly.io / AWS / GCP)
Create `Dockerfile`:
```dockerfile
FROM node:20-alpine AS builder
WORKDIR /app
COPY package*.json ./
RUN npm ci
COPY . .
RUN npm run build
FROM node:20-alpine
WORKDIR /app
COPY --from=builder /app/dist ./dist
COPY --from=builder /app/node_modules ./node_modules
COPY package*.json ./
EXPOSE 3000
CMD ["npm", "start"]
```
Create `.dockerignore`:
```
node_modules
.git
.env
*.log
dist
coverage
```
For Fly.io, create `fly.toml`:
```toml
app = "my-app"
[build]
dockerfile = "Dockerfile"
[env]
NODE_ENV = "production"
PORT = "8080"
[[services]]
internal_port = 8080
protocol = "tcp"
[[services.ports]]
port = 80
handlers = ["http"]
[[services.ports]]
port = 443
handlers = ["tls", "http"]
```
Deploy command:
```bash
fly deploy
```
---
### EAS (Expo / React Native)
Create `eas.json`:
```json
{
"cli": {
"version": ">= 5.9.0"
},
"build": {
"development": {
"developmentClient": true,
"distribution": "internal"
},
"preview": {
"distribution": "internal",
"android": {
"buildType": "apk"
}
},
"production": {
"autoIncrement": true
}
},
"submit": {
"production": {
"ios": {
"appleId": "user@example.com",
"ascAppId": "1234567890"
},
"android": {
"serviceAccountKeyPath": "./secrets/google-service-account.json",
"track": "internal"
}
}
}
}
```
GitHub Actions:
```yaml
name: EAS Build
on:
push:
branches: [main]
jobs:
build:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: actions/setup-node@v4
with:
node-version: 20
- name: Setup Expo
uses: expo/expo-github-action@v8
with:
expo-version: latest
eas-version: latest
token: ${{ secrets.EXPO_TOKEN }}
- name: Build on EAS
run: eas build --platform all --non-interactive --no-wait
```
---
### AWS (Serverless / Lambda)
Create `serverless.yml`:
```yaml
service: my-app
provider:
name: aws
runtime: nodejs20.x
region: us-east-1
stage: ${opt:stage, 'dev'}
environment:
NODE_ENV: production
DATABASE_URL: ${ssm:/my-app/${self:provider.stage}/database-url}
functions:
api:
handler: dist/index.handler
events:
- http:
path: /{proxy+}
method: ANY
cors: true
plugins:
- serverless-offline
- serverless-dotenv-plugin
```
GitHub Actions:
```yaml
name: Deploy to AWS Lambda
on:
push:
branches: [main]
jobs:
deploy:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: actions/setup-node@v4
- name: Install Serverless Framework
run: npm install -g serverless
- name: Deploy
run: serverless deploy --stage production
env:
AWS_ACCESS_KEY_ID: ${{ secrets.AWS_ACCESS_KEY_ID }}
AWS_SECRET_ACCESS_KEY: ${{ secrets.AWS_SECRET_ACCESS_KEY }}
```
---
ENVIRONMENT MANAGEMENT
Create `.env.example`:
```env
# Database
DATABASE_URL=postgresql://user:pass@localhost:5432/mydb
# API Keys (DO NOT commit actual keys)
API_KEY=your_api_key_here
STRIPE_SECRET_KEY=sk_test_...
# Third-party Services
SENDGRID_API_KEY=
AWS_ACCESS_KEY_ID=
AWS_SECRET_ACCESS_KEY=
# App Config
NODE_ENV=development
PORT=3000
```
Create docs/02-practices/secrets-management.md:
```markdown
# Secrets Management
## DO NOT commit secrets to Git
- Never commit `.env` files
- Use `.env.example` for templates only
## Deployment Platforms
### Vercel
\`\`\`bash
vercel env add DATABASE_URL production
\`\`\`
### Heroku
\`\`\`bash
heroku config:set DATABASE_URL="postgres://..." --app my-app
\`\`\`
### GitHub Actions
Add secrets in Settings → Secrets and variables → Actions
## Local Development
1. Copy `.env.example` to `.env`
2. Fill in actual values (get from team lead)
3. Never commit `.env` to git
```
DEPLOYMENT WORKFLOW
### Staging → Production Flow
```yaml
name: Deploy
on:
push:
branches:
- main # → production
- staging # → staging
jobs:
deploy:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- name: Determine environment
id: env
run: |
if [[ "${{ github.ref }}" == "refs/heads/main" ]]; then
echo "environment=production" >> $GITHUB_OUTPUT
else
echo "environment=staging" >> $GITHUB_OUTPUT
fi
- name: Deploy
run: ./deploy.sh
env:
ENVIRONMENT: ${{ steps.env.outputs.environment }}
```
WORKFLOW SUMMARY
1. Detect project type
2. Recommend platform
3. Show configuration preview:
```
Deployment Setup for: Node.js web app
Recommended platform: Vercel
Will create:
- vercel.json (deployment config)
- .github/workflows/deploy.yml (CI/CD)
- .env.example (secrets template)
- docs/02-practices/deployment.md (guide)
Environments:
- Staging: staging.example.com (branch: staging)
- Production: example.com (branch: main)
Proceed? (YES/NO)
```
4. If YES:
- Create config files
- Update CI workflows
- Create deployment docs
- Show next steps
NEXT STEPS
After setup, guide user:
```
✅ Deployment configuration created!
Next steps:
1. Add secrets to platform:
- For Vercel: `vercel env add DATABASE_URL`
- For GitHub Actions: Settings → Secrets
2. Connect repository to platform:
- Vercel: `vercel link`
- Heroku: `heroku git:remote -a my-app`
3. Test deployment:
- Push to staging branch: `git push origin staging`
- Check logs: `vercel logs` or platform dashboard
4. Deploy to production:
- Merge staging → main
- Or manually: `vercel --prod`
5. Set up custom domain (optional):
- Vercel: `vercel domains add example.com`
- Netlify: Netlify dashboard → Domain settings
Documentation: docs/02-practices/deployment.md
```
INTEGRATION
- Create story: "US-XXXX: Set up deployment pipeline"
- Update docs/02-practices/deployment.md
- Add deployment status to docs/08-project/README.md
RULES
- Preview all files before creating (diff-first, YES/NO)
- Never commit secrets to repository
- Always use environment variables
- Set up staging environment first
- Test deployment before going to production
- Document rollback procedure
OUTPUT
- Platform recommendation
- Deployment configuration files
- CI/CD workflow
- Environment management guide
- Next steps checklist

560
commands/deps.md Normal file
View File

@@ -0,0 +1,560 @@
---
description: dependencies
allowed-tools: Bash, Read, Edit, Write, Glob, Grep
---
# dependencies
Visualize and analyze story/epic dependency graphs with critical path analysis and circular dependency detection.
## Prompt
ROLE: Dependency Graph Analyzer
OBJECTIVE
Parse story dependencies from frontmatter and bus/log.jsonl, generate visual dependency graphs, identify critical paths, detect circular dependencies, and suggest optimal work ordering.
INPUTS (optional)
- SCOPE=story|epic|all (default: all)
- EPIC=<EP_ID> (show dependencies within specific epic)
- STORY=<US_ID> (show dependencies for specific story)
- FORMAT=ascii|mermaid|graphviz|json (default: ascii)
- ANALYSIS=critical-path|circular|blocking|all (default: all)
DEPENDENCY SOURCES
### 1. Story Frontmatter
```yaml
---
id: US-0042
depends_on:
- US-0040
- US-0041
blocks:
- US-0045
---
```
### 2. Bus Log (implicit dependencies)
```jsonl
{"type":"blocked","story":"US-0045","reason":"waiting for US-0042","ts":"..."}
{"type":"handoff","from":"AG-UI","to":"AG-API","story":"US-0043","reason":"depends on backend"}
```
### 3. Epic Hierarchy
```
EP-0010 (Authentication)
├─ US-0030 (Database schema) ← Foundation
├─ US-0031 (User model) ← Depends on US-0030
├─ US-0032 (Login endpoint) ← Depends on US-0031
└─ US-0033 (Login UI) ← Depends on US-0032
```
DEPENDENCY PARSING
### Extract from Story Files
```bash
for story_file in docs/06-stories/**/*.md; do
story_id=$(grep "^id:" $story_file | awk '{print $2}')
# Parse depends_on field
depends=$(sed -n '/^depends_on:/,/^[a-z]/p' $story_file | grep -oP 'US-\d+')
# Parse blocks field
blocks=$(sed -n '/^blocks:/,/^[a-z]/p' $story_file | grep -oP 'US-\d+')
echo "$story_id depends_on: $depends"
echo "$story_id blocks: $blocks"
done
```
### Extract from Bus Log
```bash
# Find blocking events
jq -r 'select(.type=="blocked" and .reason | contains("waiting for")) |
{story: .story, blocks: (.reason | match("US-\\d+").string)}' bus/log.jsonl
```
### Build Dependency Graph
```bash
# Create adjacency list
declare -A graph
for story in all_stories; do
dependencies=$(get_story_dependencies $story)
graph[$story]=$dependencies
done
```
VISUALIZATION
### ASCII Graph (Default)
```
Story Dependency Graph
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Legend:
✅ Done 🟢 Ready 🟡 In Progress 🔵 In Review ⚪ Blocked
EP-0010: Authentication Epic
┌────────────────────────────────────────────────────────────┐
│ │
│ ✅ US-0030 │
│ Database schema │
│ │ │
│ ├─▶ ✅ US-0031 │
│ │ User model │
│ │ │ │
│ │ ├─▶ 🟡 US-0032 │
│ │ │ Login endpoint (in-progress, AG-API) │
│ │ │ │ │
│ │ │ ├─▶ 🟢 US-0033 │
│ │ │ │ Login UI (ready) │
│ │ │ │ │
│ │ │ └─▶ ⚪ US-0045 │
│ │ │ Password reset (blocked, waiting for US-0032)│
│ │ │ │
│ │ └─▶ ✅ US-0034 │
│ │ JWT middleware │
│ │ │
│ └─▶ 🔵 US-0035 │
│ User registration (in-review) │
│ │
└────────────────────────────────────────────────────────────┘
EP-0011: Payment Processing Epic
┌────────────────────────────────────────────────────────────┐
│ │
│ 🟢 US-0040 │
│ Stripe integration │
│ │ │
│ ├─▶ ⚪ US-0041 │
│ │ Payment form (blocked, waiting for US-0040) │
│ │ │
│ └─▶ ⚪ US-0042 │
│ Webhook handler (blocked, waiting for US-0040) │
│ │
└────────────────────────────────────────────────────────────┘
Critical Path:
US-0030 → US-0031 → US-0032 → US-0033 (11 days total)
⚠️ US-0032 is on critical path and in-progress
Blocking Stories:
US-0040 blocks: US-0041, US-0042 (⚠️ High impact: 2 stories)
US-0032 blocks: US-0033, US-0045 (⚠️ High impact: 2 stories)
Circular Dependencies: None detected ✅
```
### Mermaid Format
```mermaid
graph TD
US0030[US-0030: Database schema ✅]
US0031[US-0031: User model ✅]
US0032[US-0032: Login endpoint 🟡]
US0033[US-0033: Login UI 🟢]
US0034[US-0034: JWT middleware ✅]
US0035[US-0035: User registration 🔵]
US0045[US-0045: Password reset ⚪]
US0030 --> US0031
US0030 --> US0035
US0031 --> US0032
US0031 --> US0034
US0032 --> US0033
US0032 --> US0045
US0040[US-0040: Stripe integration 🟢]
US0041[US-0041: Payment form ⚪]
US0042[US-0042: Webhook handler ⚪]
US0040 --> US0041
US0040 --> US0042
classDef done fill:#90EE90
classDef ready fill:#D3D3D3
classDef inProgress fill:#FFD700
classDef inReview fill:#87CEEB
classDef blocked fill:#FFCCCB
class US0030,US0031,US0034 done
class US0033,US0040 ready
class US0032 inProgress
class US0035 inReview
class US0041,US0042,US0045 blocked
```
### GraphViz DOT Format
```dot
digraph dependencies {
rankdir=TB;
node [shape=box, style=rounded];
// Nodes
US0030 [label="US-0030\nDatabase schema", fillcolor="#90EE90", style=filled];
US0031 [label="US-0031\nUser model", fillcolor="#90EE90", style=filled];
US0032 [label="US-0032\nLogin endpoint", fillcolor="#FFD700", style=filled];
US0033 [label="US-0033\nLogin UI", fillcolor="#D3D3D3", style=filled];
US0045 [label="US-0045\nPassword reset", fillcolor="#FFCCCB", style=filled];
// Edges
US0030 -> US0031;
US0031 -> US0032;
US0032 -> US0033;
US0032 -> US0045;
// Critical path (bold red)
US0030 -> US0031 [color=red, penwidth=2];
US0031 -> US0032 [color=red, penwidth=2];
US0032 -> US0033 [color=red, penwidth=2];
}
```
DEPENDENCY ANALYSIS
### 1. Critical Path Detection
**Definition**: Longest path from any root story to any leaf story
```bash
# Find all root stories (no dependencies)
roots=$(find_stories_with_no_dependencies)
# For each root, calculate longest path
for root in $roots; do
longest_path=$(find_longest_path_from $root)
echo "$root: $longest_path"
done
# Critical path is the longest of all paths
critical_path=$(find_overall_longest_path)
critical_duration=$(sum_story_estimates_in_path $critical_path)
```
**Output**:
```
Critical Path Analysis
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Longest Path: US-0030 → US-0031 → US-0032 → US-0033
Path Details:
┌──────────┬─────────────────────┬──────────┬────────┬──────────┐
│ Story │ Title │ Estimate │ Status │ Duration │
├──────────┼─────────────────────┼──────────┼────────┼──────────┤
│ US-0030 │ Database schema │ 2d │ ✅ Done│ 2d │
│ US-0031 │ User model │ 3d │ ✅ Done│ 2.5d │
│ US-0032 │ Login endpoint │ 2d │ 🟡 WIP │ 1.5d (so far)│
│ US-0033 │ Login UI │ 1d │ 🟢 Ready│ - │
└──────────┴─────────────────────┴──────────┴────────┴──────────┘
Total Estimated Duration: 8 days
Actual Duration So Far: 6 days
Remaining Work: 1-2 days (US-0032 + US-0033)
⚠️ US-0032 is on critical path and currently in-progress
- Any delay here delays entire epic completion
- Owner: AG-API
- Progress: ~75% complete (1.5d of 2d estimate used)
Recommendation:
- Prioritize US-0032 completion (critical bottleneck)
- Consider pairing to accelerate if delayed
- US-0033 is ready and should start immediately after US-0032
```
### 2. Circular Dependency Detection
```bash
# Use depth-first search to detect cycles
function has_cycle() {
local story=$1
local path=$2
# If story already in path, we found a cycle
if [[ $path == *"$story"* ]]; then
echo "CYCLE DETECTED: $path → $story"
return 0
fi
# Recursively check dependencies
for dep in $(get_dependencies $story); do
has_cycle $dep "$path → $story"
done
}
for story in all_stories; do
has_cycle $story ""
done
```
**Output**:
```
Circular Dependency Check
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
❌ CIRCULAR DEPENDENCY DETECTED!
Cycle 1:
US-0050 → US-0051 → US-0052 → US-0050
Details:
US-0050 (Auth service) depends on US-0051 (User service)
US-0051 (User service) depends on US-0052 (Session service)
US-0052 (Session service) depends on US-0050 (Auth service)
Impact: ⚠️ CRITICAL - These stories cannot be completed
Resolution:
1. Review architectural design (likely a design flaw)
2. Break circular dependency by introducing abstraction
3. Consider creating interface/contract story
4. Refactor one story to not depend on the cycle
Suggested Fix:
- Create US-0053: "Auth/User interface contract"
- Make US-0050, US-0051, US-0052 all depend on US-0053
- US-0053 becomes new foundation story
```
### 3. Blocking Story Impact
```bash
# For each story, find what it blocks
for story in all_stories; do
blocked_stories=$(find_stories_depending_on $story)
count=${#blocked_stories[@]}
if [ $count -gt 0 ]; then
status=$(get_story_status $story)
echo "$story ($status) blocks $count stories: ${blocked_stories[@]}"
# Calculate impact score
impact=$(calculate_impact_score $story)
priority=$(calculate_priority $story $impact)
echo " Impact score: $impact/10, Priority: $priority"
fi
done
```
**Output**:
```
Blocking Story Impact
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
High Impact Blockers:
┌──────────┬────────────────────┬────────┬─────────┬────────────┬──────────┐
│ Story │ Title │ Status │ Blocks │ Impact │ Priority │
├──────────┼────────────────────┼────────┼─────────┼────────────┼──────────┤
│ US-0040 │ Stripe integration │ 🟢 Ready│ 2 stories│ 9/10 ⚠️ │ P0 │
│ │ │ │ US-0041 │ (blocks │ │
│ │ │ │ US-0042 │ payment │ │
│ │ │ │ │ epic) │ │
├──────────┼────────────────────┼────────┼─────────┼────────────┼──────────┤
│ US-0032 │ Login endpoint │ 🟡 WIP │ 2 stories│ 8/10 ⚠️ │ P0 │
│ │ │ │ US-0033 │ (critical │ │
│ │ │ │ US-0045 │ path) │ │
├──────────┼────────────────────┼────────┼─────────┼────────────┼──────────┤
│ US-0030 │ Database schema │ ✅ Done│ 2 stories│ 7/10 │ - │
│ │ │ │ US-0031 │ (already │ │
│ │ │ │ US-0035 │ complete) │ │
└──────────┴────────────────────┴────────┴─────────┴────────────┴──────────┘
⚠️ Action Required:
1. US-0040: Start immediately (blocks 2 stories, epic stalled)
2. US-0032: Monitor closely (in-progress, blocks critical path)
Recommendations:
- Assign US-0040 to available agent ASAP
- Consider pairing on US-0032 if progress slows
- Review US-0041 and US-0042 to verify they truly need US-0040
```
### 4. Parallel Work Opportunities
```bash
# Find stories that can be worked on in parallel (no dependencies)
independent_stories=$(find_stories_with_no_dependencies_or_dependencies_satisfied)
# Group by epic for clarity
for epic in epics; do
parallel_stories=$(filter_by_epic $independent_stories $epic)
echo "$epic: ${#parallel_stories[@]} stories can be started now"
done
```
**Output**:
```
Parallel Work Opportunities
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Stories That Can Start Now (No Blockers):
EP-0010: Authentication
✅ US-0033 (Login UI) - AG-UI available
✅ US-0035 (Registration) - In review (almost done)
EP-0011: Payment Processing
✅ US-0040 (Stripe integration) - AG-API available
⚠️ HIGH PRIORITY: Blocks 2 other stories
EP-0012: User Dashboard
✅ US-0050 (Dashboard layout) - AG-UI available
✅ US-0051 (Profile component) - AG-UI available
Total: 5 stories ready to start (3 agents available)
Recommended Assignments:
AG-UI: US-0033 or US-0050 (both ready, pick by priority)
AG-API: US-0040 (HIGH PRIORITY - unblocks payment epic)
AG-CI: (No stories ready in their domain)
⚡ Optimize throughput: Start 2-3 stories in parallel across agents
```
GANTT CHART GENERATION
```bash
# Generate ASCII Gantt chart based on dependencies
for story in stories_in_dependency_order; do
earliest_start=$(calculate_earliest_start $story)
duration=$(get_estimate $story)
earliest_end=$((earliest_start + duration))
echo "$story: Start day $earliest_start, End day $earliest_end"
print_gantt_bar $story $earliest_start $duration
done
```
**Output**:
```
Gantt Chart (Dependency-Based Schedule)
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Timeline (days):
0 2 4 6 8 10 12 14 16
│────│────│────│────│────│────│────│────│
US-0030 ████░░ (2d) ✅ Done
US-0031 ██████░░ (3d) ✅ Done
US-0035 ██████░░ (3d) 🔵 In Review
US-0032 ████░░ (2d) 🟡 In Progress
US-0034 ████░░ (2d) ✅ Done
US-0033 ██░░ (1d) 🟢 Ready
US-0045 ████░░ (2d) ⚪ Blocked
US-0040 ████░░ (2d) 🟢 Ready (parallel)
US-0041 ██░░ (1d) ⚪ Blocked
US-0042 ██████░░ (3d) ⚪ Blocked
Legend:
█ Completed/In Progress
░ Planned
⚠️ Critical Path Stories: US-0030, US-0031, US-0032, US-0033
Insights:
- EP-0010 completion: Day 9 (if no delays)
- EP-0011 completion: Day 8 (if US-0040 starts now)
- Parallelism opportunity: US-0040 can run parallel to US-0032
```
DEPENDENCY HEALTH SCORE
```bash
score=100
# Deduct points for issues
circular_deps=$(count_circular_dependencies)
score=$((score - circular_deps * 20)) # -20 per circular dep
high_impact_blockers=$(count_high_impact_blockers)
score=$((score - high_impact_blockers * 10)) # -10 per high-impact blocker
long_chains=$(count_dependency_chains_over_length 5)
score=$((score - long_chains * 5)) # -5 per long chain
echo "Dependency Health Score: $score/100"
```
**Output**:
```
Dependency Health Score
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Score: 75/100 🟡 Fair
Breakdown:
Base score: 100
- Circular dependencies: -0 (0 found) ✅
- High-impact blockers: -20 (2 found: US-0040, US-0032) ⚠️
- Long dependency chains: -5 (1 chain of 4 stories)
Grade: C+ (Fair)
Recommendations:
1. Start US-0040 immediately (high-impact blocker)
2. Monitor US-0032 progress (critical path)
3. Consider breaking up long chains into smaller increments
To improve score to 90+:
- Resolve high-impact blockers
- Break dependency chains <3 stories
- Ensure parallel work opportunities exist
```
USAGE EXAMPLES
### Show all dependencies
```bash
/AgileFlow:dependencies
```
### Specific epic dependencies
```bash
/AgileFlow:dependencies EPIC=EP-0010
```
### Specific story dependencies
```bash
/AgileFlow:dependencies STORY=US-0032
```
### Only critical path analysis
```bash
/AgileFlow:dependencies ANALYSIS=critical-path
```
### Export as Mermaid diagram
```bash
/AgileFlow:dependencies FORMAT=mermaid > dependencies.mmd
```
### Check for circular dependencies
```bash
/AgileFlow:dependencies ANALYSIS=circular
```
INTEGRATION WITH OTHER COMMANDS
- Before `/AgileFlow:board`: Run `/AgileFlow:dependencies` to understand blockers
- After `/AgileFlow:story-new`: Run `/AgileFlow:dependencies` to visualize impact
- In `/AgileFlow:babysit`: Check `/AgileFlow:dependencies` before starting work
- With `/AgileFlow:metrics`: Correlate cycle time with dependency depth
RULES
- Parse dependencies from story frontmatter first (authoritative)
- Fall back to bus/log.jsonl for implicit dependencies
- Detect and flag circular dependencies as errors
- Highlight critical path stories for priority
- Use consistent color coding across all formats
- Export formats should be copy-paste ready
- Always show actionable recommendations
OUTPUT
- ASCII dependency graph with status indicators
- Critical path analysis with duration estimates
- Circular dependency warnings (if any)
- Blocking story impact analysis
- Parallel work opportunities
- Optional: Mermaid/GraphViz export for documentation

227
commands/diagnose.md Normal file
View File

@@ -0,0 +1,227 @@
---
description: System health diagnostics
allowed-tools: Bash, Read
---
# diagnose
Run comprehensive AgileFlow system health checks to identify potential issues before they cause failures.
## Prompt
ROLE: System Diagnostician
OBJECTIVE: Validate AgileFlow system health, identify issues, and provide actionable recommendations.
**Run these diagnostic checks**:
```bash
#!/bin/bash
echo "🔍 AgileFlow System Diagnostics"
echo "================================"
echo ""
# Check 1: Validate all JSON files
echo "📋 JSON File Validation"
echo "----------------------"
JSON_FILES=(
"docs/00-meta/agileflow-metadata.json"
"docs/09-agents/status.json"
"docs/09-agents/status-archive.json"
"docs/08-project/github-sync-map.json"
"docs/08-project/notion-sync-map.json"
"hooks/hooks.json"
)
JSON_ERRORS=0
for FILE in "${JSON_FILES[@]}"; do
if [ -f "$FILE" ]; then
if jq empty "$FILE" 2>/dev/null; then
SIZE=$(stat -f%z "$FILE" 2>/dev/null || stat -c%s "$FILE" 2>/dev/null)
SIZE_KB=$((SIZE / 1024))
echo " ✅ $FILE (${SIZE_KB}KB)"
# Warn if status.json is getting large (>100KB)
if [[ "$FILE" == "docs/09-agents/status.json" ]] && [ $SIZE -gt 102400 ]; then
echo " ⚠️ WARNING: status.json is large (${SIZE_KB}KB). Consider running archival."
JSON_ERRORS=$((JSON_ERRORS + 1))
fi
else
echo " ❌ $FILE - INVALID JSON"
echo " Error details:"
jq . "$FILE" 2>&1 | head -3 | sed 's/^/ /'
JSON_ERRORS=$((JSON_ERRORS + 1))
fi
else
# Only warn for critical files
if [[ "$FILE" == "docs/00-meta/agileflow-metadata.json" ]] || [[ "$FILE" == "docs/09-agents/status.json" ]]; then
echo " ❌ $FILE - NOT FOUND (CRITICAL)"
JSON_ERRORS=$((JSON_ERRORS + 1))
else
echo " ℹ️ $FILE - not found (optional)"
fi
fi
done
echo ""
# Check 2: Auto-Archival System
echo "📦 Auto-Archival System"
echo "----------------------"
if [ -f scripts/archive-completed-stories.sh ]; then
if [ -x scripts/archive-completed-stories.sh ]; then
echo " ✅ Archive script exists and is executable"
# Check if hooked up
if [ -f hooks/hooks.json ] && grep -q "archive-completed-stories.sh" hooks/hooks.json 2>/dev/null; then
echo " ✅ Auto-archival hook configured"
# Check threshold
if [ -f docs/00-meta/agileflow-metadata.json ]; then
THRESHOLD=$(jq -r '.archival.threshold_days // "not set"' docs/00-meta/agileflow-metadata.json 2>/dev/null)
echo " ✅ Archival threshold: $THRESHOLD days"
else
echo " ⚠️ Archival threshold not configured in metadata"
fi
else
echo " ❌ Auto-archival hook NOT configured in hooks/hooks.json"
JSON_ERRORS=$((JSON_ERRORS + 1))
fi
else
echo " ⚠️ Archive script exists but is NOT executable"
echo " Fix: chmod +x scripts/archive-completed-stories.sh"
JSON_ERRORS=$((JSON_ERRORS + 1))
fi
else
echo " ❌ Archive script NOT found (scripts/archive-completed-stories.sh)"
JSON_ERRORS=$((JSON_ERRORS + 1))
fi
echo ""
# Check 3: Hooks System
echo "🪝 Hooks System"
echo "---------------"
if [ -d hooks ] && [ -f hooks/hooks.json ]; then
if jq empty hooks/hooks.json 2>/dev/null; then
echo " ✅ hooks/hooks.json is valid JSON"
# Count hooks
SESSION_START_HOOKS=$(jq '.hooks.SessionStart | length' hooks/hooks.json 2>/dev/null)
USER_PROMPT_HOOKS=$(jq '.hooks.UserPromptSubmit | length' hooks/hooks.json 2>/dev/null)
STOP_HOOKS=$(jq '.hooks.Stop | length' hooks/hooks.json 2>/dev/null)
echo " ℹ️ SessionStart hooks: $SESSION_START_HOOKS"
echo " ℹ️ UserPromptSubmit hooks: $USER_PROMPT_HOOKS"
echo " ℹ️ Stop hooks: $STOP_HOOKS"
else
echo " ❌ hooks/hooks.json is INVALID JSON"
JSON_ERRORS=$((JSON_ERRORS + 1))
fi
else
echo " ⚠️ Hooks system not configured"
fi
echo ""
# Check 4: File Sizes
echo "📏 File Size Analysis"
echo "---------------------"
if [ -f docs/09-agents/status.json ]; then
STATUS_SIZE=$(stat -f%z docs/09-agents/status.json 2>/dev/null || stat -c%s docs/09-agents/status.json 2>/dev/null)
STATUS_KB=$((STATUS_SIZE / 1024))
STORY_COUNT=$(jq '.stories | length' docs/09-agents/status.json 2>/dev/null)
echo " status.json: ${STATUS_KB}KB ($STORY_COUNT stories)"
if [ $STATUS_SIZE -gt 102400 ]; then
echo " ⚠️ WARNING: status.json exceeds 100KB"
echo " Recommendation: Run archival to reduce file size"
echo " Command: bash scripts/archive-completed-stories.sh 7"
elif [ $STATUS_SIZE -gt 51200 ]; then
echo " ℹ️ status.json is getting large (>50KB)"
echo " Consider running archival soon"
else
echo " ✅ status.json size is healthy"
fi
fi
if [ -f docs/09-agents/status-archive.json ]; then
ARCHIVE_SIZE=$(stat -f%z docs/09-agents/status-archive.json 2>/dev/null || stat -c%s docs/09-agents/status-archive.json 2>/dev/null)
ARCHIVE_KB=$((ARCHIVE_SIZE / 1024))
ARCHIVE_COUNT=$(jq '.stories | length' docs/09-agents/status-archive.json 2>/dev/null)
echo " status-archive.json: ${ARCHIVE_KB}KB ($ARCHIVE_COUNT stories)"
fi
echo ""
# Check 5: MCP Integration
echo "🔌 MCP Integration"
echo "------------------"
if [ -f .mcp.json ]; then
if jq empty .mcp.json 2>/dev/null; then
echo " ✅ .mcp.json is valid JSON"
# Check if in .gitignore
if grep -q "^\\.mcp\\.json$" .gitignore 2>/dev/null; then
echo " ✅ .mcp.json is in .gitignore (secure)"
else
echo " ⚠️ WARNING: .mcp.json is NOT in .gitignore"
echo " This is a SECURITY RISK - add it immediately!"
JSON_ERRORS=$((JSON_ERRORS + 1))
fi
else
echo " ❌ .mcp.json is INVALID JSON"
JSON_ERRORS=$((JSON_ERRORS + 1))
fi
else
echo " ℹ️ MCP not configured (.mcp.json not found)"
fi
if [ -f .env ]; then
# Check if in .gitignore
if grep -q "^\\.env$" .gitignore 2>/dev/null; then
echo " ✅ .env is in .gitignore (secure)"
else
echo " ⚠️ WARNING: .env is NOT in .gitignore"
echo " This is a SECURITY RISK - add it immediately!"
JSON_ERRORS=$((JSON_ERRORS + 1))
fi
else
echo " ℹ️ .env not found (optional if MCP not configured)"
fi
echo ""
# Final Summary
echo "📊 Diagnostic Summary"
echo "====================="
if [ $JSON_ERRORS -eq 0 ]; then
echo "✅ All checks passed! System is healthy."
exit 0
else
echo "⚠️ Found $JSON_ERRORS issue(s) that need attention."
echo ""
echo "Next steps:"
echo "1. Fix JSON validation errors using: bash scripts/validate-json.sh <file>"
echo "2. Add missing files to .gitignore if needed"
echo "3. Run archival if status.json is too large: bash scripts/archive-completed-stories.sh 7"
echo "4. Re-run diagnostics after fixes: /AgileFlow:diagnose"
exit 1
fi
```
**Output Format**:
- Show all check results with ✅/❌/⚠️/ℹ️ indicators
- Display file sizes and story counts
- Provide actionable recommendations for issues
- Exit with code 0 if healthy, code 1 if issues found

166
commands/docs.md Normal file
View File

@@ -0,0 +1,166 @@
---
description: docs-sync
allowed-tools: Bash, Read, Edit, Write, Glob, Grep
---
# docs-sync
Synchronize documentation with codebase changes.
## Prompt
ROLE: Documentation Synchronizer
OBJECTIVE
Detect code changes and ensure corresponding documentation is created or updated.
INPUTS (optional)
- BRANCH=<branch name> (default: current branch)
- BASE=<base branch> (default: main/master)
- AUTO_CREATE=yes|no (default: no, ask first)
DETECTION WORKFLOW
1. Get git diff between BASE and BRANCH:
```bash
git diff <BASE>...<BRANCH> --name-status
```
2. Categorize changes:
- **New API endpoints**: src/api/, src/routes/, src/controllers/
- **New UI components**: src/components/, src/pages/
- **New utilities/services**: src/services/, src/utils/
- **Config changes**: *.config.js, *.yml, .env.example
- **Database changes**: migrations/, schema/
3. Map to expected docs:
- API endpoints → docs/04-architecture/api.md or OpenAPI spec
- UI components → docs/04-architecture/components.md or Storybook
- Services → docs/04-architecture/services.md
- Config → docs/02-practices/configuration.md
- Migrations → docs/04-architecture/database.md
ANALYSIS
For each changed file:
```
File: src/api/auth/login.ts (ADDED)
Expected doc: docs/04-architecture/api.md
Section: Authentication Endpoints
Status: ❌ MISSING (section exists but endpoint not documented)
Suggestion:
## POST /api/auth/login
**Added**: <date>
**Story**: <US_ID if found in commit>
Request:
\`\`\`json
{ "email": "string", "password": "string" }
\`\`\`
Response:
\`\`\`json
{ "token": "string", "user": {...} }
\`\`\`
Authentication: None (public endpoint)
Rate limit: 5 requests/minute
```
GAP REPORT
```markdown
# Documentation Sync Report
**Branch**: <BRANCH>
**Base**: <BASE>
**Generated**: <ISO timestamp>
## Missing Documentation
### API Endpoints (3)
- ❌ POST /api/auth/login (src/api/auth/login.ts)
- ❌ GET /api/users/:id (src/api/users/get.ts)
- ❌ DELETE /api/sessions (src/api/sessions/delete.ts)
### UI Components (2)
- ❌ LoginForm (src/components/LoginForm.tsx)
- ⚠️ UserProfile (src/components/UserProfile.tsx) - stub exists, needs details
### Configuration (1)
- ❌ New env var: JWT_SECRET (.env.example)
## Outdated Documentation
### Deprecated
- 📄 docs/04-architecture/api.md mentions /api/v1/login (removed in this branch)
## Up-to-Date
- ✅ UserAvatar component documented
- ✅ Database schema up-to-date
```
ACTIONS (after user review)
1. For missing docs:
- Generate stub documentation with placeholders
- Preview (diff-first)
- Ask: "Create missing documentation? (YES/NO)"
2. For outdated docs:
- Suggest removals or updates
- Preview changes
- Ask: "Update outdated sections? (YES/NO)"
3. If AUTO_CREATE=yes:
- Create all missing docs automatically
- Mark sections with "TODO: Add details" for manual review
- Commit: "docs: sync with codebase changes"
SMART INFERENCE
Try to infer documentation from:
- TypeScript types/interfaces
- JSDoc comments
- OpenAPI decorators
- Function signatures
- Test files (use as examples)
Example:
```typescript
// Code: src/api/auth/login.ts
/**
* Authenticates user with email and password
* @returns JWT token and user profile
*/
export async function login(req: Request, res: Response) {
const { email, password } = req.body;
// ...
}
// Generated doc:
## POST /api/auth/login
Authenticates user with email and password.
Returns JWT token and user profile.
```
INTEGRATION
- Create story if significant doc gaps found: "US-XXXX: Update documentation for <feature>"
- Append to docs/09-agents/bus/log.jsonl: {"type":"docs-sync","missing":3,"outdated":1}
- Optionally add to PR checklist: "- [ ] Documentation updated"
CI INTEGRATION
Suggest adding to PR checks:
```yaml
- name: Check docs sync
run: npx claude-code /AgileFlow:docs-sync BRANCH=${{ github.head_ref }}
# Fail if critical docs missing (e.g., public API endpoints)
```
RULES
- Never delete docs without explicit approval
- Preserve custom content (don't overwrite manually written sections)
- Use managed section markers: <!-- MANAGED:api-endpoints --> ... <!-- /MANAGED -->
- Link docs to source files for traceability
- Diff-first, YES/NO for all changes
OUTPUT
- Gap report (markdown)
- List of actions to take
- Optional: PR with doc updates (if approved)

27
commands/epic.md Normal file
View File

@@ -0,0 +1,27 @@
---
description: epic-new
allowed-tools: Bash, Read, Edit, Write, Glob, Grep
---
# epic-new
Create a new epic with optional child stories.
## Prompt
ROLE: Epic Creator
INPUTS
EPIC=<ID e.g., EP-0001>
TITLE=<Epic title>
OWNER=<name or agent id>
GOAL=<outcome/metric>
STORIES=<optional> comma-separated "<US_ID>|<short title>|<owner>"
ACTIONS
1) Create docs/05-epics/<EPIC>.md from epic-template.md (status=active; created/updated=now).
2) For each story, create docs/06-stories/<EPIC>/<US_ID>-<slug>.md from story-template.md (status=ready; estimate=0.5d; deps=[]).
3) Merge entries into docs/09-agents/status.json (owner,status,branch,summary,last_update).
4) Append "assign" lines to docs/09-agents/bus/log.jsonl.
Always show previews; YES/NO before writing.

307
commands/feedback.md Normal file
View File

@@ -0,0 +1,307 @@
---
description: agent-feedback
allowed-tools: Bash, Read, Edit, Write, Glob, Grep
---
# agent-feedback
Collect feedback from agents and humans for continuous process improvement.
## Prompt
ROLE: Feedback Collector & Retrospective Facilitator
OBJECTIVE
Gather feedback on story completion, agent performance, and process effectiveness for continuous improvement.
INPUTS (optional)
- SCOPE=story|epic|sprint (default: story - feedback on single story)
- STORY=<US_ID> (required if SCOPE=story)
- EPIC=<EP_ID> (required if SCOPE=epic)
- ANONYMOUS=yes|no (default: no)
FEEDBACK TYPES
### 1. Story Completion Feedback
After marking story as "done", prompt for:
```markdown
## Story Feedback: <US_ID>
**Completed by**: <agent or human>
**Date**: <ISO timestamp>
### Definition of Ready (1-5 scale)
- Were acceptance criteria clear? (1=very unclear, 5=crystal clear): ___
- Were dependencies resolved? (1=many blockers, 5=no issues): ___
- Was estimate accurate? (1=way off, 5=spot on): ___
### Implementation Process (1-5 scale)
- How smooth was implementation? (1=many obstacles, 5=smooth): ___
- Were tests adequate? (1=missing, 5=comprehensive): ___
- Was documentation sufficient? (1=inadequate, 5=excellent): ___
### What Went Well? (2-3 bullets)
-
-
-
### What Could Be Improved? (2-3 bullets)
-
-
-
### Blockers Encountered? (if any)
-
### Learning/Insights? (optional)
-
```
### 2. Agent Performance Feedback
Track agent effectiveness:
```markdown
## Agent Feedback: <AGENT_ID>
**Time Period**: <start> to <end>
**Stories Completed**: X
**Stories Blocked**: Y
**Avg Completion Time**: Z days
### Strengths (observed patterns)
- Consistently writes thorough tests
- Updates status.json reliably
- Good at identifying edge cases
### Areas for Improvement
- Sometimes skips accessibility checks
- Could improve commit message clarity
### Recommendations
- Add accessibility checklist to workflow
- Review Conventional Commits guide
```
### 3. Epic Retrospective
After epic completion:
```markdown
## Epic Retrospective: <EP_ID>
**Completed**: <ISO timestamp>
**Duration**: X days (estimated: Y days)
**Stories**: X completed, Y blocked, Z punted
### Success Metrics (from epic definition)
- [ ] Goal 1: <status>
- [ ] Goal 2: <status>
### What Went Well?
-
-
### What Didn't Go Well?
-
-
### Surprises/Learnings?
-
-
### Actions for Next Epic
- [ ] Action 1
- [ ] Action 2
```
### 4. Sprint Retrospective
After sprint/iteration:
```markdown
## Sprint Retrospective: Sprint <N>
**Dates**: <start> to <end>
**Velocity**: X stories completed
**Team**: <list of agents/humans>
### Continue (keep doing)
-
-
### Stop (no longer useful)
-
-
### Start (new practices)
-
-
### Experiments (try next sprint)
-
-
### Blockers Removed This Sprint
-
-
### Recurring Issues (need addressing)
-
-
```
COLLECTION WORKFLOW
1. Auto-prompt at trigger points:
- Story status → done
- Epic 100% complete
- Sprint end date reached
2. Present feedback form with pre-filled context
3. Ask: "Provide feedback now? (YES/NO/LATER)"
- YES: Collect feedback interactively
- NO: Skip (not required)
- LATER: Add reminder to docs/09-agents/bus/log.jsonl
4. Save feedback to:
- docs/08-project/feedback/<YYYYMMDD>-<US_ID or EP_ID>.md
- Append summary to docs/08-project/retrospectives.md
ANALYSIS
### Patterns & Insights
Scan all feedback for patterns:
- Stories with "unclear AC" → Improve story template
- "Blocked by missing tests" → Enforce test stubs earlier
- "Estimate off by 2x" → Revise estimation guide
### Metrics Tracking
Track over time:
- Avg story clarity score (target: >4.0)
- Avg estimate accuracy (target: within 50%)
- Blocker frequency (target: <20% of stories)
### Agent Performance
Per agent:
- Completion rate
- Test coverage avg
- Status update reliability
- Feedback sentiment
ACTIONABLE OUTPUTS
### Improvement Stories
Auto-generate stories for recurring issues:
```
Issue: 5 stories in last sprint had "unclear AC" (score <3)
Suggested story: "US-XXXX: Improve story template with AC examples"
Issue: Estimates consistently off by 2x for API stories
Suggested ADR: "ADR-XXXX: Update estimation guidelines for backend work"
```
### Recognition
Celebrate wins:
```
🎉 AG-UI completed 8 stories this sprint with 100% test coverage!
🎉 AG-API reduced avg completion time from 2.1d to 1.6d
```
### Process Changes
Suggest concrete improvements:
```
Pattern detected: Stories with test stubs created upfront (by epic-planner)
have 40% fewer blockers.
Recommendation: Always create test stubs with /story-new.
```
RETROSPECTIVE REPORT
```markdown
# Retrospective Summary
**Period**: <start> to <end>
**Stories Reviewed**: X
**Epics Reviewed**: Y
---
## Overall Sentiment
📈 Improving: AC clarity (4.2 → 4.5)
📉 Declining: Estimate accuracy (85% → 78%)
➡️ Stable: Test coverage (avg 87%)
---
## Top Wins 🎉
1. Zero critical bugs this sprint
2. All security stories completed on time
3. Improved docs sync (100% of PRs had doc updates)
---
## Top Challenges ⚠️
1. Dependencies blocking 3 stories
2. Estimates off for DB migration work
3. Flaky E2E tests caused delays
---
## Actions for Next Iteration
- [ ] Review estimation guide for DB work (assign: EPIC-PLANNER)
- [ ] Fix flaky tests (assign: AG-CI, priority: high)
- [ ] Improve dependency tracking in story planning
---
## Insights & Learning
- Smaller stories (<1d) have 50% fewer blockers
- Pairing AG-UI and AG-API on complex features reduces handoff issues
- Weekly debt reviews prevent accumulation
```
INTEGRATION
### Story Creation
If feedback reveals issues, offer to create stories:
```
Feedback indicates: Test coverage inadequate for 3 stories
Create story? (YES/NO)
→ US-XXXX: Add missing tests for authentication flow
```
### ADR Creation
If architectural learnings emerge:
```
Learning: Microservices added complexity without clear benefit
Create ADR to document this? (YES/NO)
→ ADR-XXXX: Revert to modular monolith architecture
```
### Message Bus
Log feedback events:
```json
{"ts":"2025-10-16T10:00:00Z","type":"feedback","story":"US-0042","clarity":5,"smooth":4,"improved":"Add more examples in AC"}
```
AUTOMATION
Suggest periodic reminders:
```
# In docs/08-project/roadmap.md
- Every Friday: Sprint retrospective (if applicable)
- End of epic: Epic retrospective
- Monthly: Review all feedback for patterns
```
RULES
- Feedback is always optional (never block workflow)
- Keep feedback forms short (<5 min to complete)
- Focus on actionable insights, not blame
- Anonymize if requested
- Share retrospective summaries with team
- Celebrate wins before discussing challenges
OUTPUT
- Feedback form (interactive)
- Saved feedback (markdown)
- Optional: Retrospective summary
- Optional: Auto-generated improvement stories

589
commands/github.md Normal file
View File

@@ -0,0 +1,589 @@
---
description: github-sync
allowed-tools: Bash, Read, Edit, Write, Glob, Grep
---
# github-sync
Two-way sync between AgileFlow stories and GitHub Issues with automatic status updates.
## Prompt
ROLE: GitHub Integration Specialist
OBJECTIVE
Synchronize AgileFlow stories with GitHub Issues bidirectionally, keeping status, labels, assignees, and milestones in sync.
INPUTS (optional)
- MODE=import|export|sync (default: sync)
- EPIC=<EP_ID> (filter by specific epic)
- STORY=<US_ID> (sync single story)
- DRY_RUN=true|false (default: false - preview changes)
- DIRECTION=agileflow-to-github|github-to-agileflow|bidirectional (default: bidirectional)
PREREQUISITES
1. **GitHub MCP Server** configured in `.mcp.json`:
```json
{
"mcpServers": {
"github": {
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-github"],
"env": {
"GITHUB_PERSONAL_ACCESS_TOKEN": "ghp_your_token_here"
}
}
}
}
```
Token permissions needed:
- `repo` (full control) - for issues, PRs, labels
- `read:org` - for organization access (if needed)
Get token from: https://github.com/settings/tokens
2. **Repository configured** in sync map or provided via GITHUB_REPO parameter
3. **Sync Mapping** (create if missing):
`docs/08-project/github-sync-map.json`:
```json
{
"last_sync": "2025-10-17T14:30:00Z",
"mappings": {
"US-0030": {"issue_number": 42, "last_synced": "2025-10-17T10:00:00Z"},
"US-0031": {"issue_number": 43, "last_synced": "2025-10-17T11:00:00Z"}
},
"config": {
"status_mapping": {
"ready": "Status: Ready",
"in-progress": "Status: In Progress",
"in-review": "Status: In Review",
"done": "Status: Done"
},
"epic_to_milestone": {
"EP-0010": "Milestone 1: Authentication",
"EP-0011": "Milestone 2: Payments"
}
}
}
```
SYNC WORKFLOW
### 1. Read Current State
```bash
# AgileFlow state
Read docs/09-agents/status.json
Read docs/06-stories/**/*.md
# GitHub state (via MCP tools)
# Use mcp__github__* tools to list issues, get repo info, etc.
# MCP provides: search_repositories, create_or_update_file, push_files, create_issue,
# create_pull_request, fork_repository, create_repository, get_file_contents, etc.
```
### 2. Detect Changes
**From AgileFlow to GitHub**:
- New stories not in mapping → Create GitHub Issues
- Status changes → Update GitHub labels
- Story updates (title, description, AC) → Update Issue body
- Assignment changes → Update Issue assignees
**From GitHub to AgileFlow**:
- New Issues with `agileflow:` label → Create stories
- Issue closed → Update status to "done"
- Label changes → Update status.json
- Assignee changes → Update story frontmatter
### 3. Apply Changes (with conflict resolution)
If both sides changed:
1. Check timestamps (last_synced vs. GitHub updated_at vs. bus/log.jsonl timestamp)
2. Prefer most recent change
3. Log conflict to docs/09-agents/bus/log.jsonl:
```json
{"ts":"2025-10-17T14:30:00Z","type":"sync-conflict","story":"US-0030","github_issue":42,"resolution":"kept_github","reason":"GitHub updated more recently"}
```
AGILEFLOW → GITHUB EXPORT
### Create GitHub Issue from Story
For each story in docs/06-stories/**/*.md:
```bash
# Read story frontmatter
story_id=US-0030
title="User registration endpoint"
owner=AG-API
epic=EP-0010
status=done
# Create issue if not exists
if ! in_mapping($story_id); then
issue_number=$(gh issue create \
--repo $GITHUB_REPO \
--title "[$story_id] $title" \
--body "$(cat <<EOF
## Story: $story_id
**Epic**: $epic
**Owner**: $owner
**Estimate**: 1d
### Acceptance Criteria
- [ ] Given a new user submits registration form
- [ ] When all fields are valid
- [ ] Then account is created and confirmation email sent
### Links
- [Story file](docs/06-stories/EP-0010/US-0030.md)
- [Test cases](docs/07-testing/test-cases/US-0030.md)
---
*Synced from AgileFlow*
EOF
)" \
--label "agileflow:story" \
--label "epic:EP-0010" \
--label "owner:AG-API" \
--label "Status: Done" \
--milestone "Milestone 1: Authentication" \
| grep -oP '#\K\d+')
# Record mapping
update_mapping $story_id $issue_number
fi
```
### Update GitHub Issue Status
```bash
# When status changes in status.json
story_id=US-0030
new_status=in-review
# Remove old status label, add new
gh issue edit $issue_number \
--remove-label "Status: In Progress" \
--add-label "Status: In Review"
# If done, close issue
if [ "$new_status" = "done" ]; then
gh issue close $issue_number --comment "✅ Story completed in AgileFlow"
fi
# Log to bus
echo "{\"ts\":\"$(date -Iseconds)\",\"type\":\"github-sync\",\"story\":\"$story_id\",\"issue\":$issue_number,\"action\":\"status_updated\",\"status\":\"$new_status\"}" >> docs/09-agents/bus/log.jsonl
```
GITHUB → AGILEFLOW IMPORT
### Create Story from GitHub Issue
For each Issue with label `agileflow:story`:
```bash
gh issue view $issue_number --json number,title,body,labels,assignees,milestone,state
# Extract story metadata from labels
epic=$(echo $labels | grep -oP 'epic:\K[A-Z]+-\d+')
owner=$(echo $labels | grep -oP 'owner:\K[A-Z]+-[A-Z]+')
status_label=$(echo $labels | grep -oP 'Status: \K.*')
# Map status
case "$status_label" in
"Ready") status=ready ;;
"In Progress") status=in-progress ;;
"In Review") status=in-review ;;
"Done") status=done ;;
esac
# Generate story ID if not in title
if [[ $title =~ \[US-([0-9]+)\] ]]; then
story_id=US-${BASH_REMATCH[1]}
else
# Find next available ID
story_id=$(find_next_story_id)
# Update GitHub issue title
gh issue edit $issue_number --title "[$story_id] $title"
fi
# Create story file if doesn't exist
if [ ! -f "docs/06-stories/$epic/$story_id.md" ]; then
cat > "docs/06-stories/$epic/$story_id.md" <<EOF
---
id: $story_id
title: $title
epic: $epic
owner: $owner
status: $status
estimate: 1d
github_issue: $issue_number
---
# $title
## Description
$body
## Acceptance Criteria
- [ ] (Imported from GitHub - please refine)
## GitHub
- Issue: #$issue_number
- [View on GitHub](https://github.com/$GITHUB_REPO/issues/$issue_number)
EOF
# Update status.json
update_status_json $story_id $status $owner
# Log to bus
echo "{\"ts\":\"$(date -Iseconds)\",\"type\":\"github-import\",\"story\":\"$story_id\",\"issue\":$issue_number,\"action\":\"created\"}" >> docs/09-agents/bus/log.jsonl
fi
```
### Sync Issue Closure
```bash
# When GitHub issue is closed
if [ "$issue_state" = "CLOSED" ]; then
# Update AgileFlow status
story_id=$(get_story_from_mapping $issue_number)
if [ -n "$story_id" ]; then
# Update status.json
update_status_json $story_id "done" "$owner"
# Log to bus
echo "{\"ts\":\"$(date -Iseconds)\",\"type\":\"github-sync\",\"story\":\"$story_id\",\"issue\":$issue_number,\"action\":\"closed\",\"status\":\"done\"}" >> docs/09-agents/bus/log.jsonl
fi
fi
```
SYNC REPORT
After sync completes, generate report:
```markdown
# GitHub Sync Report
**Generated**: 2025-10-17 14:30
**Mode**: Bidirectional sync
**Repository**: owner/repo
---
## 📊 Summary
**AgileFlow → GitHub**: 5 changes
- ✅ 3 issues created
- ✅ 2 statuses updated
**GitHub → AgileFlow**: 2 changes
- ✅ 1 story created
- ✅ 1 status updated (closed)
**Conflicts**: 1 resolved
- US-0030: GitHub updated more recently (kept GitHub state)
---
## 📤 Exported to GitHub
| Story | Issue | Action | Status |
|-------|-------|--------|--------|
| US-0042 | #45 | Created | ✅ Success |
| US-0043 | #46 | Created | ✅ Success |
| US-0044 | #47 | Created | ✅ Success |
| US-0038 | #40 | Updated status | ✅ Success |
| US-0035 | #38 | Updated status | ✅ Success |
## 📥 Imported from GitHub
| Issue | Story | Action | Status |
|-------|-------|--------|--------|
| #48 | US-0050 | Created story | ✅ Success |
| #42 | US-0030 | Closed → done | ✅ Success |
## ⚠️ Conflicts Resolved
| Story | Issue | Conflict | Resolution |
|-------|-------|----------|------------|
| US-0030 | #42 | Both updated | Kept GitHub (more recent) |
## 🔗 Mapping Updates
Updated `docs/08-project/github-sync-map.json` with 5 new mappings.
**Next sync**: Run `/AgileFlow:github-sync` again to keep in sync, or set up GitHub Actions webhook.
---
## 🤖 Automation Recommendation
Set up automatic sync with GitHub Actions:
`.github/workflows/agileflow-sync.yml`:
```yaml
name: AgileFlow Sync
on:
issues:
types: [opened, edited, closed, labeled]
schedule:
- cron: '0 */6 * * *' # Every 6 hours
jobs:
sync:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v3
- run: /AgileFlow:github-sync MODE=sync
```
```
LABEL MANAGEMENT
### Auto-create AgileFlow Labels
```bash
# Create standard labels if they don't exist
labels=(
"agileflow:story|Story tracked in AgileFlow|0366d6"
"epic:EP-0010|Epic: User Authentication|d4c5f9"
"owner:AG-UI|Owner: UI Agent|fbca04"
"owner:AG-API|Owner: API Agent|0e8a16"
"Status: Ready|Ready to start|ededed"
"Status: In Progress|Work in progress|fbca04"
"Status: In Review|Under review|0075ca"
"Status: Done|Completed|0e8a16"
)
for label_def in "${labels[@]}"; do
IFS='|' read -r name description color <<< "$label_def"
gh label create "$name" --description "$description" --color "$color" --force
done
```
WEBHOOK INTEGRATION (Advanced)
For real-time sync, set up GitHub webhook:
```bash
# webhook-handler.sh (runs on issue events)
payload=$(cat)
action=$(echo $payload | jq -r '.action')
issue_number=$(echo $payload | jq -r '.issue.number')
case $action in
opened|edited)
# Import/update story
/AgileFlow:github-sync MODE=import ISSUE=$issue_number
;;
closed)
# Mark story done
story_id=$(get_story_from_mapping $issue_number)
/AgileFlow:status STORY=$story_id STATUS=done
;;
labeled)
# Sync status if status label changed
new_label=$(echo $payload | jq -r '.label.name')
if [[ $new_label =~ ^Status: ]]; then
/AgileFlow:github-sync MODE=import ISSUE=$issue_number
fi
;;
esac
```
CONFLICT RESOLUTION STRATEGY
1. **Timestamp comparison**:
- AgileFlow: Parse latest timestamp from bus/log.jsonl for story
- GitHub: Use `updated_at` from issue
- **Winner**: Most recent timestamp
2. **Manual resolution** (if timestamps within 5 minutes):
- Show diff to user
- Ask which to keep
- Log decision to bus
3. **Auto-resolution rules**:
- Status changes: Prefer GitHub (closer to source of truth for developers)
- Content changes: Prefer AgileFlow (more detailed AC and structure)
- Assignment: Prefer GitHub (reflects actual work assignment)
DRY RUN MODE
Preview changes before applying:
```bash
/AgileFlow:github-sync DRY_RUN=true
```
Output:
```markdown
# GitHub Sync (DRY RUN)
**Would apply 7 changes** (use DRY_RUN=false to apply)
## AgileFlow → GitHub (5 changes)
✏️ **Create** Issue for US-0042 "Login form UI"
- Labels: agileflow:story, epic:EP-0010, owner:AG-UI, Status: Ready
- Milestone: Milestone 1: Authentication
✏️ **Create** Issue for US-0043 "Profile page"
- Labels: agileflow:story, epic:EP-0011, owner:AG-UI, Status: Ready
✏️ **Update** Issue #40 status label
- Remove: Status: Ready
- Add: Status: In Progress
## GitHub → AgileFlow (2 changes)
✏️ **Create** Story US-0050 from Issue #48 "Add password reset flow"
- File: docs/06-stories/EP-0010/US-0050.md
- Status: ready
- Owner: AG-API
✏️ **Update** US-0030 status to "done" (Issue #42 closed)
- Update status.json
- Log to bus
**Run with DRY_RUN=false to apply these changes.**
```
ERROR HANDLING
```bash
# Check for GitHub MCP tools
if ! command -v mcp__github__search_repositories &> /dev/null; then
echo "❌ GitHub MCP not configured. Add to .mcp.json:"
echo ' "github": {'
echo ' "command": "npx",'
echo ' "args": ["-y", "@modelcontextprotocol/server-github"],'
echo ' "env": {"GITHUB_PERSONAL_ACCESS_TOKEN": "ghp_your_token"}'
echo ' }'
echo ""
echo "Then restart Claude Code to load MCP server."
exit 1
fi
# Validate sync map
if [ ! -f "docs/08-project/github-sync-map.json" ]; then
echo "⚠️ Sync map not found. Creating new mapping file..."
mkdir -p docs/08-project
echo '{"last_sync":null,"mappings":{},"config":{}}' > docs/08-project/github-sync-map.json
fi
```
USAGE EXAMPLES
### Full bidirectional sync
```bash
/AgileFlow:github-sync
```
### Export all stories to GitHub
```bash
/AgileFlow:github-sync MODE=export
```
### Import GitHub issues to AgileFlow
```bash
/AgileFlow:github-sync MODE=import
```
### Sync single story
```bash
/AgileFlow:github-sync STORY=US-0030
```
### Sync specific epic
```bash
/AgileFlow:github-sync EPIC=EP-0010
```
### Preview changes (dry run)
```bash
/AgileFlow:github-sync DRY_RUN=true
```
### One-way sync (AgileFlow → GitHub only)
```bash
/AgileFlow:github-sync DIRECTION=agileflow-to-github
```
INTEGRATION WITH OTHER COMMANDS
- After `/AgileFlow:story-new`: Optionally prompt to create GitHub issue
- After `/AgileFlow:status`: Auto-sync status to GitHub
- In `/AgileFlow:board`: Show GitHub issue links
- In `/AgileFlow:velocity`: Include GitHub activity metrics
RULES
- Never create duplicate issues (check mapping first)
- Always log sync actions to bus/log.jsonl
- Preserve GitHub issue numbers in story frontmatter
- Use labels for all metadata (status, epic, owner)
- Handle rate limits gracefully (GitHub API: 5000 req/hour)
- Validate GitHub token before any write operations
OUTPUT
- Sync report (markdown)
- Updated github-sync-map.json
- Updated status.json (if GitHub → AgileFlow changes)
- Bus log entries for all sync actions
- Optional: Saved report to docs/08-project/sync-reports/sync-YYYYMMDD-HHMMSS.md
---
## GITHUB MCP INTEGRATION
This command uses **GitHub MCP** for all GitHub operations, providing:
### Advantages
- ✅ **No sudo required** - npx handles installation automatically
- ✅ **Consistent with Notion** - Both use MCP with tokens in `.mcp.json`
- ✅ **Native Claude Code integration** - Built-in MCP tool support
- ✅ **No CLI dependency** - Works in any environment (Docker, codespaces, etc.)
- ✅ **Unified configuration** - All integrations in one `.mcp.json` file
### Available MCP Tools
The GitHub MCP server provides these tools (prefix: `mcp__github__`):
- `search_repositories` - Search for repositories
- `create_or_update_file` - Create/update files in repo
- `create_issue` - Create GitHub issues
- `create_pull_request` - Create PRs
- `get_file_contents` - Read file contents
- `push_files` - Batch file operations
- `fork_repository` - Fork repos
- `create_repository` - Create new repos
### Migration from `gh` CLI
If you previously used GitHub CLI (`gh`):
1. Remove `gh` CLI (no longer needed)
2. Add GitHub MCP to `.mcp.json` (see Prerequisites above)
3. Restart Claude Code to load MCP server
4. Run `/AgileFlow:github-sync` - it now uses MCP automatically
### Why We Switched
- Removes sudo/installation barrier
- Consistent security model across all integrations
- Better portability across environments
- Simpler team onboarding (just copy `.mcp.json.example`)
---
## RELATED COMMANDS
- `/AgileFlow:notion-export` - Sync with Notion (uses MCP)
- `/AgileFlow:story-new` - Create new story (can auto-create GitHub issue)
- `/AgileFlow:board` - Visualize stories with GitHub links
- `/AgileFlow:velocity` - Track velocity including GitHub activity

22
commands/handoff.md Normal file
View File

@@ -0,0 +1,22 @@
---
description: handoff
allowed-tools: Bash, Read, Edit, Write, Glob, Grep
---
# handoff
Document handoff between agents with summary and blockers.
## Prompt
ROLE: Handoff Scribe
INPUTS
STORY=<US-ID> FROM=<id> TO=<id>
SUMMARY=<what changed> BLOCKERS=<optional list>
ACTIONS
1) Create docs/09-agents/comms/<STORY>-<YYYYMMDD>-handoff.md from comms-note-template.md.
2) Append bus line type="handoff".
Diff-first; YES/NO.

22
commands/help.md Normal file
View File

@@ -0,0 +1,22 @@
---
description: system-help
allowed-tools: Bash, Read, Edit, Write, Glob, Grep
---
# system-help
Display a concise overview of the AgileFlow system.
## Prompt
ROLE: System Guide
TASK
Print a concise, one-screen overview:
- Folder map (docs/*) and what lives where
- What Epics, Stories, ADRs are; how docs/09-agents/status.json + bus/log.jsonl work
- Daily flow: Pick story → Implement to AC → Tests → PR → Update status
- WIP limit: max 2 stories/agent
- List ALL available commands with one-line examples
OUTPUT: plain markdown only (no file writes)

204
commands/impact.md Normal file
View File

@@ -0,0 +1,204 @@
---
description: impact-analysis
allowed-tools: Bash, Read, Edit, Write, Glob, Grep
---
# impact-analysis
Analyze the impact of code changes on other parts of the codebase.
## Prompt
ROLE: Impact Analyzer
OBJECTIVE
Identify which files, tests, and features are affected by code changes to prevent regressions.
INPUTS (optional)
- FILES=<comma-separated paths> (default: auto-detect from git diff)
- BASE=<base branch> (default: main/master)
- RUN_TESTS=yes|no (default: yes, if tests found)
DETECTION
1. Get changed files:
```bash
git diff <BASE>...HEAD --name-only
```
2. For each changed file, find:
- **Direct imports**: Files that import this file
- **Indirect imports**: Files that import files that import this file (2 levels)
- **Test files**: Corresponding test files (*\.test\*, *\.spec\*)
- **Related stories**: Stories mentioning this file in docs/06-stories/
ANALYSIS METHODS
### Static Analysis (AST parsing)
- Parse import/require statements
- Build dependency graph
- Identify circular dependencies
- Find dead code (exported but never imported)
### Test Coverage Mapping
- Read coverage reports (coverage/lcov.info, coverage.json)
- Map changed lines to test files
- Identify uncovered changes
### Pattern Matching
- API routes → API tests
- Components → Component tests + Storybook stories
- Services → Service tests + Integration tests
- Database models → Migration tests
IMPACT REPORT
```markdown
# Impact Analysis Report
**Branch**: <BRANCH>
**Base**: <BASE>
**Changed Files**: 5
**Potentially Affected Files**: 23
**Tests to Run**: 12
## Direct Impacts
### src/api/auth/login.ts (MODIFIED)
**Type**: API endpoint
**Changes**: 23 lines modified
**Direct dependents** (3):
- src/api/auth/index.ts (exports this endpoint)
- src/middleware/auth.ts (uses login logic)
- tests/api/auth/login.test.ts (tests this file)
**Indirect dependents** (8):
- src/app.ts → src/api/auth/index.ts → login.ts
- src/routes.ts → src/api/auth/index.ts → login.ts
- [6 more...]
**Related tests**:
- ✅ tests/api/auth/login.test.ts (exists)
- ⚠️ tests/integration/auth-flow.test.ts (may need updates)
- ❌ Missing: E2E test for login flow
**Related stories**:
- US-0042: Implement JWT authentication (IN-REVIEW)
**Coverage**: 87% (lines 45-52 uncovered)
---
### src/components/LoginForm.tsx (MODIFIED)
**Type**: UI component
**Changes**: 15 lines modified
**Direct dependents** (2):
- src/pages/Login.tsx
- src/components/AuthModal.tsx
**Related tests**:
- ✅ tests/components/LoginForm.test.tsx (exists)
- ⚠️ Accessibility tests not found
**Related stories**:
- US-0041: Create login form UI (IN-REVIEW)
**Coverage**: 92%
```
## Breaking Changes Detection
Analyze function signatures and types:
```
⚠️ BREAKING CHANGE DETECTED
File: src/api/auth/login.ts
Function: login()
Before:
login(email: string, password: string): Promise<Token>
After:
login(credentials: LoginRequest): Promise<AuthResponse>
Affected callers (3):
- src/middleware/auth.ts:45
- tests/api/auth/login.test.ts:23
- tests/integration/auth-flow.test.ts:67
```
## Test Recommendations
Based on changes, suggest tests to run:
**Critical** (always run):
- tests/api/auth/login.test.ts (direct test)
- tests/integration/auth-flow.test.ts (integration)
**Recommended** (affected indirectly):
- tests/api/users/*.test.ts (uses auth)
- tests/e2e/login.spec.ts (E2E)
**Optional** (low risk):
- tests/components/Header.test.tsx (displays user from auth)
ACTIONS (after user review)
1. Show impact summary
2. Ask: "Run affected tests? (YES/NO)"
3. If YES:
```bash
# Run only affected tests
npm test -- tests/api/auth/login.test.ts tests/integration/auth-flow.test.ts
```
4. If tests fail:
- Show failures
- Suggest creating story: "US-XXXX: Fix regressions from <change>"
5. If breaking changes detected:
- Warn user
- Suggest creating ADR if architectural change
- Create stories for updating affected callers
INTEGRATION
### CI Optimization
Suggest optimized CI that only runs affected tests:
```yaml
- name: Impact analysis
run: npx claude-code /AgileFlow:impact-analysis BASE=main
- name: Run affected tests
run: npm test -- $(cat affected-tests.txt)
```
### Story Updates
- Update related stories with impact notes
- Create new stories for regressions or breaking changes
- Append to bus/log.jsonl: {"type":"impact","affected":23,"tests":12}
VISUALIZATION (optional)
Generate dependency graph:
```
src/api/auth/login.ts
├── src/api/auth/index.ts
│ ├── src/app.ts
│ └── src/routes.ts
├── src/middleware/auth.ts
│ └── src/app.ts
└── tests/api/auth/login.test.ts
```
RULES
- Use static analysis when possible (faster than running tests)
- Prioritize tests by risk (critical path first)
- Never skip tests for modified files
- Warn about uncovered changes
- Suggest creating tests for uncovered code
- Diff-first for any file modifications
OUTPUT
- Impact analysis report (markdown)
- List of affected files and tests
- Test recommendations (critical/recommended/optional)
- Optional: Run tests and report results

530
commands/metrics.md Normal file
View File

@@ -0,0 +1,530 @@
---
description: metrics
allowed-tools: Bash, Read, Edit, Write, Glob, Grep
---
# metrics
Comprehensive project analytics dashboard with cycle time, lead time, throughput, and trend analysis.
## Prompt
ROLE: Metrics & Analytics Specialist
OBJECTIVE
Generate comprehensive project metrics from AgileFlow data sources (status.json, bus/log.jsonl, story files) to enable data-driven decision making.
INPUTS (optional)
- TIMEFRAME=7d|30d|90d|all (default: 30d)
- EPIC=<EP_ID> (filter by specific epic)
- OWNER=<AG_*> (filter by agent/owner)
- FORMAT=ascii|markdown|json|csv (default: ascii)
- METRIC=cycle-time|lead-time|throughput|all (default: all)
DATA SOURCES
### Primary Sources
1. **docs/09-agents/bus/log.jsonl** - Event stream with timestamps
- Story lifecycle events (created, status changes, completed)
- Timestamps for all state transitions
- Agent assignments and handoffs
2. **docs/09-agents/status.json** - Current state
- Active stories and their statuses
- Owner assignments
- Last updated timestamps
3. **docs/06-stories/**/US-*.md** - Story metadata
- Creation dates (from frontmatter or file mtime)
- Estimates vs actuals
- Epic relationships
4. **docs/05-epics/*.md** - Epic data
- Epic start/end dates
- Story rollup
CORE METRICS
### 1. Cycle Time
**Definition**: Time from "in-progress" to "done" (actual work time)
```bash
# Extract from bus/log.jsonl
for story in stories; do
start=$(jq -r 'select(.story=="'$story'" and .status=="in-progress") | .ts' bus/log.jsonl | head -1)
end=$(jq -r 'select(.story=="'$story'" and .status=="done") | .ts' bus/log.jsonl | head -1)
cycle_time=$(date_diff $start $end)
echo "$story: $cycle_time days"
done
# Calculate statistics
avg_cycle_time=$(echo "$cycle_times" | awk '{sum+=$1; count++} END {print sum/count}')
p50_cycle_time=$(echo "$cycle_times" | sort -n | awk '{a[NR]=$1} END {print a[int(NR/2)]}')
p85_cycle_time=$(echo "$cycle_times" | sort -n | awk '{a[NR]=$1} END {print a[int(NR*0.85)]}')
```
**Output**:
```
Cycle Time (30 days)
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Average: 3.2 days
Median: 2.5 days
85th %ile: 5.0 days
Min: 0.5 days
Max: 8.0 days
Distribution:
0-1 days ████████░░ 8 stories (32%)
1-3 days ████████████████░░ 12 stories (48%)
3-5 days ████░░ 3 stories (12%)
5+ days ██░░ 2 stories (8%)
```
### 2. Lead Time
**Definition**: Time from story creation to "done" (total time including waiting)
```bash
for story in stories; do
created=$(stat -f %B docs/06-stories/*/$story.md 2>/dev/null || stat -c %Y docs/06-stories/*/$story.md)
completed=$(jq -r 'select(.story=="'$story'" and .status=="done") | .ts' bus/log.jsonl | tail -1)
lead_time=$(date_diff $created $completed)
echo "$story: $lead_time days"
done
```
**Output**:
```
Lead Time (30 days)
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Average: 7.8 days
Median: 6.0 days
85th %ile: 12.0 days
Breakdown:
Waiting (ready): 2.5 days (32%)
Active (in-progress): 3.2 days (41%)
Review (in-review): 2.1 days (27%)
```
### 3. Throughput
**Definition**: Stories completed per time period
```bash
# Count stories completed in each week
for week in weeks; do
count=$(jq -r 'select(.status=="done" and .ts >= "'$week_start'" and .ts < "'$week_end'") | .story' bus/log.jsonl | sort -u | wc -l)
echo "Week $week: $count stories"
done
```
**Output**:
```
Throughput (Last 8 Weeks)
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Week 1 ████████░░ 8 stories
Week 2 ██████████░░ 10 stories
Week 3 ██████░░ 6 stories
Week 4 ████████████░░ 12 stories ← Peak
Week 5 ████████░░ 8 stories
Week 6 ██████░░ 6 stories
Week 7 ██████████░░ 10 stories
Week 8 ████████░░ 8 stories
Average: 8.5 stories/week
Trend: ↗ +12% vs previous month
```
### 4. Work In Progress (WIP)
**Definition**: Stories currently in-progress or in-review
```bash
wip_count=$(jq -r '.stories | to_entries[] | select(.value.status == "in-progress" or .value.status == "in-review") | .key' status.json | wc -l)
wip_limit=6 # 2 per agent * 3 agents
echo "Current WIP: $wip_count / $wip_limit"
if [ $wip_count -gt $wip_limit ]; then
echo "⚠️ WIP limit exceeded! Consider finishing stories before starting new ones."
fi
```
**Output**:
```
Work In Progress
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Current WIP: 4 / 6 stories (67% capacity)
Status: ✅ Within limits
Breakdown:
in-progress: 3 stories
in-review: 1 story
blocked: 0 stories
By Owner:
AG-API: 2 stories (at limit)
AG-UI: 1 story
AG-CI: 1 story
```
### 5. Agent Utilization
**Definition**: Distribution of work across agents
```bash
for agent in AG-UI AG-API AG-CI AG-DEVOPS; do
completed=$(jq -r 'select(.status=="done" and .owner=="'$agent'") | .story' bus/log.jsonl | sort -u | wc -l)
in_progress=$(jq -r '.stories | to_entries[] | select(.value.owner=="'$agent'" and .value.status=="in-progress") | .key' status.json | wc -l)
echo "$agent: $completed done, $in_progress active"
done
```
**Output**:
```
Agent Utilization (30 days)
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
AG-API ████████████████░░ 12 stories (40%) 2 active
AG-UI ████████████░░ 10 stories (33%) 1 active
AG-CI ██████░░ 6 stories (20%) 1 active
AG-DEVOPS ██░░ 2 stories (7%) 0 active
Balance Score: 78/100 (Good distribution)
Recommendation: Consider assigning more work to AG-DEVOPS
```
### 6. Epic Health
**Definition**: Progress and health indicators for epics
```bash
for epic in epics; do
total_stories=$(ls docs/06-stories/$epic/*.md | wc -l)
done_stories=$(jq -r 'select(.epic=="'$epic'" and .status=="done")' bus/log.jsonl | wc -l)
blocked_stories=$(jq -r '.stories | to_entries[] | select(.value.epic=="'$epic'" and .value.status=="blocked") | .key' status.json | wc -l)
completion_pct=$((done_stories * 100 / total_stories))
health="🟢" # Green
[ $blocked_stories -gt 0 ] && health="🟡" # Yellow
[ $completion_pct -lt 30 ] && [ $blocked_stories -gt 1 ] && health="🔴" # Red
echo "$epic: $completion_pct% complete, $blocked_stories blocked $health"
done
```
**Output**:
```
Epic Health
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
EP-0010: Authentication
Progress: ████████████████████░░ 85% (11/13 stories)
Status: 🟢 On track
Velocity: 2.5 stories/week
ETA: ~1 week
EP-0011: Payment Processing
Progress: ████████░░ 40% (4/10 stories)
Status: 🟡 At risk (2 blocked)
Velocity: 1.2 stories/week
ETA: ~5 weeks
⚠️ Action: Unblock US-0045, US-0048
EP-0012: User Dashboard
Progress: ██░░ 10% (1/10 stories)
Status: 🟢 Healthy
Velocity: 0.5 stories/week (just started)
ETA: ~18 weeks
```
ADVANCED METRICS
### 7. Estimation Accuracy
**Definition**: Compare estimates vs actual cycle time
```bash
for story in completed_stories; do
estimate=$(grep "^estimate:" docs/06-stories/*/$story.md | awk '{print $2}' | sed 's/d//')
actual=$(calculate_cycle_time $story)
variance=$((actual - estimate))
echo "$story: Est $estimate, Act $actual, Var $variance"
done
avg_variance=$(echo "$variances" | awk '{sum+=$1; count++} END {print sum/count}')
```
**Output**:
```
Estimation Accuracy
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Average Variance: +0.5 days (underestimating by 15%)
Distribution:
Under-estimated ████████████░░ 12 stories (48%)
Accurate (±20%) ████████░░ 8 stories (32%)
Over-estimated ████░░ 5 stories (20%)
Worst Offenders:
US-0042: Est 2d, Act 5d (+150%)
US-0035: Est 1d, Act 3d (+200%)
Best Estimates:
US-0038: Est 3d, Act 3d (0%)
US-0040: Est 2d, Act 2d (0%)
Recommendation: Increase estimates by ~20% for accuracy
```
### 8. Blocked Story Analysis
**Definition**: Identify blocking patterns
```bash
blocked_stories=$(jq -r '.stories | to_entries[] | select(.value.status=="blocked")' status.json)
for story in blocked_stories; do
blocked_duration=$(date_diff $(get_blocked_timestamp $story) $(date +%s))
echo "$story: Blocked for $blocked_duration days"
done
```
**Output**:
```
Blocked Story Analysis
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Currently Blocked: 2 stories
US-0045: Payment gateway integration
Blocked: 5 days
Reason: Waiting for API keys
Owner: AG-API
Impact: Blocks EP-0011 (40% complete)
Action: Escalate to product for API access
US-0048: Stripe webhook setup
Blocked: 2 days
Reason: Depends on US-0045
Owner: AG-API
Impact: Delays payment epic by 1 week
Action: Can unblock after US-0045
⚠️ Critical: 2 stories blocked > 2 days. Review immediately.
```
### 9. Flow Efficiency
**Definition**: Active work time / total lead time
```bash
for story in stories; do
lead_time=$(calculate_lead_time $story)
cycle_time=$(calculate_cycle_time $story)
flow_efficiency=$((cycle_time * 100 / lead_time))
echo "$story: $flow_efficiency% efficiency"
done
avg_efficiency=$(echo "$efficiencies" | awk '{sum+=$1; count++} END {print sum/count}')
```
**Output**:
```
Flow Efficiency
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Average: 41% (3.2d active / 7.8d total)
Interpretation:
Stories spend 59% of time waiting (in 'ready' or 'in-review')
Only 41% of time is active work
Breakdown:
Ready → In-Progress: 2.5 days avg wait
In-Progress → Done: 3.2 days avg work
In-Review → Done: 2.1 days avg review
Recommendations:
🎯 Reduce "ready" wait time (start stories faster)
🎯 Reduce "in-review" time (faster code reviews)
Target: >60% flow efficiency
```
### 10. Cumulative Flow Diagram (CFD)
**Definition**: Stacked area chart showing story distribution over time
```bash
# Generate data for each day in timeframe
for day in $(seq 0 30); do
date=$(date -d "$day days ago" +%Y-%m-%d)
ready=$(count_stories_in_status_on_date "ready" $date)
in_progress=$(count_stories_in_status_on_date "in-progress" $date)
in_review=$(count_stories_in_status_on_date "in-review" $date)
done=$(count_stories_in_status_on_date "done" $date)
echo "$date $ready $in_progress $in_review $done"
done
```
**Output (ASCII visualization)**:
```
Cumulative Flow Diagram (Last 30 Days)
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
30 │ ████████████ Done
25 │ ████████████████████
20 │ ████████████████████████████
15 │ ████████████████████████████████████ In Review
10 │ ████████████████████████████████████████████ In Progress
5 │██████████████████████████████████████████████████ Ready
0 └────────────────────────────────────────────────→
Oct 17 Oct 24 Oct 31 Nov 7 Nov 14
Insights:
✅ Steady throughput (done stories increasing linearly)
⚠️ WIP creeping up (in-progress growing)
🎯 Review bottleneck (in-review staying constant)
```
DASHBOARD OUTPUT
### ASCII Dashboard (default)
```markdown
╔════════════════════════════════════════════════════════════════╗
║ AGILEFLOW METRICS DASHBOARD ║
║ Last 30 Days (Oct 17 - Nov 14) ║
╠════════════════════════════════════════════════════════════════╣
║ ║
║ 📊 KEY METRICS ║
║ ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ ║
║ ║
║ Cycle Time: 3.2 days avg (↓ 8% vs last month) ║
║ Lead Time: 7.8 days avg (↑ 5% vs last month) ║
║ Throughput: 8.5 stories/week (↗ +12%) ║
║ Flow Efficiency: 41% (Target: >60%) ║
║ ║
║ ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ ║
║ ║
║ 🎯 WORK IN PROGRESS ║
║ ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ ║
║ ║
║ Current WIP: 4 / 6 stories (67%) ✅ ║
║ Blocked: 2 stories ⚠️ ║
║ ║
║ AG-API: 2 stories (at limit) ║
║ AG-UI: 1 story ║
║ AG-CI: 1 story ║
║ AG-DEVOPS: 0 stories ║
║ ║
║ ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ ║
║ ║
║ 📈 EPIC HEALTH ║
║ ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ ║
║ ║
║ EP-0010 ████████████████████░░ 85% 🟢 On track ║
║ EP-0011 ████████░░ 40% 🟡 2 blocked ║
║ EP-0012 ██░░ 10% 🟢 Healthy ║
║ ║
║ ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ ║
║ ║
║ ⚡ RECOMMENDATIONS ║
║ ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ ║
║ ║
║ 1. Unblock US-0045, US-0048 (blocked >2 days) ║
║ 2. Reduce review time (currently 2.1 days avg) ║
║ 3. Assign more stories to AG-DEVOPS (0 active) ║
║ 4. Improve estimation accuracy (+15% variance) ║
║ ║
╚════════════════════════════════════════════════════════════════╝
Run `/AgileFlow:velocity` for forecasting
Run `/AgileFlow:board` for current kanban view
Run `/AgileFlow:retro` for retrospective insights
```
EXPORT FORMATS
### JSON Export
```json
{
"timeframe": "30d",
"generated_at": "2025-10-17T15:00:00Z",
"metrics": {
"cycle_time": {
"avg": 3.2,
"median": 2.5,
"p85": 5.0,
"unit": "days",
"change_pct": -8
},
"lead_time": {
"avg": 7.8,
"median": 6.0,
"p85": 12.0,
"unit": "days",
"change_pct": 5
},
"throughput": {
"avg": 8.5,
"unit": "stories/week",
"change_pct": 12,
"trend": "up"
},
"wip": {
"current": 4,
"limit": 6,
"pct": 67,
"blocked": 2
}
},
"epics": [...],
"recommendations": [...]
}
```
### CSV Export
```csv
Date,Cycle Time,Lead Time,Throughput,WIP,Blocked
2025-10-17,3.2,7.8,8.5,4,2
2025-10-16,3.1,7.5,8.2,5,1
...
```
USAGE EXAMPLES
### View all metrics for last 30 days
```bash
/AgileFlow:metrics
```
### Last 90 days, specific epic
```bash
/AgileFlow:metrics TIMEFRAME=90d EPIC=EP-0010
```
### Only cycle time, export as JSON
```bash
/AgileFlow:metrics METRIC=cycle-time FORMAT=json
```
### Agent-specific metrics
```bash
/AgileFlow:metrics OWNER=AG-API TIMEFRAME=7d
```
### Export to CSV for spreadsheet analysis
```bash
/AgileFlow:metrics FORMAT=csv > metrics.csv
```
INTEGRATION WITH OTHER COMMANDS
- After `/AgileFlow:velocity`: Run `/AgileFlow:metrics` to see detailed trends
- After `/AgileFlow:board`: Run `/AgileFlow:metrics` to understand bottlenecks
- Before `/AgileFlow:retro`: Run `/AgileFlow:metrics` to gather data for retrospective
- In `/AgileFlow:babysit`: Auto-run `/AgileFlow:metrics` when velocity drops
RULES
- Always calculate from raw data (bus/log.jsonl, status.json)
- Show trends (↗↘) compared to previous period
- Highlight actionable insights
- Use color coding (🟢🟡🔴) for health indicators
- Provide recommendations based on data
- Respect privacy (no individual developer metrics, only agent-level)
OUTPUT
- ASCII dashboard (default, shown above)
- Or JSON/CSV/Markdown based on FORMAT parameter
- Always include timeframe and generation timestamp
- Save to docs/08-project/metrics-reports/metrics-YYYYMMDD.md (optional)

820
commands/notion.md Normal file
View File

@@ -0,0 +1,820 @@
---
description: notion
allowed-tools: Bash, Read, Edit, Write, Glob, Grep
---
# notion
Export AgileFlow epics, stories, and ADRs to Notion with detailed summaries via Model Context Protocol (MCP).
**Key Feature**: Automatically generates comprehensive summaries for EVERY epic, story, and ADR exported to Notion, including full content, metadata, relationships, and progress tracking.
## Prompt
ROLE: Notion Integration Agent (MCP-based)
OBJECTIVE
Bidirectional sync between AgileFlow markdown docs and Notion databases using Model Context Protocol. **Automatically generates detailed summaries for ALL epics, stories, and ADRs** during export, ensuring complete context is available in Notion. Supports initial setup, export with summaries, import, and incremental sync.
**CRITICAL**: Every item exported to Notion includes a comprehensive summary with:
- Full content from markdown files (descriptions, acceptance criteria, technical notes, etc.)
- Metadata (status, dates, owners, estimates)
- Relationships (epic-story links, related ADRs)
- Progress tracking (for epics: story completion percentage)
This ensures Notion serves as a complete, searchable knowledge base for stakeholders and team members.
---
## PREREQUISITES
### 1. Notion Integration Token
**CRITICAL**: You need a Notion API token before using this command.
```bash
# Create integration at https://www.notion.so/my-integrations
# 1. Click "New integration"
# 2. Give it a name (e.g., "AgileFlow")
# 3. Copy the "Internal Integration Token" (starts with secret_)
# 4. Share your databases with this integration
```
### 2. Environment Setup
**CRITICAL**: Add your token to .env (gitignored, never commit):
```bash
# Add to .env file in project root
echo "NOTION_TOKEN=secret_your_token_here" >> .env
# Verify .env is in .gitignore
grep -q "^\.env$" .gitignore || echo ".env" >> .gitignore
```
### 3. MCP Server Configuration
**CRITICAL**: MCP config must be in PROJECT ROOT (.mcp.json):
```bash
# Check if MCP is configured
cat .mcp.json 2>/dev/null || echo "MCP not configured"
# If missing, run setup
/AgileFlow:setup-system
# Select "yes" for Notion integration
```
Your `.mcp.json` should contain:
```json
{
"mcpServers": {
"notion": {
"command": "npx",
"args": ["-y", "@notionhq/notion-mcp-server"],
"env": {
"NOTION_TOKEN": "${NOTION_TOKEN}"
}
}
}
}
```
**IMPORTANT**:
- .mcp.json must be in **project root** (not ~/.claude-code/ or ~/.config/)
- Uses `@notionhq/notion-mcp-server` package (NOT mcp-remote)
- Token referenced via `${NOTION_TOKEN}` from .env
- .mcp.json should be gitignored
- .mcp.json.example committed as template for teams
### 4. Restart Claude Code
**CRITICAL**: MCP servers only load on startup:
```bash
# After creating/updating .mcp.json, restart Claude Code
# Tools will be available as mcp__notion__* after restart
```
### 5. Database Setup (First Time Only)
Run this command with `MODE=setup` to create the three required databases:
```bash
/AgileFlow:notion MODE=setup
```
This will:
- Use MCP tools to create **AgileFlow Epics** database
- Create **AgileFlow Stories** database
- Create **AgileFlow ADRs** database
- Store database IDs in `docs/08-project/notion-sync-map.json`
---
## USAGE
```bash
# Initial setup (create databases)
/AgileFlow:notion MODE=setup
# Preview export without writing to Notion
# Shows detailed summaries that will be created for each item
/AgileFlow:notion DRY_RUN=true
# Export all docs to Notion WITH DETAILED SUMMARIES
# Automatically generates comprehensive summaries for ALL epics, stories, and ADRs
/AgileFlow:notion
# Export specific type only (with summaries)
/AgileFlow:notion TYPE=epics # Exports all epics with full content summaries
/AgileFlow:notion TYPE=stories # Exports all stories with AC, notes, testing strategy
/AgileFlow:notion TYPE=adrs # Exports all ADRs with context, decisions, consequences
# Import from Notion back to markdown
/AgileFlow:notion MODE=import
# Bidirectional sync (smart merge)
/AgileFlow:notion MODE=sync
# Force overwrite (export wins - includes updated summaries)
/AgileFlow:notion MODE=export FORCE=true
# Force overwrite (import wins)
/AgileFlow:notion MODE=import FORCE=true
```
**Note on Summaries**: Every export automatically includes detailed summaries. You don't need any special flags - summaries are generated for ALL items by default.
### Environment Variables
- `MODE`: `setup` | `export` | `import` | `sync` (default: export)
- `TYPE`: `epics` | `stories` | `adrs` | `all` (default: all)
- `DRY_RUN`: `true` | `false` (default: false) - Preview only
- `FORCE`: `true` | `false` (default: false) - Overwrite without merge
---
## MCP TOOLS REFERENCE
This command uses the following Notion MCP tools (via @notionhq/notion-mcp-server):
### Database Operations
- **mcp__notion__create_database** - Create AgileFlow databases during setup
- **mcp__notion__update_database** - Modify database properties
- **mcp__notion__query_database** - Read database structure and pages
### Page Management
- **mcp__notion__create_page** - Export stories/epics/ADRs to Notion
- **mcp__notion__update_page** - Sync changes back to existing pages
- **mcp__notion__retrieve_page** - Read page content for import
### Search & Retrieval
- **mcp__notion__search** - Find existing AgileFlow databases
- **mcp__notion__retrieve_block_children** - Read page content blocks
---
## ARCHITECTURE
### File Structure
```
docs/08-project/
├── notion-sync-map.json # Database IDs and sync state
└── notion-sync-log.jsonl # Audit trail (created on first sync)
```
### Sync Map Schema
```json
{
"last_sync": "2025-01-15T10:30:00Z",
"databases": {
"epics": "notion-database-id-1",
"stories": "notion-database-id-2",
"adrs": "notion-database-id-3"
},
"pages": {
"docs/05-epics/AG-001-authentication.md": {
"notion_id": "page-id-1",
"last_synced": "2025-01-15T10:30:00Z",
"checksum": "abc123def456"
},
"docs/06-stories/AG-API-001-login-endpoint.md": {
"notion_id": "page-id-2",
"last_synced": "2025-01-15T10:30:00Z",
"checksum": "xyz789uvw012"
}
},
"config": {
"auto_sync": false,
"conflict_resolution": "manual",
"workspace_url": "https://www.notion.so/your-workspace"
}
}
```
---
## IMPLEMENTATION
### Key Features
**1. Detailed Summary Generation**
For EVERY epic, story, and ADR exported to Notion, the command automatically generates a comprehensive summary that includes:
**Epics**:
- Epic ID and title
- Description (full text)
- Goals and objectives
- All linked stories with their status
- Progress percentage (completed vs total stories)
- Key dates (created, updated)
- Dependencies
- Related ADRs
**Stories**:
- Story ID and title
- Epic parent (linked)
- Description and acceptance criteria (full text)
- Status, priority, estimate
- Owner/assignee
- Technical notes
- Testing strategy
- All files modified (from implementation)
- Dependencies
- Created/updated dates
**ADRs (Architecture Decision Records)**:
- ADR ID and title
- Status (proposed, accepted, superseded)
- Context (why this decision was needed)
- Decision (what was decided)
- Consequences (positive and negative)
- Alternatives considered
- Related epics/stories
- Created/updated dates
**Why Detailed Summaries?**
- Notion pages are searchable - full content makes finding information easier
- Team members can review details without switching to markdown files
- Stakeholders can read complete context in Notion
- Better integration with Notion's AI features (Q&A, summarization)
- Preserves all critical information even if markdown files are updated
**How It Works**:
1. Command reads each markdown file (epic/story/ADR)
2. Extracts frontmatter metadata (YAML)
3. Parses markdown content sections
4. Builds comprehensive summary with all relevant details
5. Creates/updates Notion page with summary as page content
6. Links related items (epic ↔ stories, ADR ↔ epics)
### Export Process
```bash
# For each file type (epics, stories, ADRs):
# 1. Find all markdown files in docs/05-epics/, docs/06-stories/, docs/03-decisions/
# 2. Read file content and parse frontmatter
# 3. Extract all sections (Description, AC, Technical Notes, etc.)
# 4. Generate detailed summary with full content
# 5. Check if page exists in Notion (via sync map)
# 6. Create new page OR update existing page with summary
# 7. Update sync map with page ID and checksum
# 8. Link related items (epic-story relationships, etc.)
```
### Summary Format Example
**Epic Summary in Notion**:
```
📋 Epic: EP-0001 - User Authentication System
Status: In Progress (3/5 stories completed)
Created: 2025-01-15
Updated: 2025-01-20
## Description
[Full description from markdown file]
## Goals
- Enable secure user login
- Support password reset
- Implement session management
## Stories (5 total, 3 completed)
✅ US-0001: User Login API
✅ US-0002: Password Reset Flow
✅ US-0003: Session Token Management
🔄 US-0004: OAuth Integration
📝 US-0005: Multi-Factor Authentication
## Dependencies
- Depends on: None
- Blocks: EP-0002 (User Profile Management)
## Related ADRs
- ADR-0001: JWT vs Session-based Auth (Accepted)
- ADR-0002: Password Hashing Strategy (Accepted)
```
### Implementation Details
The command uses MCP tools to interact with Notion:
**Setup Phase** (MODE=setup):
- Use `mcp__notion__create_database` to create three databases
- Store database IDs in `docs/08-project/notion-sync-map.json`
**Export Phase** (default):
- Use `mcp__notion__query_database` to find existing pages
- Use `mcp__notion__create_page` for new items with full summary
- Use `mcp__notion__update_page` for existing items with updated summary
- All summaries include complete content from markdown files
**Import Phase** (MODE=import):
- Use `mcp__notion__retrieve_page` to read Notion page content
- Parse Notion blocks back to markdown format
- Update local markdown files with changes
**Sync Phase** (MODE=sync):
- Compare checksums between local and Notion
- Detect conflicts (both changed since last sync)
- Offer merge strategies or manual resolution
### Parallel Execution Architecture
**🚀 NEW: Parallel Export with Specialized Agents**
The `/AgileFlow:notion` command now uses parallel agent execution for significantly faster exports:
**How It Works**:
1. **Scan Phase**: Main command scans `docs/` for all epics, stories, and ADRs
2. **Spawn Phase**: Spawns one `agileflow-notion-exporter` agent per item
3. **Parallel Execution**: All agents run simultaneously (haiku model for speed)
4. **Collection Phase**: Collect results from all agents
5. **Sync Map Update**: Update `notion-sync-map.json` with all page IDs
**Performance**:
- **Sequential (old)**: ~2-3 seconds per item = 100 items in 3-5 minutes
- **Parallel (new)**: All items processed simultaneously = 100 items in 10-30 seconds
**Batching for Rate Limits**:
- Notion API has rate limits (~3 requests/second)
- Command batches agents in groups of 10
- Batch 1: Items 1-10 (spawn, wait for completion)
- Batch 2: Items 11-20 (spawn, wait for completion)
- etc.
**Agent Specification**:
- **Agent**: `agileflow-notion-exporter`
- **Model**: haiku (fast for summarization)
- **Tools**: Read, Bash (+ MCP tools automatically available)
- **Input**: item_path, item_type, database_id, dry_run flag
- **Output**: JSON with page_id, status, checksum
**Error Handling**:
- If agent fails: Logged and reported, other agents continue
- After all batches complete: Report failed items for retry
- Partial success: Update sync map for successful items only
**Progress Tracking**:
```
📤 Exporting to Notion...
Batch 1/5 (items 1-10):
✅ EP-0001-authentication.md → Notion
✅ EP-0002-authorization.md → Notion
...
Batch 1 complete: 10/10 successful
Batch 2/5 (items 11-20):
✅ US-0001-login-api.md → Notion
❌ US-0002-logout-api.md → Error: Rate limit
...
Batch 2 complete: 9/10 successful
...
📊 Export Summary:
✅ Successful: 48/50 items
❌ Failed: 2/50 items
⏱️ Time: 25 seconds
```
**DRY_RUN with Parallel Agents**:
- Each agent generates summary but doesn't export
- Shows what WOULD be created in Notion
- Validates file parsing and summary generation
- No API calls made (fast preview)
**Example Orchestration Flow**:
```bash
# Main command execution
/AgileFlow:notion
# 1. Scan docs/ for all items
Found 50 items: 10 epics, 35 stories, 5 ADRs
# 2. Load database IDs from sync map
Epics DB: abc123
Stories DB: def456
ADRs DB: ghi789
# 3. Spawn agents in batches of 10
Spawning batch 1 (10 agents)...
→ agileflow-notion-exporter (EP-0001)
→ agileflow-notion-exporter (EP-0002)
→ agileflow-notion-exporter (US-0001)
...
# 4. Wait for batch completion
Batch 1: 10/10 complete (8 seconds)
# 5. Spawn next batch
Spawning batch 2 (10 agents)...
...
# 6. Collect all results
Collected 50 results: 48 success, 2 failed
# 7. Update sync map
Updated notion-sync-map.json with 48 page IDs
# 8. Report summary
✅ Export complete: 48/50 items (96% success rate)
```
---
## EXAMPLE WORKFLOWS
### First-Time Setup
```bash
# 1. Create Notion integration
# Visit https://www.notion.so/my-integrations
# Create new integration, copy token
# 2. Add token to .env
echo "NOTION_TOKEN=secret_your_token_here" >> .env
# 3. Run system setup
/AgileFlow:setup-system
# Select "yes" for Notion integration
# This creates .mcp.json.example and copies to .mcp.json
# 4. Restart Claude Code
# MCP server loads on startup
# 5. Create databases
/AgileFlow:notion MODE=setup
# 6. Share databases with integration
# In Notion: Click "..." → "Add connections" → Select your integration
# 7. Preview export
/AgileFlow:notion DRY_RUN=true
# 8. Perform initial export
/AgileFlow:notion
# 9. Visit Notion to verify
# Open https://notion.so/your-workspace
```
### Daily Workflow
```bash
# Export new/changed docs to Notion
/AgileFlow:notion
# Or just export stories
/AgileFlow:notion TYPE=stories
# Import changes from Notion (team members edited in Notion)
/AgileFlow:notion MODE=import
# Bidirectional sync (smart merge)
/AgileFlow:notion MODE=sync
```
### Team Member Onboarding
```bash
# 1. Pull latest code (includes .mcp.json.example)
git pull
# 2. Create their own Notion integration
# Visit https://www.notion.so/my-integrations
# 3. Copy template to active config
cp .mcp.json.example .mcp.json
# 4. Add their token to .env
echo "NOTION_TOKEN=secret_their_token_here" >> .env
# 5. Restart Claude Code
# 6. Share databases with their integration
# In Notion: Click "..." → "Add connections" → Select their integration
# 7. Start syncing!
/AgileFlow:notion
```
### Conflict Resolution
```bash
# Check for conflicts first
/AgileFlow:notion MODE=sync DRY_RUN=true
# Manual conflict resolution (default)
# Script will list conflicts and prompt for each
# Or force local version to win
/AgileFlow:notion MODE=export FORCE=true
# Or force Notion version to win
/AgileFlow:notion MODE=import FORCE=true
```
---
## ADVANTAGES OF MCP APPROACH
### 🚀 Developer Experience
- ✅ **Standardized tool interface** - MCP provides unified API across services
- ✅ **Better error handling** - Improved over raw Notion API calls
- ✅ **Automatic rate limiting** - MCP handles throttling
- ✅ **Native Claude Code integration** - Tools available as mcp__notion__*
### 👥 Team Collaboration
- ✅ **Template-based setup** - .mcp.json.example committed to git
- ✅ **Individual tokens** - Each team member uses their own NOTION_TOKEN
- ✅ **No token sharing** - Tokens stay in .env (gitignored)
- ✅ **Consistent setup** - Same .mcp.json template for everyone
### 🔒 Security
- ✅ **Tokens in .env** - Gitignored, never committed
- ✅ **Project-level config** - .mcp.json in repo root (not user-level)
- ✅ **Easy revocation** - Just delete token from Notion integrations page
### 🛠️ Maintenance
- ✅ **Standard protocol** - MCP is consistent across tools
- ✅ **Better debugging** - Clearer error messages from MCP tools
- ✅ **No API version pinning** - MCP package handles compatibility
### ⚡ Parallel Execution (NEW in v2.19.3)
- ✅ **10-30x faster exports** - Process 100 items in 10-30 seconds instead of 3-5 minutes
- ✅ **Parallel agent architecture** - One `agileflow-notion-exporter` agent per item
- ✅ **Haiku model for speed** - Fast summarization without sacrificing quality
- ✅ **Batched rate limiting** - Respects Notion API limits with automatic batching
- ✅ **Resilient error handling** - Failed items don't block successful exports
- ✅ **Detailed progress tracking** - See real-time batch completion status
- ✅ **Scalable architecture** - Handles 10 items or 1000 items efficiently
---
## MIGRATION FROM DIRECT API APPROACH
If you previously used direct Notion API calls (curl-based):
### Step 1: Backup
```bash
# Backup your sync map (database IDs are preserved!)
cp docs/08-project/notion-sync-map.json docs/08-project/notion-sync-map.json.backup
```
### Step 2: Set Up MCP
```bash
# Your NOTION_TOKEN can stay in .env (no change needed!)
# Run setup to create .mcp.json
/AgileFlow:setup-system
# Select "yes" for Notion integration
# This creates .mcp.json with:
# {
# "mcpServers": {
# "notion": {
# "command": "npx",
# "args": ["-y", "@notionhq/notion-mcp-server"],
# "env": {
# "NOTION_TOKEN": "${NOTION_TOKEN}"
# }
# }
# }
# }
```
### Step 3: Restart Claude Code
```bash
# MCP servers only load on startup
# Restart Claude Code to load @notionhq/notion-mcp-server
```
### Step 4: Verify and Resume
```bash
# Your existing database IDs work with MCP!
# No need to recreate databases
# Verify connection
/AgileFlow:notion DRY_RUN=true
# Resume syncing
/AgileFlow:notion
```
---
## TROUBLESHOOTING
### MCP Server Not Configured
**Error**: "notion MCP server not found" or "mcp__notion__* tools not available"
**Fix**:
```bash
# Run setup
/AgileFlow:setup-system
# Or manually create .mcp.json in project root:
cat > .mcp.json <<'EOF'
{
"mcpServers": {
"notion": {
"command": "npx",
"args": ["-y", "@notionhq/notion-mcp-server"],
"env": {
"NOTION_TOKEN": "${NOTION_TOKEN}"
}
}
}
}
EOF
# CRITICAL: Restart Claude Code after creating .mcp.json
```
### Token Not Found
**Error**: "NOTION_TOKEN not set" or "Unauthorized"
**Fix**:
```bash
# Add token to .env in project root
echo "NOTION_TOKEN=secret_your_token_here" >> .env
# Verify it's there
grep NOTION_TOKEN .env
# Restart Claude Code
```
### Wrong MCP Package
**Error**: "mcp-remote not found" or connection errors
**Fix**:
```bash
# Check .mcp.json uses correct package
cat .mcp.json
# Should say "@notionhq/notion-mcp-server"
# NOT "mcp-remote"
# If wrong, update .mcp.json and restart Claude Code
```
### Project-Level Config Not Working
**Error**: MCP config not loading
**Fix**:
```bash
# CRITICAL: .mcp.json must be in PROJECT ROOT
pwd # Should show /path/to/your/project
ls -la .mcp.json # Should exist in current directory
# NOT in ~/.claude-code/ or ~/.config/claude-code/
# Those locations won't work for project-specific MCP servers
```
### Databases Not Found
**Error**: "Database IDs missing in sync map"
**Fix**:
```bash
/AgileFlow:notion MODE=setup
```
### Rate Limiting
**Error**: "Rate limit exceeded"
**Fix**: MCP handles this automatically with exponential backoff. Wait a few seconds and retry.
### Sync Conflicts
**Error**: "Conflict detected: both local and Notion changed"
**Fix**:
```bash
# Review conflict details
/AgileFlow:notion MODE=sync DRY_RUN=true
# Choose resolution strategy
/AgileFlow:notion MODE=sync # Manual prompts
# or
/AgileFlow:notion MODE=export FORCE=true # Local wins
# or
/AgileFlow:notion MODE=import FORCE=true # Notion wins
```
### Database Not Shared With Integration
**Error**: "object not found" or "insufficient permissions"
**Fix**:
```bash
# In Notion, for each database:
# 1. Click "..." (three dots) in top right
# 2. Click "Add connections"
# 3. Select your integration name
# 4. Try sync again
```
---
## FUTURE ENHANCEMENTS
- [ ] Auto-sync on file changes (watch mode)
- [ ] Conflict resolution UI in Claude Code
- [ ] Comment syncing (mcp__notion__create_comment)
- [ ] Attachment support
- [ ] Webhook integration (Notion → AgileFlow)
- [ ] Multi-workspace support
- [ ] Custom property mappings
- [ ] Rollback support (restore from log)
---
## RELATED COMMANDS
- `/AgileFlow:setup-system` - Initial AgileFlow + MCP configuration
- `/AgileFlow:github-sync` - Sync with GitHub Issues (uses GitHub CLI)
- `/AgileFlow:story-new` - Create new story (auto-exports if Notion enabled)
- `/AgileFlow:epic-new` - Create new epic (auto-exports if Notion enabled)
- `/AgileFlow:adr-new` - Create new ADR (auto-exports if Notion enabled)
- `/AgileFlow:board` - Visualize status (can pull from Notion)
## RELATED AGENTS
- `agileflow-notion-exporter` - Parallel export agent (spawned by this command)
- Haiku model for fast summarization
- Processes one epic/story/ADR at a time
- Generates detailed summaries with full content
- Uses MCP tools to export to Notion
- Returns JSON with page ID and status
---
## REFERENCES
- [@notionhq/notion-mcp-server](https://www.npmjs.com/package/@notionhq/notion-mcp-server) - Notion MCP Package
- [MCP Documentation](https://modelcontextprotocol.io/docs/getting-started/intro) - Model Context Protocol
- [MCP Supported Tools](https://developers.notion.com/docs/mcp-supported-tools) - Notion MCP Tools List
- [Claude Code MCP Guide](https://docs.claude.com/en/docs/claude-code/mcp) - MCP in Claude Code
- [Notion API Reference](https://developers.notion.com/reference/intro) - Notion API Docs
- [Create Notion Integration](https://www.notion.so/my-integrations) - Get Your Token
---
## KEY LEARNINGS (Historical: v2.3.0 Correction)
**Note**: This section documents a correction made during the v2.3.0 release (October 2025). It is preserved for historical context. See [CHANGELOG.md](../../CHANGELOG.md#230---2025-10-18) for full details.
**What We Got Wrong Initially**:
- ❌ Claimed OAuth authentication via /mcp command
- ❌ Said "no manual token management"
- ❌ Used wrong package (mcp-remote instead of @notionhq/notion-mcp-server)
- ❌ Suggested committing .mcp.json to git (should be gitignored)
**What's Actually Correct**:
- ✅ Still uses NOTION_TOKEN in .env (token-based)
- ✅ Uses @notionhq/notion-mcp-server package
- ✅ Project-level .mcp.json in repo root (not user-level)
- ✅ .mcp.json gitignored, .mcp.json.example committed as template
- ✅ MCP provides standardized tool interface, NOT authentication
- ✅ Each team member needs their own token
**Credit**: Thank you to the user who discovered the correct approach through testing!

354
commands/packages.md Normal file
View File

@@ -0,0 +1,354 @@
---
description: packages
allowed-tools: Bash, Read, Edit, Write, Glob, Grep
---
# packages
Manage project package dependencies (npm, pip, cargo, etc.) with dashboard, updates, and security audits.
## Prompt
ROLE: Package Dependency Manager
INPUTS (optional)
- ACTION=dashboard|update|audit (default: dashboard)
- SCOPE=all|security|major|minor|patch (for ACTION=update, default: all)
- OUTPUT=markdown|html|json|csv (for ACTION=dashboard, default: markdown)
- INCLUDE_DEV=yes|no (default: yes)
- SAVE_TO=<path> (default: docs/08-project/dependencies-dashboard.md)
- AUTO_PR=yes|no (for ACTION=update, default: no, ask first)
---
## ACTION=dashboard (default)
Generate comprehensive dashboard of all project dependencies.
### Detection
Scan for dependency manifests:
- **Node.js**: package.json, package-lock.json
- **Python**: requirements.txt, Pipfile, pyproject.toml
- **Ruby**: Gemfile, Gemfile.lock
- **Go**: go.mod, go.sum
- **Rust**: Cargo.toml, Cargo.lock
- **Java**: pom.xml, build.gradle
- **.NET**: *.csproj, packages.config
- **PHP**: composer.json
### Analysis
For each dependency, collect:
1. **Name**: Package name
2. **Current Version**: Installed version
3. **Latest Version**: Most recent available
4. **Type**: Production / Development / Peer
5. **Status**: Up-to-date / Minor update / Major update / Deprecated
6. **Vulnerabilities**: Known CVEs
7. **License**: Software license
8. **Last Updated**: When dependency was last updated upstream
9. **Dependents**: How many project files import it
### Data Sources
- `npm outdated`, `pip list --outdated`, etc.
- `npm audit`, `pip-audit`, etc.
- Registry APIs (npmjs.com, pypi.org, crates.io, etc.)
- License scanners
- Import/usage analysis (grep)
### Dashboard Format (Markdown)
```markdown
# Dependencies Dashboard
**Project**: <name>
**Generated**: 2025-10-25 10:00:00 UTC
**Total Dependencies**: 145 (prod: 98, dev: 47)
---
## Summary
| Category | Count | Action Needed |
|----------|-------|---------------|
| 🔴 Critical Vulnerabilities | 2 | Update immediately |
| 🟠 Major Updates | 12 | Review breaking changes |
| 🟡 Minor Updates | 28 | Safe to update |
| 🟢 Up-to-date | 85 | No action |
| ⚪ Deprecated | 3 | Find alternatives |
---
## Critical Vulnerabilities 🔴
### express@4.16.0
**Current**: 4.16.0 → **Latest**: 4.18.2 (+2 major)
**Severity**: HIGH (CVSS 7.5)
**CVE**: CVE-2022-24999
**Description**: ReDoS vulnerability in Express.js routing
**Fix**: `npm install express@4.18.2`
**Affected**: 3 files import this
**License**: MIT
---
[Additional sections: Deprecated Packages, Major Updates, Minor/Patch Updates, License Compliance, Size Analysis, etc.]
---
## Maintenance Score: 78/100
**Breakdown**:
- Security: 60/100 (2 critical vulnerabilities)
- Freshness: 80/100 (most deps recent)
- License compliance: 95/100 (2 GPL warnings)
- Bundle size: 75/100 (some optimization possible)
**Recommendation**: Address security issues immediately, then plan regular maintenance.
```
### Visualization (HTML Output)
If OUTPUT=html, generate interactive dashboard with:
- Color-coded status badges
- Sortable/filterable tables
- Dependency graph visualization (D3.js or Mermaid)
- Click to expand details
- Quick action buttons ("Update", "Learn more")
### JSON Output
If OUTPUT=json, provide structured data for tooling:
```json
{
"generated": "2025-10-25T10:00:00Z",
"project": "my-app",
"summary": {
"total": 145,
"production": 98,
"development": 47,
"critical": 2,
"major_updates": 12,
"minor_updates": 28,
"up_to_date": 85,
"deprecated": 3
},
"vulnerabilities": [...],
"outdated": [...],
"deprecated": [...],
"licenses": {...}
}
```
---
## ACTION=update
Automatically update project dependencies with security audit.
### Detection & Analysis
1. Detect package manager(s):
- Node.js: package.json, package-lock.json, yarn.lock, pnpm-lock.yaml
- Python: requirements.txt, Pipfile, pyproject.toml, poetry.lock
- Ruby: Gemfile, Gemfile.lock
- Go: go.mod, go.sum
- Rust: Cargo.toml, Cargo.lock
- Java: pom.xml, build.gradle
- .NET: *.csproj, packages.config
2. Run appropriate outdated check:
- npm outdated --json
- pip list --outdated --format=json
- bundle outdated --parseable
- go list -u -m all
- cargo outdated --format json
- mvn versions:display-dependency-updates
3. Security audit:
- npm audit --json
- pip-audit --format json
- bundle audit
- cargo audit --json
- snyk test (if available)
### Categorization
Group updates by SCOPE:
- **security**: Security vulnerabilities (CVE)
- **major**: Breaking changes (1.x → 2.x)
- **minor**: New features (1.2.x → 1.3.x)
- **patch**: Bug fixes (1.2.3 → 1.2.4)
- **all**: All of the above
### Output Report
```markdown
# Dependency Update Report
**Generated**: <ISO timestamp>
**Project**: <name from manifest>
**Package Manager**: <detected>
**Scope**: <SCOPE parameter>
## Critical Security Updates
| Package | Current | Latest | Severity | CVE |
|---------|---------|--------|----------|-----|
| express | 4.16.0 | 4.18.2 | High | CVE-2022-24999 |
## Major Updates (Breaking Changes)
| Package | Current | Latest | Changelog |
|---------|---------|--------|-----------|
| react | 17.0.2 | 18.2.0 | [link] |
## Minor Updates (New Features)
| Package | Current | Latest | Changelog |
|---------|---------|--------|-----------|
| lodash | 4.17.19 | 4.17.21 | [link] |
## Patch Updates (Bug Fixes)
| Package | Current | Latest |
|---------|---------|--------|
| uuid | 8.3.0 | 8.3.2 |
```
### Actions (after user review)
1. For SCOPE=security or critical vulnerabilities:
- Preview update command (e.g., npm update <package>)
- Ask: "Apply security updates? (YES/NO)"
2. For major updates:
- Suggest creating individual stories per major update (may require code changes)
- Format: "US-XXXX: Upgrade <package> from <old> to <new>"
3. For minor/patch:
- Offer bulk update: "Apply all minor/patch updates? (YES/NO)"
4. If AUTO_PR=yes and approved:
- Create feature branch: deps/<date>-<scope>
- Run update commands
- Run tests (if available)
- Commit with message: "chore(deps): update dependencies (<scope>)"
- Push and create PR using /AgileFlow:pr-template
### Integration
- Save report to docs/08-project/dependency-report-<YYYYMMDD>.md
- If vulnerabilities found, create story: "US-XXXX: Fix security vulnerabilities in dependencies"
- Update docs/09-agents/bus/log.jsonl with "dependency-check" event
### Schedule Suggestion
Recommend adding to CI:
```yaml
- cron: '0 0 * * 1' # Weekly on Monday
```
---
## ACTION=audit
Run security audit only (no updates).
### Process
1. Detect package manager
2. Run security audit:
- `npm audit --json`
- `pip-audit --format json`
- `bundle audit`
- `cargo audit --json`
- `snyk test` (if available)
3. Report findings with severity levels
4. Suggest fixes (but don't apply)
5. Optional: Create story for security fixes
### Output
```markdown
# Security Audit Report
**Generated**: 2025-10-25 10:00:00 UTC
**Package Manager**: npm
## Critical (2)
- express@4.16.0: CVE-2022-24999 (CVSS 7.5)
- lodash@4.17.19: CVE-2021-23337 (CVSS 7.4)
## High (0)
None
## Moderate (3)
[...]
**Recommendation**: Run /AgileFlow:packages ACTION=update SCOPE=security
```
---
## Usage Examples
```bash
# Show dependency dashboard (default)
/AgileFlow:packages
/AgileFlow:packages ACTION=dashboard
# Export dashboard as HTML
/AgileFlow:packages ACTION=dashboard OUTPUT=html
# Export as JSON for tooling
/AgileFlow:packages ACTION=dashboard OUTPUT=json > deps.json
# Security audit only
/AgileFlow:packages ACTION=audit
# Update security vulnerabilities
/AgileFlow:packages ACTION=update SCOPE=security
# Update all minor and patch versions
/AgileFlow:packages ACTION=update SCOPE=minor
# Update all with auto-PR
/AgileFlow:packages ACTION=update SCOPE=all AUTO_PR=yes
# Update only production dependencies
/AgileFlow:packages ACTION=update INCLUDE_DEV=no
```
---
## CI Integration
Suggest adding automated checks:
```yaml
- name: Dependency audit
run: npm audit --audit-level=high
- name: Check outdated
run: npm outdated || true # Don't fail, just warn
- name: Generate dashboard
run: npx claude-code /AgileFlow:packages ACTION=dashboard
```
Suggest Dependabot config (.github/dependabot.yml):
```yaml
version: 2
updates:
- package-ecosystem: "npm"
directory: "/"
schedule:
interval: "weekly"
open-pull-requests-limit: 10
```
---
## Rules
- Prioritize security updates
- Group minor/patch updates when safe
- Warn about breaking changes (major updates)
- Never auto-update without approval
- Highlight deprecated packages prominently
- Consider bundle size impact
- Check license compatibility
- Never force-update without running tests
- Preview all commands before execution (require YES/NO)
- Link to changelogs and migration guides
---
## Output
Depending on ACTION:
- **dashboard**: Dependency dashboard (markdown/html/json/csv)
- **update**: Update report + optional PR with updates (if approved)
- **audit**: Security audit report with severity levels

23
commands/pr.md Normal file
View File

@@ -0,0 +1,23 @@
---
description: pr-template
allowed-tools: Bash, Read, Edit, Write, Glob, Grep
---
# pr-template
Generate a complete PR description from story and test evidence.
## Prompt
ROLE: PR Author
INPUTS
STORY=<US-ID> TITLE=<short>
AC_CHECKED=<checkbox list> TEST_EVIDENCE=<bullets/paths> NOTES=<optional>
ACTIONS
1) Read story file to pull epic/summary/deps.
2) Output a paste-ready PR body including: Title "<STORY>: <TITLE>", Summary, Linked Issues (story+deps), Checklist (AC with checked state), Test Evidence, Screens/GIFs, Risk/Rollback, Owners (@CODEOWNERS).
3) Suggest a Conventional Commit subject for squash.
No file writes.

168
commands/readme-sync.md Normal file
View File

@@ -0,0 +1,168 @@
---
description: Synchronize a folder's README.md with its current contents
allowed-tools: Task
---
# readme-sync
Synchronize a folder's README.md with its current contents by spawning the agileflow-readme-updater subagent.
## Prompt
**ROLE**: README Sync Command Handler
**OBJECTIVE**: Spawn the `agileflow-readme-updater` subagent to synchronize a folder's README.md with its current contents.
**WORKFLOW**:
1. **Extract folder path from user's message**:
- User might say: "sync docs/02-practices"
- Or: "/AgileFlow:readme-sync docs/04-architecture"
- Or: "update README for docs/06-stories"
2. **If folder path is clear**, spawn the subagent immediately:
```
Use the Task tool to spawn agileflow-readme-updater subagent:
Task(
description: "Sync README.md for [folder]",
prompt: "Audit and synchronize README.md for the folder: [folder_path]
Your task:
1. List all files and subdirectories in [folder_path]
2. Read the current README.md (if exists)
3. Extract descriptions from each file (first heading or sentence)
4. Build a new '## Contents' section with all files listed
5. Show the proposed changes (diff format)
6. Ask user to confirm: 'Update README.md? (YES/NO)'
7. If YES: Update only the '## Contents' section (preserve everything else)
8. Report what was changed",
subagent_type: "agileflow-readme-updater"
)
```
3. **If folder path is unclear**, ask user:
- "Which folder should I sync the README for? (e.g., docs/02-practices)"
- Then spawn the subagent with the provided folder
**EXAMPLE INVOCATIONS**:
User: "sync docs/02-practices"
→ Spawn agileflow-readme-updater with prompt: "Audit and synchronize README.md for docs/02-practices"
User: "update readme for docs/06-stories"
→ Spawn agileflow-readme-updater with prompt: "Audit and synchronize README.md for docs/06-stories"
User: "/AgileFlow:readme-sync"
→ Ask: "Which folder should I sync?"
→ User responds: "docs/04-architecture"
→ Spawn agileflow-readme-updater with that folder
**KEY POINTS**:
- This command is just a launcher - it spawns the subagent
- The subagent (agileflow-readme-updater) does the actual work
- Subagent has tools: Bash, Read, Edit, Write
- Subagent will handle all file discovery, diffing, and updating
## How It Works
### Step 1: List Folder Contents
```bash
ls -la FOLDER/ # All files + one sublevel
ls -1 FOLDER/*/ # Subdirectories and their contents
```
### Step 2: Extract Descriptions
For each file found:
- Read first heading (# Heading) from markdown files
- OR first sentence from file
- Extract 1-2 line summary
### Step 3: Build Contents Section
Generate markdown bullet list:
```markdown
## Contents
- **filename.md** – Brief description of what this file is
- **subfolder/** – Description of what's in this subfolder
- subfolder/file.md – Specific file description
```
### Step 4: Show Diff & Apply
- Display the proposed changes (diff format)
- Ask user: "Update README.md? (YES/NO)"
- If YES: Use Edit tool to update "## Contents" section
- If NO: Abort without changes
## Example Output
```
📁 Syncing docs/02-practices/README.md
=====================================
Found 7 files:
• README.md (existing)
• testing.md – Test strategy, patterns, test infrastructure
• git-branching.md – Git workflow, branching strategy, commit conventions
• ci.md – CI/CD pipeline configuration, testing gates
• security.md – Security practices, input validation, authentication
• releasing.md – Release procedures, versioning, changelog
• prompts/ (directory) – Agent customization prompts
Proposed Changes to ## Contents Section:
─────────────────────────────────────────
- testing.md – Test strategy, patterns, test infrastructure
- git-branching.md – Git workflow, branching strategy, commit conventions
- ci.md – CI/CD pipeline configuration, testing gates
- security.md – Security practices, input validation, authentication
- releasing.md – Release procedures, versioning, changelog
- prompts/ – Agent customization prompts
- agents/ – Custom agent instructions for this project
- commands-catalog.md – Reference list of slash commands
Update README.md with these changes? (YES/NO)
```
## When to Use
- After adding new files to a folder (keep README current)
- Before major releases (ensure docs match code)
- During documentation cleanup (quarterly maintenance)
- After reorganizing folder structure (update navigation)
- When README "Contents" section is out of date
## Usage Examples
```bash
# Sync docs/02-practices folder
/AgileFlow:readme-sync FOLDER=docs/02-practices
# Sync docs/04-architecture folder
/AgileFlow:readme-sync FOLDER=docs/04-architecture
# Sync src/components folder (if it has README)
/AgileFlow:readme-sync FOLDER=src/components
```
## What It Updates
Only the `## Contents` section of README.md:
- Removes old file listings
- Adds all current files with descriptions
- Maintains all other sections unchanged
- Preserves custom notes and links
## How to Sync Multiple Folders
Run the command for each folder one at a time, or create a script:
```bash
for folder in docs/0[0-9]-*; do
/AgileFlow:readme-sync FOLDER="$folder"
done
```
## Related Commands
- `/AgileFlow:doc-coverage` - Report on documentation completeness
- `/AgileFlow:impact-analysis` - See what changed
- `/AgileFlow:board` - View project status

18
commands/research.md Normal file
View File

@@ -0,0 +1,18 @@
---
description: research-init
allowed-tools: Bash, Read, Edit, Write, Glob, Grep
---
# research-init
Initialize or save research notes to the research folder.
## Prompt
ROLE: Research Initializer
ACTIONS
1) Ensure docs/10-research/ exists with README.md (index table: Date | Topic | Path | Summary).
2) If pasted research content is provided, save to docs/10-research/<YYYYMMDD>-<slug>.md and add a row to README.md (newest first).
Diff-first; YES/NO.

522
commands/retro.md Normal file
View File

@@ -0,0 +1,522 @@
---
description: retro
allowed-tools: Bash, Read, Edit, Write, Glob, Grep
---
# retro
Automated retrospective generator that analyzes patterns and surfaces insights from AgileFlow data.
## Prompt
ROLE: Retrospective Facilitator
OBJECTIVE
Automatically generate retrospective insights by analyzing bus/log.jsonl, status.json, and story data to surface what went well, what needs improvement, and actionable next steps.
INPUTS (optional)
- TIMEFRAME=sprint|2weeks|30d|90d (default: 2weeks)
- EPIC=<EP_ID> (retrospective for specific epic)
- FORMAT=ascii|markdown|html (default: ascii)
- SAVE=true|false (default: true - save to docs/08-project/retrospectives/)
DATA SOURCES
1. **docs/09-agents/bus/log.jsonl** - Event patterns
- Status transitions and their frequency
- Blocking events and duration
- Handoff patterns
- Error/issue mentions
2. **docs/09-agents/status.json** - Current state snapshot
- Stories in each status
- WIP levels
- Owner distribution
3. **docs/06-stories/**/US-*.md** - Story data
- Completed vs planned
- Estimates vs actuals
- AC completion rate
4. **Velocity data** - From bus analysis
- Points completed
- Throughput trends
RETROSPECTIVE STRUCTURE
### Format: Start, Stop, Continue
**START** - Things we should start doing
**STOP** - Things we should stop doing
**CONTINUE** - Things working well to keep doing
ANALYSIS PATTERNS
### 1. What Went Well (CONTINUE)
**Pattern: High velocity**
```bash
current_velocity=$(calculate_velocity 2weeks)
previous_velocity=$(calculate_velocity 2weeks --offset=2weeks)
if [ $current_velocity -gt $previous_velocity ]; then
echo "✅ Velocity increased from $previous_velocity to $current_velocity stories/week (+X%)"
echo " Continue: Current workflow and team collaboration"
fi
```
**Pattern: Fast cycle time**
```bash
fast_stories=$(find_stories_with_cycle_time_under 2days)
if [ ${#fast_stories[@]} -gt 5 ]; then
echo "✅ ${#fast_stories[@]} stories completed in <2 days"
echo " Continue: Small, well-defined stories enable fast delivery"
fi
```
**Pattern: No blocked stories**
```bash
blocked_count=$(jq -r '.stories | to_entries[] | select(.value.status=="blocked") | .key' status.json | wc -l)
if [ $blocked_count -eq 0 ]; then
echo "✅ Zero blocked stories this period"
echo " Continue: Proactive dependency management"
fi
```
**Pattern: Epic completion**
```bash
completed_epics=$(grep -l "completed:" docs/05-epics/*.md | wc -l)
if [ $completed_epics -gt 0 ]; then
echo "✅ Completed $completed_epics epic(s): $(list_epic_names)"
echo " Continue: Epic breakdown and execution approach"
fi
```
**Pattern: Good estimation**
```bash
avg_variance=$(calculate_estimation_variance)
if [ $avg_variance -lt 0.2 ]; then # <20% variance
echo "✅ Estimation accuracy within 20% (avg variance: ${avg_variance}%)"
echo " Continue: Current estimation practices"
fi
```
**Pattern: Balanced agent workload**
```bash
utilization_variance=$(calculate_agent_utilization_variance)
if [ $utilization_variance -lt 0.15 ]; then
echo "✅ Balanced workload across agents (variance: ${utilization_variance})"
echo " Continue: Current assignment strategy"
fi
```
### 2. What Needs Improvement (START/STOP)
**Pattern: Velocity drop**
```bash
if [ $current_velocity -lt $((previous_velocity - 2)) ]; then
echo "⚠️ Velocity dropped from $previous_velocity to $current_velocity (-X%)"
echo " START: Daily standup to identify blockers earlier"
echo " STOP: Taking on too many large (>3d) stories at once"
fi
```
**Pattern: Long cycle times**
```bash
slow_stories=$(find_stories_with_cycle_time_over 5days)
if [ ${#slow_stories[@]} -gt 3 ]; then
echo "⚠️ ${#slow_stories[@]} stories took >5 days to complete"
echo " START: Breaking down stories into smaller chunks"
echo " STOP: Starting stories without clear AC"
common_themes=$(analyze_slow_story_themes)
echo " Pattern: $common_themes"
fi
```
**Pattern: High WIP**
```bash
avg_wip=$(calculate_average_wip 2weeks)
wip_limit=6
if [ $avg_wip -gt $wip_limit ]; then
echo "⚠️ Average WIP ($avg_wip) exceeded limit ($wip_limit)"
echo " START: Finish stories before starting new ones"
echo " STOP: Context switching between multiple stories"
fi
```
**Pattern: Frequent blocking**
```bash
blocked_count=$(jq -r 'select(.type=="status-change" and .new_status=="blocked")' bus/log.jsonl | wc -l)
if [ $blocked_count -gt 5 ]; then
echo "⚠️ $blocked_count stories became blocked this period"
blocking_reasons=$(analyze_blocking_reasons)
echo " Common reasons: $blocking_reasons"
echo " START: Pre-sprint dependency check"
echo " STOP: Starting stories with unresolved dependencies"
fi
```
**Pattern: Long review times**
```bash
avg_review_time=$(calculate_average_review_time)
if [ $avg_review_time -gt 2 ]; then
echo "⚠️ Average review time: $avg_review_time days"
echo " START: Dedicated review time blocks"
echo " STOP: Large PRs (aim for <400 lines changed)"
fi
```
**Pattern: Poor estimation**
```bash
avg_variance=$(calculate_estimation_variance)
if [ $avg_variance -gt 0.5 ]; then # >50% variance
echo "⚠️ Estimates off by ${avg_variance}% on average"
underestimated=$(count_underestimated_stories)
echo " $underestimated stories underestimated"
echo " START: Planning poker for complex stories"
echo " STOP: Estimating without team discussion"
fi
```
**Pattern: Agent bottleneck**
```bash
bottleneck_agent=$(find_most_overloaded_agent)
if [ -n "$bottleneck_agent" ]; then
count=$(get_agent_active_stories $bottleneck_agent)
echo "⚠️ $bottleneck_agent has $count active stories (others have 1-2)"
echo " START: Redistributing work more evenly"
echo " STOP: Assigning all $type stories to same agent"
fi
```
**Pattern: Stale stories**
```bash
stale_stories=$(find_stories_in_progress_over 10days)
if [ ${#stale_stories[@]} -gt 0 ]; then
echo "⚠️ ${#stale_stories[@]} stories in-progress >10 days: $(echo ${stale_stories[@]})"
echo " START: Weekly check-ins on long-running stories"
echo " STOP: Keeping stories in-progress without progress"
echo " Action: Consider closing or re-scoping"
fi
```
### 3. Action Items
**Derive from patterns**
```bash
# High priority: Fix immediate problems
if [ $blocked_count -gt 2 ]; then
echo "🎯 HIGH: Unblock $blocked_count stories ASAP"
for story in blocked_stories; do
echo " - $story: $(get_blocking_reason $story)"
done
fi
# Medium priority: Process improvements
if [ $avg_review_time -gt 2 ]; then
echo "🎯 MEDIUM: Reduce review time from $avg_review_time to <1 day"
echo " - Set up daily 30min review slot"
echo " - Use /AgileFlow:ai-code-review before requesting human review"
fi
# Low priority: Long-term improvements
if [ $avg_variance -gt 0.3 ]; then
echo "🎯 LOW: Improve estimation accuracy"
echo " - Track actuals vs estimates in docs/08-project/estimation-log.md"
echo " - Review monthly to calibrate"
fi
```
RETROSPECTIVE OUTPUT
### ASCII Format (Default)
```markdown
╔════════════════════════════════════════════════════════════════╗
║ AGILEFLOW RETROSPECTIVE ║
║ Sprint: Oct 17 - Oct 31 (2 weeks) ║
╠════════════════════════════════════════════════════════════════╣
║ ║
║ 📊 SPRINT SUMMARY ║
║ ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ ║
║ ║
║ Stories Completed: 17 (85% of planned 20) ║
║ Velocity: 8.5 stories/week (↗ +12%) ║
║ Cycle Time: 3.2 days avg (↓ -8%) ║
║ Stories Blocked: 2 (during sprint) ║
║ Epics Completed: 1 (EP-0010: Authentication) ║
║ ║
║ ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ ║
║ ║
║ ✅ WHAT WENT WELL (Continue) ║
║ ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ ║
║ ║
║ 1. Velocity increased +12% vs previous sprint ║
║ 👉 Continue: Current workflow and team collaboration ║
║ ║
║ 2. Completed EP-0010 (Authentication) on schedule ║
║ 👉 Continue: Epic breakdown approach (13 small stories) ║
║ ║
║ 3. 12 stories completed in <2 days ║
║ 👉 Continue: Small, well-defined stories ║
║ ║
║ 4. Estimation accuracy improved to 18% variance ║
║ 👉 Continue: Team estimation sessions ║
║ ║
║ 5. Balanced workload (all agents 30-35% utilization) ║
║ 👉 Continue: Current assignment strategy ║
║ ║
║ 6. Zero merge conflicts this sprint ║
║ 👉 Continue: Frequent rebasing and small PRs ║
║ ║
║ ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ ║
║ ║
║ ⚠️ WHAT NEEDS IMPROVEMENT ║
║ ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ ║
║ ║
║ 1. Average review time: 2.5 days (up from 1.8) ║
║ 🛑 STOP: Letting PRs sit unreviewed ║
║ ▶️ START: Daily 30min review slot ║
║ ║
║ 2. 2 stories blocked >3 days (US-0045, US-0048) ║
║ 🛑 STOP: Starting stories with external dependencies ║
║ ▶️ START: Pre-sprint dependency verification ║
║ ║
║ 3. US-0042 took 8 days (estimated 2d, +300%) ║
║ 🛑 STOP: Estimating without understanding complexity ║
║ ▶️ START: Spike stories for unknowns ║
║ ║
║ 4. AG-API at 50% utilization (others at 30%) ║
║ 🛑 STOP: Assigning all API work to one agent ║
║ ▶️ START: Cross-training agents on API development ║
║ ║
║ 5. 3 stories rolled over from previous sprint ║
║ 🛑 STOP: Over-committing in sprint planning ║
║ ▶️ START: Use velocity data for realistic planning ║
║ ║
║ ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ ║
║ ║
║ 🎯 ACTION ITEMS ║
║ ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ ║
║ ║
║ HIGH Priority (This Week): ║
║ ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ ║
║ [ ] Unblock US-0045 (escalate for API keys) ║
║ [ ] Unblock US-0048 (depends on US-0045) ║
║ [ ] Set up daily 11am review time block (30min) ║
║ ║
║ MEDIUM Priority (Next Sprint): ║
║ ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ ║
║ [ ] Cross-train AG-UI and AG-CI on API development ║
║ [ ] Add dependency check to sprint planning checklist ║
║ [ ] Create spike story template for unknowns ║
║ ║
║ LOW Priority (This Month): ║
║ ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ ║
║ [ ] Review and update estimation guide ║
║ [ ] Track estimation accuracy monthly ║
║ [ ] Document blocking patterns for future avoidance ║
║ ║
║ ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ ║
║ ║
║ 📈 TEAM CONTRIBUTIONS ║
║ ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ ║
║ ║
║ AG-API: 7 stories (41%) ████████████████████░░ ║
║ AG-UI: 6 stories (35%) ██████████████████░░ ║
║ AG-CI: 4 stories (24%) ████████████░░ ║
║ AG-DEVOPS: 0 stories (0%) ░░ ║
║ ║
║ Note: Consider assigning automation work to AG-DEVOPS ║
║ ║
║ ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ ║
║ ║
║ 🔮 PREDICTIONS FOR NEXT SPRINT ║
║ ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ ║
║ ║
║ Based on current velocity and epic progress: ║
║ ║
║ EP-0011 (Payment): 40% → 75% (6 stories) ║
║ EP-0012 (Dashboard): 10% → 35% (4 stories) ║
║ ║
║ Recommended sprint capacity: 18 stories ║
║ (Based on 8.5 avg velocity * 2 weeks + 5% buffer) ║
║ ║
║ Risks: ║
║ - Payment epic blocked on external API access ║
║ - Dashboard work may need design input ║
║ ║
╚════════════════════════════════════════════════════════════════╝
Saved to: docs/08-project/retrospectives/retro-20251031.md
Next Steps:
- Review action items in next team meeting
- Run /AgileFlow:metrics to track improvements
- Run /AgileFlow:velocity to update sprint planning
```
INSIGHTS ENGINE
### Pattern Detection
**1. Recurring Blockers**
```bash
# Find stories blocked multiple times
recurring_blockers=$(jq -r 'select(.type=="status-change" and .new_status=="blocked") | .story' bus/log.jsonl | sort | uniq -c | awk '$1>1 {print $2}')
if [ -n "$recurring_blockers" ]; then
echo "🔍 Pattern: Recurring blockers detected"
for story in $recurring_blockers; do
count=$(count_times_blocked $story)
reasons=$(get_all_blocking_reasons $story)
echo " $story: Blocked $count times ($reasons)"
done
echo " Action: Root cause analysis needed"
fi
```
**2. Day-of-Week Patterns**
```bash
# Stories completed by day of week
for day in Mon Tue Wed Thu Fri; do
count=$(jq -r 'select(.status=="done" and .ts | strftime("%a")=="'$day'")' bus/log.jsonl | wc -l)
echo "$day: $count completions"
done
# Identify productivity patterns
if [ $friday_completions -lt $((avg_completions / 2)) ]; then
echo "🔍 Pattern: Low Friday completions"
echo " Insight: Consider shorter Friday sprints or retrospective time"
fi
```
**3. Handoff Patterns**
```bash
handoff_count=$(jq -r 'select(.type=="handoff")' bus/log.jsonl | wc -l)
if [ $handoff_count -gt 5 ]; then
echo "🔍 Pattern: Frequent handoffs ($handoff_count this sprint)"
handoff_stories=$(get_handoff_stories)
echo " Stories: $handoff_stories"
echo " Insight: May indicate knowledge silos or unclear ownership"
echo " Action: Pair programming or better initial assignment"
fi
```
**4. Story Size Patterns**
```bash
# Compare cycle time by estimate
for size in 0.5d 1d 2d 3d 5d; do
avg_cycle=$(get_avg_cycle_time_for_size $size)
echo "$size stories: $avg_cycle days actual cycle time"
done
# Find sweet spot
if [ $size_1d_cycle -lt $size_2d_cycle ] && [ $size_2d_cycle -lt $size_3d_cycle ]; then
echo "🔍 Pattern: Story size correlates with cycle time (as expected)"
echo " Insight: 1d stories are most efficient"
echo " Action: Aim for more 1d stories in planning"
else
echo "🔍 Pattern: Large stories not taking proportionally longer"
echo " Insight: May indicate poor estimation or chunking issues"
fi
```
CELEBRATION MOMENTS
```bash
# Epic completion
if [ $completed_epics -gt 0 ]; then
echo "🎉 CELEBRATE: Completed $completed_epics epic(s)!"
for epic in completed_epic_ids; do
title=$(get_epic_title $epic)
duration=$(calculate_epic_duration $epic)
echo " $epic: $title (completed in $duration)"
done
fi
# Velocity milestone
if [ $current_velocity -gt 10 ]; then
echo "🎉 CELEBRATE: Hit double-digit velocity (${current_velocity} stories/week)!"
fi
# Zero bugs/issues
bug_count=$(count_stories_with_type "bug")
if [ $bug_count -eq 0 ]; then
echo "🎉 CELEBRATE: Zero bugs reported this sprint!"
fi
# Fast delivery
fastest_story=$(find_story_with_fastest_cycle_time)
if [ $fastest_cycle_time -lt 0.5 ]; then
echo "🎉 CELEBRATE: $fastest_story delivered in <4 hours!"
fi
```
EXPORT & STORAGE
### Save to File
```bash
retro_file="docs/08-project/retrospectives/retro-$(date +%Y%m%d).md"
mkdir -p docs/08-project/retrospectives
echo "$retro_content" > $retro_file
```
### Update Retrospectives Index
```bash
# docs/08-project/retrospectives/README.md
| Date | Sprint | Velocity | Completed | Top Action Item |
|------|--------|----------|-----------|-----------------|
| 2025-10-31 | Oct 17-31 | 8.5 | 17/20 (85%) | Reduce review time |
| 2025-10-17 | Oct 3-17 | 7.6 | 15/18 (83%) | Improve estimation |
```
INTEGRATION WITH OTHER COMMANDS
- After `/AgileFlow:metrics`: Run `/AgileFlow:retro` to contextualize the data
- Before planning: Run `/AgileFlow:retro` to apply learnings
- In `/AgileFlow:babysit`: Suggest `/AgileFlow:retro` at sprint boundaries
- With `/AgileFlow:velocity`: Use velocity trends in retro insights
USAGE EXAMPLES
### Standard 2-week retro
```bash
/AgileFlow:retro
```
### Last 30 days
```bash
/AgileFlow:retro TIMEFRAME=30d
```
### Epic-specific retro
```bash
/AgileFlow:retro EPIC=EP-0010
```
### Generate without saving
```bash
/AgileFlow:retro SAVE=false
```
### Export as markdown for Notion
```bash
/AgileFlow:retro FORMAT=markdown > retro.md
```
RULES
- Focus on patterns, not individuals (team-level insights)
- Balance positive (continue) with improvements (start/stop)
- Make action items specific and actionable
- Prioritize actions by impact and effort
- Celebrate wins (even small ones)
- Use data to drive insights (no subjective opinions without data)
- Always end with forward-looking predictions
- Save automatically for historical tracking
OUTPUT
- ASCII retrospective report (default)
- Saved to docs/08-project/retrospectives/retro-YYYYMMDD.md
- Updated retrospectives/README.md index
- Action items formatted as checkboxes for easy tracking

364
commands/review.md Normal file
View File

@@ -0,0 +1,364 @@
---
description: ai-code-review
allowed-tools: Bash, Read, Edit, Write, Glob, Grep
---
# ai-code-review
Perform AI-powered code review based on coding standards and best practices.
## Prompt
ROLE: AI Code Reviewer
OBJECTIVE
Analyze code changes for quality, security, performance, and adherence to best practices.
INPUTS (optional)
- BRANCH=<branch name> (default: current branch)
- BASE=<base branch> (default: main/master)
- FOCUS=all|security|performance|style|tests (default: all)
- SEVERITY=critical|high|medium|low|all (default: all)
REVIEW CATEGORIES
### 1. Code Quality
- Complexity (cyclomatic complexity, nesting depth)
- Duplication (copy-paste code)
- Naming (clear, consistent, descriptive)
- Function length (target <50 lines)
- File length (target <500 lines)
- Comments (appropriate, not excessive)
### 2. Security
- SQL injection vulnerabilities
- XSS vulnerabilities
- Hardcoded secrets/credentials
- Insecure dependencies
- Missing input validation
- Unsafe deserialization
- CORS misconfiguration
- Authentication/authorization issues
### 3. Performance
- N+1 query problems
- Inefficient algorithms (O(n²) when O(n) possible)
- Missing indexes (database)
- Unnecessary loops
- Memory leaks
- Large bundle sizes
- Unoptimized images
### 4. Best Practices
- Error handling (try/catch, null checks)
- Logging (appropriate level, includes context)
- Type safety (TypeScript strict mode, Python type hints)
- Immutability (prefer const, avoid mutations)
- Async/await (vs callbacks)
- Separation of concerns
- DRY principle
### 5. Testing
- Missing tests for new code
- Test quality (assertions, edge cases)
- Test coverage (aim for >80%)
- Flaky tests
- Slow tests (>100ms for unit tests)
### 6. Documentation
- Missing JSDoc/docstrings
- Outdated comments
- Missing README updates
- API documentation
ANALYSIS PROCESS
1. Get diff:
```bash
git diff <BASE>...<BRANCH>
```
2. Parse changed files and hunks
3. For each change, analyze:
- What changed?
- Why is this potentially problematic?
- What's the risk/impact?
- How to fix it?
REVIEW REPORT
```markdown
# AI Code Review Report
**Branch**: feature/user-auth
**Base**: main
**Files Changed**: 8
**Lines Added**: 245
**Lines Removed**: 32
**Generated**: 2025-10-16T10:30:00Z
---
## Summary
**Critical**: 2 | **High**: 5 | **Medium**: 12 | **Low**: 8
**Must Fix Before Merge**: 7 issues
---
## Critical Issues 🔴
### 1. Hardcoded API Key (SECURITY)
**File**: src/api/payments/stripe.ts:15
**Severity**: CRITICAL
\`\`\`typescript
// ❌ BAD
const stripeKey = "sk_live_abc123...";
// ✅ GOOD
const stripeKey = process.env.STRIPE_SECRET_KEY;
if (!stripeKey) throw new Error("STRIPE_SECRET_KEY not set");
\`\`\`
**Risk**: API key exposed in version control. Can lead to unauthorized charges.
**Fix**: Move to environment variable. Rotate the exposed key immediately.
**Priority**: Block merge
---
### 2. SQL Injection Vulnerability (SECURITY)
**File**: src/api/users/search.ts:42
**Severity**: CRITICAL
\`\`\`typescript
// ❌ BAD
const query = \`SELECT * FROM users WHERE email = '\${email}'\`;
db.query(query);
// ✅ GOOD
const query = 'SELECT * FROM users WHERE email = ?';
db.query(query, [email]);
\`\`\`
**Risk**: Attacker can inject SQL to dump database or escalate privileges.
**Fix**: Use parameterized queries or ORM.
**Priority**: Block merge
---
## High Issues 🟠
### 3. Missing Error Handling (RELIABILITY)
**File**: src/api/auth/login.ts:67
**Severity**: HIGH
\`\`\`typescript
// ❌ BAD
async function login(email: string, password: string) {
const user = await db.users.findOne({ email });
return generateToken(user.id); // Crashes if user is null
}
// ✅ GOOD
async function login(email: string, password: string) {
const user = await db.users.findOne({ email });
if (!user) throw new UnauthorizedError("Invalid credentials");
return generateToken(user.id);
}
\`\`\`
**Risk**: Unhandled rejection crashes server.
**Fix**: Add null check and throw appropriate error.
---
### 4. N+1 Query Problem (PERFORMANCE)
**File**: src/api/posts/list.ts:23
**Severity**: HIGH
\`\`\`typescript
// ❌ BAD (N+1 queries)
const posts = await db.posts.findMany();
for (const post of posts) {
post.author = await db.users.findOne({ id: post.authorId });
}
// ✅ GOOD (1 query with join)
const posts = await db.posts.findMany({
include: { author: true }
});
\`\`\`
**Risk**: Scales poorly. 100 posts = 101 queries.
**Fix**: Use eager loading/join.
---
### 5. Missing Tests (TESTING)
**File**: src/api/auth/login.ts
**Severity**: HIGH
**Coverage**: 0% (0/45 lines covered)
**Suggested tests**:
- ✅ Should return token for valid credentials
- ✅ Should reject invalid password
- ✅ Should reject non-existent email
- ✅ Should handle database errors gracefully
- ✅ Should rate-limit login attempts
**Fix**: Add test file tests/api/auth/login.test.ts
---
## Medium Issues 🟡
### 6. High Cyclomatic Complexity (MAINTAINABILITY)
**File**: src/utils/validator.ts:validateUser()
**Complexity**: 15 (threshold: 10)
**Suggestion**: Extract validation rules into separate functions:
\`\`\`typescript
function validateEmail(email) { ... }
function validatePassword(password) { ... }
function validateAge(age) { ... }
function validateUser(user) {
return [
validateEmail(user.email),
validatePassword(user.password),
validateAge(user.age)
].every(Boolean);
}
\`\`\`
---
[9 more medium issues...]
---
## Low Issues ⚪
### 15. Inconsistent Naming (STYLE)
**Files**: Multiple files
Variables use both camelCase and snake_case. Project standard is camelCase.
---
## Positive Observations ✅
- ✅ Good use of TypeScript strict mode
- ✅ Consistent error handling pattern in new middleware
- ✅ Well-structured component separation
- ✅ Clear commit messages following Conventional Commits
---
## Recommendations
### Immediate (Block Merge)
1. Remove hardcoded API key (critical)
2. Fix SQL injection (critical)
3. Add error handling to login (high)
### Before Merge
4. Add tests for auth endpoints (high)
5. Fix N+1 query in posts API (high)
6. Reduce complexity in validator.ts (medium)
### Follow-up (Create Stories)
7. Standardize naming conventions project-wide (medium)
8. Add ESLint rule to catch hardcoded secrets (medium)
9. Set up automated security scanning (Snyk/Dependabot)
---
## Automated Fixes Available
Some issues can be auto-fixed:
\`\`\`bash
npm run lint -- --fix # Fixes 8 style issues
\`\`\`
---
## Code Quality Score: 72/100
**Breakdown**:
- Security: 40/100 (2 critical issues)
- Performance: 75/100 (1 N+1 query)
- Maintainability: 80/100 (some complexity)
- Testing: 65/100 (coverage gaps)
- Style: 90/100 (mostly consistent)
**Recommendation**: Fix critical/high issues before merge.
```
ACTIONS (after user review)
1. Ask: "Fix auto-fixable issues? (YES/NO)"
- If YES: Run linters with --fix flag
2. Ask: "Create stories for follow-up work? (YES/NO)"
- If YES: Create stories for medium/low issues
3. Ask: "Block merge for critical/high issues? (YES/NO)"
- If YES: Fail CI check or add "changes requested" review
4. Save report to:
- docs/08-project/code-reviews/<YYYYMMDD>-<BRANCH>.md
INTEGRATION
### CI Integration
Suggest adding to .github/workflows/pr.yml:
\`\`\`yaml
- name: AI Code Review
run: npx claude-code /AgileFlow:ai-code-review BRANCH=${{ github.head_ref }}
- name: Check for critical issues
run: |
if grep -q "CRITICAL" code-review-report.md; then
echo "::error::Critical issues found. Fix before merge."
exit 1
fi
\`\`\`
### GitHub PR Comment
Optionally post summary as PR comment via GitHub API.
CUSTOMIZATION
Read project-specific rules from:
- .agileflow/review-rules.md
- docs/02-practices/code-standards.md
Example custom rules:
\`\`\`markdown
# Code Review Rules
## Critical
- No console.log in production code
- All API endpoints must have rate limiting
- All database queries must use ORM
## High
- Functions >30 lines should be refactored
- Test coverage must be >85%
\`\`\`
RULES
- Be constructive, not critical
- Provide specific, actionable feedback
- Show both bad and good examples
- Prioritize by severity
- Celebrate good practices
- Never auto-commit fixes without approval
OUTPUT
- Code review report (markdown)
- Issue count by severity
- Code quality score
- Recommendations
- Optional: Auto-fixes (if approved)

1498
commands/setup.md Normal file
View File

File diff suppressed because it is too large Load Diff

475
commands/sprint.md Normal file
View File

@@ -0,0 +1,475 @@
---
description: sprint-plan
allowed-tools: Bash, Read, Edit, Write, Glob, Grep
---
# sprint-plan
Intelligent sprint planning with capacity-based story selection, dependency validation, and velocity forecasting.
## Prompt
ROLE: Sprint Planner
OBJECTIVE
Create a data-driven sprint plan by analyzing backlog priorities, agent capacity, historical velocity, and dependency chains. Ensure realistic commitments that respect WIP limits and Definition of Ready criteria.
INPUTS
- SPRINT=<sprint-id> — Sprint identifier (e.g., "Sprint-42", "2025-W43")
- DURATION=<days> — Sprint duration in days (default: 10, typical 2-week sprint)
- AGENTS=<agent-list> — Comma-separated agents to plan for (default: all active agents)
- MODE=<suggest|commit> — "suggest" shows preview, "commit" updates status.json (default: suggest)
- FOCUS_EPIC=<epic-id> — Optionally focus on specific epic
KNOWLEDGE LOADING (run first, silently)
Read in order:
1. docs/09-agents/status.json — Current state, WIP, agent assignments
2. docs/09-agents/bus/log.jsonl — Historical velocity data (completed stories with timestamps)
3. docs/08-project/backlog.md — Priority order for stories
4. docs/08-project/roadmap.md — Strategic priorities
5. docs/08-project/milestones.md — Deadline constraints
6. docs/05-epics/*.md — Epic priorities and goals
7. docs/06-stories/**/US-*.md — Story details, AC, estimates
8. docs/03-decisions/adr-*.md — Recent ADRs that might spawn stories
SPRINT PLANNING PHASES
## Phase 1: Current State Analysis
### Agent Capacity Assessment
```bash
# Calculate available capacity per agent
echo "=== Current Agent Status ==="
for agent in AG-UI AG-API AG-CI AG-DEVOPS MENTOR; do
in_progress=$(jq -r ".stories | to_entries[] | select(.value.owner==\"$agent\") | select(.value.status==\"in-progress\") | .key" docs/09-agents/status.json | wc -l)
in_review=$(jq -r ".stories | to_entries[] | select(.value.owner==\"$agent\") | select(.value.status==\"in-review\") | .key" docs/09-agents/status.json | wc -l)
# WIP limit is 2
available=$((2 - in_progress))
echo "$agent: $in_progress in-progress, $in_review in-review → $available slots available"
# If agent has in-review stories, they might free up soon
if [ "$in_review" -gt 0 ]; then
echo " ⚠️ $in_review stories in review may complete soon (add conditional capacity)"
fi
done
```
### Backlog Health Check
```bash
# Count ready stories (meet Definition of Ready)
ready_count=$(jq -r '.stories | to_entries[] | select(.value.status=="ready") | .key' docs/09-agents/status.json | wc -l)
echo "Ready stories in backlog: $ready_count"
# Check for blocked stories that might unblock during sprint
blocked_count=$(jq -r '.stories | to_entries[] | select(.value.status=="blocked") | .key' docs/09-agents/status.json | wc -l)
echo "Blocked stories (may unblock): $blocked_count"
```
## Phase 2: Historical Velocity Calculation
### Calculate Team Velocity (last 3 sprints or 30 days)
```bash
# Parse bus/log.jsonl for completed stories with timestamps
thirty_days_ago=$(date -u -d '30 days ago' +%Y-%m-%dT%H:%M:%S 2>/dev/null || date -u -v-30d +%Y-%m-%dT%H:%M:%S 2>/dev/null)
# Extract story completion events
grep '"type":"status"' docs/09-agents/bus/log.jsonl | grep '"done"' | while read -r line; do
ts=$(echo "$line" | jq -r '.ts')
story=$(echo "$line" | jq -r '.story')
# Check if within last 30 days
if [[ "$ts" > "$thirty_days_ago" ]]; then
# Get story estimate
estimate=$(jq -r ".stories[\"$story\"].estimate" docs/09-agents/status.json 2>/dev/null)
echo "$story|$estimate|$ts"
fi
done > /tmp/completed_stories.txt
# Sum estimates (convert "0.5d", "1d", "2d" to numeric)
total_days=0
count=0
while IFS='|' read -r story estimate ts; do
# Extract numeric value
days=$(echo "$estimate" | grep -oE '[0-9.]+')
total_days=$(echo "$total_days + $days" | bc)
count=$((count + 1))
done < /tmp/completed_stories.txt
if [ "$count" -gt 0 ]; then
velocity=$(echo "scale=1; $total_days / 30 * ${DURATION:-10}" | bc)
echo "Historical velocity: $total_days days completed in last 30 days"
echo "Projected capacity for ${DURATION:-10}-day sprint: ${velocity} days"
else
echo "⚠️ No historical data. Using default capacity: 1 story per agent per sprint"
velocity="N/A"
fi
```
### Agent-Specific Velocity
```bash
# Calculate velocity per agent (for more accurate planning)
for agent in AG-UI AG-API AG-CI AG-DEVOPS; do
agent_total=0
while IFS='|' read -r story estimate ts; do
owner=$(jq -r ".stories[\"$story\"].owner" docs/09-agents/status.json 2>/dev/null)
if [ "$owner" == "$agent" ]; then
days=$(echo "$estimate" | grep -oE '[0-9.]+')
agent_total=$(echo "$agent_total + $days" | bc)
fi
done < /tmp/completed_stories.txt
if [ $(echo "$agent_total > 0" | bc) -eq 1 ]; then
agent_velocity=$(echo "scale=1; $agent_total / 30 * ${DURATION:-10}" | bc)
echo "$agent velocity: ${agent_velocity} days per ${DURATION:-10}-day sprint"
fi
done
```
## Phase 3: Story Selection & Prioritization
### Selection Criteria (in priority order)
1. **Must be "ready" status** (Definition of Ready met)
2. **Dependencies resolved** (all deps have status="done")
3. **Backlog priority** (from backlog.md or roadmap.md)
4. **Epic alignment** (if FOCUS_EPIC specified, prioritize that epic)
5. **Milestone deadlines** (check milestones.md for urgent items)
6. **Team capacity** (don't exceed calculated velocity)
7. **Agent balance** (distribute work evenly across agents)
### Story Selection Algorithm
```bash
# Extract all ready stories
jq -r '.stories | to_entries[] | select(.value.status=="ready") |
"\(.key)|\(.value.owner)|\(.value.estimate)|\(.value.epic // \"none\")|\(.value.deps // [] | join(\",\"))"' \
docs/09-agents/status.json > /tmp/ready_stories.txt
# Filter by dependencies (must be resolved)
while IFS='|' read -r story owner estimate epic deps; do
blocked=false
if [ -n "$deps" ]; then
IFS=',' read -ra DEP_ARRAY <<< "$deps"
for dep in "${DEP_ARRAY[@]}"; do
dep_status=$(jq -r ".stories[\"$dep\"].status" docs/09-agents/status.json 2>/dev/null)
if [ "$dep_status" != "done" ]; then
blocked=true
break
fi
done
fi
# If not blocked, eligible for sprint
if [ "$blocked" == "false" ]; then
# Check if agent has capacity
in_progress=$(jq -r ".stories | to_entries[] | select(.value.owner==\"$owner\") | select(.value.status==\"in-progress\") | .key" docs/09-agents/status.json | wc -l)
if [ "$in_progress" -lt 2 ]; then
echo "$story|$owner|$estimate|$epic|eligible"
else
echo "$story|$owner|$estimate|$epic|waiting-for-capacity"
fi
else
echo "$story|$owner|$estimate|$epic|blocked"
fi
done < /tmp/ready_stories.txt > /tmp/eligible_stories.txt
```
### Backlog Priority Matching
```bash
# Read backlog.md to get priority order
if [ -f docs/08-project/backlog.md ]; then
# Extract story IDs in order of appearance
grep -oE 'US-[0-9]{4}' docs/08-project/backlog.md > /tmp/backlog_order.txt
# Match with eligible stories
while read -r story_id; do
grep "^${story_id}|" /tmp/eligible_stories.txt
done < /tmp/backlog_order.txt > /tmp/prioritized_stories.txt
else
# No backlog.md, use status.json order
cat /tmp/eligible_stories.txt > /tmp/prioritized_stories.txt
fi
```
### Capacity-Based Selection
```bash
# Select stories until capacity is reached
capacity_days=${velocity:-10} # Default to sprint duration if no historical data
committed_days=0
echo "=== Sprint Story Selection ==="
echo "Target capacity: ${capacity_days} days"
echo ""
while IFS='|' read -r story owner estimate epic status; do
# Extract numeric estimate
days=$(echo "$estimate" | grep -oE '[0-9.]+' || echo "1")
# Check if adding this story exceeds capacity
new_total=$(echo "$committed_days + $days" | bc)
if [ $(echo "$new_total <= $capacity_days" | bc) -eq 1 ]; then
echo "✅ $story ($estimate) - $owner - Epic: $epic"
committed_days=$new_total
else
echo "⚠️ Capacity reached. Remaining stories in backlog:"
echo " $story ($estimate) - $owner - Epic: $epic [deferred]"
fi
done < /tmp/prioritized_stories.txt
```
## Phase 4: Risk Assessment
### Dependency Chain Analysis
```bash
# For each selected story, check dependency depth
echo ""
echo "=== Dependency Risk Assessment ==="
# Warn if selected stories have complex dependency chains
grep "^✅" /tmp/sprint_selection.txt | while read -r line; do
story=$(echo "$line" | grep -oE 'US-[0-9]{4}')
# Check if other stories depend on this one
dependents=$(jq -r ".stories | to_entries[] | select(.value.deps) | select(.value.deps | index(\"$story\")) | .key" docs/09-agents/status.json)
if [ -n "$dependents" ]; then
dep_count=$(echo "$dependents" | wc -l)
echo "⚠️ $story is blocking $dep_count other stories: $dependents"
echo " → Prioritize completion to unblock others"
fi
done
```
### Cross-Agent Coordination Check
```bash
# Identify stories requiring AG-API + AG-UI coordination
echo ""
echo "=== Cross-Agent Coordination ==="
ag_ui_stories=$(grep "^✅" /tmp/sprint_selection.txt | grep "AG-UI" | grep -oE 'US-[0-9]{4}')
ag_api_stories=$(grep "^✅" /tmp/sprint_selection.txt | grep "AG-API" | grep -oE 'US-[0-9]{4}')
if [ -n "$ag_ui_stories" ] && [ -n "$ag_api_stories" ]; then
echo "Sprint includes both AG-UI and AG-API work:"
echo "AG-UI stories: $ag_ui_stories"
echo "AG-API stories: $ag_api_stories"
echo ""
echo "💡 Tip: Sequence AG-API stories first to avoid blocking AG-UI"
fi
```
### Stale Epic Check
```bash
# Warn if sprint is mixing old and new epics
echo ""
echo "=== Epic Freshness Check ==="
grep "^✅" /tmp/sprint_selection.txt | grep -oE 'Epic: EP-[0-9]{4}' | sort -u | while read -r epic_line; do
epic=$(echo "$epic_line" | grep -oE 'EP-[0-9]{4}')
if [ -f "docs/05-epics/${epic}.md" ]; then
created=$(grep "^created:" "docs/05-epics/${epic}.md" | head -n1 | awk '{print $2}')
echo "$epic created on $created"
fi
done
```
## Phase 5: Sprint Commitment (if MODE=commit)
If MODE=commit, update status.json with sprint metadata:
```bash
# Add sprint field to selected stories
jq '.stories |= with_entries(
if (.key | IN("US-0042", "US-0043", "US-0045")) then
.value.sprint = "Sprint-42" |
.value.sprint_committed = "2025-10-22T00:00:00Z"
else
.
end
)' docs/09-agents/status.json > /tmp/status_updated.json
# Diff preview
diff -u docs/09-agents/status.json /tmp/status_updated.json
# Ask for confirmation
echo ""
echo "Update status.json with sprint commitments? (YES/NO)"
# Wait for user input
```
### Create Sprint Milestone
```bash
# Update milestones.md with sprint
sprint_end=$(date -u -d '+10 days' +%Y-%m-%d 2>/dev/null || date -u -v+10d +%Y-%m-%d 2>/dev/null)
cat >> docs/08-project/milestones.md <<EOF
## ${SPRINT:-Sprint} (${sprint_end})
**Stories**: ${committed_count} stories, ${committed_days} estimated days
**Team Capacity**: ${velocity} days (based on historical velocity)
**Committed Stories**:
$(grep "^✅" /tmp/sprint_selection.txt)
**Sprint Goals**:
- [Fill in sprint goals based on epic alignment]
**Risks**:
- [Identify from dependency and coordination analysis]
**Definition of Done**:
- All stories merged to main
- CI passing
- Documentation updated
- Demo prepared
EOF
```
### Bus Message
```bash
# Append sprint planning bus message
cat >> docs/09-agents/bus/log.jsonl <<EOF
{"ts":"$(date -u +%Y-%m-%dT%H:%M:%S)Z","from":"EPIC-PLANNER","type":"sprint-planned","text":"${SPRINT:-Sprint} planned: ${committed_count} stories, ${committed_days} days estimated, ends ${sprint_end}"}
EOF
```
OUTPUT FORMAT
```
📅 Sprint Planning Report
=========================
Sprint: ${SPRINT}
Duration: ${DURATION} days
Mode: ${MODE}
Generated: <timestamp>
📊 CAPACITY ANALYSIS
--------------------
Historical Velocity (last 30 days):
- Team: ${velocity} days per ${DURATION}-day sprint
- AG-UI: X days
- AG-API: X days
- AG-CI: X days
- AG-DEVOPS: X days
Current Agent Status:
AG-UI: 1/2 slots filled (1 available)
AG-API: 2/2 slots filled (at capacity, but 1 in review)
AG-CI: 0/2 slots filled (2 available)
AG-DEVOPS: 1/2 slots filled (1 available)
Total Available Capacity: ~X days
📋 BACKLOG STATUS
-----------------
Ready stories: X
Blocked stories: X (may unblock during sprint)
Eligible for sprint: X
✅ RECOMMENDED SPRINT COMMITMENT
--------------------------------
Committed: X stories, Y.Z estimated days (Y% of capacity)
1. US-0042 (1d) - AG-UI - Epic: EP-0010 [Priority: High]
"User login form with validation"
Dependencies: None ✅
Risk: None
2. US-0043 (0.5d) - AG-API - Epic: EP-0010 [Priority: High]
"POST /auth/login endpoint"
Dependencies: None ✅
Risk: Blocks US-0042 → Schedule first ⚠️
3. US-0045 (2d) - AG-UI - Epic: EP-0011 [Priority: Medium]
"User profile page"
Dependencies: US-0044 (done) ✅
Risk: None
4. US-0050 (1d) - AG-CI - Epic: EP-0012 [Priority: Medium]
"Add E2E tests for auth flow"
Dependencies: US-0042, US-0043 (both in this sprint) ⚠️
Risk: Should be done AFTER US-0042 and US-0043 complete
⚠️ DEFERRED (capacity reached)
-------------------------------
5. US-0055 (1d) - AG-API - Epic: EP-0013
"GET /user/settings endpoint"
→ Move to next sprint or pick up if capacity frees up
🎯 SPRINT GOALS
---------------
(Based on epic distribution)
1. Complete core authentication (EP-0010): 3 stories
2. User profile foundation (EP-0011): 1 story
3. Test coverage for auth (EP-0012): 1 story
⚠️ RISKS & DEPENDENCIES
------------------------
1. Cross-agent coordination required:
- AG-API must complete US-0043 before AG-UI can finish US-0042
- Suggest: AG-API prioritizes US-0043 in first 2 days
2. Test story (US-0050) depends on 2 sprint stories:
- Schedule for end of sprint after US-0042 and US-0043 are done
3. AG-API at capacity:
- Has 1 story in review (US-0038) likely to complete soon
- If US-0038 completes early, can pick up deferred US-0055
💡 RECOMMENDATIONS
------------------
1. Sequence stories: US-0043 (AG-API) → US-0042 (AG-UI) → US-0050 (AG-CI)
2. Daily standup focus: AG-API unblocking AG-UI (check /blockers)
3. Mid-sprint checkpoint: Day 5 - assess if US-0055 can be added
4. End-of-sprint: Run /AgileFlow:velocity to update historical data
📅 SPRINT TIMELINE
------------------
Start: <today>
End: <sprint_end>
Demo: <sprint_end - 1 day>
Definition of Done:
✅ All stories merged to main
✅ CI passing on main
✅ Documentation updated
✅ Demo prepared for stakeholders
Next Steps:
${MODE == "suggest" && "1. Review commitment and run /AgileFlow:sprint-plan MODE=commit to finalize"}
${MODE == "commit" && "1. ✅ Sprint committed! Stories updated in status.json"}
2. Assign first stories: /AgileFlow:assign STORY=US-0043 (highest priority)
3. Monitor progress: /AgileFlow:board
4. Track blockers: /AgileFlow:blockers
5. Sync to external systems: /AgileFlow:github-sync or /AgileFlow:notion
```
RULES
- Always calculate historical velocity before planning
- Respect WIP limits (max 2 per agent)
- Validate dependencies are resolved
- Prioritize by backlog order, milestones, epic goals
- Show diff before committing changes (MODE=commit)
- Provide sequencing recommendations for dependent stories
- Warn about cross-agent coordination needs
- Suggest concrete next commands
FOLLOW-UP QUESTIONS
After displaying plan, ask:
- "Does this sprint commitment look reasonable?"
- "Should I commit this plan (update status.json and milestones.md)?"
- "Any stories you'd like to add/remove?"

38
commands/status.md Normal file
View File

@@ -0,0 +1,38 @@
---
description: status
allowed-tools: Bash, Read, Edit, Write, Glob, Grep
---
# status
Update story status and broadcast to agents via message bus.
## Prompt
ROLE: Status Updater
INPUTS
STORY=<US-ID> STATUS=in-progress|blocked|in-review|done
SUMMARY=<1–2 lines> PR=<url optional> TO=<agent id optional>
ACTIONS
1) Update docs/09-agents/status.json (status,summary,last_update,pr).
**CRITICAL**: Always use jq for JSON operations to prevent corruption.
2) **Validate JSON after update**:
```bash
# Validate status.json after modification
if ! jq empty docs/09-agents/status.json 2>/dev/null; then
echo "❌ ERROR: status.json is now invalid JSON after update!"
echo "Run: bash scripts/validate-json.sh docs/09-agents/status.json"
exit 1
fi
```
3) Append a bus line: {"ts":now,"from":"<self>","to":"<TO or ALL>","type":"status","story":"<STORY>","text":"<SUMMARY>"}.
**JSON Safety Guidelines**:
- ALWAYS use jq or the Edit tool (never echo/cat > status.json)
- User-provided text (summaries, descriptions) is automatically escaped by jq
- Validate status.json after ANY modification
- If validation fails, restore from backup: docs/09-agents/status.json.backup
Diff-first; YES/NO.

228
commands/story-validate.md Normal file
View File

@@ -0,0 +1,228 @@
---
description: story-validate
allowed-tools: Bash, Read, Edit, Write, Glob, Grep
---
# story-validate
Validate a specific story for completeness, architecture context, and readiness for development.
## Prompt
ROLE: Story Validator
OBJECTIVE
Validate that a story is complete, well-structured, and ready for implementation. Check for:
1. All required sections present (per story template)
2. Architecture Context populated with source citations
3. Clear, testable Acceptance Criteria
4. Dev Agent Record structure
5. Dependencies documented
6. Realistic estimation
SCOPE
- Validating individual user stories in docs/06-stories/
- Checking story completeness before assignment to dev agents
- Verifying Architecture Context extraction
- Ensuring compliance with story template structure
- NOT modifying stories (read-only validation)
VALIDATION CHECKLIST
## 1. Required Sections Presence
Check that story file has all required sections:
- ✓ Story metadata (YAML frontmatter with: story_id, epic, title, owner, status, estimate, created, updated, dependencies)
- ✓ Story header (# {{STORY_ID}}: {{TITLE}})
- ✓ Description
- ✓ Acceptance Criteria (with Given/When/Then format)
- ✓ Architecture Context section with subsections:
- Data Models & Schemas
- API Specifications
- Component Specifications
- File Locations & Naming
- Testing Requirements
- Technical Constraints
- ✓ Technical Notes
- ✓ Testing Strategy
- ✓ Dependencies
- ✓ Dev Agent Record section (structure/placeholders acceptable at ready/draft stage)
- ✓ Previous Story Insights section (if applicable to epic)
## 2. Architecture Context Validation (CRITICAL)
**Verify Architecture Context is populated**:
- Architecture Context section exists
- Each subsection (Data Models, API Specs, Components, etc.) has content
- Content includes source citations: `[Source: architecture/{filename}.md#{section}]`
- All sources reference docs/04-architecture/ files
- Technical details are extracted (NOT invented) from actual docs
- If subsection is empty, explicitly states: "No specific guidance found in architecture docs"
**Sources must be real**:
- Format: `[Source: architecture/{filename}.md#{section}]` or `[Source: docs/04-architecture/{filename}.md#{section}]`
- Check that files referenced actually exist in docs/04-architecture/
- Verify section anchors make sense for the file
## 3. Acceptance Criteria Validation
**Check AC clarity and testability**:
- Minimum 2, maximum 5 acceptance criteria
- Uses Given/When/Then format (not bullet points alone)
- Each criterion is specific and measurable
- Criteria reference implementation details (not just descriptions)
- Example GOOD: "Given a valid email, When form submitted, Then confirmation email sent within 30s"
- Example BAD: "User can reset password" (too vague)
## 4. Story Completeness Checks
**Estimation**:
- Estimate exists and is one of: 0.5d, 1d, 2d
- For estimates >2d: suggest breaking story into smaller pieces
**Dependencies**:
- If dependencies exist, check format: "Depends on US-#### (description)"
- Verify referenced stories exist in status.json
- Check for circular dependencies
**Owner Assignment**:
- Owner is assigned: AG-UI, AG-API, AG-CI, or AG-DEVOPS
- Owner is appropriate for story scope
**Status**:
- Status is one of: ready, draft, in-progress, blocked, in-review, done
- If "draft": story not yet ready for assignment (AC or AC need work)
- If "ready": story is ready for development
- If "blocked": reason documented in dependencies section
## 5. Dev Agent Record Structure
**Check structure is present** (content may be empty at ready/draft stage):
- Section exists with subsections:
- Agent Model & Version (placeholder OK: "To be populated during implementation")
- Completion Notes (placeholder OK)
- Issues Encountered (placeholder OK)
- Lessons Learned (placeholder OK)
- Files Modified (placeholder OK)
- Debug References (placeholder OK)
- Comments explain when section will be populated: "POPULATED BY DEVELOPMENT AGENT DURING IMPLEMENTATION"
## 6. Previous Story Insights
**If epic has multiple stories** (not first story):
- Section exists
- References previous story ID: {{PREV_STORY_ID}}
- Contains insights:
- Key learnings from previous story
- Architectural patterns that worked
- Technical debt discovered
- Challenges from previous story to avoid
**If first story in epic**:
- Section may reference non-existent previous story (acceptable)
- Or explicitly state: "First story in this epic, no previous story insights"
## 7. Cross-Story Consistency
**Check story aligns with epic**:
- Story's epic field matches actual epic
- Story's acceptance criteria align with epic requirements
- Story fits within epic's overall goal
**Check story fits team capacity**:
- Estimate (0.5d-2d) is realistic for story scope
- Owner (if assigned) has capacity
- Dependencies don't block critical path
OUTPUT FORMAT
Display validation results in clear format:
```
🔍 Story Validation Report
==========================
Story: {{STORY_ID}} - {{TITLE}}
File: {{FILE_PATH}}
Status: {{STATUS}}
✅ PASSED (X checks)
------------------
[List all passed checks]
❌ FAILED (X issues)
-------------------
Issue 1: {{DESCRIPTION}}
Location: {{SECTION}} line {{N}}
Suggestion: {{FIX}}
Issue 2: {{DESCRIPTION}}
Location: {{SECTION}} line {{N}}
Suggestion: {{FIX}}
⚠️ WARNINGS (X issues)
-----------------------
Warning 1: {{DESCRIPTION}}
Suggestion: {{FIX}}
📊 SUMMARY
----------
Architecture Context: {{✓ populated | ⚠️ partial | ❌ missing}}
Acceptance Criteria: {{✓ clear | ⚠️ unclear | ❌ missing}}
Dependencies: {{✓ documented | ⚠️ unclear | ❌ missing}}
Dev Agent Record: {{✓ structured | ⚠️ incomplete | ❌ missing}}
Ready for Development: {{YES | ⚠️ needs fixes | NO}}
Next Steps:
1. {{ACTION}}
2. {{ACTION}}
```
WORKFLOW
1. **Story Selection**:
- Ask user: "Which story would you like to validate? (provide story ID like US-0001)"
- Or: Auto-detect if run with `/AgileFlow:story-validate US-0001`
2. **Load Story File**:
- Find story file: `docs/06-stories/*/{{STORY_ID}}*.md`
- Parse YAML frontmatter
- Extract all sections
3. **Run Validation Checks**:
- Check all sections present (Step 1)
- Validate Architecture Context (Step 2) - CRITICAL
- Validate Acceptance Criteria (Step 3)
- Check completeness (Step 4)
- Check Dev Agent Record structure (Step 5)
- Check Previous Story Insights (Step 6)
- Cross-story consistency (Step 7)
4. **Generate Report**:
- Count passed/failed/warnings
- Group by severity
- Provide specific suggestions for fixes
- Determine if story is "ready for development"
5. **Next Steps Recommendation**:
- If "ready": "Story is ready for development. Assign to owner with /AgileFlow:assign"
- If warnings: "Story has X warnings. Consider addressing before assigning."
- If failed: "Story needs X critical fixes before development can start"
RULES
- Read-only operation (never modify story)
- Always check Architecture Context citations are real files/sections
- Be strict on Acceptance Criteria format (Given/When/Then required)
- Be lenient on Dev Agent Record content at draft/ready stage (structure only)
- Suggest concrete fixes for all issues
- Color code output: ✅ green, ❌ red, ⚠️ yellow
- Exit code 0 if ready for development, 1 if issues found
FIRST ACTION
When invoked:
1. Ask user: "Which story would you like to validate? (e.g., US-0001)"
2. Or parse story ID from command: `/AgileFlow:story-validate US-0001`
3. Load story file
4. Run all validation checks
5. Generate comprehensive report
6. Provide next steps

25
commands/story.md Normal file
View File

@@ -0,0 +1,25 @@
---
description: story-new
allowed-tools: Bash, Read, Edit, Write, Glob, Grep
---
# story-new
Create a new user story with acceptance criteria and test stubs.
## Prompt
ROLE: Story Creator
INPUTS
EPIC=<EP-ID> STORY=<US-ID> TITLE=<title>
OWNER=<name or agent id> ESTIMATE=<e.g., 0.5d>
DEPENDENCIES=[US-000X,...] (optional)
AC=<Given/When/Then bullets>
ACTIONS
1) Create docs/06-stories/<EPIC>/<STORY>-<slug>.md from story-template.md with frontmatter & AC.
2) Create docs/07-testing/test-cases/<STORY>.md (stub referencing AC).
3) Merge into docs/09-agents/status.json; append "assign" line to bus/log.jsonl.
Diff-first; YES/NO.

458
commands/template.md Normal file
View File

@@ -0,0 +1,458 @@
---
description: custom-template
allowed-tools: Bash, Read, Edit, Write, Glob, Grep
---
# custom-template
Create and manage custom templates for stories, epics, ADRs, and other documents.
## Prompt
ROLE: Template Manager
OBJECTIVE
Allow users to create, edit, and manage custom templates to standardize documentation across the project.
INPUTS (optional)
- ACTION=create|edit|list|use (default: list)
- TYPE=story|epic|adr|meeting|research|custom (required for create/edit/use)
- NAME=<template name> (required for create/edit/use)
- PATH=<file path> (optional: save template to custom location)
TEMPLATE TYPES
AgileFlow includes default templates in `docs/00-meta/templates/`:
- `story-template.md` - User stories
- `epic-template.md` - Epics
- `adr-template.md` - Architecture Decision Records
- `agent-profile-template.md` - Agent profiles
- `comms-note-template.md` - Handoff notes
- `research-template.md` - Research notes
- `README-template.md` - Folder READMEs
Users can create custom templates for:
- Meeting notes
- Sprint retrospectives
- Incident reports
- Design proposals
- RFC (Request for Comments)
- Onboarding docs
- API documentation
- Component specs
TEMPLATE SYNTAX
Templates use **placeholder variables** in double curly braces:
```
{{VARIABLE_NAME}}
```
Example:
```markdown
---
id: {{ID}}
title: {{TITLE}}
created: {{DATE}}
owner: {{OWNER}}
---
# {{TITLE}}
## Description
{{DESCRIPTION}}
```
BUILT-IN VARIABLES
Available in all templates:
- `{{DATE}}` - Current date (YYYY-MM-DD)
- `{{DATETIME}}` - Current datetime (ISO 8601)
- `{{USER}}` - Current user (from git config)
- `{{YEAR}}` - Current year
Template-specific variables:
- Story: `{{STORY_ID}}`, `{{EPIC_ID}}`, `{{OWNER}}`, `{{ESTIMATE}}`, `{{AC}}`, `{{DEPENDENCIES}}`
- Epic: `{{EPIC_ID}}`, `{{GOAL}}`, `{{OWNER}}`, `{{STORIES}}`
- ADR: `{{NUMBER}}`, `{{STATUS}}`, `{{CONTEXT}}`, `{{DECISION}}`, `{{CONSEQUENCES}}`
ACTIONS
### 1. List Templates
Show all available templates:
```markdown
# Available Templates
## Built-in Templates (docs/00-meta/templates/)
- story-template.md
- epic-template.md
- adr-template.md
- agent-profile-template.md
- comms-note-template.md
- research-template.md
- README-template.md
## Custom Templates (docs/00-meta/templates/custom/)
- meeting-notes.md (created 2025-10-15)
- incident-report.md (created 2025-10-10)
- sprint-retro.md (created 2025-10-01)
Usage: /AgileFlow:custom-template ACTION=use TYPE=custom NAME=meeting-notes
```
### 2. Create Template
Interactive template builder:
```
Creating new template: meeting-notes
Template type:
1. Meeting notes
2. Sprint retrospective
3. Incident report
4. Design proposal
5. Custom (blank)
Select (1-5): 1
--- Template Content ---
---
title: {{TITLE}}
date: {{DATE}}
attendees: {{ATTENDEES}}
---
# {{TITLE}}
**Date**: {{DATE}}
**Attendees**: {{ATTENDEES}}
## Agenda
1.
2.
3.
## Notes
### Topic 1
### Topic 2
## Action Items
- [ ] Task 1 (Owner: {{OWNER}}, Due: {{DUE_DATE}})
- [ ] Task 2
## Decisions Made
-
## Next Meeting
**Date**:
**Topics**:
--- End Template ---
Save to: docs/00-meta/templates/custom/meeting-notes.md
Proceed? (YES/NO)
```
### 3. Edit Template
Edit existing template:
```
Editing template: meeting-notes
Current path: docs/00-meta/templates/custom/meeting-notes.md
[Opens editor or shows diff with changes]
Save changes? (YES/NO)
```
### 4. Use Template
Generate document from template:
```
Using template: meeting-notes
Fill in template variables:
TITLE: Weekly Team Sync
ATTENDEES: Alice, Bob, Carol, Agent-UI, Agent-API
OWNER: Alice
Generated document preview:
---
title: Weekly Team Sync
date: 2025-10-16
attendees: Alice, Bob, Carol, Agent-UI, Agent-API
---
# Weekly Team Sync
**Date**: 2025-10-16
**Attendees**: Alice, Bob, Carol, Agent-UI, Agent-API
## Agenda
1.
2.
3.
[...]
Save to: docs/08-project/meetings/2025-10-16-weekly-sync.md
Proceed? (YES/NO)
```
EXAMPLE: Custom Template - Incident Report
```markdown
---
template: incident-report
version: 1.0
---
# Incident Report: {{TITLE}}
**ID**: INC-{{INCIDENT_ID}}
**Date**: {{DATE}}
**Severity**: {{SEVERITY}}
**Status**: {{STATUS}}
**Reporter**: {{REPORTER}}
---
## Summary
{{SUMMARY}}
---
## Timeline
| Time | Event |
|------|-------|
| {{TIME_1}} | {{EVENT_1}} |
| {{TIME_2}} | {{EVENT_2}} |
| {{TIME_3}} | {{EVENT_3}} |
---
## Impact
**Users Affected**: {{USERS_AFFECTED}}
**Duration**: {{DURATION}}
**Services**: {{SERVICES}}
---
## Root Cause
{{ROOT_CAUSE}}
---
## Resolution
{{RESOLUTION}}
---
## Prevention
### Immediate Actions
- [ ] {{ACTION_1}}
- [ ] {{ACTION_2}}
### Long-term Actions
- [ ] {{ACTION_3}} (Story: US-XXXX)
- [ ] {{ACTION_4}} (Story: US-XXXX)
---
## Related
- ADRs:
- Stories:
- PRs:
---
**Post-Incident Review**: {{PIR_DATE}}
```
EXAMPLE: Custom Template - Sprint Retrospective
```markdown
# Sprint {{SPRINT_NUMBER}} Retrospective
**Dates**: {{START_DATE}} to {{END_DATE}}
**Team**: {{TEAM}}
**Facilitator**: {{FACILITATOR}}
---
## Sprint Goals
### Planned
{{GOALS_PLANNED}}
### Achieved
{{GOALS_ACHIEVED}}
---
## Metrics
| Metric | Target | Actual | Status |
|--------|--------|--------|--------|
| Stories Completed | {{TARGET_STORIES}} | {{ACTUAL_STORIES}} | {{STATUS}} |
| Velocity | {{TARGET_VELOCITY}} | {{ACTUAL_VELOCITY}} | {{STATUS}} |
| Test Coverage | {{TARGET_COVERAGE}}% | {{ACTUAL_COVERAGE}}% | {{STATUS}} |
| Bugs | <{{MAX_BUGS}} | {{ACTUAL_BUGS}} | {{STATUS}} |
---
## What Went Well? 🎉
1.
2.
3.
---
## What Didn't Go Well? 😞
1.
2.
3.
---
## What Should We Try? 💡
1.
2.
3.
---
## Action Items
- [ ] {{ACTION_1}} (Owner: {{OWNER_1}}, Due: {{DUE_1}})
- [ ] {{ACTION_2}} (Owner: {{OWNER_2}}, Due: {{DUE_2}})
- [ ] {{ACTION_3}} (Owner: {{OWNER_3}}, Due: {{DUE_3}})
---
## Shoutouts 🙌
-
---
**Next Retrospective**: {{NEXT_RETRO_DATE}}
```
TEMPLATE REGISTRY
Store template metadata in `docs/00-meta/templates/registry.json`:
```json
{
"templates": [
{
"name": "meeting-notes",
"type": "custom",
"path": "docs/00-meta/templates/custom/meeting-notes.md",
"created": "2025-10-15",
"author": "Alice",
"description": "Weekly team meeting notes",
"variables": ["TITLE", "DATE", "ATTENDEES", "OWNER", "DUE_DATE"]
},
{
"name": "incident-report",
"type": "custom",
"path": "docs/00-meta/templates/custom/incident-report.md",
"created": "2025-10-10",
"author": "Bob",
"description": "Post-incident documentation",
"variables": ["INCIDENT_ID", "SEVERITY", "SUMMARY", "ROOT_CAUSE", ...]
}
]
}
```
WORKFLOW INTEGRATION
### Auto-suggest Templates
When creating certain documents, suggest templates:
```
Creating: docs/08-project/meetings/weekly-sync.md
Found matching template: meeting-notes
Use template? (YES/NO)
```
### Template Validation
Validate that required fields are filled:
```
Warning: Template variable {{ATTENDEES}} not filled in.
Continue anyway? (YES/NO)
```
### Template Versioning
Track template versions:
```markdown
---
template: incident-report
version: 2.0
changelog: Added "Prevention" section
---
```
SHARING TEMPLATES
Templates in `docs/00-meta/templates/custom/` are committed to repo, so:
- ✅ Teams share consistent templates
- ✅ Templates are versioned with code
- ✅ Can review template changes in PRs
INTEGRATION
### Story Creation
When `/AgileFlow:story-new` is called, use story-template.md:
```bash
/AgileFlow:story-new EPIC=EP-0001 STORY=US-0050 TITLE="Login form"
# Internally uses docs/00-meta/templates/story-template.md
```
### Custom Story Templates
Teams can override default templates:
```
If docs/00-meta/templates/custom/story-template.md exists:
Use custom template
Else:
Use built-in template
```
RULES
- Template variables MUST use {{VARIABLE_NAME}} format
- Built-in templates cannot be deleted (only overridden)
- Custom templates saved to docs/00-meta/templates/custom/
- Template names must be unique
- Diff-first, YES/NO before saving templates
- Preview generated documents before saving
OUTPUT
- List of available templates (if ACTION=list)
- New template file (if ACTION=create)
- Updated template file (if ACTION=edit)
- Generated document from template (if ACTION=use)
- Updated registry.json

342
commands/tests.md Normal file
View File

@@ -0,0 +1,342 @@
---
description: setup-tests
allowed-tools: Bash, Read, Edit, Write, Glob, Grep
---
# setup-tests
Automatically set up testing infrastructure for projects without existing tests.
## Prompt
ROLE: Test Infrastructure Bootstrapper
OBJECTIVE
Detect project type and set up appropriate testing framework with example tests and CI integration.
INPUTS (optional)
- FRAMEWORK=auto|jest|mocha|pytest|rspec|go-test|cargo-test (default: auto-detect)
- COVERAGE=yes|no (default: yes)
- E2E=yes|no (default: no, ask if needed)
PROJECT DETECTION
1. Detect language/runtime:
- Node.js: package.json
- Python: requirements.txt, pyproject.toml
- Ruby: Gemfile
- Go: go.mod
- Rust: Cargo.toml
- Java: pom.xml, build.gradle
- .NET: *.csproj
2. Detect framework (if applicable):
- React, Vue, Angular (npm deps)
- Django, Flask, FastAPI (Python imports)
- Rails, Sinatra (Gemfile)
3. Check existing test setup:
- Test directories: test/, tests/, __tests__/, spec/
- Test config: jest.config.js, pytest.ini, .rspec
- CI config: .github/workflows/*test*
SETUP ACTIONS
### For Node.js (Jest)
```bash
npm install --save-dev jest @types/jest ts-jest
# If TypeScript: npm install --save-dev @types/jest ts-jest
# If React: npm install --save-dev @testing-library/react @testing-library/jest-dom
```
Create jest.config.js:
```javascript
module.exports = {
preset: 'ts-jest',
testEnvironment: 'node',
coverageDirectory: 'coverage',
collectCoverageFrom: [
'src/**/*.{js,ts}',
'!src/**/*.d.ts',
'!src/**/*.spec.ts'
],
coverageThreshold: {
global: {
branches: 70,
functions: 70,
lines: 70,
statements: 70
}
}
};
```
### For Python (pytest)
```bash
pip install pytest pytest-cov pytest-mock
```
Create pytest.ini:
```ini
[pytest]
testpaths = tests
python_files = test_*.py *_test.py
python_classes = Test*
python_functions = test_*
addopts = --cov=src --cov-report=html --cov-report=term
```
### For Ruby (RSpec)
```ruby
# Add to Gemfile
group :test do
gem 'rspec'
gem 'rspec-rails' # if Rails
gem 'factory_bot'
gem 'simplecov'
end
```
```bash
bundle install
rspec --init
```
CREATE EXAMPLE TESTS
### Unit Test Example (Node.js/Jest)
```typescript
// tests/unit/example.test.ts
describe('Example Test Suite', () => {
it('should pass this example test', () => {
expect(true).toBe(true);
});
it('should test basic math', () => {
expect(2 + 2).toBe(4);
});
});
```
### Component Test Example (React)
```typescript
// tests/components/Button.test.tsx
import { render, screen, fireEvent } from '@testing-library/react';
import Button from '@/components/Button';
describe('Button Component', () => {
it('renders with text', () => {
render(<Button>Click Me</Button>);
expect(screen.getByText('Click Me')).toBeInTheDocument();
});
it('calls onClick when clicked', () => {
const handleClick = jest.fn();
render(<Button onClick={handleClick}>Click</Button>);
fireEvent.click(screen.getByText('Click'));
expect(handleClick).toHaveBeenCalledTimes(1);
});
});
```
### API Test Example (Integration)
```typescript
// tests/integration/api.test.ts
import request from 'supertest';
import app from '@/app';
describe('API Integration Tests', () => {
it('GET / should return 200', async () => {
const response = await request(app).get('/');
expect(response.status).toBe(200);
});
it('POST /api/users should create user', async () => {
const response = await request(app)
.post('/api/users')
.send({ name: 'Test User', email: 'test@example.com' });
expect(response.status).toBe(201);
expect(response.body).toHaveProperty('id');
});
});
```
DIRECTORY STRUCTURE
Create:
```
tests/
├── unit/ # Unit tests (isolated functions/classes)
├── integration/ # Integration tests (multiple components)
├── e2e/ # End-to-end tests (full user flows) [if E2E=yes]
├── fixtures/ # Test data
└── helpers/ # Test utilities
```
E2E SETUP (if E2E=yes)
### Playwright (recommended)
```bash
npm install --save-dev @playwright/test
npx playwright install
```
Create playwright.config.ts and example E2E test:
```typescript
// tests/e2e/login.spec.ts
import { test, expect } from '@playwright/test';
test('user can log in', async ({ page }) => {
await page.goto('http://localhost:3000/login');
await page.fill('input[name="email"]', 'test@example.com');
await page.fill('input[name="password"]', 'password123');
await page.click('button[type="submit"]');
await expect(page).toHaveURL('http://localhost:3000/dashboard');
});
```
CI INTEGRATION
Add to .github/workflows/ci.yml (or create):
```yaml
test:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- name: Setup Node
uses: actions/setup-node@v4
with:
node-version: '20'
cache: 'npm'
- name: Install dependencies
run: npm ci
- name: Run tests
run: npm test -- --coverage
- name: Upload coverage
uses: codecov/codecov-action@v3
with:
files: ./coverage/lcov.info
```
NPM SCRIPTS
Add to package.json:
```json
{
"scripts": {
"test": "jest",
"test:watch": "jest --watch",
"test:coverage": "jest --coverage",
"test:unit": "jest tests/unit",
"test:integration": "jest tests/integration",
"test:e2e": "playwright test"
}
}
```
DOCUMENTATION
Create docs/02-practices/testing.md:
```markdown
# Testing Guide
## Running Tests
\`\`\`bash
npm test # Run all tests
npm run test:watch # Watch mode
npm run test:coverage # With coverage report
npm run test:unit # Unit tests only
\`\`\`
## Writing Tests
### Unit Tests
- Test individual functions/classes in isolation
- Mock external dependencies
- Fast (<10ms per test)
### Integration Tests
- Test multiple components together
- Use real dependencies when possible
- Medium speed (<100ms per test)
### E2E Tests
- Test full user flows
- Run against real app
- Slow (seconds per test)
## Coverage Requirements
- Minimum 70% coverage (enforced in CI)
- New code should be 90%+ covered
- Critical paths require 100% coverage
## Best Practices
- Use descriptive test names (Given/When/Then)
- One assertion per test when possible
- Avoid test interdependence
- Use factories/fixtures for test data
```
WORKFLOW
1. Detect project type and existing setup
2. Show proposed setup plan (diff-first):
```
Will install:
- jest, @types/jest, ts-jest
- @testing-library/react, @testing-library/jest-dom
Will create:
- jest.config.js
- tests/unit/example.test.ts
- tests/integration/api.test.ts
- docs/02-practices/testing.md
Will update:
- package.json (add test scripts)
- .github/workflows/ci.yml (add test job)
```
3. Ask: "Proceed with test setup? (YES/NO)"
4. If YES:
- Run installations
- Create config files
- Create example tests
- Update CI
- Run tests to verify setup
5. Show results:
```
✅ Testing framework installed
✅ Example tests created
✅ CI integration added
Try running: npm test
```
INTEGRATION
- Create story: "US-XXXX: Set up testing infrastructure"
- Update docs/02-practices/testing.md
- Suggest setting required checks in GitHub
RULES
- Preview all changes (diff-first, YES/NO)
- Run test suite after setup to verify
- Create working examples, not just config
- Document how to run and write tests
- Integrate with CI immediately
- Set reasonable coverage thresholds (not 100%)
OUTPUT
- Setup summary
- Test framework configuration
- Example tests (unit + integration + E2E if requested)
- CI integration
- Testing documentation

407
commands/update.md Normal file
View File

@@ -0,0 +1,407 @@
---
description: stakeholder-update
allowed-tools: Bash, Read, Edit, Write, Glob, Grep
---
# stakeholder-update
Generate stakeholder communication updates from project status.
## Prompt
ROLE: Stakeholder Communication Generator
OBJECTIVE
Automatically generate high-level project updates suitable for stakeholders, executives, or clients.
INPUTS (optional)
- PERIOD=week|sprint|month|quarter|custom (default: week)
- START_DATE=<YYYY-MM-DD> (optional: for custom period)
- END_DATE=<YYYY-MM-DD> (optional: for custom period)
- AUDIENCE=exec|client|team|board (default: exec)
- FORMAT=email|markdown|slides|pdf (default: markdown)
DATA SOURCES
Aggregate information from:
1. **Status**: docs/09-agents/status.json
2. **Epics**: docs/05-epics/*.md
3. **Stories**: docs/06-stories/**/US-*.md
4. **Backlog**: docs/08-project/backlog.md
5. **Roadmap**: docs/08-project/roadmap.md
6. **Milestones**: docs/08-project/milestones.md
7. **Risks**: docs/08-project/risks.md
8. **Git History**: Commits, PRs merged
9. **Bus Log**: docs/09-agents/bus/log.jsonl (for context)
10. **ADRs**: docs/03-decisions/adr-*.md (recent decisions)
UPDATE STRUCTURE
### Executive Summary
- 2-3 sentence overview
- Key accomplishments
- Critical issues (if any)
- Overall status (On Track / At Risk / Blocked)
### Progress This Period
- Stories completed
- Epics progress
- Milestones reached
### Upcoming Work
- Next priorities
- Upcoming milestones
### Metrics
- Velocity
- Completion rate
- Quality metrics
### Blockers & Risks
- Current blockers
- Risk mitigation
### Decisions Made
- Recent ADRs
### Budget/Resources (if applicable)
- Sprint capacity used
- Team changes
EXAMPLE OUTPUT (Email Format)
```markdown
Subject: Weekly Update - Project XYZ (Oct 9-16, 2025)
Hi Team,
Here's this week's progress update for Project XYZ.
---
## 📊 Executive Summary
**Status**: 🟢 On Track
We completed the user authentication epic this week, delivering all planned features on schedule. The team is now focused on the payment integration milestone. No critical blockers at this time.
**Key Highlights**:
- ✅ User authentication fully implemented and tested
- ✅ 12 stories completed (velocity: 18 points)
- 🎯 Payment integration on track for end-of-month launch
---
## ✅ Completed This Week
### Epic: User Authentication (EP-0010) - 100%
- ✅ US-0050: User registration with email verification
- ✅ US-0051: Login with session management
- ✅ US-0052: Password reset flow
- ✅ US-0053: OAuth login (Google)
- ✅ US-0054: Rate limiting for security
**Impact**: Users can now create accounts, log in securely, and reset passwords. OAuth support enables faster onboarding.
### Other Completions
- ✅ US-0048: Improved dashboard loading time by 60%
- ✅ US-0049: Fixed critical bug in payment processing
---
## 🚀 In Progress
### Epic: Payment Integration (EP-0011) - 40%
- 🔄 US-0060: Stripe integration (in review)
- 🔄 US-0061: Checkout flow UI (in progress)
- ⏳ US-0062: Invoice generation (ready to start)
**Expected Completion**: October 30, 2025
---
## 📅 Upcoming Priorities (Next Week)
1. **Complete payment integration MVP** (EP-0011)
- Finish Stripe integration
- Build and test checkout flow
- Generate invoices
2. **Start notification system** (EP-0012)
- Email notifications for key events
- In-app notification center
3. **Address technical debt**
- Refactor auth service (improves maintainability)
- Add missing integration tests
---
## 📈 Metrics
| Metric | This Week | Last Week | Trend |
|--------|-----------|-----------|-------|
| Stories Completed | 12 | 10 | ↗️ +20% |
| Velocity (points) | 18 | 15 | ↗️ +20% |
| Test Coverage | 87% | 85% | ↗️ +2% |
| Open Bugs | 3 | 5 | ↗️ -40% |
| Deployment Success Rate | 100% | 95% | ↗️ +5% |
**Sprint Burndown**: On track. 18 of 20 planned points completed.
---
## 🎯 Milestone Progress
### Q4 2025 Roadmap
- ✅ **User Authentication** (Oct 16) - COMPLETED
- 🔄 **Payment Integration** (Oct 30) - 40% complete, on track
- ⏳ **Public Beta Launch** (Nov 15) - On schedule
- ⏳ **Mobile App MVP** (Dec 1) - Planning phase
---
## ⚠️ Blockers & Risks
### Current Blockers
*None at this time*
### Risks Being Monitored
1. **Stripe API rate limits** (Medium Risk)
- *Mitigation*: Implementing request queuing and caching
- *Owner*: AG-API
- *Status*: Mitigation in progress
2. **Third-party OAuth service downtime** (Low Risk)
- *Mitigation*: Fallback to email login always available
- *Owner*: AG-API
- *Status*: Fallback implemented
---
## 🏗️ Key Decisions Made
### ADR-0015: Use Stripe for payment processing
**Decision**: Selected Stripe over PayPal for payment integration
**Rationale**: Better developer experience, lower fees, excellent documentation
**Impact**: Faster integration, reduced costs
### ADR-0016: Implement JWT-based authentication
**Decision**: Use JWT tokens with 15-minute expiry + refresh tokens
**Rationale**: Stateless, scalable, industry-standard
**Impact**: Simplified auth architecture
---
## 👥 Team Updates
- Team velocity increased 20% this week (improved planning)
- AG-CI agent optimized CI pipeline (reduced build time from 8min → 5min)
- No team changes
---
## 📦 Releases
- **v1.3.0** deployed to production (Oct 15)
- User authentication features
- Performance improvements
- Security patches
---
## 💬 Additional Notes
The team is performing well and morale is high after completing the auth epic ahead of schedule. We're confident in hitting the October 30 payment integration milestone.
Next stakeholder update: October 23, 2025
---
Best regards,
Project Team
---
*Generated with AgileFlow /stakeholder-update*
*Data sources: status.json, epics, stories, git history*
```
AUDIENCE CUSTOMIZATION
### Executive (C-level)
- Very high-level
- Focus on business impact
- Include metrics and ROI
- Highlight risks early
- 1-page max
### Client
- Feature-focused
- Emphasize user benefits
- Transparent about issues
- Include screenshots/demos
- Show progress toward contract deliverables
### Team
- More technical detail
- Include architecture decisions
- Celebrate wins
- Retrospective insights
- Action items
### Board
- Strategic overview
- Financial implications
- Competitive positioning
- Long-term roadmap
- Risk assessment
FORMAT VARIATIONS
### Email (default)
Plain text or HTML email ready to send
### Markdown
For posting to internal wikis, Notion, etc.
### Slides
Generate slide deck outline:
```markdown
Slide 1: Title
- Project XYZ Update
- Week of Oct 9-16, 2025
Slide 2: Executive Summary
- Status: On Track
- 12 stories completed
- Auth epic finished
Slide 3: Progress This Week
- [Bullet points]
Slide 4: Metrics Dashboard
- [Charts/graphs data]
Slide 5: Next Priorities
- [Upcoming work]
Slide 6: Risks & Mitigation
- [Risk table]
```
### PDF
Formatted report with:
- Cover page
- Table of contents
- Charts/graphs
- Appendices
METRICS & VISUALIZATION
Include data visualizations (as ASCII art or suggest tools):
```
Sprint Burndown Chart (Remaining Points)
20 │ ●
18 │ ╱
16 │ ●
14 │ ╱
12 │ ●
10 │╱
8 │●
6 │ ╲
4 │ ●
2 │ ╲
0 │ ●
└────────────
M T W T F
● = Actual
╱╲ = Ideal
```
Or suggest: "Generate charts with Chart.js / Google Sheets / Tableau"
AUTOMATION
### Scheduled Reports
Suggest adding to CI:
```yaml
- cron: '0 9 * * 1' # Every Monday at 9am
jobs:
stakeholder-update:
runs-on: ubuntu-latest
steps:
- name: Generate update
run: npx claude-code /AgileFlow:stakeholder-update PERIOD=week
- name: Email stakeholders
uses: dawidd6/action-send-mail@v3
with:
server_address: smtp.gmail.com
subject: Weekly Project Update
body: file://update.md
to: stakeholders@example.com
```
### Slack/Discord Integration
Post summary to team channels
WORKFLOW
1. Determine period (this week, last sprint, etc.)
2. Collect data from all sources
3. Calculate metrics and trends
4. Identify completed work
5. Identify blockers and risks
6. Format for audience
7. Preview (show to user)
8. Ask: "Send update? (YES/NO/EDIT)"
9. If YES:
- Save to docs/08-project/updates/<YYYYMMDD>-update.md
- Optionally email stakeholders
- Log to bus/log.jsonl
INTEGRATION
- Link to epics and stories for details
- Reference ADRs for context on decisions
- Include GitHub PR links
- Optionally attach screenshots or demo videos
CUSTOMIZATION
Read project-specific settings from `.agileflow/stakeholder-config.json`:
```json
{
"stakeholders": {
"exec": ["ceo@example.com", "cto@example.com"],
"client": ["client@example.com"],
"board": ["board@example.com"]
},
"schedule": {
"exec": "weekly",
"client": "bi-weekly",
"board": "monthly"
},
"metrics": ["velocity", "coverage", "bugs"],
"includeFinancials": false
}
```
RULES
- Always be honest about blockers and risks
- Focus on business value, not technical jargon (for exec/client)
- Include specific numbers and metrics
- Highlight trends (improving/declining)
- Preview before sending (diff-first, YES/NO)
- Save all updates to docs/08-project/updates/ for history
- Never expose sensitive data (credentials, internal conflicts)
OUTPUT
- Stakeholder update (formatted for audience)
- Saved to docs/08-project/updates/
- Optional: Email sent to stakeholders
- Log entry in bus/log.jsonl

369
commands/velocity.md Normal file
View File

@@ -0,0 +1,369 @@
---
description: velocity
allowed-tools: Bash, Read, Edit, Write, Glob, Grep
---
# velocity
Track team velocity, calculate trends, and forecast completion dates.
## Prompt
ROLE: Velocity Analyst & Forecaster
OBJECTIVE
Calculate team velocity from completed stories, identify trends, and forecast epic/milestone completion dates.
INPUTS (optional)
- PERIOD=week|sprint|month|all (default: sprint - last 2 weeks)
- FORECAST=<EPIC_ID or milestone> (predict completion date)
- FORMAT=report|chart|json (default: report)
DATA SOURCES
1. **Story Completion Data**
- docs/09-agents/status.json (current state)
- docs/09-agents/bus/log.jsonl (historical status changes)
- docs/06-stories/**/US-*.md (story estimates and metadata)
2. **Epic/Milestone Data**
- docs/05-epics/*.md (epic definitions)
- docs/08-project/milestones.md (milestone targets)
VELOCITY CALCULATION
### Story Points Completed
Parse bus/log.jsonl for status changes to "done":
```json
{"ts":"2025-10-10T10:00:00Z","type":"status","story":"US-0030","status":"done"}
{"ts":"2025-10-11T14:30:00Z","type":"status","story":"US-0031","status":"done"}
```
For each story, get estimate from story file frontmatter:
```yaml
estimate: 1.5d
```
Convert to points (1d = 1 point) and sum by time period.
### Velocity Calculation
```
Velocity = Total points completed / Number of time periods
```
Example:
- Week 1: 8 points
- Week 2: 10 points
- Week 3: 7 points
- **Average velocity**: (8+10+7)/3 = **8.3 points/week**
VELOCITY REPORT
```markdown
# Velocity Report
**Generated**: 2025-10-17 14:30
**Period**: Last 4 sprints (8 weeks)
**Team**: AG-UI, AG-API, AG-CI, AG-DEVOPS
---
## 📊 Current Velocity
**Average**: 8.3 points/week
**Trend**: ↗️ +15% (improving)
**Last sprint**: 10 points
**Best sprint**: 12 points (Week of 2025-09-15)
**Worst sprint**: 5 points (Week of 2025-09-01)
---
## 📈 Historical Velocity
```
Points
12 │ ●
11 │ ╱
10 │ ● ● ●
9 │ ╱ ╲ ╱
8 │ ● ●
7 │ ●
6 │ ╱
5 │ ● ●
4 │ ╱
3 │
└────────────────────
W1 W2 W3 W4 W5 W6 W7 W8
Trend line: ─── (moving average)
Actual: ● ─ ●
```
**Weekly Breakdown**:
| Week | Points | Stories | Avg Size | Notes |
|------|--------|---------|----------|-------|
| 2025-10-14 | 10 | 6 | 1.7d | ↗️ +25% |
| 2025-10-07 | 8 | 5 | 1.6d | ↗️ +14% |
| 2025-09-30 | 7 | 4 | 1.8d | ↘️ -30% |
| 2025-09-23 | 10 | 7 | 1.4d | ↗️ +100% |
| 2025-09-16 | 5 | 3 | 1.7d | ↘️ -50% |
| 2025-09-09 | 10 | 6 | 1.7d | - |
**Insights**:
- Velocity is trending upward (+15% over 6 weeks)
- Best performance when story size ≤1.5d
- Week of 2025-09-23 had highest throughput (7 stories)
- Consistency improving (std dev: 2.1 → 1.8)
---
## 👥 Velocity by Owner
| Owner | Points/Week | Stories/Week | Utilization | Trend |
|-------|-------------|--------------|-------------|-------|
| AG-UI | 3.2 | 2.1 | 80% | ↗️ +10% |
| AG-API | 4.1 | 2.8 | 85% | ↗️ +20% |
| AG-CI | 0.8 | 0.6 | 40% | → Stable |
| AG-DEVOPS | 0.2 | 0.2 | 10% | 🆕 New |
**Observations**:
- AG-API is the team workhorse (4.1 pts/wk)
- AG-CI underutilized (consider more stories)
- AG-DEVOPS just started (too early for trends)
---
## 🎯 Forecast: Epic Completion
### EP-0010: User Authentication
- **Stories**: 12 total
- **Completed**: 8 (66%)
- **Remaining**: 4 stories, 6 points
- **At current velocity** (8.3 pts/wk): **< 1 week**
- **Forecast completion**: **2025-10-24** (7 days)
- **Confidence**: High (85%)
### EP-0011: Payment Integration
- **Stories**: 8 total
- **Completed**: 2 (25%)
- **Remaining**: 6 stories, 9 points
- **At current velocity** (8.3 pts/wk): **~1.1 weeks**
- **Forecast completion**: **2025-10-28** (11 days)
- **Confidence**: Medium (70%)
### Milestone: Public Beta Launch
- **Target date**: 2025-11-15
- **Total remaining**: 15 stories, 24 points
- **Weeks needed**: 24/8.3 = **2.9 weeks**
- **Forecast completion**: **2025-11-07** (21 days)
- **Status**: ✅ **On track** (8 days buffer)
- **Risk level**: Low
---
## ⚠️ Risk Analysis
### Velocity Risks
1. **AG-API dependency**: 50% of points from one agent
- *Mitigation*: Cross-train, pair programming
2. **Story size variance**: Some 2d stories slow velocity
- *Mitigation*: Split stories >1.5d
3. **Seasonal slowdown**: Historical dip in Week 5
- *Mitigation*: Add buffer to forecasts
### Schedule Risks
- EP-0011 blocking Milestone: Public Beta
- If velocity drops 20% → Beta delayed to 2025-11-12
- If AG-API unavailable → 50% velocity loss
---
## 📅 Capacity Planning
**Current Capacity**: 8.3 points/week (4 agents)
**Recommendations**:
1. **This Sprint** (2 weeks):
- Plan: 16-18 points (2x velocity)
- Buffer: Keep 2-3 ready stories
- Focus: Complete EP-0010
2. **Next Sprint**:
- Plan: 16-20 points
- Priority: EP-0011 (Beta blocker)
- Consider: Add stories for AG-CI (underutilized)
3. **Long-term**:
- Maintain 8-10 points/week sustained velocity
- Reserve 20% for tech debt (/AgileFlow:tech-debt command)
- Keep story sizes ≤1.5d for predictability
---
## 🎯 Velocity Goals
**Current**: 8.3 points/week
**Target**: 10 points/week (by end of quarter)
**Stretch**: 12 points/week
**Action Items**:
- [ ] Split 2 large stories (US-0050, US-0051)
- [ ] Assign 2 more stories to AG-CI
- [ ] Review blockers (US-0041)
- [ ] Celebrate hitting 10 pts/wk milestone! 🎉
---
## 📊 Export Options
Save this report?
- `docs/08-project/velocity/velocity-2025-10-17.md`
- Update velocity dashboard
- Add to stakeholder update
```
FORECASTING ALGORITHM
### Simple Linear Forecast
```
Days to complete = (Remaining points / Velocity) * 7
Completion date = Today + Days to complete
```
### Confidence Calculation
```
Confidence = 100% - (Velocity std dev / Velocity avg) * 100
High confidence: >80% (stable velocity)
Medium: 60-80% (some variance)
Low: <60% (high variance, unreliable)
```
### Monte Carlo Simulation (optional, advanced)
Run 1000 simulations with velocity variance:
```
For each simulation:
- Sample velocity from normal distribution (mean, std dev)
- Calculate completion date
- Record result
Forecast:
- P50 (median): 50% chance of completing by this date
- P80: 80% chance
- P90: 90% chance (conservative estimate)
```
VELOCITY CHART (ASCII Art)
```
Velocity Trend (8 weeks)
Points/Week
12 ┤ ●●●
11 ┤ ●
10 ┤ ●● ●
9 ┤ ● ●
8 ┤ ● ← Current (8.3 avg)
7 ┤ ●
6 ┤ ●
5 ┤ ● ●
4 ┤ ●
3 ┤
└─────────────────────────────────────
W1 W2 W3 W4 W5 W6 W7 W8
Legend:
● Actual velocity
─ Trend line (moving average)
↗️ Trend: +15% over period
```
VELOCITY BY STORY SIZE
```
Velocity by Story Size
Size | Count | Avg Days | Success Rate
--------|-------|----------|-------------
≤0.5d | 8 | 0.4d | 100% ✅
0.5-1d | 12 | 0.9d | 92% ✅
1-1.5d | 10 | 1.3d | 80% ⚠️
1.5-2d | 6 | 2.1d | 67% ⚠️
>2d | 3 | 3.5d | 33% 🔴
**Insight**: Stories ≤1d complete faster and more reliably.
**Recommendation**: Split stories >1.5d into smaller increments.
```
JSON OUTPUT (for tooling)
```json
{
"generated": "2025-10-17T14:30:00Z",
"period": "8 weeks",
"velocity": {
"current": 8.3,
"trend": "+15%",
"last_sprint": 10,
"best": 12,
"worst": 5,
"std_dev": 2.1
},
"by_owner": {
"AG-UI": 3.2,
"AG-API": 4.1,
"AG-CI": 0.8,
"AG-DEVOPS": 0.2
},
"forecasts": [
{
"epic": "EP-0010",
"remaining_points": 6,
"weeks_needed": 0.7,
"completion_date": "2025-10-24",
"confidence": 85
}
],
"risks": [
{
"type": "dependency",
"description": "50% of points from AG-API",
"severity": "medium"
}
]
}
```
WORKFLOW
1. Parse bus/log.jsonl for "done" status changes
2. Match stories to estimates from frontmatter
3. Group completions by time period (week/sprint)
4. Calculate velocity stats (avg, trend, std dev)
5. If FORECAST specified:
- Calculate remaining points
- Apply velocity to forecast completion
- Calculate confidence level
6. Render report/chart
7. Suggest actions based on findings
INTEGRATION
- Save velocity history to docs/08-project/velocity/
- Update /AgileFlow:stakeholder-update with velocity data
- Alert if velocity drops >20% from average
- Suggest sprint planning capacity based on velocity
RULES
- Always calculate over at least 3 time periods (for reliability)
- Warn if sample size too small (<5 stories)
- Exclude outliers (stories >3x avg) from velocity calc
- Account for holidays/time off in forecasts
- Update forecast confidence based on variance
OUTPUT
- Velocity report (markdown/chart/json)
- Trend analysis
- Forecasts for epics/milestones
- Risk analysis
- Action items