agileflow 2.36.2 → 2.37.0

package/src/core/commands/readme-sync.md

@@ -1,69 +1,52 @@
 ---
 description: Synchronize a folder's README.md with its current contents
+argument-hint: FOLDER=<path> | FOLDER=all
 ---
 
 # readme-sync
 
-Synchronize a folder's README.md with its current contents by spawning the readme-updater subagent.
+Synchronize a folder's README.md with its current contents.
 
 ## Prompt
 
-**ROLE**: README Sync Command Handler
+ROLE: README Sync Orchestrator
 
-**OBJECTIVE**: Spawn the `readme-updater` subagent to synchronize a folder's README.md with its current contents.
+INPUTS
+FOLDER=<path>   Path to folder (e.g., docs/02-practices)
+FOLDER=all      Sync all docs/ subfolders
 
-**WORKFLOW**:
+AGENT SPAWNING
+This command spawns the `readme-updater` agent to do the actual work:
 
-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 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: "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 readme-updater with prompt: "Audit and synchronize README.md for docs/02-practices"
+```
+Task(
+  description: "Sync README for <FOLDER>",
+  prompt: "Audit and synchronize README.md for: <FOLDER>
+    1. List all files and subdirectories
+    2. Read current README.md (if exists)
+    3. Extract descriptions from each file
+    4. Build new '## Contents' section
+    5. Show diff and ask for confirmation
+    6. Update if approved",
+  subagent_type: "AgileFlow:readme-updater"
+)
+```
 
-User: "update readme for docs/06-stories"
-→ Spawn readme-updater with prompt: "Audit and synchronize README.md for docs/06-stories"
+ACTIONS
+1) If FOLDER=all:
+   - List all docs/*/ subdirectories
+   - Spawn readme-updater agent for each folder (can run in parallel)
+   - Report summary of all folders updated
 
-User: "/AgileFlow:readme-sync"
-→ Ask: "Which folder should I sync?"
-→ User responds: "docs/04-architecture"
-→ Spawn readme-updater with that folder
+2) If FOLDER=<path>:
+   - Validate folder exists
+   - Spawn readme-updater agent with the folder path
+   - Agent handles: listing, diffing, confirmation, updating
 
-**KEY POINTS**:
-- This command is just a launcher - it spawns the subagent
-- The subagent (readme-updater) does the actual work
-- Subagent has tools: Bash, Read, Edit, Write
-- Subagent will handle all file discovery, diffing, and updating
+3) If FOLDER is missing:
+   - Ask: "Which folder should I sync? (e.g., docs/02-practices, or 'all')"
 
-## How It Works
+WORKFLOW DETAILS
 
 ### Step 1: List Folder Contents
 ```bash
@@ -93,75 +76,64 @@ Generate markdown bullet list:
 - If YES: Use Edit tool to update "## Contents" section
 - If NO: Abort without changes
 
-## Example Output
+EXAMPLE OUTPUT
 
 ```
 📁 Syncing docs/02-practices/README.md
 =====================================
 
-Found 7 files:
+Found 8 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
+  • diagrams.md – Mermaid diagram generation with light/dark themes
+  • async-agent-spawning.md – Launch, monitor, and retrieve background agents
+  • ask-user-question.md – Using the AskUserQuestion tool effectively
 
 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
+- **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
+- **diagrams.md** – Mermaid diagram generation with light/dark themes
+- **async-agent-spawning.md** – Launch, monitor, and retrieve background agents
+- **ask-user-question.md** – Using the AskUserQuestion tool effectively
 
 Update README.md with these changes? (YES/NO)
 ```
 
-## When to Use
-
+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
+- Use FOLDER=all to sync entire docs/ directory at once
 
-## Usage Examples
-
+USAGE EXAMPLES
 ```bash
-# Sync docs/02-practices folder
-/AgileFlow:readme-sync FOLDER=docs/02-practices
+# Sync single folder
+/agileflow:readme-sync FOLDER=docs/02-practices
 
-# Sync docs/04-architecture folder
-/AgileFlow:readme-sync FOLDER=docs/04-architecture
+# Sync all docs folders
+/agileflow:readme-sync FOLDER=all
 
-# Sync src/components folder (if it has README)
-/AgileFlow:readme-sync FOLDER=src/components
+# Sync architecture docs
+/agileflow:readme-sync FOLDER=docs/04-architecture
 ```
 
-## What It Updates
-
+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
+RELATED
+- [Diagram Practice](docs/02-practices/diagrams.md) - How to create diagrams
+- [Async Agent Spawning](docs/02-practices/async-agent-spawning.md) - Background agent patterns

package/src/core/commands/retro.md

@@ -241,7 +241,7 @@ fi
 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"
+  echo "   - Use /agileflow:ai-code-review before requesting human review"
 fi
 
 # Low priority: Long-term improvements
@@ -377,8 +377,8 @@ 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
+  - Run /agileflow:metrics to track improvements
+  - Run /agileflow:velocity to update sprint planning
 ```
 
 INSIGHTS ENGINE
@@ -498,36 +498,36 @@ echo "$retro_content" > $retro_file
 
 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
+- 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
+/agileflow:retro
 ```
 
 ### Last 30 days
 ```bash
-/AgileFlow:retro TIMEFRAME=30d
+/agileflow:retro TIMEFRAME=30d
 ```
 
 ### Epic-specific retro
 ```bash
-/AgileFlow:retro EPIC=EP-0010
+/agileflow:retro EPIC=EP-0010
 ```
 
 ### Generate without saving
 ```bash
-/AgileFlow:retro SAVE=false
+/agileflow:retro SAVE=false
 ```
 
 ### Export as markdown
 ```bash
-/AgileFlow:retro FORMAT=markdown > retro.md
+/agileflow:retro FORMAT=markdown > retro.md
 ```
 
 RULES

package/src/core/commands/review.md

@@ -1,5 +1,6 @@
 ---
 description: AI-powered code review with quality suggestions
+argument-hint: [BRANCH=<name>] [BASE=<branch>] [FOCUS=all|security|performance|style]
 ---
 
 # ai-code-review
@@ -314,7 +315,7 @@ 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 }}
+  run: npx claude-code /agileflow:ai-code-review BRANCH=${{ github.head_ref }}
 
 - name: Check for critical issues
   run: |

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

@@ -5,7 +5,7 @@ argument-hint: (no arguments)
 
 # End Session
 
-You are running the `/AgileFlow:session:end` command to cleanly close the current AgileFlow session. This records what was accomplished, updates session history, and prepares for the next session.
+You are running the `/agileflow:session:end` command to cleanly close the current AgileFlow session. This records what was accomplished, updates session history, and prepares for the next session.
 
 ## Command Purpose
 
@@ -44,7 +44,7 @@ Proper session closure that:
 if [ ! -f "docs/09-agents/session-state.json" ]; then
   echo "⚠️  No active session to end"
   echo ""
-  echo "Run /AgileFlow:session:resume to start a session first"
+  echo "Run /agileflow:session:resume to start a session first"
   exit 0
 fi
 
@@ -198,7 +198,7 @@ Ready to pick up:
   • US-0045: Add email verification
   • US-0046: Create admin dashboard
 
-Run /AgileFlow:session:resume to start next session
+Run /agileflow:session:resume to start next session
 
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 ```
@@ -289,10 +289,10 @@ Completed:
 
 | Command | Purpose |
 |---------|---------|
-| `/AgileFlow:session:init` | One-time setup of session harness |
-| `/AgileFlow:session:resume` | Start session with verification |
-| `/AgileFlow:session:status` | Quick view of current session |
-| `/AgileFlow:session:history` | View past sessions and analytics |
+| `/agileflow:session:init` | One-time setup of session harness |
+| `/agileflow:session:resume` | Start session with verification |
+| `/agileflow:session:status` | Quick view of current session |
+| `/agileflow:session:history` | View past sessions and analytics |
 
 ## Integration Points
 
@@ -305,7 +305,7 @@ Completed:
 - `docs/09-agents/session-state.json` - Moves current to last, updates history
 
 ### Optionally Runs
-- `/AgileFlow:verify` - Final test check
+- `/agileflow:verify` - Final test check
 
 ## Implementation Notes
 

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

@@ -5,7 +5,7 @@ argument-hint: [DAYS=7|30|90|all]
 
 # Session History
 
-You are running the `/AgileFlow:session:history` command to view past session history, productivity metrics, and trends over time.
+You are running the `/agileflow:session:history` command to view past session history, productivity metrics, and trends over time.
 
 ## Command Purpose
 
@@ -22,9 +22,9 @@ Analytics view of your session history showing:
 | `DAYS` | Time period to show | `7` (last 7 days) |
 
 **Examples:**
-- `/AgileFlow:session:history` - Last 7 days
-- `/AgileFlow:session:history DAYS=30` - Last 30 days
-- `/AgileFlow:session:history DAYS=all` - All time
+- `/agileflow:session:history` - Last 7 days
+- `/agileflow:session:history DAYS=30` - Last 30 days
+- `/agileflow:session:history DAYS=all` - All time
 
 ## Execution Flow
 
@@ -165,9 +165,9 @@ Test stability:
 No session history found.
 
 Start tracking sessions with:
-  1. /AgileFlow:session:init (one-time setup)
-  2. /AgileFlow:session:resume (each session)
-  3. /AgileFlow:session:end (end of session)
+  1. /agileflow:session:init (one-time setup)
+  2. /agileflow:session:resume (each session)
+  3. /agileflow:session:end (end of session)
 
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 ```
@@ -246,12 +246,12 @@ Oct 2025:  ████████████         18 stories │ 58h
 
 | Command | Purpose |
 |---------|---------|
-| `/AgileFlow:session:init` | One-time setup of session harness |
-| `/AgileFlow:session:resume` | Start session with verification |
-| `/AgileFlow:session:status` | Quick view of current session |
-| `/AgileFlow:session:end` | Cleanly end session and record summary |
-| `/AgileFlow:metrics` | Full project analytics dashboard |
-| `/AgileFlow:velocity` | Sprint velocity tracking |
+| `/agileflow:session:init` | One-time setup of session harness |
+| `/agileflow:session:resume` | Start session with verification |
+| `/agileflow:session:status` | Quick view of current session |
+| `/agileflow:session:end` | Cleanly end session and record summary |
+| `/agileflow:metrics` | Full project analytics dashboard |
+| `/agileflow:velocity` | Sprint velocity tracking |
 
 ## Integration Points
 

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

@@ -5,7 +5,7 @@ argument-hint: (no arguments)
 
 # Session Harness Initialization
 
-You are running the `/AgileFlow:session:init` command to set up test verification and session management for the AgileFlow project.
+You are running the `/agileflow:session:init` command to set up test verification and session management for the AgileFlow project.
 
 ## Command Purpose
 
@@ -21,7 +21,7 @@ First-time setup of the **Session Harness System**. Detects project configuratio
 4. Create docs/00-meta/environment.json
 5. Create docs/00-meta/init.sh
 6. Create docs/09-agents/session-state.json
-7. Run initial test verification (/AgileFlow:verify)
+7. Run initial test verification (/agileflow:verify)
 8. Create baseline git tag (if tests pass)
 9. Configure SessionStart hook (optional)
 10. Display final summary
@@ -31,7 +31,7 @@ Mark each step complete as you finish it. This ensures nothing is forgotten duri
 
 ## Prerequisites
 
-- AgileFlow must be initialized (`/AgileFlow:setup` must have been run)
+- AgileFlow must be initialized (`/agileflow:setup` must have been run)
 - Project must have a test suite configured
 - Must be in project root directory
 
@@ -44,7 +44,7 @@ Mark each step complete as you finish it. This ensures nothing is forgotten duri
 if [ ! -f "docs/09-agents/status.json" ]; then
   echo "❌ AgileFlow not initialized"
   echo ""
-  echo "Run /AgileFlow:setup first to create the docs structure"
+  echo "Run /agileflow:setup first to create the docs structure"
   exit 1
 fi
 
@@ -220,7 +220,7 @@ Initialize session state file:
 
 ### 7. Run Initial Test Verification
 
-Run `/AgileFlow:verify` to establish baseline test status:
+Run `/agileflow:verify` to establish baseline test status:
 
 ```
 🧪 Running initial test verification...
@@ -321,9 +321,9 @@ echo "✅ SessionStart hook configured"
 echo "✅ docs/00-meta/resume-session.sh created"
 ```
 
-**IMPORTANT**: The hook calls a **shell script** (`bash docs/00-meta/resume-session.sh`), NOT the slash command `/AgileFlow:session:resume`. This is because:
+**IMPORTANT**: The hook calls a **shell script** (`bash docs/00-meta/resume-session.sh`), NOT the slash command `/agileflow:session:resume`. This is because:
 - Hooks execute shell commands, not Claude Code slash commands
-- The shell script replicates `/AgileFlow:session:resume` functionality
+- The shell script replicates `/agileflow:session:resume` functionality
 - This enables true automatic session resumption
 
 ### 10. Final Summary
@@ -353,9 +353,9 @@ Configuration:
 
 Next Steps:
   1. Restart Claude Code to activate SessionStart hook
-  2. Run /AgileFlow:verify to check tests anytime
-  3. Run /AgileFlow:baseline to mark new baselines
-  4. Run /AgileFlow:session:resume manually or let the hook run it
+  2. Run /agileflow:verify to check tests anytime
+  3. Run /agileflow:baseline to mark new baselines
+  4. Run /agileflow:session:resume manually or let the hook run it
 
 On Next Session:
   - Hook will automatically run: bash docs/00-meta/resume-session.sh
@@ -369,10 +369,10 @@ Session harness is ready! 🚀
 
 | Command | Purpose |
 |---------|---------|
-| `/AgileFlow:session:resume` | Start session with verification and context loading |
-| `/AgileFlow:session:status` | View current session state and activity |
-| `/AgileFlow:session:end` | Cleanly end session and record summary |
-| `/AgileFlow:session:history` | View past session history and metrics |
+| `/agileflow:session:resume` | Start session with verification and context loading |
+| `/agileflow:session:status` | View current session state and activity |
+| `/agileflow:session:end` | Cleanly end session and record summary |
+| `/agileflow:session:history` | View past session history and metrics |
 
 ## Error Handling
 
@@ -430,10 +430,10 @@ This is optional - you can add baseline tags manually later using:
 ## Integration Points
 
 ### Called By
-- `/AgileFlow:setup` - Optionally runs session:init during initial setup
+- `/agileflow:setup` - Optionally runs session:init during initial setup
 
 ### Calls
-- `/AgileFlow:verify` - For initial test verification
+- `/agileflow:verify` - For initial test verification
 - Template system - Uses templates/environment.json, templates/init.sh
 
 ### Creates

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

@@ -5,7 +5,7 @@ argument-hint: (no arguments)
 
 # Resume AgileFlow Session
 
-You are running the `/AgileFlow:session:resume` command to start an AgileFlow session with environment verification, test checking, and context loading.
+You are running the `/agileflow:session:resume` command to start an AgileFlow session with environment verification, test checking, and context loading.
 
 ## Command Purpose
 
@@ -17,7 +17,7 @@ Standard startup routine for every AgileFlow session. Verifies environment, runs
 ```
 1. Check if session harness initialized
 2. Run init script (if configured)
-3. Verify tests (/AgileFlow:verify)
+3. Verify tests (/agileflow:verify)
 4. Load git context (commits, branch, status)
 5. Load AgileFlow context (in-progress stories, recent completions)
 6. Update session-state.json with current session metadata
@@ -29,11 +29,11 @@ Mark each step complete as you finish it. This ensures comprehensive session sta
 
 **When to use:**
 - Manually: Start of each coding session
-- Automatically: Via SessionStart hook (configured in `/AgileFlow:session:init`)
+- Automatically: Via SessionStart hook (configured in `/agileflow:session:init`)
 
 ## Prerequisites
 
-- Session harness must be initialized (`/AgileFlow:session:init`)
+- Session harness must be initialized (`/agileflow:session:init`)
 - Must be in project root directory
 
 ## Execution Flow
@@ -44,7 +44,7 @@ Mark each step complete as you finish it. This ensures comprehensive session sta
 if [ ! -f "docs/00-meta/environment.json" ]; then
   echo "⚠️  Session harness not initialized"
   echo ""
-  echo "Run /AgileFlow:session:init to set up test verification"
+  echo "Run /agileflow:session:init to set up test verification"
   echo ""
   echo "Or continue without session harness? [y/N]: "
 
@@ -89,7 +89,7 @@ fi
 
 ### 3. Verify Tests
 
-Run `/AgileFlow:verify` to check current test status:
+Run `/agileflow:verify` to check current test status:
 
 ```
 🧪 Running tests...
@@ -279,7 +279,7 @@ Next steps:
   2. Check Architecture Context for implementation guidance
   3. Review Previous Story Insights above
   4. Implement to acceptance criteria
-  5. Run /AgileFlow:verify before marking complete
+  5. Run /agileflow:verify before marking complete
 
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 ```
@@ -294,7 +294,7 @@ If session harness not initialized, provide basic context:
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 
 ⚠️  Session harness not initialized
-   Run /AgileFlow:session:init for:
+   Run /agileflow:session:init for:
    • Automatic test verification
    • Session state tracking
    • Baseline management
@@ -332,9 +332,9 @@ No stories in progress yet. Ready to start work!
 
 Next steps:
   1. Review available stories: docs/06-stories/
-  2. Assign yourself a story: /AgileFlow:assign
+  2. Assign yourself a story: /agileflow:assign
   3. Start implementation following AC
-  4. Run /AgileFlow:verify before completion
+  4. Run /agileflow:verify before completion
 
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 ```
@@ -352,7 +352,7 @@ Since then:
   • 45 commits
   • 3 new epics added
 
-Consider running /AgileFlow:session:status for full overview
+Consider running /agileflow:session:status for full overview
 
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 ```
@@ -361,10 +361,10 @@ Consider running /AgileFlow:session:status for full overview
 
 | Command | Purpose |
 |---------|---------|
-| `/AgileFlow:session:init` | One-time setup of session harness |
-| `/AgileFlow:session:status` | View current session state and activity |
-| `/AgileFlow:session:end` | Cleanly end session and record summary |
-| `/AgileFlow:session:history` | View past session history and metrics |
+| `/agileflow:session:init` | One-time setup of session harness |
+| `/agileflow:session:status` | View current session state and activity |
+| `/agileflow:session:end` | Cleanly end session and record summary |
+| `/agileflow:session:history` | View past session history and metrics |
 
 ## Error Handling
 
@@ -433,10 +433,10 @@ Choice [1/2/3]: _
 
 ### Called By
 - SessionStart hook (if configured)
-- User manually via `/AgileFlow:session:resume`
+- User manually via `/agileflow:session:resume`
 
 ### Calls
-- `/AgileFlow:verify` - Test verification
+- `/agileflow:verify` - Test verification
 - Init script (`docs/00-meta/init.sh`)
 
 ### Reads