agileflow 2.37.1 → 2.38.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agileflow",
-  "version": "2.37.1",
+  "version": "2.38.0",
   "description": "AI-driven agile development system for Claude Code, Cursor, Windsurf, and more",
   "keywords": [
     "agile",

package/src/core/agents/api.md

@@ -364,6 +364,30 @@ RESEARCH INTEGRATION
 - Validation libraries (Zod, Yup, class-validator)
 - External integrations (Stripe, SendGrid, Twilio, etc.)
 
+PLAN MODE FOR COMPLEX API WORK
+
+**Reference**: `@docs/02-practices/plan-mode.md`
+
+Before implementing, evaluate complexity:
+
+| Situation | Action |
+|-----------|--------|
+| Simple CRUD endpoint | Just implement it |
+| Schema migration | → `EnterPlanMode` (analyze impact) |
+| New auth pattern | → `EnterPlanMode` (architectural decision) |
+| External integration | → `EnterPlanMode` (research first) |
+| Multi-service changes | → `EnterPlanMode` (coordinate approach) |
+
+**Plan Mode Workflow**:
+1. `EnterPlanMode` → Read-only exploration
+2. Explore existing API patterns (routes, middleware, validation)
+3. Design endpoint/schema approach
+4. Present plan with file paths
+5. Get approval → `ExitPlanMode`
+6. Implement
+
+**Skip Plan Mode For**: Single endpoint additions following existing patterns, simple CRUD operations, minor bug fixes.
+
 WORKFLOW
 1. **[KNOWLEDGE LOADING]** Before implementation:
    - Read CLAUDE.md for project-specific API conventions

package/src/core/agents/configuration/archival.md

@@ -20,6 +20,8 @@ Configure auto-archival system to manage status.json file size.
 
 ROLE: Auto-Archival Configurator
 
+🔴 **AskUserQuestion Format**: NEVER ask users to "type" anything. Use proper options with XML invoke format. See `docs/02-practices/ask-user-question.md`.
+
 OBJECTIVE
 Configure the auto-archival system that prevents `docs/09-agents/status.json` from exceeding Claude Code's token limit by automatically moving old completed stories to an archive.
 

package/src/core/agents/configuration/attribution.md

@@ -20,6 +20,8 @@ Configure CLAUDE.md file with git attribution preferences.
 
 ROLE: Attribution Configurator
 
+🔴 **AskUserQuestion Format**: NEVER ask users to "type" anything. Use proper options with XML invoke format. See `docs/02-practices/ask-user-question.md`.
+
 OBJECTIVE
 Create or update CLAUDE.md with user's git attribution preferences. CLAUDE.md is the AI assistant's primary configuration file and controls whether Claude Code adds attribution to git commits.
 

package/src/core/agents/configuration/ci.md

@@ -20,6 +20,8 @@ Configure automated CI/CD workflow for testing, linting, and quality checks.
 
 ROLE: CI/CD Configurator
 
+🔴 **AskUserQuestion Format**: NEVER ask users to "type" anything. Use proper options with XML invoke format. See `docs/02-practices/ask-user-question.md`.
+
 OBJECTIVE
 Set up continuous integration and deployment workflows to automate testing, linting, type checking, and build verification on every commit/PR.
 

package/src/core/agents/configuration/git-config.md

@@ -20,6 +20,8 @@ Configure git initialization and remote repository connection.
 
 ROLE: Git Configuration Specialist
 
+🔴 **AskUserQuestion Format**: NEVER ask users to "type" anything. Use proper options with XML invoke format. See `docs/02-practices/ask-user-question.md`.
+
 OBJECTIVE
 Set up git repository with remote connection to enable version control, team collaboration, and backup for the AgileFlow project.
 

package/src/core/agents/configuration/hooks.md

@@ -19,6 +19,8 @@ Configure hooks system for event-driven automation in Claude Code.
 
 ROLE: Hooks System Configurator
 
+🔴 **AskUserQuestion Format**: NEVER ask users to "type" anything. Use proper options with XML invoke format. See `docs/02-practices/ask-user-question.md`.
+
 OBJECTIVE
 Set up the hooks system that enables event-driven automation in Claude Code. Hooks automatically execute shell commands when Claude Code lifecycle events occur (SessionStart, UserPromptSubmit, Stop).
 

package/src/core/agents/configuration/status-line.md

@@ -19,6 +19,8 @@ Configure a custom status line for Claude Code that displays AgileFlow project c
 
 ROLE: Status Line Configurator
 
+🔴 **AskUserQuestion Format**: NEVER ask users to "type" anything. Use proper multi-select options with XML invoke format. See `docs/02-practices/ask-user-question.md`.
+
 OBJECTIVE
 Set up a custom AgileFlow status line that displays contextual information at the bottom of Claude Code. The status line shows current story, work-in-progress count, context usage, session cost, and git branch.
 

package/src/core/agents/configuration/verify.md

@@ -20,6 +20,8 @@ Verify that configurations work and handle authentication for private repositori
 
 ROLE: Configuration Verification Specialist
 
+🔴 **AskUserQuestion Format**: NEVER ask users to "type" anything. Use proper options with XML invoke format. See `docs/02-practices/ask-user-question.md`.
+
 OBJECTIVE
 Verify that configurations actually work by running test commands and checking results. Handle authentication tokens securely for private repositories.
 
@@ -82,37 +84,61 @@ fi
 
 **ALWAYS ask permission first**:
 
-```javascript
-const needsToken = AskUserQuestion({
-  question: "Verification requires a GitHub personal access token. Do you want to provide one?",
-  options: ["Yes, I'll provide a token", "No, skip verification"]
-})
-
-if (needsToken === "No, skip verification") {
-  echo "⏭️ Skipping verification"
-  exit 0
-}
+```xml
+<invoke name="AskUserQuestion">
+<parameter name="questions">[{
+  "question": "Verification requires a GitHub personal access token. Do you want to provide one?",
+  "header": "Token",
+  "multiSelect": false,
+  "options": [
+    {"label": "Yes, provide token (Recommended)", "description": "I'll enter my GitHub PAT for verification"},
+    {"label": "No, skip verification", "description": "Skip verification - configure manually later"}
+  ]
+}]</parameter>
+</invoke>
 ```
 
-**Then ask for token**:
+If user selects "No, skip verification":
+```bash
+echo "⏭️ Skipping verification"
+exit 0
+```
 
-```javascript
-const token = AskUserQuestion({
-  question: "Enter your GitHub personal access token (ghp_xxx):\n\nCreate one at: https://github.com/settings/tokens/new\nRequired scopes: repo, workflow\n\nToken:"
-})
+**Then ask for token** (user selects "Other" to enter custom text):
+
+```xml
+<invoke name="AskUserQuestion">
+<parameter name="questions">[{
+  "question": "Enter your GitHub personal access token. Create at: github.com/settings/tokens/new (scopes: repo, workflow)",
+  "header": "Token",
+  "multiSelect": false,
+  "options": [
+    {"label": "Skip - I'll enter later", "description": "Skip token entry for now"},
+    {"label": "Other", "description": "Enter token (select this, paste ghp_xxx in text field)"}
+  ]
+}]</parameter>
+</invoke>
 ```
 
 **Offer to save token**:
 
-```javascript
-const saveToken = AskUserQuestion({
-  question: "Save token to .claude/settings.local.json for future use? (Recommended - file is gitignored)",
-  options: ["Yes, save token", "No, use once only"]
-})
+```xml
+<invoke name="AskUserQuestion">
+<parameter name="questions">[{
+  "question": "Save token to .claude/settings.local.json for future use?",
+  "header": "Save token",
+  "multiSelect": false,
+  "options": [
+    {"label": "Yes, save token (Recommended)", "description": "Store securely in .claude/settings.local.json (gitignored)"},
+    {"label": "No, use once only", "description": "Don't save - you'll be asked again next time"}
+  ]
+}]</parameter>
+</invoke>
+```
 
-if (saveToken === "Yes, save token") {
-  // Save to .claude/settings.local.json
-}
+If user selected "Yes, save token":
+```bash
+# Save to .claude/settings.local.json
 ```
 
 ### Saving Token Securely
@@ -151,11 +177,18 @@ save_token "GITHUB_TOKEN" "$token"
 - Do we have push permissions?
 
 **Ask permission first**:
-```javascript
-const verifyGit = AskUserQuestion({
-  question: "Verify git remote connection? (This will test if you can access the repository)",
-  options: ["Yes, verify", "No, skip"]
-})
+```xml
+<invoke name="AskUserQuestion">
+<parameter name="questions">[{
+  "question": "Verify git remote connection? (Tests if you can access the repository)",
+  "header": "Verify git",
+  "multiSelect": false,
+  "options": [
+    {"label": "Yes, verify (Recommended)", "description": "Test connection to remote repository"},
+    {"label": "No, skip", "description": "Skip verification - test manually later"}
+  ]
+}]</parameter>
+</invoke>
 ```
 
 **Verification command**:
@@ -232,11 +265,18 @@ validate_github_workflow() {
 **Step 2: Test commands locally**
 
 **Ask permission**:
-```javascript
-const testLocally = AskUserQuestion({
-  question: "Test CI commands locally? (This will run: npm test, npm run lint, etc.)",
-  options: ["Yes, run tests now", "No, skip local testing"]
-})
+```xml
+<invoke name="AskUserQuestion">
+<parameter name="questions">[{
+  "question": "Test CI commands locally? (This will run: npm test, npm run lint, etc.)",
+  "header": "Test local",
+  "multiSelect": false,
+  "options": [
+    {"label": "Yes, run tests now (Recommended)", "description": "Execute CI commands locally to catch issues early"},
+    {"label": "No, skip local testing", "description": "Skip local testing - assume commands work"}
+  ]
+}]</parameter>
+</invoke>
 ```
 
 **Run commands**:
@@ -279,11 +319,18 @@ test_ci_commands "npm ci" "npm test" "npm run lint" "npm run build"
 **Step 3: Trigger CI run (optional)**
 
 **Ask permission**:
-```javascript
-const triggerCI = AskUserQuestion({
-  question: "Trigger a test CI run? (Requires GitHub token with workflow scope)",
-  options: ["Yes, trigger CI run", "No, I'll push manually"]
-})
+```xml
+<invoke name="AskUserQuestion">
+<parameter name="questions">[{
+  "question": "Trigger a test CI run? (Requires GitHub token with workflow scope)",
+  "header": "Trigger CI",
+  "multiSelect": false,
+  "options": [
+    {"label": "Yes, trigger CI run", "description": "Use GitHub API to trigger workflow now"},
+    {"label": "No, I'll push manually (Recommended)", "description": "Skip - CI will run when you push code"}
+  ]
+}]</parameter>
+</invoke>
 ```
 
 **Trigger via API**:
@@ -366,11 +413,18 @@ test_get_env() {
 ```
 
 **Test hook execution** (MUST ask permission):
-```javascript
-const testHook = AskUserQuestion({
-  question: "Test SessionStart hook? (This will execute the hook commands)",
-  options: ["Yes, test hook", "No, skip"]
-})
+```xml
+<invoke name="AskUserQuestion">
+<parameter name="questions">[{
+  "question": "Test SessionStart hook? (This will execute the hook commands)",
+  "header": "Test hook",
+  "multiSelect": false,
+  "options": [
+    {"label": "Yes, test hook (Recommended)", "description": "Execute hook commands to verify they work"},
+    {"label": "No, skip", "description": "Skip hook testing"}
+  ]
+}]</parameter>
+</invoke>
 ```
 
 ### 4. Archival Verification

package/src/core/agents/database.md

@@ -305,6 +305,31 @@ SLASH COMMANDS
 - `/agileflow:impact-analysis` → Analyze impact of schema changes on other tables
 - `/agileflow:status STORY=... STATUS=...` → Update status
 
+PLAN MODE FOR DATABASE CHANGES (CRITICAL)
+
+**Reference**: `@docs/02-practices/plan-mode.md`
+
+**Database changes are high-risk**. Always plan before schema modifications:
+
+| Situation | Action |
+|-----------|--------|
+| Simple query optimization | May skip planning |
+| New table/column | → `EnterPlanMode` (design schema) |
+| Schema migration | → `EnterPlanMode` (rollback strategy) |
+| Index changes | → `EnterPlanMode` (analyze query patterns) |
+| Data model refactoring | → `EnterPlanMode` (impact on all queries) |
+
+**Plan Mode Workflow**:
+1. `EnterPlanMode` → Read-only exploration
+2. Map current schema and relationships
+3. Identify all queries affected by change
+4. Design migration with rollback strategy
+5. Plan data migration if needed
+6. Present plan → Get approval → `ExitPlanMode`
+7. Implement with reversible migrations
+
+**Database Principle**: Schema changes are permanent. Plan twice, migrate once.
+
 WORKFLOW
 
 1. **[KNOWLEDGE LOADING]**:

package/src/core/agents/devops.md

@@ -291,6 +291,31 @@ RESEARCH INTEGRATION
 - Monitoring and observability (Prometheus, Grafana, Datadog, Sentry)
 - Infrastructure as Code (Terraform, Pulumi, CloudFormation)
 
+PLAN MODE FOR INFRASTRUCTURE CHANGES
+
+**Reference**: `@docs/02-practices/plan-mode.md`
+
+**Infrastructure changes affect production**. Plan before deploying:
+
+| Situation | Action |
+|-----------|--------|
+| Minor config tweak | May skip planning |
+| New CI/CD pipeline | → `EnterPlanMode` (design workflow) |
+| Deployment strategy change | → `EnterPlanMode` (rollback plan) |
+| Infrastructure as Code | → `EnterPlanMode` (terraform plan) |
+| Environment changes | → `EnterPlanMode` (impact analysis) |
+
+**Plan Mode Workflow**:
+1. `EnterPlanMode` → Read-only exploration
+2. Map current infrastructure and dependencies
+3. Design change with rollback strategy
+4. Identify blast radius (what breaks if this fails?)
+5. Plan monitoring/alerting for the change
+6. Present plan → Get approval → `ExitPlanMode`
+7. Implement with verification at each step
+
+**DevOps Principle**: Infrastructure is cattle, not pets—but still needs planning.
+
 WORKFLOW
 1. **[KNOWLEDGE LOADING]** Before implementation:
    - Read CLAUDE.md for project-specific infrastructure setup

package/src/core/agents/mentor.md

@@ -241,6 +241,41 @@ IMPLEMENTATION FLOW
 8. Generate PR body with /agileflow:pr-template command
 9. Suggest syncing docs/context.md and saving research if applicable
 
+PLAN MODE FOR COMPLEX IMPLEMENTATIONS
+
+**Reference**: `@docs/02-practices/plan-mode.md`
+
+Before implementing, evaluate task complexity:
+
+| Situation | Action |
+|-----------|--------|
+| Trivial fix (typo, small tweak) | Just do it |
+| Specific instructions given | Follow directly |
+| Research/exploration only | Use Task tool with Explore agent |
+| Complex/multi-file/unclear | → `EnterPlanMode` first |
+
+**When to Enter Plan Mode**:
+- New features with multiple valid approaches
+- Multi-file changes or refactoring
+- Architectural decisions (choosing patterns, libraries, approaches)
+- Unclear requirements (need to explore before designing)
+
+**Plan Mode Workflow**:
+1. `EnterPlanMode` → Read-only exploration
+2. Explore codebase with Glob, Grep, Read
+3. Design implementation approach
+4. Present plan with file paths and steps
+5. Clarify decisions with user
+6. Get approval → `ExitPlanMode`
+7. Implement the approved plan
+
+**Plan Quality Checklist**:
+- [ ] Explored relevant codebase
+- [ ] Identified all files to change
+- [ ] Considered existing patterns
+- [ ] Noted risks/breaking changes
+- [ ] Got user approval
+
 AGENT COORDINATION PATTERNS
 
 **When to Delegate to Specialized Agents**:

package/src/core/agents/performance.md

@@ -308,6 +308,31 @@ SLASH COMMANDS
 - `/agileflow:impact-analysis` → Analyze performance impact of changes
 - `/agileflow:status STORY=... STATUS=...` → Update status
 
+PLAN MODE FOR PERFORMANCE OPTIMIZATION
+
+**Reference**: `@docs/02-practices/plan-mode.md`
+
+**Performance work requires measurement first**. Always plan before optimizing:
+
+| Situation | Action |
+|-----------|--------|
+| "Make it faster" (vague) | → `EnterPlanMode` (profile first!) |
+| Known bottleneck | → `EnterPlanMode` (design optimization) |
+| Caching implementation | → `EnterPlanMode` (invalidation strategy) |
+| Query optimization | → `EnterPlanMode` (measure before/after) |
+| Bundle size reduction | → `EnterPlanMode` (analyze dependencies) |
+
+**Plan Mode Workflow**:
+1. `EnterPlanMode` → Read-only exploration
+2. **Profile first** - measure current performance
+3. Identify actual bottlenecks (not assumptions)
+4. Design optimization with benchmarks
+5. Plan verification (how to prove it's faster?)
+6. Present plan → Get approval → `ExitPlanMode`
+7. Implement, measure, verify improvement
+
+**Performance Principle**: Measure, don't guess. Premature optimization is the root of all evil.
+
 WORKFLOW
 
 1. **[KNOWLEDGE LOADING]**:

package/src/core/agents/refactor.md

@@ -345,6 +345,31 @@ SLASH COMMANDS
 - `/agileflow:impact-analysis` → Analyze impact of refactoring changes
 - `/agileflow:status STORY=... STATUS=...` → Update status
 
+PLAN MODE FOR REFACTORING (ALWAYS USE)
+
+**Reference**: `@docs/02-practices/plan-mode.md`
+
+**Refactoring REQUIRES planning**. Always enter plan mode before refactoring:
+
+| Situation | Action |
+|-----------|--------|
+| ANY refactoring work | → `EnterPlanMode` |
+| Rename across codebase | → `EnterPlanMode` (find all usages) |
+| Extract component/function | → `EnterPlanMode` (identify dependencies) |
+| Architectural changes | → `EnterPlanMode` (impact analysis) |
+| Technical debt cleanup | → `EnterPlanMode` (prioritize changes) |
+
+**Plan Mode Workflow**:
+1. `EnterPlanMode` → Read-only exploration
+2. Map current architecture and dependencies
+3. Identify all affected files and tests
+4. Design migration path (small, reversible steps)
+5. Note breaking changes and risks
+6. Present plan → Get approval → `ExitPlanMode`
+7. Implement incrementally, verify tests after each step
+
+**Refactoring Principle**: Never refactor without a plan. Small changes cascade.
+
 WORKFLOW
 
 1. **[KNOWLEDGE LOADING]**:

package/src/core/agents/security.md

@@ -303,6 +303,31 @@ AGENT COORDINATION
 {"ts":"2025-10-21T10:10:00Z","from":"AG-SECURITY","type":"status","story":"US-0050","text":"Security review complete: 3 high vulnerabilities found in dependency X, recommended updates"}
 ```
 
+PLAN MODE FOR SECURITY IMPLEMENTATIONS
+
+**Reference**: `@docs/02-practices/plan-mode.md`
+
+**Security changes require careful planning**. Always plan before implementing:
+
+| Situation | Action |
+|-----------|--------|
+| Simple dependency update | May skip planning |
+| New auth mechanism | → `EnterPlanMode` (design security model) |
+| Vulnerability remediation | → `EnterPlanMode` (root cause analysis) |
+| Access control changes | → `EnterPlanMode` (audit impact) |
+| Encryption/secrets handling | → `EnterPlanMode` (key management plan) |
+
+**Plan Mode Workflow**:
+1. `EnterPlanMode` → Read-only exploration
+2. Audit current security posture
+3. Identify all attack surfaces affected
+4. Design fix with defense-in-depth approach
+5. Plan verification (how to prove it's secure?)
+6. Present plan → Get approval → `ExitPlanMode`
+7. Implement with security review at each step
+
+**Security Principle**: Security is not a feature—it's a property. Plan comprehensively.
+
 WORKFLOW
 
 1. **[KNOWLEDGE LOADING]** Before review:

package/src/core/agents/ui.md

@@ -606,6 +606,30 @@ RESEARCH INTEGRATION
 - Animation libraries (Framer Motion, React Spring, GSAP)
 - State management for UI (React Context, Zustand, Redux)
 
+PLAN MODE FOR COMPLEX UI WORK
+
+**Reference**: `@docs/02-practices/plan-mode.md`
+
+Before implementing, evaluate complexity:
+
+| Situation | Action |
+|-----------|--------|
+| Simple component tweak | Just implement it |
+| New design system pattern | → `EnterPlanMode` (explore existing patterns) |
+| Multi-component feature | → `EnterPlanMode` (plan component hierarchy) |
+| Responsive/accessibility overhaul | → `EnterPlanMode` (audit first) |
+| State management changes | → `EnterPlanMode` (impact analysis) |
+
+**Plan Mode Workflow**:
+1. `EnterPlanMode` → Read-only exploration
+2. Explore existing UI patterns (components, styles, state)
+3. Design component structure and props
+4. Present plan with file paths
+5. Get approval → `ExitPlanMode`
+6. Implement
+
+**Skip Plan Mode For**: Single component additions following existing patterns, style tweaks, minor bug fixes.
+
 WORKFLOW
 1. **[PROACTIVE - First Story Only]** Check for design system (see DESIGN SYSTEM INITIALIZATION section above)
    - If none exists → Ask to create one

package/src/core/commands/babysit.md

@@ -29,6 +29,8 @@ ROLE: Babysitter (Mentor + Orchestrator)
 
 **Principle**: Be helpful, not annoying. Ask for decisions, not permissions.
 
+🔴 **Format**: NEVER ask users to "type" anything. Use proper options with XML invoke format. See `docs/02-practices/ask-user-question.md`.
+
 ---
 
 TODO LIST TRACKING
@@ -544,6 +546,62 @@ This ensures the expert loads their mental model before working.
 
 ---
 
+PLAN MODE FOR COMPLEX IMPLEMENTATIONS
+
+**Reference**: `@docs/02-practices/plan-mode.md`
+
+Before implementing features, evaluate complexity to decide whether to plan first or implement directly.
+
+**Decision Tree**:
+```
+Is this a trivial fix (typo, obvious bug, small tweak)?
+  → Just do it (no planning needed)
+
+Are specific, detailed instructions given?
+  → Follow instructions directly
+
+Is this research/exploration only?
+  → Use Task tool with Explore agent (no plan mode)
+
+Is this complex, multi-file, or unclear?
+  → EnterPlanMode FIRST
+```
+
+**When to Enter Plan Mode**:
+| Trigger | Example |
+|---------|---------|
+| New feature with choices | "Add user authentication" (JWT vs sessions?) |
+| Multiple valid approaches | "Add caching" (Redis vs in-memory?) |
+| Multi-file changes | "Refactor the auth system" |
+| Architectural decisions | "Add real-time updates" (WebSocket vs SSE?) |
+| Unclear requirements | "Make the app faster" |
+
+**Plan Mode Workflow**:
+1. `EnterPlanMode` → Switches to read-only exploration
+2. Explore with Glob, Grep, Read (understand codebase)
+3. Design implementation approach
+4. Present plan to user with file paths and steps
+5. Use AskUserQuestion to clarify decisions
+6. Get user approval
+7. `ExitPlanMode` → Resume with write access
+8. Implement the approved plan
+
+**Skip Plan Mode For**:
+- Single-line or few-line fixes
+- Adding a single function with clear requirements
+- Tasks where user gave very specific instructions
+- Pure research (use Task tool with Explore agent)
+
+**Plan Quality Checklist** (before ExitPlanMode):
+- [ ] Explored relevant parts of codebase
+- [ ] Identified all files that need changes
+- [ ] Considered existing patterns/conventions
+- [ ] Noted potential risks or breaking changes
+- [ ] Presented clear implementation steps
+- [ ] Got explicit user approval
+
+---
+
 ERROR HANDLING & RECOVERY
 
 When things go wrong, diagnose the issue and provide recovery steps. Follow the general recovery pattern:

package/src/core/commands/configure.md

@@ -11,6 +11,8 @@ Interactive orchestrator for configuring advanced AgileFlow features.
 
 ROLE: Configuration Orchestrator
 
+🔴 **AskUserQuestion Format**: NEVER ask users to "type" anything. Use proper options with XML invoke format. See `docs/02-practices/ask-user-question.md`.
+
 OBJECTIVE
 Guide users through interactive configuration of advanced AgileFlow features by spawning specialized configuration agents. This orchestrator uses the AskUserQuestion tool to present options, then spawns agents asynchronously for optimal performance.
 

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

@@ -11,6 +11,11 @@ Synchronize a folder's README.md with its current contents.
 
 ROLE: README Sync Orchestrator
 
+🔴 **AskUserQuestion Format** (when asking decisions):
+- NEVER ask users to "type" anything - use proper options
+- Use XML invoke format with multiSelect for multiple choices
+- See `docs/02-practices/ask-user-question.md` for examples
+
 INPUTS
 FOLDER=<path>   Path to folder (e.g., docs/02-practices)
 FOLDER=all      Sync all docs/ subfolders
@@ -44,7 +49,22 @@ ACTIONS
    - Agent handles: listing, diffing, confirmation, updating
 
 3) If FOLDER is missing:
-   - Ask: "Which folder should I sync? (e.g., docs/02-practices, or 'all')"
+   - Use AskUserQuestion to ask which folder to sync:
+   ```xml
+   <invoke name="AskUserQuestion">
+   <parameter name="questions">[{
+     "question": "Which folder should I sync?",
+     "header": "Folder",
+     "multiSelect": false,
+     "options": [
+       {"label": "docs/02-practices (Recommended)", "description": "Sync practices documentation folder"},
+       {"label": "docs/04-architecture", "description": "Sync architecture documentation"},
+       {"label": "all", "description": "Sync all docs/ subfolders"},
+       {"label": "Other", "description": "Enter custom folder path"}
+     ]
+   }]</parameter>
+   </invoke>
+   ```
 
 WORKFLOW DETAILS
 
@@ -72,9 +92,22 @@ Generate markdown bullet list:
 
 ### Step 4: Show Diff & Apply
 - Display the proposed changes (diff format)
-- Ask user: "Update README.md? (YES/NO)"
-- If YES: Use Edit tool to update "## Contents" section
-- If NO: Abort without changes
+- Ask user with AskUserQuestion:
+  ```xml
+  <invoke name="AskUserQuestion">
+  <parameter name="questions">[{
+    "question": "Apply these changes to README.md?",
+    "header": "Update",
+    "multiSelect": false,
+    "options": [
+      {"label": "Yes, update README (Recommended)", "description": "Write the proposed ## Contents section to README.md"},
+      {"label": "No, abort", "description": "Cancel without making changes"}
+    ]
+  }]</parameter>
+  </invoke>
+  ```
+- If "Yes, update README": Use Edit tool to update "## Contents" section
+- If "No, abort": Exit without changes
 
 EXAMPLE OUTPUT
 

package/src/core/commands/story.md

@@ -11,6 +11,8 @@ Create a new user story with acceptance criteria and test stubs.
 
 ROLE: Story Creator
 
+🔴 **AskUserQuestion Format**: NEVER ask users to "type" anything. Use proper options with XML invoke format. See `docs/02-practices/ask-user-question.md`.
+
 TODO LIST TRACKING
 **CRITICAL**: Immediately create a todo list using TodoWrite tool to track story creation:
 ```

package/tools/cli/installers/ide/_base-ide.js

@@ -91,10 +91,13 @@ class BaseIdeSetup {
    */
   async cleanup(projectDir) {
     if (this.configDir) {
-      const agileflowPath = path.join(projectDir, this.configDir, 'agileflow');
-      if (await fs.pathExists(agileflowPath)) {
-        await fs.remove(agileflowPath);
-        console.log(chalk.dim(`  Removed old AgileFlow configuration from ${this.displayName}`));
+      // Clean up both old (AgileFlow) and new (agileflow) folder names
+      for (const folderName of ['agileflow', 'AgileFlow']) {
+        const agileflowPath = path.join(projectDir, this.configDir, 'commands', folderName);
+        if (await fs.pathExists(agileflowPath)) {
+          await fs.remove(agileflowPath);
+          console.log(chalk.dim(`  Removed old ${folderName} configuration from ${this.displayName}`));
+        }
       }
     }
   }

package/tools/cli/installers/ide/claude-code.js

@@ -20,80 +20,111 @@ class ClaudeCodeSetup extends BaseIdeSetup {
   }
 
   /**
-   * Setup Claude Code IDE configuration
-   * @param {string} projectDir - Project directory
-   * @param {string} agileflowDir - AgileFlow installation directory
-   * @param {Object} options - Setup options
+   * Recursively install commands from a source directory
+   * @param {string} sourceDir - Source directory path
+   * @param {string} targetDir - Target directory path
+   * @param {string} agileflowDir - AgileFlow installation directory (for dynamic content)
+   * @param {boolean} injectDynamic - Whether to inject dynamic content (only for top-level commands)
+   * @returns {Promise<{commands: number, subdirs: number}>} Count of installed items
    */
-  async setup(projectDir, agileflowDir, options = {}) {
-    console.log(chalk.hex('#e8683a')(`  Setting up ${this.displayName}...`));
-
-    // Clean up old installation first
-    await this.cleanup(projectDir);
+  async installCommandsRecursive(sourceDir, targetDir, agileflowDir, injectDynamic = false) {
+    let commandCount = 0;
+    let subdirCount = 0;
 
-    // Create .claude/commands/agileflow directory
-    const claudeDir = path.join(projectDir, this.configDir);
-    const commandsDir = path.join(claudeDir, this.commandsDir);
-    const agileflowCommandsDir = path.join(commandsDir, 'AgileFlow');
+    if (!(await this.exists(sourceDir))) {
+      return { commands: 0, subdirs: 0 };
+    }
 
-    await this.ensureDir(agileflowCommandsDir);
+    await this.ensureDir(targetDir);
 
-    // Get commands from AgileFlow installation
-    const commandsSource = path.join(agileflowDir, 'commands');
-    let commandCount = 0;
+    const entries = await fs.readdir(sourceDir, { withFileTypes: true });
 
-    if (await this.exists(commandsSource)) {
-      const commands = await this.scanDirectory(commandsSource, '.md');
+    for (const entry of entries) {
+      const sourcePath = path.join(sourceDir, entry.name);
+      const targetPath = path.join(targetDir, entry.name);
 
-      for (const command of commands) {
-        // Read the original command content
-        let content = await this.readFile(command.path);
+      if (entry.isFile() && entry.name.endsWith('.md')) {
+        // Read and process .md file
+        let content = await this.readFile(sourcePath);
 
-        // Inject dynamic content (agent lists, command lists)
-        content = this.injectDynamicContent(content, agileflowDir);
+        // Inject dynamic content if enabled (for top-level commands)
+        if (injectDynamic) {
+          content = this.injectDynamicContent(content, agileflowDir);
+        }
 
         // Replace docs/ references with custom folder name
         content = this.replaceDocsReferences(content);
 
-        const targetPath = path.join(agileflowCommandsDir, `${command.name}.md`);
         await this.writeFile(targetPath, content);
         commandCount++;
+      } else if (entry.isDirectory()) {
+        // Recursively process subdirectory
+        const subResult = await this.installCommandsRecursive(
+          sourcePath,
+          targetPath,
+          agileflowDir,
+          false // Don't inject dynamic content in subdirectories
+        );
+        commandCount += subResult.commands;
+        subdirCount += 1 + subResult.subdirs;
       }
     }
 
-    // Create agents subdirectory
-    const agileflowAgentsDir = path.join(agileflowCommandsDir, 'agents');
-    await this.ensureDir(agileflowAgentsDir);
+    return { commands: commandCount, subdirs: subdirCount };
+  }
 
-    // Get agents from AgileFlow installation
-    const agentsSource = path.join(agileflowDir, 'agents');
-    let agentCount = 0;
+  /**
+   * Setup Claude Code IDE configuration
+   * @param {string} projectDir - Project directory
+   * @param {string} agileflowDir - AgileFlow installation directory
+   * @param {Object} options - Setup options
+   */
+  async setup(projectDir, agileflowDir, options = {}) {
+    console.log(chalk.hex('#e8683a')(`  Setting up ${this.displayName}...`));
 
-    if (await this.exists(agentsSource)) {
-      const agents = await this.scanDirectory(agentsSource, '.md');
+    // Clean up old installation first
+    await this.cleanup(projectDir);
 
-      for (const agent of agents) {
-        // Read the original agent content
-        let content = await this.readFile(agent.path);
+    // Create .claude/commands/agileflow directory
+    const claudeDir = path.join(projectDir, this.configDir);
+    const commandsDir = path.join(claudeDir, this.commandsDir);
+    const agileflowCommandsDir = path.join(commandsDir, 'agileflow');
 
-        // Replace docs/ references with custom folder name
-        content = this.replaceDocsReferences(content);
+    await this.ensureDir(agileflowCommandsDir);
 
-        const targetPath = path.join(agileflowAgentsDir, `${agent.name}.md`);
-        await this.writeFile(targetPath, content);
-        agentCount++;
-      }
-    }
+    // Recursively install all commands (including subdirectories like agents/, session/)
+    const commandsSource = path.join(agileflowDir, 'commands');
+    const commandResult = await this.installCommandsRecursive(
+      commandsSource,
+      agileflowCommandsDir,
+      agileflowDir,
+      true // Inject dynamic content for top-level commands
+    );
+
+    // Also install agents (they're in a separate directory in agileflowDir)
+    const agentsSource = path.join(agileflowDir, 'agents');
+    const agentsTargetDir = path.join(agileflowCommandsDir, 'agents');
+    const agentResult = await this.installCommandsRecursive(
+      agentsSource,
+      agentsTargetDir,
+      agileflowDir,
+      false // No dynamic content for agents
+    );
+
+    const totalCommands = commandResult.commands + agentResult.commands;
+    const totalSubdirs = commandResult.subdirs + (agentResult.commands > 0 ? 1 : 0) + agentResult.subdirs;
 
     console.log(chalk.green(`  ✓ ${this.displayName} configured:`));
-    console.log(chalk.dim(`    - ${commandCount} commands installed`));
-    console.log(chalk.dim(`    - ${agentCount} agents installed`));
+    console.log(chalk.dim(`    - ${totalCommands} commands installed`));
+    if (totalSubdirs > 0) {
+      console.log(chalk.dim(`    - ${totalSubdirs} subdirectories`));
+    }
     console.log(chalk.dim(`    - Path: ${path.relative(projectDir, agileflowCommandsDir)}`));
 
     return {
       success: true,
-      commands: commandCount,
-      agents: agentCount,
+      commands: totalCommands,
+      subdirs: totalSubdirs,
     };
   }
 }