agileflow 2.94.1 → 2.95.1

package/src/core/commands/velocity.md

@@ -547,6 +547,80 @@ OUTPUT
 
 ---
 
+## Expected Output
+
+### Success - Velocity Report
+
+```
+📊 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
+Confidence: High (85%)
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+🎯 Forecast: EP-0010 (User Auth)
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+Stories: 8/12 completed (66%)
+Remaining: 6 points
+At current velocity: < 1 week
+Forecast completion: 2025-10-24
+Confidence: High (85%)
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+Saved to: docs/08-project/velocity/velocity-2025-10-17.md
+```
+
+### Success - Forecast Mode
+
+```
+📊 Epic Completion Forecast
+══════════════════════════════════════════════════════════════
+
+Epic: EP-0011 (Payment Integration)
+Current velocity: 8.3 points/week
+
+Stories: 2/8 completed (25%)
+Remaining: 6 stories, 9 points
+
+Forecast:
+  P50 (50% confidence): 2025-10-28 (11 days)
+  P80 (80% confidence): 2025-11-01 (15 days)
+  P90 (90% confidence): 2025-11-04 (18 days)
+
+⚠️ Risks:
+  - AG-API dependency (50% of velocity)
+  - 2 stories have external dependencies
+```
+
+### Error - Insufficient Data
+
+```
+⚠️ Insufficient velocity data
+
+Sample size: 3 stories completed
+Minimum required: 5 stories
+
+Velocity calculations require at least 5 completed stories
+over 3+ time periods for reliable forecasting.
+
+Complete more stories and try again.
+```
+
+---
+
 ## Related Commands
 
 - `/agileflow:sprint` - Sprint planning

package/src/core/commands/verify.md

@@ -411,6 +411,97 @@ Run without story_id to verify all in_progress stories.
 
 ---
 
+## Expected Output
+
+### Success - Tests Passing
+
+```
+🧪 Test Verification Complete
+══════════════════════════════════════════════════════════════
+
+Command: npm test
+Duration: 12.3s
+Result: ✅ PASSED
+
+Tests: 42 passed, 0 failed, 42 total
+
+Updated stories:
+  • US-0042: passing
+  • US-0043: passing
+
+All in-progress stories have passing tests ✅
+```
+
+### Error - Tests Failing
+
+```
+🧪 Test Verification Complete
+══════════════════════════════════════════════════════════════
+
+Command: npm test
+Duration: 8.7s
+Result: ❌ FAILED
+
+Tests: 40 passed, 2 failed, 42 total
+
+Failed tests:
+  ❌ auth.test.ts:42
+     Expected redirect to /dashboard
+     Got redirect to /login
+
+  ❌ auth.test.ts:67
+     Session token not persisting
+     Cookie not set after login
+
+Updated stories:
+  • US-0042: failing
+  • US-0043: failing
+
+⚠️ WARNING: 2 stories now have failing tests
+```
+
+### Error - Timeout
+
+```
+🧪 Test Verification Failed
+══════════════════════════════════════════════════════════════
+
+Command: npm test
+Result: ⏱️ TIMEOUT (60s)
+
+The test suite did not complete within 60 seconds.
+
+Updated stories:
+  • US-0042: failing (timeout)
+
+⚠️ Consider:
+1. Increase test_timeout_ms in environment.json
+2. Optimize slow tests
+3. Run specific test suites instead of all tests
+```
+
+### Error - Session Not Initialized
+
+```
+⚠️ Session Harness Not Initialized
+══════════════════════════════════════════════════════════════
+
+The verify command requires session harness configuration.
+
+Run /agileflow:session:init to:
+1. Detect your project type and test command
+2. Create environment.json configuration
+3. Enable test verification for all stories
+
+Or manually create docs/00-meta/environment.json with:
+{
+  "test_command": "npm test",
+  "test_timeout_ms": 60000
+}
+```
+
+---
+
 ## Example Execution
 
 ```

package/src/core/commands/whats-new.md

@@ -125,6 +125,75 @@ If a newer version exists, show:
 
 ---
 
+## Expected Output
+
+### Success - Changelog Display
+
+```
+╭─────────────────────────────────────────────────────╮
+│  AgileFlow Changelog                                │
+│  Current: v2.57.0                                   │
+╰─────────────────────────────────────────────────────╯
+
+## v2.57.0 (2025-12-27)
+
+### Added
+• Auto-update system with configurable check frequency
+• Update notifications in welcome message and status line
+• Changelog display after updates
+
+---
+
+## v2.56.0 (2025-12-27)
+
+### Added
+• Dynamic IDE discovery - Codex CLI now in setup
+
+### Changed
+• Replaced hardcoded IDE list with dynamic loading
+
+---
+
+## v2.55.0 (2025-12-26)
+
+### Changed
+• Consolidated code improvements and debugging
+
+---
+
+📖 Full changelog: https://github.com/projectquestorg/AgileFlow/blob/main/packages/cli/CHANGELOG.md
+🔄 Check for updates: npx agileflow update
+⚙️ Configure auto-update: /agileflow:configure --auto-update
+```
+
+### Success - Update Available
+
+```
+╭─────────────────────────────────────────────────────╮
+│  AgileFlow Changelog                                │
+│  Current: v2.57.0                                   │
+╰─────────────────────────────────────────────────────╯
+
+[changelog content...]
+
+⚡ Update available: v2.57.0 → v2.58.0
+   Run: npx agileflow update
+```
+
+### Error - Changelog Not Found
+
+```
+⚠️ Changelog not found
+
+Expected location: .agileflow/CHANGELOG.md
+
+The changelog file may be missing or AgileFlow may need to be reinstalled.
+
+Check: https://github.com/projectquestorg/AgileFlow/releases
+```
+
+---
+
 ## Related Commands
 
 - `/agileflow:changelog` - Generate changelog from commits

package/src/core/commands/workflow.md

@@ -350,6 +350,94 @@ Custom workflows (docs/08-project/workflows/):
 
 ---
 
+## Expected Output
+
+### Success - Workflow Executed
+
+```
+🔄 Workflow: review
+══════════════════════════════════════════════════════════════
+
+Arguments:
+  • path: src/auth.ts
+  • focus: security
+
+Executing workflow steps...
+
+Step 1: Reading target file(s)
+  ✓ Read src/auth.ts (245 lines)
+
+Step 2: Spawning security expert
+  ✓ agileflow-security analyzing...
+
+Step 3: Generating findings
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+📋 Review Results
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+Security Analysis: src/auth.ts
+
+🔴 HIGH: Hardcoded JWT secret (line 42)
+   Suggestion: Use environment variable
+
+🟡 MEDIUM: No rate limiting on login endpoint
+   Suggestion: Add rate limiter middleware
+
+🟢 LOW: Console.log in production code (line 87)
+   Suggestion: Remove or use proper logging
+
+Summary: 1 high, 1 medium, 1 low severity issues
+```
+
+### Success - List Workflows
+
+```
+📋 Available Workflows
+══════════════════════════════════════════════════════════════
+
+Built-in workflows:
+  • review        Code review with configurable focus
+  • test-feature  Test a feature end-to-end
+  • implement     Implement a story/feature
+  • analyze       Analyze codebase for issues
+
+Custom workflows (docs/08-project/workflows/):
+  • deploy-staging   Deploy to staging environment
+  • release-check    Pre-release checklist
+
+Usage: /agileflow:workflow <name> [args...]
+```
+
+### Error - Unknown Workflow
+
+```
+❌ Workflow not found: my-workflow
+
+Available workflows:
+  • review
+  • test-feature
+  • implement
+  • analyze
+
+Create custom workflow:
+  docs/08-project/workflows/my-workflow.md
+```
+
+### Error - Missing Required Argument
+
+```
+❌ Missing required argument: path
+
+Workflow 'review' requires:
+  • path (required): File or glob pattern to review
+  • focus (optional): Review focus (default: all)
+
+Usage: /agileflow:workflow review path=src/auth.ts focus=security
+```
+
+---
+
 ## Related Commands
 
 - `/agileflow:babysit` - Interactive mentor workflow

package/src/core/templates/command-documentation.md

@@ -0,0 +1,187 @@
+# Command Documentation Template
+
+This template provides a standardized structure for documenting AgileFlow slash commands.
+
+## File Structure
+
+```markdown
+---
+# REQUIRED: Frontmatter section
+description: Brief one-line description of what the command does
+argument-hint: PARAM1=<value> [PARAM2=<optional>]
+compact_context:
+  priority: high|medium|low
+  preserve_rules:
+    - "Rule descriptions for compact context"
+  state_fields:
+    - field_name
+---
+
+# command-name
+
+Full description of the command's purpose and primary use case.
+
+---
+
+## STEP 0: Gather Context
+
+```bash
+node .agileflow/scripts/obtain-context.js command-name
+```
+
+This gathers relevant context for the command.
+
+---
+
+## Context Loading (Documentation)
+
+**PURPOSE**: Description of why context is loaded.
+
+**ACTIONS**:
+1. Action item 1
+2. Action item 2
+
+**WHY**: Explanation of benefits.
+
+---
+
+## Syntax
+
+```
+/agileflow:command-name PARAM1=value [PARAM2=optional]
+```
+
+### Parameters
+
+| Parameter | Required | Default | Description |
+|-----------|----------|---------|-------------|
+| PARAM1 | Yes | - | Description |
+| PARAM2 | No | default | Description |
+
+---
+
+## Examples
+
+### Basic Usage
+
+```
+/agileflow:command-name PARAM1=example
+```
+
+### Advanced Usage
+
+```
+/agileflow:command-name PARAM1=example PARAM2=custom
+```
+
+---
+
+## Expected Output
+
+### Success Case
+
+```
+✓ Operation completed successfully
+
+Results:
+- Item 1: value
+- Item 2: value
+```
+
+### Error Cases
+
+#### Missing Required Parameter
+
+```
+❌ Error: PARAM1 is required
+Usage: /agileflow:command-name PARAM1=<value>
+```
+
+#### Invalid Parameter Value
+
+```
+❌ Error: Invalid value for PARAM1: 'invalid'
+Expected: description of valid values
+```
+
+---
+
+## Related Commands
+
+- `/agileflow:related1` - Description
+- `/agileflow:related2` - Description
+
+---
+
+## Troubleshooting
+
+### Common Issue 1
+
+**Symptom**: Description of what goes wrong.
+
+**Cause**: Explanation of why it happens.
+
+**Solution**: Steps to resolve.
+
+### Common Issue 2
+
+**Symptom**: Description.
+
+**Cause**: Explanation.
+
+**Solution**: Steps.
+
+---
+
+## See Also
+
+- [Practice Guide](link) - Related practice documentation
+- [Architecture Doc](link) - Technical implementation details
+```
+
+## Best Practices for Command Documentation
+
+### 1. Description Quality
+
+- **Frontmatter description**: Keep to one line, action-oriented (e.g., "Create a new story" not "This command creates stories")
+- **Main description**: 1-2 sentences explaining the command's purpose and when to use it
+
+### 2. Expected Output Section
+
+Always include:
+- **Success case**: Show actual CLI output the user will see
+- **At least 2 error cases**: Common failures with their messages
+- Use actual ANSI color indicators if present:
+  - `✓` (green) for success
+  - `❌` (red) for errors
+  - `⚠️` (yellow) for warnings
+
+### 3. Parameter Documentation
+
+- Table format for clarity
+- Always specify Required/Optional
+- Include default values
+- Provide meaningful descriptions
+
+### 4. Examples
+
+- Start with simplest usage
+- Progress to advanced scenarios
+- Include real-world use cases
+
+### 5. Consistency
+
+- Use consistent heading levels
+- Follow the template structure
+- Match the formatting of existing commands
+
+## Checklist Before Publishing
+
+- [ ] Frontmatter has description and argument-hint
+- [ ] Expected Output section exists
+- [ ] At least one success example shown
+- [ ] At least two error scenarios documented
+- [ ] Parameters are documented in a table
+- [ ] Examples demonstrate common use cases
+- [ ] Related commands are linked
+- [ ] Troubleshooting section addresses common issues