agileflow 2.91.0 → 2.92.1

package/src/core/commands/agent.md

@@ -124,3 +124,123 @@ ACTIONS
 3) Print a persona snippet to paste as that terminal's system prompt.
 
 Diff-first; YES/NO.
+
+---
+
+## Expected Output
+
+### Successful Agent Onboarding
+
+```
+📋 Onboarding New Agent: AG-UI
+
+AGENT_ID: AG-UI
+ROLE: Frontend Developer
+TOOLS: Read, Write, Edit, Bash, Glob
+SCOPE:
+  - Directories: src/components/, src/pages/
+  - Story Tags: frontend, ui, ux
+
+Files to create:
+───────────────────────────────────────────────
+1. docs/02-practices/prompts/agents/agent-AG-UI.md
+
+Preview:
+─────────────────────────────────────────────
+---
+agent_id: AG-UI
+role: Frontend Developer
+tools: [Read, Write, Edit, Bash, Glob]
+scope:
+  directories: [src/components/, src/pages/]
+  story_tags: [frontend, ui, ux]
+---
+
+# AG-UI: Frontend Developer Agent
+
+## Responsibilities
+Build and maintain user interface components, pages, and styling.
+
+## System Prompt (Contract)
+**Scope**: Only modify files in src/components/ and src/pages/
+**Testing**: Run `npm test` before committing
+**Commits**: Prefix with "feat(ui):" or "fix(ui):"
+**Status**: Update status.json after completing stories
+─────────────────────────────────────────────
+
+2. docs/09-agents/roster.yaml (update)
+
+   + agents:
+   +   - id: AG-UI
+   +     role: Frontend Developer
+   +     tools: [Read, Write, Edit, Bash, Glob]
+   +     scope:
+   +       directories: [src/components/, src/pages/]
+   +       story_tags: [frontend, ui, ux]
+
+[AskUserQuestion: "Create this agent profile?"]
+
+✅ Agent onboarded successfully!
+   Profile: docs/02-practices/prompts/agents/agent-AG-UI.md
+   Roster: docs/09-agents/roster.yaml updated
+
+📝 System Prompt Snippet (paste into terminal):
+
+You are AG-UI, a Frontend Developer agent.
+Your scope is limited to: src/components/, src/pages/
+You work on stories tagged: frontend, ui, ux
+Always run tests before committing.
+Always update status.json after completing work.
+```
+
+### Missing Required Inputs
+
+```
+❌ Missing required inputs
+
+Please provide:
+  • AGENT_ID - Agent identifier (e.g., AG-UI, AG-API)
+  • ROLE - Agent role description (e.g., "Frontend Developer")
+
+Optional:
+  • TOOLS - Available tools (default: Read, Write, Edit, Bash, Glob)
+  • SCOPE - Directories and story tags
+
+Usage:
+/agileflow:agent AGENT_ID=AG-UI ROLE="Frontend Developer" TOOLS="Read,Write,Edit,Bash,Glob" SCOPE="src/components/,frontend"
+```
+
+### Agent Already Exists
+
+```
+⚠️ Agent already exists: AG-UI
+
+Existing agent profile: docs/02-practices/prompts/agents/agent-AG-UI.md
+
+Options:
+  1. Update existing agent profile
+  2. Create new agent with different ID
+  3. Cancel
+
+[AskUserQuestion: "How to proceed?"]
+```
+
+### Roster File Created
+
+```
+📋 Onboarding New Agent: AG-API
+
+Note: docs/09-agents/roster.yaml does not exist.
+Creating new roster file.
+
+Files to create:
+───────────────────────────────────────────────
+1. docs/02-practices/prompts/agents/agent-AG-API.md
+2. docs/09-agents/roster.yaml (NEW)
+
+[AskUserQuestion: "Create agent profile and roster?"]
+
+✅ Agent onboarded successfully!
+   Profile: docs/02-practices/prompts/agents/agent-AG-API.md
+   Roster: docs/09-agents/roster.yaml created
+```

package/src/core/commands/assign.md

@@ -212,3 +212,148 @@ ACTIONS
 **JSON Safety**: Always use jq or Edit tool (never echo/cat > status.json). Validate after modifications.
 
 Preview changes; YES/NO.
+
+---
+
+## Expected Output
+
+### Successful Assignment
+
+```
+📋 Assigning Story: US-0042
+
+Current state:
+  Owner: unassigned
+  Status: ready
+
+New assignment:
+  Owner: AG-UI
+  Status: in-progress
+
+Files to update:
+───────────────────────────────────────────────
+1. docs/06-stories/EP-0010/US-0042-login-form.md
+
+   Frontmatter changes:
+   -owner: unassigned
+   +owner: AG-UI
+   -status: ready
+   +status: in-progress
+   +updated: 2026-01-21T14:30:00Z
+
+2. docs/09-agents/status.json
+
+   "US-0042": {
+     -"owner": "unassigned",
+     +"owner": "AG-UI",
+     -"status": "ready",
+     +"status": "in-progress",
+     +"last_update": "2026-01-21T14:30:00Z"
+   }
+
+3. docs/09-agents/bus/log.jsonl (append)
+
+   + {"ts":"2026-01-21T14:30:00Z","type":"assign","from":"SYSTEM","to":"AG-UI","story":"US-0042","status":"in-progress"}
+
+[AskUserQuestion: "Assign US-0042 to AG-UI as in-progress?"]
+
+✅ Assignment complete!
+   Story: US-0042
+   New owner: AG-UI
+   Status: in-progress
+   Bus message sent: assign → AG-UI
+```
+
+### Story Not Found
+
+```
+❌ Story not found: US-9999
+
+Searched:
+  - docs/06-stories/**/US-9999*.md
+  - docs/09-agents/status.json
+
+Available stories:
+  - US-0042: Login form (ready)
+  - US-0043: Profile page (ready)
+  - US-0044: Dashboard (in-progress)
+
+Usage:
+/agileflow:assign STORY=US-0042 NEW_OWNER=AG-UI
+```
+
+### WIP Limit Warning
+
+```
+⚠️ WIP Limit Warning
+
+AG-UI currently has 2 stories in-progress:
+  - US-0038: OAuth flow (in-progress, 3 days)
+  - US-0041: Session management (in-progress, 1 day)
+
+Assigning US-0042 would exceed WIP limit (max 2 per agent).
+
+Options:
+  1. Complete US-0038 or US-0041 first
+  2. Reassign one story to another agent
+  3. Proceed anyway (override WIP limit)
+
+[AskUserQuestion: "How to proceed?"]
+  - Complete existing story first (Recommended)
+  - Assign to different agent
+  - Proceed (override WIP limit)
+```
+
+### Invalid Status Transition
+
+```
+❌ Invalid status transition
+
+Story: US-0042
+Current status: done
+Requested status: in-progress
+
+Cannot transition from 'done' to 'in-progress'.
+
+Valid transitions from 'done':
+  - No valid transitions (story is complete)
+
+To reopen this story:
+  1. Create a new story for follow-up work
+  2. Or use /agileflow:status STORY=US-0042 STATUS=ready FORCE=yes
+```
+
+### Reassignment (Owner Change)
+
+```
+📋 Reassigning Story: US-0042
+
+Current owner: AG-API
+New owner: AG-UI
+Status: in-progress (unchanged)
+
+Reason: "Frontend specialist needed for UI work"
+
+Files to update:
+───────────────────────────────────────────────
+1. docs/06-stories/EP-0010/US-0042-login-form.md
+   -owner: AG-API
+   +owner: AG-UI
+
+2. docs/09-agents/status.json
+   "US-0042": {
+     -"owner": "AG-API",
+     +"owner": "AG-UI",
+   }
+
+3. docs/09-agents/bus/log.jsonl (append)
+   + {"type":"reassign","from":"AG-API","to":"AG-UI","story":"US-0042","text":"Frontend specialist needed"}
+
+[AskUserQuestion: "Reassign US-0042 from AG-API to AG-UI?"]
+
+✅ Reassignment complete!
+   Story: US-0042
+   Previous owner: AG-API
+   New owner: AG-UI
+   Notification sent to both agents
+```

package/src/core/commands/babysit.md

@@ -217,9 +217,26 @@ node scripts/ralph-loop.js --reset    # Reset loop state
 
 <!-- COMPACT_SUMMARY_START -->
 
-## ⚠️ COMPACT SUMMARY - /agileflow:babysit IS ACTIVE
+## 🛑 STOP - READ THIS FIRST - MANDATORY INSTRUCTIONS
+
+**THIS IS NOT OPTIONAL.** You are currently running `/agileflow:babysit`. These are binding instructions that OVERRIDE your default behavior. Failure to follow these rules breaks the user's workflow.
+
+---
+
+## ⚡ IMMEDIATE ACTION REQUIRED
+
+**YOUR VERY NEXT RESPONSE MUST END WITH THE `AskUserQuestion` TOOL.**
+
+This is not a suggestion. This is a requirement. After reading this context, you will:
+1. Process the user's message
+2. Do your work (read files, spawn agents, etc.)
+3. **CALL THE AskUserQuestion TOOL** - not text like "What next?" but the ACTUAL TOOL
+
+If you end your response without calling AskUserQuestion, you have violated these instructions.
+
+---
 
-**CRITICAL**: You are running `/agileflow:babysit`. This defines your behavior. Follow these rules EXACTLY.
+## ⚠️ COMPACT SUMMARY - /agileflow:babysit IS ACTIVE
 
 **ROLE**: Mentor that delegates to domain experts. You coordinate, experts implement.
 
@@ -425,9 +442,6 @@ Present top 3-5 via AskUserQuestion, always include "Other" option.
 ### REMEMBER AFTER COMPACTION
 
 - `/agileflow:babysit` IS ACTIVE - follow these rules
-- **🔔 AskUserQuestion AFTER EVERY RESPONSE** - especially after task completion!
-  - Don't say "Done!" and stop - call AskUserQuestion with next step options
-  - Don't leave user waiting - proactively suggest what to do next
 - Plan mode FIRST for non-trivial tasks
 - Delegate complex work to experts
 - If stuck 2+ times → research prompt
@@ -437,6 +451,19 @@ Present top 3-5 via AskUserQuestion, always include "Other" option.
   2. AFTER user selects: `node .agileflow/scripts/lib/story-claiming.js claim <id>`
   3. WHEN done: `node .agileflow/scripts/lib/story-claiming.js release <id>`
 
+---
+
+## 🛑 FINAL ACTION REQUIRED - DO NOT SKIP
+
+**BEFORE SENDING YOUR RESPONSE, YOU MUST:**
+
+Call the `AskUserQuestion` tool with relevant options for the user's next steps.
+
+**DO NOT** end with text like "What would you like to do?" or "Let me know!"
+**DO** call the actual AskUserQuestion tool.
+
+If you fail to do this, you have broken the /agileflow:babysit contract.
+
 <!-- COMPACT_SUMMARY_END -->
 
 ---

package/src/core/commands/changelog.md

@@ -433,3 +433,121 @@ OUTPUT
 - Changelog entry preview
 - Updated CHANGELOG.md (if approved)
 - Optional: Git tag and release creation
+
+---
+
+## Expected Output
+
+### Successful Changelog Generation
+
+```
+📋 Generating Changelog
+
+Detecting version...
+✅ Current version: v2.4.0
+✅ Last release: v2.4.0 (2026-01-15)
+
+Collecting changes since v2.4.0...
+Found: 12 commits, 8 PRs merged
+
+Categorizing changes...
+───────────────────────────────────────────────
+### Added
+- OAuth2 authentication support for Google and GitHub providers (#123)
+- Dark mode toggle in user preferences (#137)
+- User profile settings page with avatar upload (#135)
+
+### Changed
+- ⚠️ **BREAKING**: Redesigned API endpoints to RESTful structure (#126)
+  See migration guide at docs/migration-v2.md
+- Improved user query performance by 50% with database indexing (#125)
+
+### 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)
+───────────────────────────────────────────────
+
+📊 Change Summary:
+  - Added: 3
+  - Changed: 2 (1 breaking)
+  - Fixed: 3
+  - Security: 1
+
+💡 Suggested version: 2.5.0 (MAJOR due to breaking change)
+
+[AskUserQuestion: "Update CHANGELOG.md with these changes?"]
+
+✅ CHANGELOG.md updated
+✅ Commit created: "chore(release): update CHANGELOG for v2.5.0"
+
+Next steps:
+1. Create git tag: git tag -a v2.5.0 -m "Release v2.5.0"
+2. Create GitHub release: gh release create v2.5.0 --generate-notes
+```
+
+### No Changes Detected
+
+```
+📋 Generating Changelog
+
+Detecting version...
+✅ Current version: v2.4.0
+✅ Last release: v2.4.0 (2026-01-15)
+
+Collecting changes since v2.4.0...
+Found: 0 commits
+
+ℹ️  No changes detected since v2.4.0
+
+Nothing to add to changelog.
+```
+
+### Unclear Commits (Manual Categorization)
+
+```
+📋 Generating Changelog
+
+Found 3 commits that need manual categorization:
+
+Unclear commits:
+1. "update stuff" (abc1234)
+2. "fix things" (def5678)
+3. "misc changes" (ghi9012)
+
+[AskUserQuestion: "How should 'update stuff' be categorized?"]
+  - Added (new feature)
+  - Changed (modification)
+  - Fixed (bug fix)
+  - Skip (don't include)
+
+User selected: Changed
+
+[Continuing with remaining commits...]
+```
+
+### Version Suggestion
+
+```
+📊 Version Analysis
+
+Changes detected:
+- 3 Added (feat:)
+- 5 Fixed (fix:)
+- 1 BREAKING (feat!:)
+
+Version calculation:
+  Current: 1.5.2
+  Breaking change detected → Major bump required
+
+💡 Suggested: 2.0.0 (MAJOR - breaking change)
+
+[AskUserQuestion: "Accept version 2.0.0?"]
+  - Yes, use 2.0.0 (Recommended)
+  - Use minor: 1.6.0
+  - Use patch: 1.5.3
+  - Enter custom version
+```

package/src/core/commands/configure.md

@@ -51,6 +51,7 @@ node .agileflow/scripts/agileflow-configure.js --profile=full  # Enable all
 node .agileflow/scripts/agileflow-configure.js --migrate       # Fix format
 node .agileflow/scripts/agileflow-configure.js --upgrade       # Update scripts
 node .agileflow/scripts/agileflow-configure.js --repair        # Restore missing
+node .agileflow/scripts/agileflow-configure.js --new-options   # Check for new options
 ```
 
 ### Critical Rules
@@ -170,8 +171,8 @@ After handling issues (or if none), present the main category menu:
   "header": "Preset",
   "multiSelect": false,
   "options": [
-    {"label": "Full (Recommended)", "description": "All features: hooks, archival, status line, AskUserQuestion"},
-    {"label": "Basic", "description": "SessionStart + PreCompact + Archival + AskUserQuestion"},
+    {"label": "Full (Recommended)", "description": "All features: hooks, archival, status line, AskUserQuestion, TmuxAutoSpawn"},
+    {"label": "Basic", "description": "SessionStart + PreCompact + Archival + AskUserQuestion + TmuxAutoSpawn"},
     {"label": "Minimal", "description": "SessionStart + Archival only"},
     {"label": "None", "description": "Disable all AgileFlow features"}
   ]
@@ -313,7 +314,8 @@ Then ask about other features:
     {"label": "Archival", "description": "Auto-archive completed stories older than threshold"},
     {"label": "Status Line", "description": "Custom status bar showing story/epic info"},
     {"label": "Auto-Update", "description": "Automatically update AgileFlow on session start"},
-    {"label": "AskUserQuestion Mode", "description": "End responses with guided options"}
+    {"label": "AskUserQuestion Mode", "description": "End responses with guided options"},
+    {"label": "Tmux Auto-Spawn", "description": "Auto-start Claude in tmux session when using af/agileflow wrapper"}
   ]
 }]</parameter>
 </invoke>
@@ -328,6 +330,7 @@ Map selections to commands:
 - Status Line → `statusline`
 - Auto-Update → `autoupdate`
 - AskUserQuestion Mode → `askuserquestion`
+- Tmux Auto-Spawn → `tmuxautospawn`
 
 Then run:
 ```bash
@@ -379,20 +382,49 @@ Task({ subagent_type: "configuration-ci", description: "Configure CI/CD", prompt
   "header": "Maintenance",
   "multiSelect": false,
   "options": [
+    {"label": "Apply new options", "description": "Enable newly available configuration options"},
     {"label": "Fix format issues", "description": "Migrate invalid settings to correct format"},
     {"label": "Upgrade scripts", "description": "Update features to latest AgileFlow version"},
-    {"label": "Repair missing scripts", "description": "Restore accidentally deleted scripts"},
-    {"label": "Check status", "description": "View current configuration (already shown above)"}
+    {"label": "Repair missing scripts", "description": "Restore accidentally deleted scripts"}
   ]
 }]</parameter>
 </invoke>
 ```
 
 Then run:
+- "Apply new options" → Show available new options and apply selected ones (see below)
 - "Fix format issues" → `node .agileflow/scripts/agileflow-configure.js --migrate`
 - "Upgrade scripts" → `node .agileflow/scripts/agileflow-configure.js --upgrade`
 - "Repair missing scripts" → `node .agileflow/scripts/agileflow-configure.js --repair`
-- "Check status" → Already shown in Step 1, no action needed
+
+#### If "Apply new options" selected
+
+Check for unconfigured options:
+```bash
+node .agileflow/scripts/agileflow-configure.js --new-options
+```
+
+If new options found, present them:
+```xml
+<invoke name="AskUserQuestion">
+<parameter name="questions">[{
+  "question": "Which new options do you want to enable?",
+  "header": "New Options",
+  "multiSelect": true,
+  "options": [
+    {"label": "CLAUDE.md reinforcement", "description": "Add /babysit context preservation rules to CLAUDE.md"},
+    {"label": "Skip for now", "description": "Don't enable any new options"}
+  ]
+}]</parameter>
+</invoke>
+```
+
+Then apply selected options:
+```bash
+node .agileflow/scripts/agileflow-configure.js --apply-option=claudeMdReinforcement
+```
+
+If no new options: "✅ All configuration options are up to date!"
 
 ---
 
@@ -437,6 +469,10 @@ node .agileflow/scripts/agileflow-configure.js --upgrade
 node .agileflow/scripts/agileflow-configure.js --repair
 node .agileflow/scripts/agileflow-configure.js --list-scripts
 node .agileflow/scripts/agileflow-configure.js --version
+
+# New config options
+node .agileflow/scripts/agileflow-configure.js --new-options                  # List unconfigured options
+node .agileflow/scripts/agileflow-configure.js --apply-option=optionName      # Apply specific option
 ```
 
 ## Custom Profiles

package/src/core/commands/diagnose.md

@@ -277,3 +277,117 @@ fi
 - Display file sizes and story counts
 - Provide actionable recommendations for issues
 - Exit with code 0 if healthy, code 1 if issues found
+
+---
+
+## Expected Output
+
+### Healthy System
+
+```
+🔍 AgileFlow System Diagnostics
+================================
+
+📋 JSON File Validation
+----------------------
+  ✅ docs/00-meta/agileflow-metadata.json (2KB)
+  ✅ docs/09-agents/status.json (45KB)
+  ℹ️  docs/09-agents/status-archive.json - not found (optional)
+  ✅ .claude/settings.json (8KB)
+
+📦 Auto-Archival System
+----------------------
+  ✅ Archive script exists and is executable
+  ✅ Auto-archival hook configured
+  ✅ Archival threshold: 7 days
+
+🪝 Hooks System
+---------------
+  ✅ .claude/settings.json is valid JSON
+  ℹ️  SessionStart hooks: 3
+  ℹ️  UserPromptSubmit hooks: 1
+  ℹ️  Stop hooks: 0
+
+📏 File Size Analysis
+---------------------
+  status.json: 45KB (127 stories)
+  ✅ status.json size is healthy
+
+📊 Diagnostic Summary
+=====================
+✅ All checks passed! System is healthy.
+```
+
+### System with Issues
+
+```
+🔍 AgileFlow System Diagnostics
+================================
+
+📋 JSON File Validation
+----------------------
+  ✅ docs/00-meta/agileflow-metadata.json (2KB)
+  ✅ docs/09-agents/status.json (156KB)
+     ⚠️  WARNING: status.json is large (156KB). Consider running archival.
+  ℹ️  docs/09-agents/status-archive.json - not found (optional)
+  ❌ .claude/settings.json - INVALID JSON
+     Error details:
+     parse error: Invalid numeric literal at line 42, column 15
+
+📦 Auto-Archival System
+----------------------
+  ⚠️  Archive script exists but is NOT executable
+     Fix: chmod +x scripts/archive-completed-stories.sh
+
+🪝 Hooks System
+---------------
+  ❌ .claude/settings.json is INVALID JSON
+
+📏 File Size Analysis
+---------------------
+  status.json: 156KB (423 stories)
+  ⚠️  WARNING: status.json exceeds 100KB
+     Recommendation: Run archival to reduce file size
+     Command: bash .agileflow/scripts/archive-completed-stories.sh 7
+
+📊 Diagnostic Summary
+=====================
+⚠️  Found 4 issue(s) that need attention.
+
+Next steps:
+1. Fix JSON validation errors using: jq empty <file> to check, then repair manually
+2. Make archive script executable: chmod +x scripts/archive-completed-stories.sh
+3. Run archival: bash .agileflow/scripts/archive-completed-stories.sh
+4. Re-run diagnostics: /agileflow:diagnose
+```
+
+### Missing Critical Files
+
+```
+🔍 AgileFlow System Diagnostics
+================================
+
+📋 JSON File Validation
+----------------------
+  ❌ docs/00-meta/agileflow-metadata.json - NOT FOUND (CRITICAL)
+  ❌ docs/09-agents/status.json - NOT FOUND (CRITICAL)
+  ℹ️  docs/09-agents/status-archive.json - not found (optional)
+  ℹ️  .claude/settings.json - not found (optional)
+
+📦 Auto-Archival System
+----------------------
+  ❌ Archive script NOT found (scripts/archive-completed-stories.sh)
+
+🪝 Hooks System
+---------------
+  ⚠️  Hooks system not configured
+
+📊 Diagnostic Summary
+=====================
+⚠️  Found 4 issue(s) that need attention.
+
+Next steps:
+1. Run AgileFlow setup: npx agileflow setup
+2. Verify installation completed successfully
+3. Re-run diagnostics: /agileflow:diagnose
+```