agileflow 3.1.0 → 3.2.0

package/src/core/commands/configure.md

@@ -37,12 +37,12 @@ Main Menu → "What would you like to configure?"
 ├─ Profiles       → Apply preset | Apply custom | Save current | Manage
 │                   ├─ Presets: Full | Basic | Minimal | None
 │                   └─ Custom: Save, Export, Import, Delete
-├─ Features       → Enable | Disable | View status
-│                   └─ Hooks (4) + Other Features (4)
+├─ Features       → Enable | Disable | Context Verbosity | View status
+│                   └─ Hooks (4) + Other Features (4) + Context Verbosity (full/lite/minimal)
 ├─ 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
+├─ Infrastructure → UI Testing | Damage Control | CI/CD | Quality Gates
 └─ Maintenance    → Fix format | Upgrade | Repair | Check status
 ```
 
@@ -137,7 +137,7 @@ After handling issues (or if none), present the main category menu:
     {"label": "Profiles", "description": "Quick setup with preset configurations (full, basic, minimal)"},
     {"label": "Features", "description": "Enable or disable individual hooks and features"},
     {"label": "Sessions", "description": "Configure default startup mode for new sessions"},
-    {"label": "Infrastructure", "description": "Set up Visual E2E, Damage Control, or CI/CD"},
+    {"label": "Infrastructure", "description": "Set up UI Testing, Damage Control, or CI/CD"},
     {"label": "Maintenance", "description": "Fix issues, repair scripts, or check status"}
   ]
 }]</parameter>
@@ -612,7 +612,7 @@ Then re-ask the enable/disable question.
   "header": "Setup",
   "multiSelect": false,
   "options": [
-    {"label": "Visual E2E Testing", "description": "Playwright + screenshot verification workflow"},
+    {"label": "UI Testing (Bowser)", "description": "Agentic browser testing + visual verification with Playwright"},
     {"label": "Damage Control", "description": "Block destructive commands, protect sensitive paths"},
     {"label": "CI/CD Workflow", "description": "GitHub Actions for automated testing"},
     {"label": "Quality Gates", "description": "Configure TeammateIdle and TaskCompleted gate thresholds"}
@@ -623,7 +623,7 @@ Then re-ask the enable/disable question.
 
 Handle each selection directly:
 
-- **Visual E2E**: `node .agileflow/scripts/agileflow-configure.js --enable=visuale2e`
+- **UI Testing (Bowser)**: `node .agileflow/scripts/agileflow-configure.js --enable=browserqa`
 - **Damage Control**: `node .agileflow/scripts/agileflow-configure.js --enable=damagecontrol`
 - **CI/CD**: `node .agileflow/scripts/agileflow-configure.js --enable=ci`
 - **Quality Gates**: Update `docs/00-meta/agileflow-metadata.json` under the `quality_gates` key with enable/disable for tests, lint, types gates per hook and coverage thresholds
@@ -1120,7 +1120,7 @@ Installed Features:
 ✅ damage-control (v2.94.1) - 31 patterns
 ✅ precompact (v2.94.1) - context preservation
 ✅ status-line (v2.94.1) - story tracking
-⚪ visual-e2e (not installed)
+⚪ browserqa (not installed)
 ⚪ hooks (not installed)
 
 Scripts:
@@ -1139,7 +1139,7 @@ Available features:
 - damage-control: Protect against destructive commands
 - precompact: Context preservation during compaction
 - status-line: Story status in Claude Code UI
-- visual-e2e: Screenshot-based testing
+- browserqa: Agentic browser testing + visual verification
 - hooks: Event-driven automation
 - ci: CI/CD workflow setup
 

package/src/core/commands/research/ask.md

@@ -11,7 +11,7 @@ compact_context:
     - "MUST include exact error messages verbatim if troubleshooting"
     - "MUST list 2+ approaches already tried with detailed results"
     - "MUST ask 3+ specific questions (not vague)"
-    - "NO FILE WRITES - output only, user will copy/paste to external AI"
+    - "OUTPUT-ONLY by default - optional save to docs/10-research/prompts/"
     - "Validation required before output: length, code snippets, error details, attempts, questions"
     - "If validation fails: gather missing info and regenerate"
   state_fields:
@@ -202,15 +202,21 @@ Every research prompt MUST have:
 
 ---
 
-### 🚨 RULE #7: NO FILE WRITES
+### 🚨 RULE #7: OUTPUT-ONLY BY DEFAULT (OPTIONAL SAVE)
 
-**This command outputs a prompt only. User will copy/paste to ChatGPT/Claude/Perplexity.**
+**This command generates a prompt for copy/paste. Optionally save to prompts directory after displaying.**
 
 ```
-❌ WRONG: Write prompt to file
-✅ RIGHT: Output prompt in code block, instruct user to copy
+❌ WRONG: Save prompt WITHOUT also displaying for copy/paste
+✅ RIGHT: Output prompt in code block, then offer to save to docs/10-research/prompts/
 ```
 
+**Save flow (if user selects save):**
+1. Create `docs/10-research/prompts/` directory if needed
+2. Save as `docs/10-research/prompts/YYYYMMDD-prompt-<topic-slug>.md`
+3. Update `docs/10-research/README.md` with 5-column entry (Type=Prompt)
+4. Confirm save location
+
 ---
 
 ### VALIDATION CHECKLIST (BEFORE OUTPUT)
@@ -240,7 +246,7 @@ Every research prompt MUST have:
 ❌ List no or vague attempted solutions
 ❌ Ask generic questions without context
 ❌ Output prompt shorter than 200 lines
-❌ Save prompt to file instead of displaying for copy/paste
+❌ Save prompt WITHOUT also displaying for copy/paste
 ❌ Skip validation before outputting
 
 ### DO THESE INSTEAD
@@ -252,6 +258,7 @@ Every research prompt MUST have:
 ✅ Ask 3+ specific, contextualized questions
 ✅ Validate prompt quality before outputting
 ✅ Display prompt in code block for user copy/paste
+✅ Offer to save prompt to docs/10-research/prompts/ after displaying
 ✅ Instruct user where to paste results back
 
 ---
@@ -287,6 +294,7 @@ Every research prompt MUST have:
 18. Display prompt in code block
 19. Instruct user: "Copy this prompt and paste into ChatGPT/Claude/Perplexity"
 20. Provide post-answer instructions: "When you get results, use /agileflow:research:import to save"
+21. Offer to save prompt to `docs/10-research/prompts/YYYYMMDD-prompt-<topic-slug>.md`
 
 ---
 
@@ -372,7 +380,7 @@ Actual: [What actually happens]
 - MUST list 2+ attempts with detailed results
 - MUST ask 3+ specific questions
 - Validate all checks BEFORE outputting
-- NO file writes - output for user to copy/paste
+- Output-only by default - optional save to docs/10-research/prompts/
 - After user gets results, they use /agileflow:research:import to save
 
 <!-- COMPACT_SUMMARY_END -->
@@ -607,6 +615,31 @@ Copy this prompt and paste it into ChatGPT, Claude web, Perplexity, or Gemini.
 When you get the answer, paste the results here and I'll save them to your research folder using `/agileflow:research:import`.
 ```
 
+### Step 8b: Save Prompt (if user selects save)
+
+If the user selects "Save prompt to docs/10-research/prompts/":
+
+1. **Create directories** if they don't exist:
+   - Ensure `docs/10-research/` exists (create if needed on fresh projects)
+   - Ensure `docs/10-research/prompts/` exists
+
+2. **Generate filename**: `YYYYMMDD-prompt-<topic-slug>.md`
+   - Use today's date
+   - Slugify the TOPIC (lowercase, hyphens, no special chars)
+
+3. **Save the prompt** to `docs/10-research/prompts/YYYYMMDD-prompt-<topic-slug>.md`
+
+4. **Update README index** - Add entry to `docs/10-research/README.md`:
+   ```markdown
+   | YYYY-MM-DD | [TOPIC] Research Prompt | Prompt | [prompts/YYYYMMDD-prompt-topic-slug.md](./prompts/YYYYMMDD-prompt-topic-slug.md) | Research prompt for [TOPIC]: [N] files referenced, [M] questions |
+   ```
+
+5. **Confirm save**:
+   ```
+   Saved prompt to docs/10-research/prompts/YYYYMMDD-prompt-<topic-slug>.md
+   Updated research index (README.md)
+   ```
+
 ---
 
 ## Anti-Pattern: Lazy Prompts
@@ -772,7 +805,7 @@ After clicking "Sign in with Google", immediately get unauthorized_client error.
 
 ## Rules
 
-- **NO file writes** - This is output-only
+- **Output-only by default** - Display prompt for copy/paste, optionally save to prompts/
 - **MUST validate quality** before outputting
 - **MUST include actual code** from the codebase
 - **MUST be detailed** - 200+ lines minimum
@@ -792,8 +825,8 @@ After generating the research prompt, suggest contextual next steps:
   "multiSelect": false,
   "options": [
     {"label": "Copy & paste to ChatGPT/Perplexity (Recommended)", "description": "Prompt covers [N] files and [M] specific questions - ready to paste"},
+    {"label": "Save prompt to docs/10-research/prompts/", "description": "Save as prompts/YYYYMMDD-prompt-[topic-slug].md and update README index"},
     {"label": "Regenerate with more detail", "description": "Add [missing element: more code from X / error details / attempted solutions]"},
-    {"label": "Save prompt to docs/10-research/", "description": "Save as [YYYYMMDD]-prompt-[topic-slug].md for later use"},
     {"label": "Done", "description": "Prompt generated, no further action needed"}
   ]
 }]</parameter>

package/src/core/commands/research/import.md

@@ -163,14 +163,20 @@ Phase 4: IMPLEMENTATION IDEATION (If Requested)
 
 **After saving, ALWAYS update `docs/10-research/README.md` with new entry.**
 
-Add entry to the top of the table:
+Add entry to the top of the table (5-column format with Type):
 ```markdown
-| Date | Topic | File | Summary |
-|------|-------|------|---------|
-| 2026-01-07 | New Research Title | 20260107-topic-slug.md | One-line summary |
+| Date | Topic | Type | Path | Summary |
+|------|-------|------|------|---------|
+| 2026-01-07 | New Research Title | Research | [20260107-topic-slug.md](./20260107-topic-slug.md) | One-line summary |
 | [older entries...] |
 ```
 
+**Note**: If existing README.md uses 4-column format (no Type column), migrate first:
+1. Insert `Type` as the 3rd column in the header row (between Topic and Path)
+2. Add `------|` to the separator row in the same position
+3. For existing entries, assign Type = `Research` (safe default)
+4. Then insert the new 5-column entry
+
 **Never skip this step.** Index is how users discover research.
 
 ---
@@ -647,12 +653,12 @@ If YES:
 
 ### Step 8: Update Index
 
-Add entry to `docs/10-research/README.md`:
+Add entry to `docs/10-research/README.md` (5-column format):
 
 ```markdown
-| Date | Topic | File | Summary |
-|------|-------|------|---------|
-| YYYY-MM-DD | [Topic] | [filename.md] | [One-line summary] |
+| Date | Topic | Type | Path | Summary |
+|------|-------|------|------|---------|
+| YYYY-MM-DD | [Topic] | Research | [filename.md](./filename.md) | [One-line summary] |
 ```
 
 Insert newest entries at the top of the table.

package/src/core/commands/research/list.md

@@ -65,18 +65,19 @@ node .agileflow/scripts/obtain-context.js research:list
 
 ### 🚨 RULE #2: READ INDEX FROM docs/10-research/README.md
 
-**Primary source: `docs/10-research/README.md` should contain a table:**
+**Primary source: `docs/10-research/README.md` should contain a 5-column table:**
 
 ```markdown
 ## Research Notes
 
-| Date | Topic | File | Summary |
-|------|-------|------|---------|
-| 2026-01-07 | OAuth Integration | 20260107-oauth.md | Setup Google OAuth |
-| 2026-01-06 | Performance Tips | 20260106-perf.md | Caching strategies |
+| Date | Topic | Type | Path | Summary |
+|------|-------|------|------|---------|
+| 2026-01-07 | OAuth Integration | Research | 20260107-oauth.md | Setup Google OAuth |
+| 2026-01-06 | Performance Tips | Research | 20260106-perf.md | Caching strategies |
 ```
 
-**If README doesn't exist:** List files from the directory directly.
+**If README doesn't exist:** List files from `docs/10-research/` directory and from `docs/10-research/prompts/` (if it exists), merging results sorted by date.
+**If README uses old 4-column format (no Type):** Handle gracefully - display without Type column and note the format is outdated.
 
 ---
 
@@ -102,11 +103,11 @@ Quick start:
 Research Notes
 ==============
 
-| Date       | Topic                  | File                        |
-|------------|------------------------|-----------------------------|
-| 2026-01-07 | OAuth Integration       | 20260107-oauth.md           |
-| 2026-01-06 | Performance Tips        | 20260106-perf.md            |
-| 2026-01-05 | Database Migrations     | 20260105-migrations.md      |
+| Date       | Topic                  | Type     | File                        |
+|------------|------------------------|----------|-----------------------------|
+| 2026-01-07 | OAuth Integration       | Research | 20260107-oauth.md           |
+| 2026-01-06 | Performance Tips        | Research | 20260106-perf.md            |
+| 2026-01-05 | DB Migration Guide      | Prompt   | prompts/20260105-prompt-db-migrations.md |
 
 Total: 3 research notes
 ```
@@ -231,11 +232,11 @@ Format output:
 ```
 ## Research Notes
 
-| Date | Topic | File |
-|------|-------|------|
-| 2024-12-31 | OAuth 2.0 Setup | 20241231-oauth-setup.md |
-| 2024-12-30 | Session Tracking | 20241230-session-tracking.md |
-| 2024-12-28 | Mermaid Diagrams | 20241228-mermaid-diagrams.md |
+| Date | Topic | Type | File |
+|------|-------|------|------|
+| 2024-12-31 | OAuth 2.0 Setup | Research | 20241231-oauth-setup.md |
+| 2024-12-30 | Session Tracking | Research | 20241230-session-tracking.md |
+| 2024-12-28 | Mermaid Diagrams | Research | 20241228-mermaid-diagrams.md |
 
 Total: 3 research notes
 

package/src/core/commands/research/synthesize.md

@@ -88,13 +88,13 @@ If neither provided, ask user:
 ### 🚨 RULE #2: SEARCH OR SELECT RESEARCH FILES
 
 **If TOPIC provided:**
-1. Search `docs/10-research/*.md` for files containing keyword
+1. Search `docs/10-research/*.md` AND `docs/10-research/prompts/*.md` for files containing keyword
 2. Check filename, title (# header), key findings, summary
 3. Present matching files to user for confirmation
 
 **If FILES provided:**
-1. Validate each file exists in `docs/10-research/`
-2. Warn if any file not found
+1. Validate each file exists in `docs/10-research/` or `docs/10-research/prompts/`
+2. Warn if any file not found in either location
 3. Proceed with valid files
 
 **Auto-select if <5 matches. Ask user to confirm if 5+ matches.**
@@ -470,7 +470,7 @@ Upon invocation, execute these steps:
 ### Step 3: Search/Select Research Files
 
 **If TOPIC search:**
-1. List all files in `docs/10-research/`
+1. List all files in `docs/10-research/` and `docs/10-research/prompts/` (if exists)
 2. For each file, check if topic keyword appears in:
    - Filename
    - First `# ` header (title)
@@ -888,11 +888,11 @@ If user chooses to save:
 
 **Filename format**: `YYYYMMDD-synthesis-[topic-slug].md`
 
-**Add to docs/10-research/README.md index:**
+**Add to docs/10-research/README.md index (5-column format):**
 ```markdown
-| Date | Topic | File | Summary |
-|------|-------|------|---------|
-| 2026-01-17 | Synthesis: Authentication | 20260117-synthesis-authentication.md | Cross-research synthesis of N files... |
+| Date | Topic | Type | Path | Summary |
+|------|-------|------|------|---------|
+| 2026-01-17 | Synthesis: Authentication | Synthesis | [20260117-synthesis-authentication.md](./20260117-synthesis-authentication.md) | Cross-research synthesis of N files... |
 ```
 
 **Mark as synthesis type** in file header:

package/src/core/commands/research/view.md

@@ -233,10 +233,16 @@ If FILE not provided, show available files:
 
 Read `docs/10-research/[FILE]`.
 
-If file doesn't exist:
+If file doesn't exist, check `docs/10-research/prompts/[FILE]` as a fallback (prompts are stored in a subdirectory).
+
+If file doesn't exist in either location:
 ```
 Research note not found: [FILE]
 
+Checked:
+- docs/10-research/[FILE]
+- docs/10-research/prompts/[FILE]
+
 Use /agileflow:research:list to see available notes.
 ```
 
@@ -246,8 +252,9 @@ Output the full content of the research note.
 
 ### Step 4: Suggest Actions
 
-After displaying, offer contextual actions based on the research content:
+After displaying, count action items (lines starting with `- [ ]` in the file) and build contextual options:
 
+**If N > 0 action items found:**
 ```xml
 <invoke name="AskUserQuestion">
 <parameter name="questions">[{
@@ -256,15 +263,32 @@ After displaying, offer contextual actions based on the research content:
   "multiSelect": false,
   "options": [
     {"label": "Analyze for implementation in [current epic/project] (Recommended)", "description": "Deploy multi-expert analysis to map research to your codebase"},
-    {"label": "Synthesize with related notes on [detected topic]", "description": "Cross-reference with [count] other notes on similar topics"},
     {"label": "Create story from [N] action items", "description": "Turn research action items into trackable stories"},
+    {"label": "Synthesize with related notes on [detected topic]", "description": "Cross-reference with [count] other notes on similar topics"},
+    {"label": "View another note", "description": "Browse other research notes"}
+  ]
+}]</parameter>
+</invoke>
+```
+
+**If N = 0 (no action items - informational research):**
+```xml
+<invoke name="AskUserQuestion">
+<parameter name="questions">[{
+  "question": "Viewed '[TOPIC]' research (reference material). What next?",
+  "header": "Actions",
+  "multiSelect": false,
+  "options": [
+    {"label": "Analyze for implementation in [current epic/project] (Recommended)", "description": "Deploy multi-expert analysis to map research to your codebase"},
+    {"label": "Import additional research on [detected topic]", "description": "Gather more detailed research to build on this note"},
+    {"label": "Synthesize with related notes on [detected topic]", "description": "Cross-reference with [count] other notes on similar topics"},
     {"label": "View another note", "description": "Browse other research notes"}
   ]
 }]</parameter>
 </invoke>
 ```
 
-**Key**: Always include specific counts (action items found), detected topics, and reference the current epic if one is active. If no action items exist, replace that option with "Import additional research on [topic]".
+**Key**: Always populate placeholders - `[TOPIC]` from file title, `[N]` from action item count, `[detected topic]` from content keywords, `[current epic/project]` from status.json (or "your project" if none active), `[count]` from related file count.
 
 If "Analyze for implementation" selected, invoke:
 ```

package/src/core/commands/whats-new.md

@@ -83,7 +83,7 @@ Parse the CHANGELOG.md and display:
 ## v2.56.0 (2025-12-27)
 
 ### Added
-• Dynamic IDE discovery - Codex CLI now in setup
+• Dynamic IDE discovery - OpenAI Codex now in setup
 
 ### Changed
 • Replaced hardcoded IDE list with dynamic loading
@@ -147,7 +147,7 @@ If a newer version exists, show:
 ## v2.56.0 (2025-12-27)
 
 ### Added
-• Dynamic IDE discovery - Codex CLI now in setup
+• Dynamic IDE discovery - OpenAI Codex now in setup
 
 ### Changed
 • Replaced hardcoded IDE list with dynamic loading

package/src/core/experts/devops/expertise.yaml

@@ -1,6 +1,7 @@
 domain: devops
-last_updated: 2025-12-21
-version: 1.1
+last_updated: 2026-02-15
+last_audit_date: 2026-02-15
+version: 1.2
 
 # AgileFlow-specific file structure (learned from actual codebase)
 files:
@@ -103,3 +104,13 @@ learnings:
     context: "Analyzed session hooks"
     insight: "get-env.js outputs project info on session start; archive-completed-stories.sh runs automatically"
     source: "CLAUDE.md, .claude/settings.json"
+
+  - date: 2026-02-15
+    context: "Analyzed Claude Code Feb 2026 planning/hooks/MCP research"
+    insight: "plansDirectory, PostToolUse ExitPlanMode, --init/--maintenance flags, MCP tool search align well with AgileFlow architecture. Ready for Phase 1 implementation: 2 weeks, 28-40 hours"
+    source: "docs/10-research/20260215-claude-code-planning-hooks-mcp-updates.md"
+
+  - date: 2026-02-15
+    context: "Planned Claude Code feature integration"
+    insight: "5 features categorized: Phase 1 (plansDirectory, PostToolUse, MCP search - high priority), Phase 2 (--init/--maintenance, PreToolUse context - medium priority). Effort estimate: 13-18 days, 56-76 hours total"
+    source: "docs/10-research/20260215-devops-analysis-claude-code-features.md"

package/src/core/experts/documentation/expertise.yaml

@@ -1,6 +1,6 @@
 domain: documentation
-last_updated: 2026-02-03
-version: 1.3
+last_updated: 2026-02-14
+version: 1.4
 
 # AgileFlow-specific documentation structure (learned from actual codebase)
 files:
@@ -153,7 +153,7 @@ learnings:
 
   - date: 2026-01-09
     context: "Created IDE Integrations documentation for AgileFlow"
-    insight: "IDE handler system supports 4 IDEs (Claude Code, Cursor, Windsurf, Codex CLI) through plugin architecture. Each IDE has custom config directory (.claude/, .cursor/, .windsurf/, .codex/) and different installation models. Claude Code most advanced (damage control, spawnable agents), Codex CLI unique (per-repo skills, user-level prompts, AGENTS.md instructions)"
+    insight: "IDE handler system supports 4 IDEs (Claude Code, Cursor, Windsurf, OpenAI Codex) through plugin architecture. Each IDE has custom config directory (.claude/, .cursor/, .windsurf/, .codex/) and different installation models. Claude Code most advanced (damage control, spawnable agents), OpenAI Codex unique (per-repo skills, user-level prompts, AGENTS.md instructions)"
     created_files:
       - "apps/docs/content/docs/features/ide-integrations.mdx (700+ lines)"
       - "apps/docs/content/docs/features/index.mdx (updated with IDE section)"
@@ -168,7 +168,7 @@ learnings:
       - "Claude Code subagent spawning, damage control hooks"
       - "Cursor unique features, differences from Claude Code"
       - "Windsurf workflow management, VSCode integration"
-      - "Codex CLI dual installation model (per-repo skills, user-level prompts, AGENTS.md)"
+      - "OpenAI Codex dual installation model (per-repo skills, user-level prompts, AGENTS.md)"
       - "Dynamic IDE handler system, extensibility guide"
       - "Content injection system explanation"
       - "Troubleshooting guide for common issues"
@@ -235,3 +235,25 @@ learnings:
       - "Formatting consistent (tables, code blocks, bullets) ✓"
     source: "packages/cli/src/core/commands/*.md vs apps/docs/content/docs/commands/*.mdx"
     notes: "Used systematic comparison approach: extracted descriptions, parameters, and features from 50 source commands against documentation. Prioritized commands with most feature additions: babysit (Smart Detection, Story Claiming, Logic Audit), configure (profiles, hierarchical menus). All changes preserve source accuracy while making docs more discoverable and comprehensive."
+
+  - date: 2026-02-14
+    context: "Audited README files for v3.0.2 - IDE config locations and badge accuracy"
+    insight: "Found and fixed 2 discrepancies between root and npm README files: (1) Cursor IDE config was .cursor/rules/ instead of .cursor/commands/ (verified against cursor.js installer), (2) OpenAI Codex location was incomplete - missing ~/.codex/prompts/ directory for user-level prompts. Both files now synchronized and identical."
+    fixed_issues:
+      - "packages/cli/README.md line 42: Updated Cursor from .cursor/rules/agileflow/ to .cursor/commands/agileflow/"
+      - "packages/cli/README.md line 44: Updated Codex from .codex/skills/ to .codex/skills/ and ~/.codex/prompts/"
+    verified:
+      - "Badge counts: 93 commands (correct), 45 agents (correct), dynamic skills (correct)"
+      - "All 11 referenced documentation files exist"
+      - "All 6 example commands/agents exist in source"
+      - "External links functional: npm (HTTP 200), GitHub (HTTP 200), docs site (HTTP 200)"
+      - "README files now identical (diff shows no differences)"
+    quality_gates:
+      - "Documentation current with v3.0.2 code ✓"
+      - "Counts verified against actual source files ✓"
+      - "IDE config verified against installers ✓"
+      - "All example commands/agents exist ✓"
+      - "No deprecated information remains ✓"
+      - "Two README files synchronized ✓"
+    source: "README.md, packages/cli/README.md, packages/cli/tools/cli/installers/ide/*.js"
+    notes: "Learned that IDE config locations can drift from documentation. Always verify against actual installer code (cursor.js, codex.js, etc.) not assumptions. OpenAI Codex has dual installation model (per-repo .codex/skills/ + user-level ~/.codex/prompts/) - this must be documented completely."

package/src/core/profiles/COMPARISON.md

@@ -0,0 +1,170 @@
+# IDE Capability Comparison Matrix
+
+Complete comparison of all supported IDEs. Profiles at `/packages/cli/src/core/profiles/`.
+
+## Core Capabilities
+
+| Capability | Claude Code | Cursor | Windsurf | Codex |
+|---|---|---|---|---|
+| **File Operations** | ✅ Native tools | ✅ read_file, edit_file | ✅ Native | ⚠️ Via skills |
+| **Shell Execution** | ✅ Bash tool | ✅ run_terminal_cmd | ✅ run_command | ⚠️ Via sandbox |
+| **File Search** | ✅ Glob, Grep | ✅ codebase_search, grep_search | ✅ search_files, search_codebase | ⚠️ Via sandbox |
+| **Interactive Input** | ✅ Structured (AskUserQuestion) | ⚠️ Conversational | ⚠️ Conversational | ⚠️ Text-only |
+| **Sub-Agents** | ✅ Task tool | ✅ Async native agents | ⚠️ Cascades + chaining | ❌ Cannot nest |
+| **Nested Sub-Agents** | ✅ Full nesting | ✅ Full nesting | ❌ Parallel only | ❌ None |
+
+## Planning & Execution
+
+| Capability | Claude Code | Cursor | Windsurf | Codex |
+|---|---|---|---|---|
+| **Plan Mode** | ✅ EnterPlanMode/ExitPlanMode | ✅ Native | ✅ Native + "megaplan" | ❌ None |
+| **Plan Editing** | ✅ User can edit | ✅ User can edit | ✅ User can edit | N/A |
+| **Persistent Plans** | ✅ Yes | ✅ Yes | ✅ ~/.windsurf/plans/ | N/A |
+
+## Lifecycle & Hooks
+
+| Hook Event | Claude Code | Cursor | Windsurf | Codex |
+|---|---|---|---|---|
+| **SessionStart** | ✅ | ❌ | ❌ | ❌ |
+| **PreToolUse** | ✅ | ❌ | ❌ | ❌ |
+| **PostToolUse** | ✅ | ❌ | ❌ | ❌ |
+| **beforeSubmitPrompt** | ❌ | ✅ | ❌ | ❌ |
+| **beforeShellExecution** | ❌ | ✅ | ❌ | ❌ |
+| **beforeMCPExecution** | ❌ | ✅ | ❌ | ❌ |
+| **beforeReadFile** | ❌ | ✅ | ❌ | ❌ |
+| **afterFileEdit** | ❌ | ✅ | ❌ | ❌ |
+| **pre_read_code** | ❌ | ❌ | ✅ | ❌ |
+| **post_read_code** | ❌ | ❌ | ✅ | ❌ |
+| **pre_write_code** | ❌ | ❌ | ✅ | ❌ |
+| **post_write_code** | ❌ | ❌ | ✅ | ❌ |
+| **pre_run_command** | ❌ | ❌ | ✅ | ❌ |
+| **post_run_command** | ❌ | ❌ | ✅ | ❌ |
+| **pre_mcp_tool_use** | ❌ | ❌ | ✅ | ❌ |
+| **post_mcp_tool_use** | ❌ | ❌ | ✅ | ❌ |
+| **pre_user_prompt** | ❌ | ❌ | ✅ | ❌ |
+| **post_cascade_response** | ❌ | ❌ | ✅ | ❌ |
+| **post_setup_worktree** | ❌ | ❌ | ✅ | ❌ |
+| **Total Hook Events** | 5 | 6 | 11 | 0 |
+
+**Status**: SessionStart, PreToolUse, PostToolUse (Claude Code); beforeSubmitPrompt, beforeShellExecution, beforeMCPExecution, beforeReadFile, afterFileEdit (Cursor); stop hook (all IDEs)
+
+## External Integration
+
+| Capability | Claude Code | Cursor | Windsurf | Codex |
+|---|---|---|---|---|
+| **Web Search** | ✅ WebSearch | ✅ web_search + @web | ✅ web_search | ❌ |
+| **Web Fetch** | ✅ WebFetch | ✅ @web + MCP | ✅ url_read, view_chunk | ❌ |
+| **MCP Support** | ✅ Full | ✅ Full | ✅ Full | ✅ Extension |
+| **MCP Tool Cap** | **0 (unlimited)** | **40** | **100** | **0 (unlimited)** |
+| **Browser** | ✅ Playwright MCP | ✅ Native browser (v2.0+) | ✅ Browser Preview | ⚠️ Limited |
+
+## Collaboration & Tracking
+
+| Capability | Claude Code | Cursor | Windsurf | Codex |
+|---|---|---|---|---|
+| **Task Tracking** | ✅ TaskCreate/Update/List | ❌ Plan checklists only | ❌ Conversation-embedded | ❌ None |
+| **Persistent Tasks** | ✅ Yes | ❌ | ❌ | ❌ |
+| **Git Worktrees** | ✅ EnterWorktree | ⚠️ Background agents use branches | ✅ Native (up to 20) | ⚠️ Manual |
+| **Parallel Execution** | ⚠️ Sequential Tasks | ✅ Async subagents | ✅ @cascade worktrees | ❌ |
+
+## Configuration Paths
+
+| Item | Claude Code | Cursor | Windsurf | Codex |
+|---|---|---|---|---|
+| **Config Dir** | `.claude/` | `.cursor/` | `.windsurf/` | `.codex/` |
+| **Commands** | `.claude/commands/agileflow/` | `.cursor/commands/` | `.windsurf/workflows/` | N/A |
+| **Agents** | `.claude/agents/agileflow/` | `.cursor/agents/` | N/A (use workflows) | N/A |
+| **Skills** | `.claude/skills/` | N/A (use agents) | `.windsurf/skills/*/` | `.codex/skills/agileflow-*/` |
+| **Rules** | N/A | `.cursor/rules/` (MDC) | `.windsurf/rules/` | N/A |
+| **Hooks Config** | `.claude/settings.json` | `.cursor/hooks.json` | `.windsurf/hooks.json` | N/A |
+| **MCP Config** | `.claude/settings.json` | `.cursor/mcp.json` | `~/.codeium/windsurf/mcp_config.json` | N/A |
+| **Instructions** | `CLAUDE.md` | `CURSOR.md` | `WINDSURF.md` | `AGENTS.md` |
+
+## Limits & Constraints
+
+| Constraint | Claude Code | Cursor | Windsurf | Codex |
+|---|---|---|---|---|
+| **Max File Size** | Unlimited | Unlimited | Unlimited | Unlimited |
+| **Max Command Length** | Unlimited | Unlimited | Unlimited | Unlimited |
+| **Workflow Size** | N/A | N/A | **12,000 chars** | N/A |
+| **MCP Tools** | 0 (unlimited) | **40** | 100 | 0 (unlimited) |
+| **Git Worktrees** | Via tool | Via branches | Up to 20 | Manual |
+| **Parallel Agents** | Sequential | Unlimited | Via @cascade | No nesting |
+
+**Key constraint**: Cursor's 40-tool MCP limit is the binding constraint for multi-IDE installations.
+
+## AgileFlow Feature Support
+
+| Feature | Claude Code | Cursor | Windsurf | Codex |
+|---|---|---|---|---|
+| **/agileflow:babysit** | ✅ Full | ⚠️ Conversational input | ⚠️ Conversational input | ❌ Limited |
+| **AskUserQuestion** | ✅ Structured menus | ❌ Fallback to text | ❌ Fallback to text | ✅ Text-only |
+| **Task delegation** | ✅ Task tool | ✅ Async agents | ⚠️ Workflow chaining | ❌ Skill suggestions |
+| **Plan mode hooks** | ✅ Full integration | ✅ Native mode | ✅ Native mode | ❌ None |
+| **Sub-agent nesting** | ✅ Full support | ✅ Full support | ⚠️ Parallel only | ❌ None |
+| **Persistent task list** | ✅ Yes | ❌ | ❌ | ❌ |
+| **Async execution** | ❌ Sequential | ✅ Native | ⚠️ @cascade | ❌ |
+
+## Implementation Notes
+
+### Claude Code
+- **Recommended target** for new AgileFlow features
+- All capabilities validated here first
+- Full support for structured user interaction
+- No tool limits for multi-IDE deployments
+
+### Cursor
+- **Fast-follower to Claude Code** (v2.5 Feb 2026)
+- Async native agents eliminate need for Task tool
+- 40-tool MCP cap is **binding constraint** for all IDEs
+- No AskUserQuestion - replace with numbered text prompts
+- Plan mode fully native (no enter/exit needed)
+
+### Windsurf
+- **Most hook events** (11 total) but most restrictive
+- **No true sub-agent spawning** - use workflow chaining or @cascade
+- **12,000 char limit per workflow** - must split large commands
+- **Global MCP config only** - no project-level customization
+- Native worktrees (up to 20)
+- Browser preview built-in to IDE
+
+### Codex
+- **Most restrictive** - use as minimum baseline
+- Skills cannot spawn other skills (no delegation)
+- No plan mode, hooks, or task tracking
+- Text-only user input
+- Best for linear workflows only
+
+## Multi-IDE Deployment Strategy
+
+**Canonical source**: Claude Code format
+**Generation**: Read IDE profile → Transform to IDE-native format
+**MCP constraint**: Cap at 40 tools (Cursor's limit) for consistency
+
+**Fallback order when feature unavailable**:
+1. Use native IDE equivalent (if exists)
+2. Replace with text-based alternative
+3. Document limitation in profile
+
+**Example - AskUserQuestion replacement**:
+```
+Claude Code:
+  AskUserQuestion(options=[{label: "Yes"}, {label: "No"}])
+
+Cursor/Windsurf:
+  Would you like to continue? (Type "Yes" or "No")
+
+Codex:
+  Please choose:
+  1. Yes
+  2. No
+```
+
+## Version Support
+
+- **Claude Code**: Latest (no version pinning)
+- **Cursor**: v2.5+ (Feb 2026)
+- **Windsurf**: Wave 13+ (native worktrees, 11 hooks)
+- **Codex**: Latest (limited feature set)
+
+Last updated: 2026-02-20 | Source: Cross-IDE Compatibility Findings