agileflow 2.51.0 → 2.56.0

package/src/core/commands/session/status.md

@@ -3,275 +3,63 @@ description: View current session state and activity
 argument-hint: (no arguments)
 ---
 
-# Session Status
+# /agileflow:session:status
 
-You are running the `/agileflow:session:status` command to view a quick snapshot of the current session.
+Quick view of all sessions and their status.
 
-## IMMEDIATE ACTIONS
-
-**Execute these steps NOW (read-only, fast):**
-
-### Step 1: Read session-state.json
-```bash
-cat docs/09-agents/session-state.json
-```
-If `current_session` is null, display "No active session" and suggest `/agileflow:session:resume`.
-
-### Step 2: Calculate current duration
-Get current time and calculate duration from `current_session.started_at`.
-
-### Step 3: Get git status (quick)
-```bash
-git status --short | wc -l
-git branch --show-current
-```
-
-### Step 4: Display compact summary
-Output a one-liner or short summary:
-```
-Session: {id} | Duration: {duration} | Story: {current_story} | Branch: {branch} | Uncommitted: {count}
-```
-
-**This command is READ-ONLY. It never modifies files or runs tests.**
-
-## Command Purpose
+---
 
-Quick view of current session activity without running tests or loading full context. Use this when you want to see:
-- What story you're currently working on
-- How long this session has been running
-- Whether you have uncommitted changes
-- Recent activity in this session
+## Purpose
 
-## Execution Flow
+Display a compact overview of all registered sessions without prompting for action.
 
-### 1. Load Session State
+## IMMEDIATE ACTIONS
 
-Read from `docs/09-agents/session-state.json`:
+### Step 1: Get Session Data
 
 ```bash
-if [ ! -f "docs/09-agents/session-state.json" ]; then
-  echo "⚠️  No active session"
-  echo ""
-  echo "Run /agileflow:session:resume to start a session"
-  exit 0
-fi
+node .agileflow/scripts/session-manager.js list --json
 ```
 
-### 2. Calculate Session Duration
-
-```bash
-STARTED_AT=$(jq -r '.current_session.started_at' docs/09-agents/session-state.json)
-NOW=$(date -u +%Y-%m-%dT%H:%M:%SZ)
+### Step 2: Display Formatted Table
 
-# Calculate duration
-DURATION=$(calculate_duration "$STARTED_AT" "$NOW")
 ```
+📊 Session Status
 
-### 3. Get Current Work
+Current: Session 1 (main)
+         Branch: main │ Story: US-0042 │ Active
 
-Read from `docs/09-agents/status.json`:
-- Current in-progress story
-- Story owner/assignee
-- Story progress/status
+Other Sessions:
+┌─────┬──────────────────┬─────────────┬────────────┐
+│  #  │ Name/Branch      │ Story       │ Status     │
+├─────┼──────────────────┼─────────────┼────────────┤
+│  2  │ "auth"           │ US-0038     │ ● Active   │
+│  3  │ feature/payments │ -           │ ○ Inactive │
+└─────┴──────────────────┴─────────────┴────────────┘
 
-### 4. Check Git Status
-
-```bash
-# Uncommitted changes
-UNCOMMITTED=$(git status --short | wc -l)
-
-# Commits this session
-SESSION_START_COMMIT=$(jq -r '.current_session.baseline_commit // "HEAD~10"' docs/09-agents/session-state.json)
-COMMITS_THIS_SESSION=$(git rev-list --count $SESSION_START_COMMIT..HEAD 2>/dev/null || echo "0")
+Total: 3 sessions │ 2 active
 ```
 
-### 5. Get Test Status
-
-Read last test status from session-state.json (without re-running tests):
-- Last test result
-- Time since last test run
-- Pass/fail count
-
-### 6. Display Summary
+### Step 3: Show Quick Actions
 
 ```
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-📊 Current Session
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-
-Session ID: sess-20251216-140000
-Started: 2 hours 15 minutes ago
-Duration: 2h 15m
-
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-🎯 Current Work
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-
-Story: US-0043
-Title: Add user profile settings page
-Status: in_progress
-Owner: ui
-Epic: EP-0001 (User Management)
-
-Progress:
-  ✅ 3/5 acceptance criteria met
-  📝 2 remaining
-
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-📁 Git Activity
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-
-Branch: feature/user-profile
-Commits this session: 3
-Uncommitted changes: 2 files
-
-Modified:
-  M src/components/ProfileForm.tsx
-  M src/api/user.ts
-
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-🧪 Test Status
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-
-Last run: 45 minutes ago
-Result: ✅ Passing (42/42)
-Command: npm test
-
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-⚡ Quick Actions
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-
-• Run tests: /agileflow:verify
-• End session: /agileflow:session:end
-• View full context: /agileflow:session:resume
-• View story: docs/06-stories/EP-0001/US-0043.md
-
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+💡 Quick actions:
+   /agileflow:session:new    - Create parallel session
+   /agileflow:session:resume - Switch to another session
+   /agileflow:session:end    - End current session
 ```
 
-## Compact Mode
-
-For a shorter output, show minimal info:
+## No Sessions Case
 
 ```
-📊 Session: 2h 15m | 🎯 US-0043 (in_progress) | 📁 3 commits, 2 uncommitted | 🧪 ✅ 42/42
-```
-
-## Output Variations
-
-### No Active Session
-```
-⚠️  No Active Session
-
-No session is currently tracked.
-
-To start a session:
-  /agileflow:session:resume
-
-This will:
-  • Run environment initialization
-  • Verify tests
-  • Load context
-  • Start session tracking
-```
-
-### Session With No Current Story
-```
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-📊 Current Session
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-
-Session ID: sess-20251216-140000
-Started: 30 minutes ago
-Duration: 30m
-
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-🎯 Current Work
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-
-No story currently assigned.
-
-Ready stories (5):
-  • US-0044: Implement password reset flow
-  • US-0045: Add email verification
-  • US-0046: Create admin dashboard
-  • US-0047: Add user roles
-  • US-0048: Implement audit logging
+📊 Session Status
 
-Assign a story: /agileflow:assign STORY=US-0044
-
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-```
-
-### Session With Failing Tests
-```
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-📊 Current Session
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-
-Session ID: sess-20251216-140000
-Started: 1 hour ago
-
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-🧪 Test Status ⚠️
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-
-Last run: 10 minutes ago
-Result: ❌ FAILING (40/42)
-
-Failed tests:
-  ❌ auth.test.ts:42 - Session redirect
-  ❌ auth.test.ts:67 - Token persistence
-
-Run /agileflow:verify to see full output
-
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-```
-
-### Long Session Warning
-```
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-📊 Current Session
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-
-Session ID: sess-20251216-080000
-Started: 8 hours ago
-Duration: 8h 15m
-
-⚠️  Long session detected!
-Consider:
-  • Taking a break
-  • Committing your work
-  • Running /agileflow:session:end to save progress
-
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+No sessions registered yet. You're in the main project directory.
+Run /agileflow:session:new to create a parallel workspace.
 ```
 
 ## Related Commands
 
-| Command | Purpose |
-|---------|---------|
-| `/agileflow:session:init` | One-time setup of session harness |
-| `/agileflow:session:resume` | Start session with full verification |
-| `/agileflow:session:end` | Cleanly end session and record summary |
-| `/agileflow:session:history` | View past session history and metrics |
-
-## Integration Points
-
-### Reads
-- `docs/09-agents/session-state.json` - Current session info
-- `docs/09-agents/status.json` - Story status
-- Git status - Uncommitted changes
-
-### Does NOT
-- Run tests (use `/agileflow:verify` for that)
-- Modify any files
-- Start a new session
-
-## Implementation Notes
-
-1. **Fast**: No tests, no heavy operations - instant response
-2. **Read-Only**: Never modifies files
-3. **Non-Blocking**: No user input required
-4. **Informative**: Shows actionable next steps
-5. **Context-Aware**: Adapts output based on current state
+- `/agileflow:session:new` - Create new session
+- `/agileflow:session:resume` - Switch sessions
+- `/agileflow:session:end` - End current session

package/src/core/commands/sprint.md

@@ -62,6 +62,39 @@ Sprint Planner that creates data-driven sprint commitments based on historical v
 - Recommendations (sequencing, monitoring, next commands)
 - Next steps (different for MODE=suggest vs MODE=commit)
 
+**Tool Usage Examples**:
+
+TodoWrite:
+```xml
+<invoke name="TodoWrite">
+<parameter name="content">1. Load knowledge sources (status.json, bus log, backlog)
+2. Analyze agent capacity and WIP
+3. Calculate historical velocity (last 30 days)
+4. Select stories based on priority and capacity
+5. Assess risks (dependencies, cross-agent coordination)
+6. Generate sprint plan report
+7. If MODE=commit: Update status.json and milestones.md
+8. Create sprint milestone and bus message</parameter>
+<parameter name="status">in-progress</parameter>
+</invoke>
+```
+
+AskUserQuestion:
+```xml
+<invoke name="AskUserQuestion">
+<parameter name="questions">[{
+  "question": "Commit this sprint plan: 5 stories, 8.5 days?",
+  "header": "Confirm Sprint Commitment",
+  "multiSelect": false,
+  "options": [
+    {"label": "Yes, commit plan", "description": "Update status.json and create milestone"},
+    {"label": "No, adjust", "description": "Modify story selection"},
+    {"label": "Cancel", "description": "Exit without changes"}
+  ]
+}]</parameter>
+</invoke>
+```
+
 <!-- COMPACT_SUMMARY_END -->
 
 # sprint-plan

package/src/core/commands/status.md

@@ -49,6 +49,24 @@ This gathers git status, stories/epics, session state, and registers for PreComp
 - **Output**: Diff-first, then YES/NO confirmation
 - **Critical**: User text automatically escaped by jq
 - **Related**: docs/09-agents/status.json, bus/log.jsonl
+
+**Tool Usage Examples**:
+
+AskUserQuestion:
+```xml
+<invoke name="AskUserQuestion">
+<parameter name="questions">[{
+  "question": "Update US-0042 to in-review?",
+  "header": "Confirm Status Update",
+  "multiSelect": false,
+  "options": [
+    {"label": "Yes, update", "description": "Update status.json and bus log"},
+    {"label": "No, cancel", "description": "Don't update"}
+  ]
+}]</parameter>
+</invoke>
+```
+
 <!-- COMPACT_SUMMARY_END -->
 
 ---

package/src/core/commands/story-validate.md

@@ -51,6 +51,38 @@ node .agileflow/scripts/obtain-context.js story-validate
 - **Read-Only**: Never modifies story, only validates
 - **Exit Code**: 0 if ready, 1 if issues found
 - **Related**: Story template, Architecture docs, status.json
+
+**Tool Usage Examples**:
+
+TodoWrite:
+```xml
+<invoke name="TodoWrite">
+<parameter name="content">1. Parse story ID from input
+2. Load story file from docs/06-stories/
+3. Parse YAML frontmatter and extract sections
+4. Run validation checks (7 categories)
+5. Count passed/failed/warnings
+6. Generate comprehensive report
+7. Provide next steps recommendation</parameter>
+<parameter name="status">in-progress</parameter>
+</invoke>
+```
+
+AskUserQuestion:
+```xml
+<invoke name="AskUserQuestion">
+<parameter name="questions">[{
+  "question": "Story has 3 warnings. Continue with validation?",
+  "header": "Story Validation",
+  "multiSelect": false,
+  "options": [
+    {"label": "Show full report", "description": "Display all validation results"},
+    {"label": "Cancel", "description": "Exit validation"}
+  ]
+}]</parameter>
+</invoke>
+```
+
 <!-- COMPACT_SUMMARY_END -->
 
 ---

package/src/core/commands/story.md

@@ -59,17 +59,32 @@ node .agileflow/scripts/obtain-context.js story
 - Status: docs/09-agents/status.json (merged)
 - Log: docs/09-agents/bus/log.jsonl (appended)
 
-**AskUserQuestion Format** (XML invoke):
+**Tool Usage Examples**:
+
+TodoWrite:
+```xml
+<invoke name="TodoWrite">
+<parameter name="content">1. Parse inputs (EPIC, STORY, TITLE, OWNER, ESTIMATE, AC)
+2. Create story file from template
+3. Create test case stub
+4. Merge into status.json
+5. Append assign event to bus log
+6. Show preview and confirm</parameter>
+<parameter name="status">in-progress</parameter>
+</invoke>
+```
+
+AskUserQuestion (XML invoke):
 ```xml
 <invoke name="AskUserQuestion">
 <parameter name="questions">[{
-  "question": "Create story <STORY>: <TITLE> with these files?",
-  "header": "Create story",
+  "question": "Create story US-0042: Login Form with these files?",
+  "header": "Confirm Story Creation",
   "multiSelect": false,
   "options": [
-    {"label": "Yes, create story", "description": "Write story file, test stub, and update status.json (Recommended)"},
-    {"label": "No, revise first", "description": "I want to modify the content before creating"},
-    {"label": "Cancel", "description": "Don't create this story"}
+    {"label": "Yes, create story", "description": "Write files and update status.json"},
+    {"label": "No, revise first", "description": "Modify before creating"},
+    {"label": "Cancel", "description": "Don't create"}
   ]
 }]</parameter>
 </invoke>

package/src/core/commands/template.md

@@ -70,6 +70,24 @@ node .agileflow/scripts/obtain-context.js template
 - registry.json updated with metadata
 - User confirmed via YES/NO prompt
 
+**Tool Usage Example**:
+When ACTION=create, user interaction:
+```xml
+<invoke name="AskUserQuestion">
+<parameter name="questions">[{
+  "question": "Select template type to create:",
+  "header": "Create Template",
+  "multiSelect": false,
+  "options": [
+    {"label": "Meeting notes", "description": "Weekly team meeting template"},
+    {"label": "Incident report", "description": "Post-incident documentation"},
+    {"label": "Sprint retrospective", "description": "Sprint review and retrospective"},
+    {"label": "Custom (blank)", "description": "Start with blank template"}
+  ]
+}]</parameter>
+</invoke>
+```
+
 <!-- COMPACT_SUMMARY_END -->
 
 ## Prompt

package/src/core/commands/tests.md

@@ -83,6 +83,28 @@ tests/
 - Documentation created
 - User confirmed via YES/NO prompt
 
+**Tools Used**:
+- TodoWrite: Track 10-step test infrastructure setup
+
+**TodoWrite Example**:
+```xml
+<invoke name="TodoWrite">
+<parameter name="content">
+1. Detect language/runtime and framework
+2. Check existing test setup
+3. Install testing framework dependencies
+4. Create test configuration files
+5. Create example tests (unit, integration, E2E if requested)
+6. Create test directory structure
+7. Add test scripts to package.json/equivalent
+8. Integrate with CI workflow
+9. Create docs/02-practices/testing.md documentation
+10. Run tests to verify setup
+</parameter>
+<parameter name="status">in-progress</parameter>
+</invoke>
+```
+
 <!-- COMPACT_SUMMARY_END -->
 
 ## Prompt

package/src/core/commands/update.md

@@ -19,75 +19,89 @@ node .agileflow/scripts/obtain-context.js update
 <!-- COMPACT_SUMMARY_START -->
 ## Compact Summary
 
-**Purpose**: Stakeholder Communication Generator - Generate high-level project updates from status, epics, stories, and git history
+**Command**: `stakeholder-update` - Generate high-level project updates from status, epics, stories, and git history
 
-**Role**: Stakeholder Communication Generator responsible for creating executive summaries, progress reports, and metrics
+**Quick Usage**:
+```
+/agileflow:stakeholder-update PERIOD=week AUDIENCE=exec FORMAT=markdown
+```
 
 **Critical Rules**:
-- MUST aggregate data from 10 sources (status.json, epics, stories, backlog, roadmap, milestones, risks, git history, bus log, ADRs)
-- MUST preview update before sending (diff-first, YES/NO/EDIT)
-- MUST save all updates to docs/08-project/updates/ for history
+- MUST aggregate data from 10 sources (status, epics, stories, roadmap, risks, git history, bus log, ADRs)
+- MUST preview before sending (diff-first, YES/NO/EDIT)
+- MUST save to docs/08-project/updates/ for history
 - MUST be honest about blockers and risks
-- MUST focus on business value, not technical jargon (for exec/client)
-- MUST include specific numbers and metrics
-- MUST highlight trends (improving/declining)
-- NEVER expose sensitive data (credentials, internal conflicts)
+- Focus on business value, not technical jargon
+
+### Tool Usage Examples
+
+**Read** (to gather data from all 10 sources):
+```xml
+<invoke name="Read">
+<parameter name="file_path">/full/path/to/docs/09-agents/status.json</parameter>
+</invoke>
+```
+
+**Write** (to save update):
+```xml
+<invoke name="Write">
+<parameter name="file_path">/full/path/to/docs/08-project/updates/20251222-update.md</parameter>
+<parameter name="content"># Weekly Update - Project XYZ (Dec 15-22, 2025)
+
+## Executive Summary
+Status: On Track. Completed 12 stories, velocity up 20%. Payment integration on track for EOMonth.
+
+## Progress This Period
+- Completed auth epic (5 stories, 7.5 days)
+- Velocity: 18 points (↗ +20% from last week)
+- Test coverage: 87% (↗ +2%)
+
+## Blockers & Risks
+- Stripe API rate limits (Medium) - Mitigation in progress
+- Third-party OAuth downtime (Low) - Fallback available
+
+## Upcoming Priorities
+1. Complete payment integration MVP
+2. Start notification system
+3. Address technical debt</parameter>
+</invoke>
+```
+
+**Bash** (to get git commit history):
+```xml
+<invoke name="Bash">
+<parameter name="command">git log --oneline --since="7 days ago" | head -20</parameter>
+<parameter name="description">Get recent commits for this week</parameter>
+</invoke>
+```
 
-**Inputs** (optional):
+**Glob** (to find update files):
+```xml
+<invoke name="Glob">
+<parameter name="pattern">docs/08-project/updates/*.md</parameter>
+</invoke>
+```
+
+**AskUserQuestion** (for confirmation):
+```xml
+<invoke name="AskUserQuestion">
+<parameter name="questions">[{"question": "Send this update?", "header": "Preview", "multiSelect": false, "options": [{"label": "Yes, save and send", "description": "Save to docs/08-project/updates/ and email stakeholders"}, {"label": "Edit first", "description": "Let me review and edit"}, {"label": "Cancel", "description": "Don't send"}]}]</parameter>
+</invoke>
+```
+
+**Optional Inputs**:
 - 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)
+- START_DATE=<YYYY-MM-DD> (for custom period)
+- END_DATE=<YYYY-MM-DD> (for custom period)
 - AUDIENCE=exec|client|team|board (default: exec)
 - FORMAT=email|markdown|slides|pdf (default: markdown)
 
-**Data Sources**:
-1. docs/09-agents/status.json - Current story status
-2. docs/05-epics/*.md - Epic progress
-3. docs/06-stories/**/US-*.md - Story details
-4. docs/08-project/backlog.md - Backlog items
-5. docs/08-project/roadmap.md - Roadmap milestones
-6. docs/08-project/milestones.md - Milestone targets
-7. docs/08-project/risks.md - Risk register
-8. Git history - Commits, PRs merged
-9. docs/09-agents/bus/log.jsonl - Activity context
-10. docs/03-decisions/adr-*.md - Recent decisions
+**Data Sources**: Status.json | Epics | Stories | Roadmap | Milestones | Risks | Git history | Bus log | ADRs
 
 **Update Structure**:
-- Executive Summary (2-3 sentences, overall status, key accomplishments, critical issues)
-- 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 (sprint capacity, team changes)
-
-**Audience Customization**:
-- Executive: High-level, business impact, metrics/ROI, risks early, 1-page max
-- Client: Feature-focused, user benefits, transparent, screenshots/demos, contract deliverables
-- Team: Technical detail, architecture decisions, celebrate wins, retrospective insights, action items
-- Board: Strategic overview, financial implications, competitive positioning, long-term roadmap, risk assessment
-
-**Workflow**:
-1. Determine period (this week, last sprint, etc.)
-2. Collect data from all 10 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 and optionally email stakeholders
-
-**Output Files**:
-- Update: docs/08-project/updates/<YYYYMMDD>-update.md
-- Log entry: docs/09-agents/bus/log.jsonl
-
-**Success Criteria**:
-- All data sources aggregated
-- Metrics calculated with trends
-- Formatted for target audience
-- Saved to updates directory
-- User confirmed via YES/NO/EDIT prompt
+- Executive Summary | Progress This Period | Upcoming Work | Metrics | Blockers & Risks | Decisions Made | Budget/Resources
+
+**Output Files**: `docs/08-project/updates/<YYYYMMDD>-update.md` | Log entry in bus/log.jsonl
 
 <!-- COMPACT_SUMMARY_END -->