agileflow 2.37.0 → 2.37.2

package/package.json

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

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).
 
@@ -33,6 +35,59 @@ Set up the hooks system that enables event-driven automation in Claude Code. Hoo
 
 ## Configuration Steps
 
+### Step 0: Check and Migrate Old Format
+
+**IMPORTANT**: Before configuring, check if `.claude/settings.json` exists with old format and migrate it.
+
+The NEW hooks format uses `matcher` and `hooks` array:
+```json
+{
+  "hooks": {
+    "SessionStart": [
+      {
+        "matcher": "",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "echo 'Hello'"
+          }
+        ]
+      }
+    ]
+  }
+}
+```
+
+The OLD format (pre-2024) used `enabled`, `command`, `description` directly - THIS IS INVALID NOW:
+```json
+{
+  "hooks": {
+    "SessionStart": [
+      {
+        "enabled": true,
+        "command": "echo 'Hello'",
+        "description": "..."
+      }
+    ]
+  }
+}
+```
+
+**Migration check**:
+```bash
+if [ -f .claude/settings.json ]; then
+  # Check for old format (has "enabled" but no "hooks" array inside)
+  if jq -e '.hooks.SessionStart[0].enabled' .claude/settings.json >/dev/null 2>&1; then
+    echo "⚠️  Old hooks format detected - migration needed"
+    # Backup
+    cp .claude/settings.json .claude/settings.json.backup
+    echo "Backed up to .claude/settings.json.backup"
+  fi
+fi
+```
+
+If old format detected, the agent should rebuild the hooks configuration from scratch using the new format.
+
 ### Step 1: Create Directories
 
 ```bash

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.
 
@@ -223,15 +225,45 @@ else
 fi
 ```
 
+**Check for old statusLine format** (string instead of object):
+
+The NEW format uses an object:
+```json
+{
+  "statusLine": {
+    "type": "command",
+    "command": "bash scripts/agileflow-statusline.sh",
+    "padding": 0
+  }
+}
+```
+
+The OLD format (invalid) was just a string:
+```json
+{
+  "statusLine": "bash scripts/agileflow-statusline.sh"
+}
+```
+
+```bash
+# Check for old string format
+if [ -f .claude/settings.json ]; then
+  OLD_FORMAT=$(jq -r 'if .statusLine | type == "string" then "yes" else "no" end' .claude/settings.json 2>/dev/null)
+  if [ "$OLD_FORMAT" = "yes" ]; then
+    echo "⚠️  Old statusLine format detected (string) - will be replaced with object format"
+  fi
+fi
+```
+
 Add or update the statusLine configuration:
 
-Use `jq` to add/update the statusLine field:
+Use `jq` to add/update the statusLine field (this will replace old string format):
 
 ```bash
 # Backup existing settings
 cp .claude/settings.json .claude/settings.json.backup 2>/dev/null
 
-# Add statusLine configuration
+# Add statusLine configuration (replaces any old format)
 jq '. + {"statusLine": {"type": "command", "command": "bash scripts/agileflow-statusline.sh", "padding": 0}}' .claude/settings.json > .claude/settings.json.tmp && mv .claude/settings.json.tmp .claude/settings.json
 ```
 

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/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

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:
 ```