agileflow 2.99.8 → 3.0.0

package/src/core/commands/babysit.md

@@ -5,16 +5,14 @@ compact_context:
   priority: critical
   preserve_rules:
     - "ACTIVE COMMAND: /agileflow-babysit - Mentor mode with expert delegation"
-    - "🔔 MANDATORY: Call AskUserQuestion tool at END of EVERY response - especially after completing tasks"
-    - "NEVER end with text like 'Done!' or 'What's next?' - ALWAYS use AskUserQuestion tool instead"
+    - "AskUserQuestion: ALWAYS end with it, but make it SMART - specific recommended option, contextual descriptions, logical next step"
+    - "NEVER generic AskUserQuestion like 'Continue?' - always specific: 'Run npm test for auth changes (Recommended)'"
+    - "BIAS TOWARD IMPLEMENTATION: Read 3-5 files max then start coding. Don't explore endlessly."
     - "{{RULES:plan_mode}}"
     - "{{RULES:delegation}}"
-    - "STUCK DETECTION: If same error 2+ times, suggest /agileflow:research:ask with 200+ line detailed prompt"
-    - "Research prompts MUST include: 50+ lines actual code, exact error, what was tried, 3+ specific questions"
+    - "STUCK DETECTION: If same error 2+ times, suggest /agileflow:research:ask with detailed prompt"
     - "PLAN FILE CONTEXT: BEFORE ExitPlanMode, EDIT plan file to add babysit rules header at TOP - rules survive context clear"
-    - "STORY CLAIMING: Run 'node .agileflow/scripts/lib/story-claiming.js claim <id>' IMMEDIATELY after user selects story"
-    - "STORY CLAIMING: Run 'node .agileflow/scripts/lib/story-claiming.js others' BEFORE suggesting stories, exclude 🔒 claimed"
-    - "STORY CLAIMING: Run 'node .agileflow/scripts/lib/story-claiming.js release <id>' when story marked done"
+    - "STORY CLAIMING: claim after selection, release after completion, check others before suggesting"
     - "LOGIC AUDIT: After implementation, offer '🔍 Run logic audit' option via AskUserQuestion (not automatic)"
   state_fields:
     - current_story
@@ -41,80 +39,84 @@ This gathers: git status, stories/epics, session state, docs structure, research
 
 ---
 
-## 🧠 SMART DETECTION (Auto-Enable Features)
+## 🧠 CONTEXTUAL FEATURE ROUTER
 
-**After running context script, automatically detect and enable features.**
+**After running context script, read `docs/09-agents/smart-detect.json` for programmatic recommendations.**
 
-Smart detection eliminates the need for users to specify parameters like `MODE=loop`, `VISUAL=true`, or `COVERAGE=80`. The mentor analyzes project context and enables appropriate features automatically.
+The smart detection system analyzes project signals deterministically (via `smart-detect.js`) and outputs contextual feature recommendations. This replaces manual signal analysis with script-driven detection.
 
-### Detection Rules
+### How It Works
 
-| Feature | Auto-Enable When | Override |
-|---------|------------------|----------|
-| **Loop Mode** | Epic has 3+ ready stories AND test setup exists | User says "just one story" or `MODE=once` |
-| **Visual Mode** | Epic/story mentions UI/component/styling OR owner=AG-UI | User says "no screenshots" or `VISUAL=false` |
-| **Coverage Mode** | `coverage/` dir exists with baseline >50% | User says "skip coverage" or `COVERAGE=0` |
-| **Conditions** | Auto-detect from package.json scripts (lint, tsc, build) | N/A (always apply detected) |
-| **Team Mode** | Agent Teams enabled + task spans multiple domains (API+UI) | User says "no teams" or `TEAM=false` |
+1. `obtain-context.js` gathers project data (status.json, git, metadata, session state)
+2. `smart-detect.js` runs 42 feature detectors against the data
+3. Results are written to `docs/09-agents/smart-detect.json`
+4. Context output includes a "Smart Recommendations" section
+5. You act on the recommendations below
 
-### Detection Flow
+### Reading Recommendations
 
-1. Parse context output for signals
-2. Check each detection rule
-3. Enable applicable features silently
-4. Inform user: "🧠 Auto-enabled: Loop Mode, Visual Mode (UI epic detected)"
-5. Proceed with work
+The context output's "Smart Recommendations" section contains:
 
-### Signal Detection
+- **Phase**: Current lifecycle phase (pre-story, planning, implementation, post-impl, pre-pr)
+- **Immediate**: High-priority features to act on NOW (suggest via AskUserQuestion or auto-run)
+- **Available**: Medium/low-priority features to include as AskUserQuestion options
+- **Auto-enabled**: Existing mode flags (loop_mode, visual_mode, coverage_mode)
 
-**Loop Mode signals:**
-- `status.json` has 3+ stories with status "ready" in same epic
-- `package.json` has "test" script
-- Stories have clear acceptance criteria
+### Acting on Recommendations
 
-**Visual Mode signals:**
-- Epic title contains: UI, component, frontend, styling, design
-- Story owner is "AG-UI"
-- Files in scope include: `src/components/`, `*.tsx`, `*.css`
-- `screenshots/` directory exists
-- Context shows "📸 VISUAL E2E TESTING: ENABLED"
+| Category | Action |
+|----------|--------|
+| **immediate** (high priority) | Present via AskUserQuestion with YES as default. If action=auto, run without asking. |
+| **available** (medium/low) | Include as options in your next AskUserQuestion. Group related features. |
+| **auto_enabled** modes | Enable Loop/Visual/Coverage modes silently, inform user. |
+| **skipped features** | Do NOT re-offer features the user already declined this session. |
 
-**Coverage Mode signals:**
-- `coverage/coverage-summary.json` exists
-- Current line coverage is >50%
-- Auto-set threshold to: current_coverage + 5%
+### Lifecycle-Aware Feature Routing
 
-**Team Mode signals:**
-- `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS` env var is set
-- Epic has stories with different owners (AG-API + AG-UI)
-- Task description mentions multiple domains (backend + frontend)
-- Template auto-selection: API+UI stories → `fullstack`, security review → `code-review`
-- When detected: Start native team via `/agileflow:team:start <template>`
+Features are filtered by lifecycle phase. Only phase-relevant features appear:
 
-**Conditions signals (auto-add all detected):**
-- `package.json` has "lint" → add "no linting errors"
-- `tsconfig.json` exists → add "no type errors"
-- `package.json` has "build" → add "build succeeds"
+| Phase | Focus | Example Features |
+|-------|-------|-----------------|
+| **pre-story** | Story selection, project planning | blockers, choose, board, sprint, batch |
+| **planning** | Impact analysis, architecture | impact, adr, research, council |
+| **implementation** | Code quality, testing | verify, tests, diagnose, ci, deps |
+| **post-impl** | Review, documentation | review, logic-audit, docs, changelog |
+| **pre-pr** | Final checks, PR creation | pr, compress |
 
-### Example Auto-Detection Output
+### User Overrides
 
-```
-🧠 Smart Detection Results:
-━━━━━━━━━━━━━━━━━━━━━━━━━━
-✓ Loop Mode: ENABLED (5 ready stories in EP-0042)
-✓ Visual Mode: ENABLED (epic mentions "UI components")
-✓ Coverage Mode: ENABLED @ 75% (current baseline: 70%)
-✓ Conditions: lint ✓, types ✓, build ✓
+Respect explicit user parameters (these override smart detection):
+- `/babysit MODE=once` → Force single story mode (overrides loop_mode)
+- `/babysit VISUAL=false` → Disable visual even if detected
+- `/babysit COVERAGE=0` → Disable coverage mode
+- User says "skip X" → Add to `features_skipped` in session state, don't re-offer
+
+### Session State Tracking
 
-Proceeding with: US-0050 (first ready story)
+Track offered/used/skipped features in session state to prevent re-offering:
+```json
+{
+  "smart_detect": {
+    "features_offered": ["impact", "tests"],
+    "features_used": ["impact"],
+    "features_skipped": ["tests"]
+  }
+}
 ```
 
-### User Override
+### Example Router Output
 
-If user explicitly specifies a parameter, respect it:
-- `/babysit EPIC=EP-0042 MODE=once` → Force single story mode
-- `/babysit VISUAL=false` → Disable visual even if detected
-- `/babysit COVERAGE=0` → Disable coverage mode
+```
+🧠 Contextual Feature Router:
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+Phase: implementation (5 files changed)
+Auto-enabled: loop mode, coverage mode
+
+! verify: Tests are failing (/agileflow:verify)
+! review: 250 lines changed - code review recommended (/agileflow:review)
+> docs: 2 API files changed - docs sync recommended (/agileflow:docs)
+> logic-audit: 4 source files modified (/agileflow:logic:audit)
+```
 
 ---
 
@@ -134,6 +136,22 @@ If user explicitly specifies a parameter, respect it:
 
 ---
 
+## SCALE-ADAPTIVE BEHAVIOR
+
+The context output includes a **Project Scale** section. Adjust your approach based on detected scale:
+
+| Scale | Planning Depth | Expert Usage | Workflow |
+|-------|---------------|--------------|----------|
+| **Micro** | Skip plan mode for most tasks. Implement directly. | 2 experts max | No epics needed. Quick stories or direct implementation. |
+| **Small** | Light planning. Skip plan mode for familiar tasks. | 3 experts max | Simple stories. Epics optional. |
+| **Medium** | Standard planning. Use plan mode for complex tasks. | 4 experts | Full story workflow with epics. |
+| **Large** | Thorough planning. Always use plan mode. | 5 experts | Full workflow with architecture review. |
+| **Enterprise** | Comprehensive planning with council review. | 5 experts | Full workflow with ADRs and multi-expert analysis. |
+
+**Important**: User can always override scale behavior. If they say "plan this carefully" for a micro project, do it.
+
+---
+
 <!-- SECTION: loop-mode -->
 ## LOOP MODE (Autonomous Execution)
 
@@ -178,7 +196,7 @@ To force single-story mode, say "just work on one story" or specify `MODE=once`.
 | `COVERAGE` | No | Auto-detected from coverage baseline; set `0` to disable |
 | `CONDITIONS` | No | Auto-detected from package.json; or configured in metadata |
 
-**Note:** Most parameters are auto-detected by Smart Detection. Only specify if you need to override the detected values.
+**Note:** Most parameters are auto-detected by the Contextual Feature Router. Only specify if you need to override the detected values.
 
 ### To Start Loop Mode
 
@@ -335,61 +353,61 @@ If you end your response without calling AskUserQuestion, you have violated thes
 
 ---
 
-### 🚨 RULE #0: SMART DETECTION (Before Starting)
-
-**After running context script, auto-detect and enable features:**
+### 🚨 RULE #0: CONTEXTUAL FEATURE ROUTER (Before Starting)
 
-| Feature | Auto-Enable When | Override |
-|---------|------------------|----------|
-| **Loop Mode** | 3+ ready stories + test setup | `MODE=once` or "just one story" |
-| **Visual Mode** | UI keywords or AG-UI owner | `VISUAL=false` or "no screenshots" |
-| **Coverage Mode** | coverage baseline >50% | `COVERAGE=0` or "skip coverage" |
-| **Conditions** | Auto-add from package.json scripts | N/A |
+**After running context script, read the "Smart Recommendations" section and act on it:**
 
-**Detection flow:**
-1. Parse context output
-2. Check detection rules
-3. Enable applicable features
-4. Inform user: "🧠 Auto-enabled: Loop Mode, Visual Mode..."
-5. Proceed with work
+1. Read `docs/09-agents/smart-detect.json` (or the recommendations in context output)
+2. Note the lifecycle phase and auto-enabled modes (loop/visual/coverage)
+3. **Immediate** recommendations → present via AskUserQuestion or auto-run
+4. **Available** recommendations → include as options in your next AskUserQuestion
+5. Inform user: "🧠 Phase: X | Auto-enabled: Y | Recommended: Z"
+6. Track offered/used/skipped features in session state
 
 ---
 
-### 🚨 RULE #1: ALWAYS END WITH AskUserQuestion (NEVER SKIP)
+### 🚨 RULE #1: ALWAYS END WITH SMART AskUserQuestion (NEVER SKIP)
 
-**EVERY response MUST end with the AskUserQuestion tool.** Not text like "Want me to...?" - the ACTUAL TOOL CALL.
+**EVERY response MUST end with the AskUserQuestion tool** - but make it SMART and contextual.
 
-**This applies (natural pause points):**
-- ✅ After completing a task (ESPECIALLY important - don't leave user hanging)
-- ✅ After spawning an agent and receiving results
-- ✅ When presenting options or decisions
-- ✅ Even when you think you're "done" - ask what's next
+**Smart suggestion principles:**
+- **Always have a Recommended option** - Mark the best next step with "(Recommended)" based on where you are in the workflow
+- **Be specific, not generic** - "Run tests for auth middleware" not "Run tests". "Implement the API endpoint next" not "Continue"
+- **Suggest the logical next step** - If you just finished planning, recommend "Start implementation". If code is written, recommend "Run tests". If tests pass, recommend "Commit changes"
+- **Include context in descriptions** - "3 files changed, 45 lines added" not just "Review changes"
+- **Offer 3-4 options max** - One recommended, one alternative, one "pause/other"
+
+**Contextual recommendations by phase:**
+| Phase | Recommended Option | Why |
+|-------|-------------------|-----|
+| After context gathering | The most impactful ready story | Based on epic progress, blockers, dependencies |
+| After plan approval | "Start implementing now" | Don't ask permission, suggest action |
+| After code is written | "Run tests to verify (Recommended)" | Always verify before committing |
+| After tests pass | "Commit and continue to next story" | Keep momentum |
+| After error | "Try [specific alternative approach]" | Don't just say "fix it" |
+| After expert returns | "Review and apply changes" or "Run tests" | Based on expert output quality |
 
 **Don't be annoying - DON'T ask for:**
 - ❌ Permission to read files, spawn experts, or do routine work
 - ❌ Confirmation of obvious next steps you should just do
 - ❌ Every micro-step in a workflow
 
-**Required format:**
-```xml
-<function_calls>
-<invoke name="AskUserQuestion">
-<parameter name="questions">[{
-  "question": "What would you like to do next?",
-  "header": "Next step",
-  "multiSelect": false,
-  "options": [
-    {"label": "Option A (Recommended)", "description": "Why this is best"},
-    {"label": "Option B", "description": "Alternative"},
-    {"label": "Pause", "description": "Stop here"}
-  ]
-}]</parameter>
-</invoke>
-</function_calls>
+**BAD (generic, unhelpful):**
+```json
+[{"label": "Continue", "description": "Keep going"},
+ {"label": "Pause", "description": "Stop here"}]
+```
+
+**GOOD (smart, contextual):**
+```json
+[{"label": "Run npm test to verify auth changes (Recommended)", "description": "3 files changed in packages/cli/scripts/ - verify before committing"},
+ {"label": "Review the withAuth middleware diff", "description": "14 files touched - quick review before testing"},
+ {"label": "Commit and move to US-0044", "description": "EP-0018 is 80% done - 2 stories left"},
+ {"label": "Pause here", "description": "Changes saved, not committed"}]
 ```
 
 **❌ WRONG:** "Want me to continue?" / "Should I proceed?" / "Done! Let me know what's next"
-**✅ RIGHT:** Call the AskUserQuestion tool with actual options - NEVER end without it
+**✅ RIGHT:** Call the AskUserQuestion tool with specific, contextual options - NEVER end without it
 
 ---
 
@@ -407,6 +425,17 @@ If you end your response without calling AskUserQuestion, you have violated thes
 
 ---
 
+### 🚨 RULE #2b: BIAS TOWARD IMPLEMENTATION
+
+**Don't explore endlessly. Start writing code early.**
+
+- Read at most 3-5 key files before starting implementation
+- If plan mode is active, keep exploration under 2 minutes
+- After plan approval, start implementing IMMEDIATELY - don't ask "ready?"
+- If a session is 10+ minutes in with zero code changes, something is wrong
+
+---
+
 ### 🚨 RULE #3: DELEGATION FRAMEWORK
 
 ```
@@ -561,9 +590,11 @@ After implementation completes, you MUST call AskUserQuestion with options like:
 11. Call `ExitPlanMode` for user approval
 
 **Phase 3: Execution**
-12. Delegate to experts based on scope
-13. Collect results if async (TaskOutput)
-14. Verify tests pass
+12. **AUTO-PROGRESS**: After plan approval, start implementing immediately - suggest "Start implementing now (Recommended)" not "Ready to implement?"
+13. Delegate to experts based on scope
+14. Collect results if async (TaskOutput)
+15. Verify tests pass
+16. AskUserQuestion with specific test results: "All tests pass - commit changes? (Recommended)"
 
 **Phase 4: Completion**
 15. Update status.json (mark story done)
@@ -669,10 +700,28 @@ After completing an implementation, offer logic audit as an **optional quality c
 
 ---
 
+### SMART ASKUSERQUESTION EXAMPLES
+
+After implementation:
+- "Run `npm test` in packages/cli/ (Recommended)" + "3 files changed, verify before commit"
+- "🔍 Run logic audit on modified files" + "5 analyzers check for edge cases"
+
+After tests pass:
+- "Commit: 'fix: resolve tmux socket path' (Recommended)" + "All tests pass"
+- "Review diff before committing" + "14 files touched"
+
+After error:
+- "Try alternative: use execFileSync instead (Recommended)" + "Current approach has shell injection risk"
+- "Run /agileflow:research:ask" + "Same error occurred twice"
+
+---
+
 ### REMEMBER AFTER COMPACTION
 
 - `/agileflow:babysit` IS ACTIVE - follow these rules
-- **SMART DETECTION**: Auto-enable Loop/Visual/Coverage modes based on context
+- **CONTEXTUAL ROUTER**: Read smart-detect.json for recommendations, act on immediate items
+- **SMART AskUserQuestion**: Always specific, always contextual, always with (Recommended) option
+- **BIAS TOWARD IMPLEMENTATION**: Read 3-5 files max then start coding
 - Plan mode FIRST for non-trivial tasks
 - Delegate complex work to experts
 - If stuck 2+ times → research prompt
@@ -1412,16 +1461,14 @@ After running context script:
 ```
 **AgileFlow Mentor** ready. I'll coordinate domain experts for your implementation.
 
-🧠 Smart Detection Results:
-━━━━━━━━━━━━━━━━━━━━━━━━━━
-[Show detected features based on context analysis]
-✓ Loop Mode: ENABLED/DISABLED (reason)
-✓ Visual Mode: ENABLED/DISABLED (reason)
-✓ Coverage Mode: ENABLED/DISABLED @ N% (reason)
-✓ Conditions: [detected from package.json]
+🧠 Contextual Router:
+━━━━━━━━━━━━━━━━━━━━
+Phase: [lifecycle phase] | [phase reason]
+[Show auto-enabled modes: loop/visual/coverage]
+[Show immediate recommendations if any]
 
 Based on your project state:
-[Present 3-5 ranked suggestions via AskUserQuestion]
+[Present 3-5 ranked suggestions via AskUserQuestion, incorporating smart-detect recommendations]
 
 **My approach:**
 1. You select a task

package/src/core/commands/changelog.md

@@ -95,19 +95,36 @@ Automatically generate changelog from PR titles, commits, and tags.
 - Memory leak in WebSocket handler (#139)
 ```
 
-**Tool Usage Example**:
+**Tool Usage Examples**:
+
+Post-generation (use actual commit counts):
+```xml
+<invoke name="AskUserQuestion">
+<parameter name="questions">[{
+  "question": "Changelog preview: [N] entries ([added] added, [fixed] fixed, [changed] changed). Suggested version: [version]. What next?",
+  "header": "Changelog",
+  "multiSelect": false,
+  "options": [
+    {"label": "Add [N] entries to CHANGELOG.md (Recommended)", "description": "Update changelog with [version] section and commit"},
+    {"label": "Preview entries first", "description": "Show full formatted changelog section before writing"},
+    {"label": "Edit entries manually", "description": "Adjust wording, recategorize, or remove entries"},
+    {"label": "Skip", "description": "Preview generated, no changes to CHANGELOG.md"}
+  ]
+}]</parameter>
+</invoke>
+```
+
 When commits need manual categorization:
 ```xml
 <invoke name="AskUserQuestion">
 <parameter name="questions">[{
-  "question": "How should this commit be categorized?",
-  "header": "Categorize Commit",
+  "question": "How should '[commit message]' be categorized?",
+  "header": "Categorize",
   "multiSelect": false,
   "options": [
     {"label": "Added", "description": "New feature or capability (feat:)"},
     {"label": "Changed", "description": "Modification or enhancement (refactor:, perf:)"},
     {"label": "Fixed", "description": "Bug fix (fix:)"},
-    {"label": "Security", "description": "Security fix (security:)"},
     {"label": "Skip", "description": "Don't include in changelog"}
   ]
 }]</parameter>

package/src/core/commands/configure.md

@@ -39,8 +39,9 @@ Main Menu → "What would you like to configure?"
 │                   └─ Custom: Save, Export, Import, Delete
 ├─ Features       → Enable | Disable | View status
 │                   └─ Hooks (4) + Other Features (4)
-├─ Sessions       → Default startup mode for new sessions
-│                   └─ Normal | Skip permissions | Accept edits | No Claude
+├─ Sessions       → Startup mode and Agent Teams configuration
+│                   ├─ Startup Mode: Normal | Skip permissions | Accept edits | No Claude
+│                   └─ Agent Teams: Enable/disable native multi-agent orchestration
 ├─ Infrastructure → Visual E2E | Damage Control | CI/CD | Quality Gates
 └─ Maintenance    → Fix format | Upgrade | Repair | Check status
 ```
@@ -390,6 +391,24 @@ node .agileflow/scripts/agileflow-configure.js --disable=feature1,feature2
 
 ### If "Sessions" selected
 
+Present the Sessions sub-menu:
+
+```xml
+<invoke name="AskUserQuestion">
+<parameter name="questions">[{
+  "question": "What session setting would you like to configure?",
+  "header": "Sessions",
+  "multiSelect": false,
+  "options": [
+    {"label": "Default startup mode", "description": "How Claude launches in new sessions (permissions, worktree-only)"},
+    {"label": "Agent Teams", "description": "Enable/disable native multi-agent orchestration (experimental)"}
+  ]
+}]</parameter>
+</invoke>
+```
+
+#### If "Default startup mode" selected
+
 Configure default startup mode for new sessions created with `/agileflow:session:new`.
 
 First, read current setting:
@@ -498,6 +517,88 @@ The 'af' command already reads the configured startup mode automatically.
 No additional changes needed.
 ```
 
+#### If "Agent Teams" selected
+
+Configure Claude Code's native multi-agent orchestration (experimental feature).
+
+First, read current setting:
+```bash
+node -e "try{const m=JSON.parse(require('fs').readFileSync('docs/00-meta/agileflow-metadata.json','utf8'));console.log(JSON.stringify({enabled:m.features?.agentTeams?.enabled||false}))}catch(e){console.log(JSON.stringify({enabled:false}))}"
+```
+
+Then present options:
+```xml
+<invoke name="AskUserQuestion">
+<parameter name="questions">[{
+  "question": "Enable native Agent Teams? This uses Claude Code's experimental multi-agent orchestration (TeamCreate, SendMessage) for parallel agent coordination.",
+  "header": "Agent Teams",
+  "multiSelect": false,
+  "options": [
+    {"label": "Enable (Recommended)", "description": "Use native Agent Teams when available, subagent fallback when not"},
+    {"label": "Disable", "description": "Always use subagent mode (Task/TaskOutput) for multi-agent work"},
+    {"label": "What is this?", "description": "Learn more about Agent Teams before deciding"}
+  ]
+}]</parameter>
+</invoke>
+```
+
+**If "Enable" selected:**
+```bash
+node .agileflow/scripts/agileflow-configure.js --enable=agentteams
+```
+
+Display:
+```
+✅ Native Agent Teams enabled
+
+When Claude Code sets CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1, AgileFlow will:
+  • Use native TeamCreate for parallel agent spawning
+  • Send messages via both native SendMessage AND JSONL bus
+  • Track team lifecycle events in session-state.json
+
+When the flag is not set, AgileFlow falls back to subagent mode automatically.
+```
+
+**If "Disable" selected:**
+```bash
+node .agileflow/scripts/agileflow-configure.js --disable=agentteams
+```
+
+Display:
+```
+✅ Native Agent Teams disabled
+
+AgileFlow will use subagent mode (Task/TaskOutput) for all multi-agent
+orchestration. This is the stable, well-tested mode.
+```
+
+**If "What is this?" selected:**
+
+Display this explanation:
+```
+## Agent Teams (Experimental)
+
+Claude Code's native Agent Teams feature enables parallel multi-agent
+orchestration with explicit coordination tools:
+
+  • TeamCreate/TeamDelete - Spawn and manage agent teams
+  • SendMessage - Direct agent-to-agent communication (3ms vs 150ms JSONL)
+  • Enhanced TaskCreate/Update - Native task coordination
+
+How AgileFlow integrates:
+  1. When enabled, team-manager.js builds native TeamCreate payloads
+  2. messaging-bridge.js sends to BOTH native channel AND JSONL bus
+  3. damage-control-multi-agent.js validates Team/Task operations
+  4. Subagent mode remains available as automatic fallback
+
+Requirements:
+  • Claude Code must set CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1
+  • Feature is opt-in per project via this configuration
+  • CI/CD always uses subagent mode (safety gate)
+```
+
+Then re-ask the enable/disable question.
+
 ---
 
 ### If "Infrastructure" selected
@@ -637,6 +738,8 @@ node .agileflow/scripts/agileflow-configure.js --disable=statusline
 node .agileflow/scripts/agileflow-configure.js --enable=archival --archival-days=14
 node .agileflow/scripts/agileflow-configure.js --enable=shellaliases
 node .agileflow/scripts/agileflow-configure.js --enable=claudemdreinforcement
+node .agileflow/scripts/agileflow-configure.js --enable=agentteams
+node .agileflow/scripts/agileflow-configure.js --disable=agentteams
 
 # Maintenance
 node .agileflow/scripts/agileflow-configure.js --detect

package/src/core/commands/debt.md

@@ -119,10 +119,20 @@ Clear separation: AuthService, AuthRepository, AuthController...</parameter>
 </invoke>
 ```
 
-**AskUserQuestion** (for approval):
+**AskUserQuestion** (use actual counts from scan):
 ```xml
 <invoke name="AskUserQuestion">
-<parameter name="questions">[{"question": "Generate stories for critical debt?", "header": "Action", "multiSelect": false, "options": [{"label": "Yes, create stories", "description": "Generate stories for top 5 critical items"}, {"label": "No, report only", "description": "Save report without creating stories"}]}]</parameter>
+<parameter name="questions">[{
+  "question": "Found [N] debt items ([critical] critical, [high] high). Total effort: ~[days] days. What next?",
+  "header": "Action",
+  "multiSelect": false,
+  "options": [
+    {"label": "Generate [N] stories for critical items (Recommended)", "description": "Create trackable stories for the [critical] critical-severity debt items"},
+    {"label": "Review debt items in detail first", "description": "Show full analysis for each item before deciding"},
+    {"label": "Export debt report to docs/08-project/", "description": "Save report as tech-debt-[date].md for team review"},
+    {"label": "Skip for now", "description": "Scan complete, [N] items identified"}
+  ]
+}]</parameter>
 </invoke>
 ```
 

package/src/core/commands/feedback.md

@@ -194,17 +194,18 @@ Suggested Story: "US-XXXX: Improve story template with AC examples"
 </invoke>
 ```
 
-**AskUserQuestion** (for feedback permission):
+**AskUserQuestion** (use actual story/sprint context):
 ```xml
 <invoke name="AskUserQuestion">
 <parameter name="questions">[{
-  "question": "Provide feedback on US-0042 completion?",
-  "header": "Optional Feedback",
+  "question": "[STORY] completed in [duration]. Quick feedback? (optional, ~2 min)",
+  "header": "Feedback",
   "multiSelect": false,
   "options": [
-    {"label": "Yes, provide feedback", "description": "Take 2-3 min to share insights"},
-    {"label": "Not now", "description": "Skip feedback"},
-    {"label": "Remind me later", "description": "Ask again next time"}
+    {"label": "Rate this story's workflow (Recommended)", "description": "Quick 1-5 ratings on AC clarity, estimate accuracy, and smoothness"},
+    {"label": "Report a workflow issue", "description": "Flag a specific problem encountered during [STORY]"},
+    {"label": "Suggest process improvement", "description": "Share an idea based on what you learned"},
+    {"label": "Skip for now", "description": "No feedback needed for [STORY]"}
   ]
 }]</parameter>
 </invoke>

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

@@ -173,7 +173,7 @@ Consolidate into unified error handling with typed exceptions.
 💡 Actions:
   • Create story: /agileflow:story "Error Handling Consolidation"
   • Mark in progress: Update ideation index manually
-  • View original report: Read docs/08-project/ideation-20260106.md
+  • View original report: Read docs/08-project/ideation/ideation-20260106.md
 ```
 
 **Status Filter Output** (when STATUS=pending):