agileflow 3.1.0 → 3.2.0

package/src/core/profiles/README.md

@@ -0,0 +1,178 @@
+# IDE Capability Profiles
+
+IDE-agnostic capability declarations for AgileFlow's multi-IDE support strategy.
+
+## Overview
+
+This directory contains one YAML profile per supported IDE. Each profile declares:
+- Supported capabilities (plan mode, hooks, task tracking, MCP, etc.)
+- Config directory structure and paths
+- Tool name mappings (how each IDE names equivalent functions)
+- Frontmatter formats for commands/agents
+- Limitations and workarounds
+
+## Design Philosophy
+
+**Capability profiles separate declarations from implementation.** Instead of baking IDE differences into generators, prompts, or installers, we declaratively describe what each IDE supports. This enables:
+
+1. **Build-time generation** - Generators read profiles and produce IDE-native output
+2. **Feature detection** - Commands can check IDE capabilities at install time
+3. **Graceful fallbacks** - Prompts suggest alternatives when features unavailable
+4. **Extensibility** - Adding new IDEs requires only a new YAML file, not code changes
+
+## Files
+
+### claude-code.yaml
+**Primary target.** Anthropic's CLI-based environment with full support for:
+- Structured interactive input (AskUserQuestion)
+- True sub-agent spawning with nesting (Task tool)
+- Plan mode with programmatic control
+- Persistent task tracking (TaskCreate/Update)
+- Comprehensive hooks (SessionStart, PreToolUse, PostToolUse)
+- Unlimited MCP tools
+
+**Key paths:**
+- Commands: `.claude/commands/agileflow/`
+- Agents: `.claude/agents/agileflow/`
+- Instructions: `CLAUDE.md`
+
+### cursor.yaml
+**Closest competitor to Claude Code.** v2.5 (Feb 2026) now supports:
+- Async subagents with nesting (no Task tool needed)
+- Plan mode with native interface
+- 6 lifecycle hooks (beta)
+- 40-tool MCP limit (binding constraint)
+- Native browser tool
+
+**Gaps:**
+- No structured menus (conversational only)
+- No persistent task tracking
+- No background sub-agent execution
+
+**Key paths:**
+- Commands: `.cursor/commands/`
+- Agents: `.cursor/agents/`
+- Rules: `.cursor/rules/` (MDC format)
+- MCP config: `.cursor/mcp.json`
+
+### windsurf.yaml
+**Most comprehensive hooks (11 events).** Wave 13+ with:
+- Native worktrees (up to 20 per workspace)
+- 11 lifecycle hook events
+- 100-tool MCP limit
+- Native browser preview (in-IDE)
+
+**Gaps:**
+- No true sub-agent spawning (use workflow chaining or cascades)
+- 12,000 character limit per workflow file
+- Global-only MCP config (`~/.codeium/windsurf/mcp_config.json`)
+- No persistent task tracking
+- Conversational input only
+
+**Key paths:**
+- Workflows: `.windsurf/workflows/`
+- Skills: `.windsurf/skills/*/SKILL.md` (agentskills.io spec)
+- Rules: `.windsurf/rules/`
+- MCP config: `~/.codeium/windsurf/mcp_config.json` (global-only)
+
+### codex.yaml
+**Most restrictive.** OpenAI's CLI with:
+- Skills (no direct file tools)
+- Sandbox modes (read-only, auto, full-access)
+- Text-only user input (no structured menus)
+
+**Gaps:**
+- No plan mode
+- No hooks
+- No sub-agent delegation
+- No task tracking
+- No MCP
+
+## Usage
+
+### For Installers
+```javascript
+const profile = require('./profiles/claude-code.yaml');
+if (profile.capabilities.core.planMode) {
+  installPlanModePrompts();
+}
+```
+
+### For Generators
+```javascript
+// Read profile to generate IDE-native commands
+const generator = new CommandGenerator(profile);
+const ideSpecificMarkdown = generator.transform(canonicalCommand);
+```
+
+### For Feature Detection
+```javascript
+// Check if IDE supports a feature
+if (!profile.capabilities.collaboration.taskTracking) {
+  console.warn('Task tracking not available in this IDE');
+  suggestFileBasedAlternative();
+}
+```
+
+## Capability Categories
+
+### Core Capabilities
+- **fileOperations** - Read, write, edit files
+- **shell** - Execute shell commands
+- **fileSearch** - Glob and grep
+- **interactiveInput** - Structured user menus (structured vs conversational)
+- **subAgents** - Spawn sub-agents/skills
+- **nestedSubAgents** - Sub-agents can spawn other sub-agents
+
+### Planning
+- **planMode** - Explicit planning phase
+- **planModeEditable** - Plans can be edited during execution
+
+### Lifecycle
+- **hooks** - Pre/post execution hooks
+- **hookEvents** - List of specific hook events supported
+
+### External Integration
+- **webSearch** - Internet search capability
+- **webFetch** - Fetch URLs
+- **mcp** - Model Context Protocol support
+- **mcpToolLimit** - Max tools per MCP (0 = unlimited)
+- **browser** - Screenshot/browser automation
+
+### Collaboration
+- **taskTracking** - Persistent task tracking
+- **persistentTasks** - Tasks survive across sessions
+- **worktrees** - Git worktree support
+
+## MCP Tool Limits
+
+| IDE | Tool Cap | Notes |
+|---|---|---|
+| Claude Code | Unlimited (0) | Can install entire ecosystem |
+| Cursor | 40 | Hard limit; binding constraint for multi-IDE |
+| Windsurf | 100 | Good balance |
+| Codex | Unlimited (0) | Via MCP extension |
+
+**Design decision**: Cap multi-IDE MCP installations at 40 tools (Cursor's limit) to ensure compatibility across all platforms.
+
+## Implementation Priority
+
+| Tier | Capabilities | IDEs | Status |
+|---|---|---|---|
+| 1 | File ops, shell, search, web | All | Ready |
+| 2 | Hooks, plan mode | Claude Code, Cursor, Windsurf | Profiles complete |
+| 3 | Sub-agents, task tracking | Claude Code, Cursor | Profiles complete |
+| 4 | Worktrees, MCP | All | Profiles complete |
+
+## Next Steps
+
+1. **Validators** - Build validators to check profile format/completeness
+2. **Loaders** - Create load functions (YAML → JS objects) with caching
+3. **Generators** - Build content transformers that read profiles and output IDE-native prompts
+4. **Tests** - Snapshot tests per IDE profile
+5. **Documentation** - ADR-0011 documenting the capability profile strategy
+
+## References
+
+- Cross-IDE Compatibility Findings: `docs/10-research/20260220-ide-cross-compatibility-findings.md`
+- ADR-0011 (TBD): Capability Profile Strategy

package/src/core/profiles/claude-code.yaml

@@ -0,0 +1,111 @@
+# Claude Code IDE Capability Profile
+# Anthropic CLI - Primary target, fully supported
+# Reference: Cross-IDE Compatibility Findings (20260220)
+
+ide:
+  id: claude-code
+  name: Claude Code
+  displayName: Claude Code
+  description: Anthropic's native CLI-based development environment
+  configDir: .claude
+  instructionsFile: CLAUDE.md
+  fileFormat: markdown
+  commandPrefix: "/agileflow:"
+  agentPrefix: "agileflow-"
+
+paths:
+  commands: .claude/commands/agileflow/
+  agents: .claude/agents/agileflow/
+  skills: .claude/skills/
+  hooks: .claude/settings.json
+  mcp: .claude/settings.json
+
+capabilities:
+  core:
+    fileOperations: true      # Read, Write, Edit tools
+    shell: true               # Bash tool with full execution
+    fileSearch: true          # Glob and Grep tools
+    interactiveInput: true    # AskUserQuestion with structured options
+    subAgents: true           # Task tool for spawning subagents
+    nestedSubAgents: true     # Sub-agents can spawn sub-sub-agents
+  planning:
+    planMode: true            # EnterPlanMode/ExitPlanMode
+    planModeEditable: true    # User can edit plans mid-execution
+  lifecycle:
+    hooks: true               # PreToolUse, PostToolUse, SessionStart
+    hookEvents:
+      - SessionStart
+      - PreToolUse
+      - PostToolUse
+      - Notification
+      - Stop
+  external:
+    webSearch: true           # WebSearch tool
+    webFetch: true            # WebFetch tool
+    mcp: true                 # Model Context Protocol
+    mcpToolLimit: 0           # 0 = unlimited
+    browser: true             # Playwright MCP for screenshots
+  collaboration:
+    taskTracking: true        # TaskCreate, TaskUpdate, TaskList
+    persistentTasks: true     # Tasks survive across sessions
+    worktrees: true           # EnterWorktree for parallel branches
+
+toolNames:
+  # Interactive
+  askUser: AskUserQuestion
+  # Delegation
+  spawnAgent: Task
+  createTask: TaskCreate
+  updateTask: TaskUpdate
+  listTasks: TaskList
+  # Planning
+  planModeEnter: EnterPlanMode
+  planModeExit: ExitPlanMode
+  # Execution
+  bash: Bash
+  # Files
+  read: Read
+  write: Write
+  edit: Edit
+  # Search
+  glob: Glob
+  grep: Grep
+  # Web
+  webSearch: WebSearch
+  webFetch: WebFetch
+  # Branching
+  worktree: EnterWorktree
+
+frontmatter:
+  agents:
+    format: yaml
+    fields:
+      - name
+      - description
+      - tools
+      - model
+  commands:
+    format: yaml
+    fields:
+      - description
+      - argument-hint
+
+limits:
+  maxFileSize: 0              # 0 = unlimited
+  maxCommandLength: 0         # 0 = unlimited
+  maxToolsPerMCP: 0           # 0 = unlimited
+
+installation:
+  supportsFileOps: true
+  supportsHooks: true
+  supportsMCP: true
+  commandsRequireApproval: false
+  agentFilesCanBeNestedDirs: true
+
+notes:
+  - "Primary target for AgileFlow development"
+  - "All new capabilities are validated against Claude Code first"
+  - "AskUserQuestion provides structured menu presentation with JSON options"
+  - "Task tool supports full async delegation with result callbacks"
+  - "Plan mode integrated via native EnterPlanMode/ExitPlanMode"
+  - "No tool count limits - can install entire MCP ecosystem"

package/src/core/profiles/codex.yaml

@@ -0,0 +1,103 @@
+# OpenAI Codex CLI Capability Profile
+# Reference: Cross-IDE Compatibility Findings (20260220)
+
+ide:
+  id: codex
+  name: OpenAI Codex CLI
+  displayName: Codex
+  description: OpenAI's CLI-based development assistant
+  configDir: .codex
+  configDirUser: ~/.codex
+  instructionsFile: AGENTS.md
+  fileFormat: markdown
+  commandPrefix: "$agileflow-"
+  agentPrefix: "agileflow-"
+
+paths:
+  commands: null              # Not directly supported
+  agents: null                # Not directly supported
+  skills: .codex/skills/agileflow-*/SKILL.md
+  skillsUser: ~/.codex/prompts/agileflow-*.md
+  hooks: null                 # Not supported
+  mcp: null                   # Not supported
+
+capabilities:
+  core:
+    fileOperations: true      # Via skills (no direct tools)
+    shell: true               # Via sandbox
+    fileSearch: true          # Via sandbox search
+    interactiveInput: true    # ask_user_question (text-only, no structured menus)
+    subAgents: false          # Experimental multi-agent support (disabled by default)
+    nestedSubAgents: false    # No nested delegation; experimental agents are flat
+  planning:
+    planMode: true            # On by default since v0.96
+    planModeEditable: true    # Plans are editable
+  lifecycle:
+    hooks: false              # No lifecycle hooks
+    approvalPolicies: true    # Approval gates only
+  external:
+    webSearch: false          # Not built-in
+    webFetch: false           # Not built-in
+    mcp: true                 # Via MCP extension
+    mcpToolLimit: 0           # 0 = unlimited
+    browser: false            # Not available
+  collaboration:
+    taskTracking: false       # No task tracking
+    persistentTasks: false
+    worktrees: false          # Manual git operations
+
+sandboxModes:
+  - id: read-only
+    description: "No file modifications, workspace read access"
+  - id: auto
+    description: "Auto-approved operations within workspace"
+  - id: full-access
+    description: "Full system access with approval"
+
+toolNames:
+  # Interactive
+  askUser: ask_user_question  # Text-only, not structured
+  # File operations (via skill)
+  read: null                  # Use skill instead
+  write: null                 # Use skill instead
+  edit: null                  # Use skill instead
+  # Execution (via skill)
+  bash: null                  # Use sandbox instead
+  # Search (via skill)
+  glob: null                  # Use sandbox instead
+  grep: null                  # Use sandbox instead
+  # Web (not available)
+  webSearch: null
+  webFetch: null
+
+frontmatter:
+  skills:
+    format: yaml
+    fields:
+      - name
+      - description
+      - model
+      - requiredPermissions
+
+limitations:
+  noSubAgents: "Cannot spawn other skills; use numbered prompts for sequential work"
+  noInteractiveMenus: "ask_user_question is text-only; convert to numbered options"
+  noPlanning: "No plan mode; use sequential skill instructions instead"
+  noHooks: "No lifecycle hooks; use approval policies"
+  noTaskTracking: "No persistent task tracking; use external tools"
+  skillScope: "Skills are repository-scoped, user prompts are global"
+
+installation:
+  supportsFileOps: false      # Via skills, not native tools
+  supportsHooks: false
+  supportsMCP: true           # Via MCP extension
+  commandsRequireApproval: true
+  skillsCanBeNestedDirs: false
+
+notes:
+  - "Skills are the primary extension mechanism"
+  - "Per-repo skills in .codex/skills/, global prompts in ~/.codex/prompts/"
+  - "Plan mode available (on by default since v0.96); no hooks or true sub-agent delegation"
+  - "AgileFlow /babysit features must fallback to conversational prompts"
+  - "Best used for simple linear workflows"
+  - "ask_user_question produces text output, not structured menus"

package/src/core/profiles/cursor.yaml

@@ -0,0 +1,134 @@
+# Cursor IDE Capability Profile
+# v2.5 (Feb 2026) - Closest competitor to Claude Code
+# Reference: Cross-IDE Compatibility Findings (20260220)
+
+ide:
+  id: cursor
+  name: Cursor
+  displayName: Cursor
+  description: AI-native code editor with async subagents and hooks
+  configDir: .cursor
+  instructionsFile: CURSOR.md
+  fileFormat: markdown
+  commandPrefix: "/"
+  agentPrefix: "agileflow-"
+  marketplaceId: cursor.com/marketplace
+
+paths:
+  commands: .cursor/commands/
+  agents: .cursor/agents/
+  skills: null                # Uses agents instead
+  rules: .cursor/rules/
+  hooks: .cursor/hooks.json
+  mcp: .cursor/mcp.json
+
+capabilities:
+  core:
+    fileOperations: true      # read_file, edit_file, ApplyPatch
+    shell: true               # run_terminal_cmd, YOLO mode for auto-execution
+    fileSearch: true          # codebase_search, grep_search, file_search, list_dir
+    interactiveInput: true    # Conversational only (no structured AskUserQuestion)
+    subAgents: true           # Async subagents with nesting
+    nestedSubAgents: true     # Sub-agents can spawn sub-sub-agents
+  planning:
+    planMode: true            # Native plan mode with Markdown plans
+    planModeEditable: true    # User can edit plans during execution
+  lifecycle:
+    hooks: true               # Beta - 6 hook events
+    hookEvents:
+      - beforeSubmitPrompt
+      - beforeShellExecution
+      - beforeMCPExecution
+      - beforeReadFile
+      - afterFileEdit
+      - stop
+  external:
+    webSearch: true           # Native web_search + @web syntax + MCP
+    webFetch: true            # Can fetch URLs
+    mcp: true                 # Full MCP support
+    mcpToolLimit: 40          # 40-tool cap (binding constraint)
+    browser: true             # Native browser tool (v2.0+)
+  collaboration:
+    taskTracking: false       # Plan mode checklists only (not persistent)
+    persistentTasks: false
+    worktrees: false          # Background agents use branches instead
+
+toolNames:
+  # Interactive
+  askUser: null               # Conversational only, no AskUserQuestion
+  # Delegation
+  spawnAgent: null            # Use native async subagents in .cursor/agents/
+  # Planning
+  planModeEnter: null         # Native, activated via interface
+  planModeExit: null          # Native
+  # Execution
+  bash: run_terminal_cmd
+  # Files
+  read: read_file
+  write: null                 # Use ApplyPatch or edit_file
+  edit: edit_file
+  # Search
+  glob: file_search
+  grep: grep_search
+  # Web
+  webSearch: web_search
+  webFetch: null              # Use web_search with @web
+  # Browser
+  browser: native_browser
+
+frontmatter:
+  agents:
+    format: yaml
+    fields:
+      - name
+      - description
+      - model
+      - readonly
+      - is_background
+  commands:
+    format: markdown           # Slash commands
+  rules:
+    format: mdc                # MDC format (YAML: description, globs, alwaysApply)
+
+subAgentConfig:
+  format: yaml
+  fields:
+    name: "Agent display name"
+    description: "What this agent does"
+    model: "claude-3-5-sonnet or gpt-4-turbo"
+    readonly: "boolean - read-only workspace"
+    is_background: "boolean - runs without user interaction"
+  async: true
+  supportsNesting: true
+  resultsAreAccessible: true
+
+limits:
+  maxFileSize: 0              # 0 = unlimited
+  maxCommandLength: 0         # 0 = unlimited
+  maxToolsPerMCP: 40          # Hard limit
+  maxBackgroundAgents: 5      # Practical limit
+
+installation:
+  supportsFileOps: true
+  supportsHooks: true         # Beta support
+  supportsMCP: true
+  commandsRequireApproval: false
+  agentFilesCanBeNestedDirs: false
+  rulesFormat: MDC            # Modern YAML-based rule format
+
+features:
+  marketplace: "Plugin marketplace at cursor.com/marketplace"
+  backendAgents: "Can run agents in background without UI blocking"
+  asyncModel: "Agents don't wait for each other - true parallelism"
+  hookBeta: "6 hooks in beta; more events coming in Wave 2.6"
+
+notes:
+  - "Cursor v2.5 now rivals Claude Code with async subagents"
+  - "Agents are native; no separate Task tool needed"
+  - "Conversational input instead of structured menus (AskUserQuestion replacement)"
+  - "40-tool MCP limit is binding constraint for multi-IDE installations"
+  - "MDC rule format is modern YAML-based (legacy .cursorrules still supported)"
+  - "Plan mode fully built-in; no explicit enter/exit needed"
+  - "Hook events have different names but similar functionality to Claude Code"
+  - "CAVEAT: Task tools (TaskCreate/TaskUpdate) bypass PreToolUse/PostToolUse hooks"
+  - "Background agents enable true parallel task execution"