agileflow 2.91.0 → 2.92.0

package/src/core/commands/epic.md

@@ -362,3 +362,116 @@ Suggested actions:
 - `/agileflow:story:list` - View all stories
 - `/agileflow:sprint` - Plan sprint with epic stories
 - `/agileflow:board` - Visual kanban board
+
+---
+
+## Expected Output
+
+### Successful Epic Creation
+
+```
+📦 Creating Epic: EP-0010
+
+Title: User Authentication System
+Owner: AG-API
+Goal: Enable secure user login with OAuth support
+
+Files to create:
+───────────────────────────
+1. docs/05-epics/EP-0010.md
+   - Epic definition with goal and stories
+
+2. docs/06-stories/EP-0010/US-0042-login-form.md
+   - Story: Login Form (AG-UI)
+
+3. docs/06-stories/EP-0010/US-0043-oauth-integration.md
+   - Story: OAuth Integration (AG-API)
+
+4. docs/06-stories/EP-0010/US-0044-session-management.md
+   - Story: Session Management (AG-API)
+
+5. docs/09-agents/status.json (merge)
+   + "EP-0010": {
+   +   "id": "EP-0010",
+   +   "owner": "AG-API",
+   +   "status": "active",
+   +   "stories": ["US-0042", "US-0043", "US-0044"]
+   + }
+   + "US-0042": { "epic": "EP-0010", "owner": "AG-UI", "status": "ready" }
+   + "US-0043": { "epic": "EP-0010", "owner": "AG-API", "status": "ready" }
+   + "US-0044": { "epic": "EP-0010", "owner": "AG-API", "status": "ready" }
+
+6. docs/09-agents/bus/log.jsonl (append)
+   + {"type":"assign","to":"AG-API","epic":"EP-0010","text":"Epic created"}
+   + {"type":"assign","to":"AG-UI","story":"US-0042","text":"Story created"}
+   + {"type":"assign","to":"AG-API","story":"US-0043","text":"Story created"}
+   + {"type":"assign","to":"AG-API","story":"US-0044","text":"Story created"}
+
+[AskUserQuestion: "Create epic EP-0010 with 3 stories?"]
+
+✅ Epic EP-0010 created successfully!
+✅ Created 3 stories: US-0042, US-0043, US-0044
+✅ Bus messages sent to assigned owners
+
+[AskUserQuestion: "What would you like to do next?"]
+```
+
+### Research Validation Warning
+
+```
+📦 Creating Epic: EP-0010 (5 stories)
+
+⚠️  Research Check
+
+This epic has no linked research.
+Complex features (3+ stories) benefit from research-first planning.
+
+[AskUserQuestion: "What would you like to do?"]
+  - Create research first (Recommended)
+  - Continue without research
+  - Link existing research
+```
+
+### With Linked Research
+
+```
+📦 Creating Epic: EP-0010
+
+Research linked: 20260121-auth-system-analysis.md
+
+✅ Research file validated
+✅ Key findings extracted:
+   • OAuth 2.0 recommended over custom auth
+   • JWT for session tokens
+   • 3 integration points identified
+
+[Proceeding with epic creation...]
+```
+
+### Validation Error
+
+```
+❌ Invalid STORIES format
+
+Received: US-0042,US-0043
+Expected: US-0042|title|owner,US-0043|title|owner
+
+Format: "US-ID|title|owner,US-ID2|title2|owner2"
+
+Example:
+STORIES="US-0042|Login Form|AG-UI,US-0043|OAuth|AG-API"
+```
+
+### Epic Already Exists
+
+```
+❌ Epic EP-0010 already exists
+
+Existing epic:
+  Title: User Authentication System
+  Status: in_progress
+  Stories: 3 (1 done, 2 in progress)
+
+To add stories, use:
+  /agileflow:story EPIC=EP-0010 STORY=US-00XX TITLE="..." OWNER=...
+```

package/src/core/commands/handoff.md

@@ -246,3 +246,131 @@ ACTIONS
 2) Append bus line type="handoff".
 
 Diff-first; YES/NO.
+
+---
+
+## Expected Output
+
+### Successful Handoff
+
+```
+📋 Creating Handoff: US-0042
+
+From: AG-API
+To: AG-UI
+Summary: Completed auth endpoints, tests passing
+
+Files to create:
+───────────────────────────────────────────────
+1. docs/09-agents/comms/US-0042-20260121-handoff.md
+
+Preview:
+─────────────────────────────────────────────
+# Handoff: US-0042
+
+**From**: AG-API
+**To**: AG-UI
+**Date**: 2026-01-21
+
+## Summary
+Completed all authentication API endpoints including login, logout, and token refresh.
+Unit and integration tests passing (14 tests).
+
+## Work Completed
+- POST /api/auth/login endpoint
+- POST /api/auth/logout endpoint
+- POST /api/auth/refresh endpoint
+- JWT token generation with 1h expiry
+- Integration tests with mocked database
+
+## Blockers
+- None - API is ready for UI integration
+
+## Notes for Next Agent
+- Use the `useAuth` hook for token management
+- Login endpoint returns { token, user } on success
+- Error responses use standard { error, code } format
+- See docs/04-architecture/auth-api.md for full spec
+
+## Files Modified
+- src/api/auth/login.ts
+- src/api/auth/logout.ts
+- src/api/auth/refresh.ts
+- tests/api/auth/*.test.ts
+─────────────────────────────────────────────
+
+2. docs/09-agents/bus/log.jsonl (append)
+   + {"ts":"2026-01-21T14:30:00Z","type":"handoff","story":"US-0042","from":"AG-API","to":"AG-UI","summary":"Completed auth endpoints"}
+
+[AskUserQuestion: "Create this handoff?"]
+
+✅ Handoff created successfully!
+   Note: docs/09-agents/comms/US-0042-20260121-handoff.md
+   Bus log updated: handoff event appended
+```
+
+### Missing Required Inputs
+
+```
+❌ Missing required inputs
+
+Please provide:
+  • STORY - Story ID (e.g., US-0042)
+  • FROM - Source agent (e.g., AG-API)
+  • TO - Target agent (e.g., AG-UI)
+  • SUMMARY - What was done
+
+Usage:
+/agileflow:handoff STORY=US-0042 FROM=AG-API TO=AG-UI SUMMARY="Completed auth endpoints"
+
+Optional:
+  • BLOCKERS - Issues for next agent (e.g., "Need DBA review")
+```
+
+### Handoff with Blockers
+
+```
+📋 Creating Handoff: US-0042
+
+From: AG-API
+To: AG-UI
+Summary: Completed auth endpoints
+Blockers: 2 identified
+
+Files to create:
+───────────────────────────────────────────────
+1. docs/09-agents/comms/US-0042-20260121-handoff.md
+
+## Blockers
+
+⚠️ The following blockers need attention:
+
+1. **Database migration pending**
+   Schema changes need DBA review before deployment.
+   Related: ADR-0015 (database upgrade strategy)
+
+2. **Rate limiting not configured**
+   Need to decide on rate limits for login endpoint.
+   Suggest: /agileflow:adr for rate limiting decision
+
+[AskUserQuestion: "Create handoff with blockers?"]
+```
+
+### Invalid Agent ID
+
+```
+❌ Invalid agent ID: AG-UNKNOWN
+
+Valid agent IDs:
+  • AG-UI - UI/frontend specialist
+  • AG-API - API/backend specialist
+  • AG-DATABASE - Database specialist
+  • AG-CI - CI/CD specialist
+  • AG-TESTING - Testing specialist
+  • AG-DEVOPS - DevOps specialist
+
+Check the FROM and TO parameters.
+
+Usage:
+/agileflow:handoff STORY=US-0042 FROM=AG-API TO=AG-UI SUMMARY="..."
+```

package/src/core/commands/help.md

@@ -92,3 +92,78 @@ Print a concise, one-screen overview:
 <!-- {{COMMAND_LIST}} -->
 
 OUTPUT: plain markdown only (no file writes)
+
+---
+
+## Expected Output
+
+```markdown
+# AgileFlow System Overview
+
+## Folder Structure
+
+```
+docs/
+├── 00-meta/           # Metadata and configuration
+├── 01-brainstorming/  # Ideas and proposals
+├── 02-practices/      # Development guidelines
+├── 03-decisions/      # Architecture Decision Records (ADRs)
+├── 04-architecture/   # System design documentation
+├── 05-epics/          # Epic definitions (EP-XXXX.md)
+├── 06-stories/        # User stories by epic (US-XXXX-<slug>.md)
+├── 07-testing/        # Test plans and coverage
+├── 08-project/        # Project overview, roadmaps, reviews
+├── 09-agents/         # Agent communication
+│   ├── status.json    # Story/epic status tracking
+│   └── bus/log.jsonl  # Inter-agent message bus
+└── 10-research/       # Research notes and findings
+```
+
+## Key Concepts
+
+**Epics** (EP-XXXX): Large features broken into stories
+**Stories** (US-XXXX): Work items with acceptance criteria
+**ADRs**: Architecture Decision Records for technical choices
+**status.json**: Central source of truth for story/epic status
+**bus/log.jsonl**: Async message bus for agent coordination
+
+## Daily Workflow
+
+1. Pick a ready story from status.json
+2. Mark as `in-progress`
+3. Implement to acceptance criteria
+4. Write/update tests
+5. Create PR
+6. Mark as `in-review`
+7. After merge: Mark as `done`
+
+## WIP Limits
+
+- **Max 2 stories per agent** in progress or review
+- Complete or unblock before starting new work
+
+## Available Commands
+
+### Project Management
+- `/agileflow:epic` - Create a new epic
+- `/agileflow:story` - Create a user story
+- `/agileflow:status` - Update story status
+- `/agileflow:board` - Visual kanban board
+- `/agileflow:sprint` - Plan sprint stories
+
+### Development
+- `/agileflow:babysit` - Guided implementation mentor
+- `/agileflow:review` - AI code review
+- `/agileflow:pr` - Generate PR description
+- `/agileflow:tests` - Generate test cases
+
+### Documentation
+- `/agileflow:adr` - Create architecture decision
+- `/agileflow:docs` - Generate documentation
+- `/agileflow:changelog` - Generate changelog entry
+
+### Utilities
+- `/agileflow:help` - This overview
+- `/agileflow:diagnose` - System health check
+- `/agileflow:configure` - Setup AgileFlow
+```

package/src/core/commands/pr.md

@@ -227,3 +227,99 @@ ACTIONS
 3) Suggest a Conventional Commit subject for squash.
 
 No file writes.
+
+---
+
+## Expected Output
+
+### Successful PR Description
+
+```
+📝 Generating PR description for US-0042...
+
+Reading story file: docs/06-stories/EP-0010/US-0042-login-form.md
+✅ Found epic: EP-0010 (User Authentication)
+✅ Found 3 acceptance criteria
+✅ Found 1 dependency: US-0041
+
+───────────────────────────────────────────────────────────
+PASTE-READY PR BODY (Copy everything below this line)
+───────────────────────────────────────────────────────────
+
+## US-0042: Implement Login Form with Validation
+
+### Summary
+
+Implements the user login form with email/password validation as part of the
+User Authentication epic (EP-0010). This PR adds client-side validation,
+error handling, and integration with the authentication API.
+
+### Linked Issues
+
+- Closes #US-0042
+- Depends on #US-0041 (Authentication API)
+
+### Acceptance Criteria
+
+- [x] User can enter email and password
+- [x] Form validates email format
+- [ ] Form shows error messages for invalid input
+- [x] Submit button disabled while validating
+
+### Test Evidence
+
+- `npm test src/components/LoginForm.test.tsx` - 12 tests passing
+- Manual testing: Verified on Chrome, Firefox, Safari
+- Screenshot: login-form-validation.png
+
+### Screenshots
+
+![Login Form](./screenshots/login-form.png)
+
+### Risk Assessment
+
+- **Low risk**: UI-only changes, no backend modifications
+- **Rollback**: Revert this PR if issues detected
+
+### Code Owners
+
+@frontend-team
+
+───────────────────────────────────────────────────────────
+
+**Suggested commit message:**
+```
+feat(auth): implement login form with validation
+
+Closes US-0042
+```
+
+[AskUserQuestion: "Use this PR description?"]
+```
+
+### Missing Story ID
+
+```
+❌ Missing required input: STORY
+
+Usage:
+/agileflow:pr STORY=US-0042 TITLE="Login Form"
+
+Optional parameters:
+- AC_CHECKED="1,2,4" - Mark AC items 1, 2, 4 as checked
+- TEST_EVIDENCE="npm test passes, manual QA complete"
+- NOTES="Additional context for reviewers"
+```
+
+### Story File Not Found
+
+```
+❌ Story file not found
+
+Searched:
+- docs/06-stories/US-0042.md
+- docs/06-stories/EP-*/US-0042-*.md
+
+Create the story first:
+/agileflow:story EPIC=EP-0010 STORY=US-0042 TITLE="Login Form" OWNER=AG-UI
+```