agileflow 3.1.0 → 3.2.1

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"

package/src/core/profiles/examples.js

@@ -0,0 +1,250 @@
+/**
+ * IDE Capability Profile - Usage Examples
+ *
+ * This file demonstrates how to use the profile loader
+ * in installers, generators, and feature-detection code.
+ *
+ * Run: node examples.js
+ */
+
+const loader = require('./loader');
+
+console.log('IDE Capability Profile - Usage Examples\n');
+console.log('='.repeat(60) + '\n');
+
+// ============================================================
+// Example 1: Load a single profile
+// ============================================================
+console.log('1. LOAD A SINGLE PROFILE\n');
+
+const claudeCodeProfile = loader.load('claude-code');
+console.log(`Loaded: ${claudeCodeProfile.ide.displayName}`);
+console.log(`Config dir: ${claudeCodeProfile.paths.commands}`);
+console.log(`Instructions: ${claudeCodeProfile.paths.instructionsFile}`);
+console.log();
+
+// ============================================================
+// Example 2: Load all profiles
+// ============================================================
+console.log('2. LOAD ALL PROFILES\n');
+
+const allProfiles = loader.loadAll();
+console.log('Available IDEs:');
+Object.keys(allProfiles).sort().forEach(ide => {
+  const profile = allProfiles[ide];
+  console.log(`  - ${profile.ide.displayName}`);
+});
+console.log();
+
+// ============================================================
+// Example 3: List available profiles
+// ============================================================
+console.log('3. LIST AVAILABLE PROFILES\n');
+
+const available = loader.listAvailable();
+console.log(`Supported IDEs: ${available.join(', ')}`);
+console.log();
+
+// ============================================================
+// Example 4: Check if IDE is supported
+// ============================================================
+console.log('4. CHECK IDE SUPPORT\n');
+
+['claude-code', 'cursor', 'unknown-ide'].forEach(ide => {
+  const supported = loader.isSupported(ide);
+  console.log(`${ide}: ${supported ? '✓ supported' : '✗ not supported'}`);
+});
+console.log();
+
+// ============================================================
+// Example 5: Check specific capability
+// ============================================================
+console.log('5. CHECK SPECIFIC CAPABILITIES\n');
+
+const capabilities = [
+  { ide: 'claude-code', group: 'core', cap: 'planMode' },
+  { ide: 'cursor', group: 'core', cap: 'planMode' },
+  { ide: 'windsurf', group: 'collaboration', cap: 'taskTracking' },
+  { ide: 'codex', group: 'planning', cap: 'planMode' },
+];
+
+capabilities.forEach(({ ide, group, cap }) => {
+  const has = loader.hasCapability(ide, group, cap);
+  const status = has ? '✅' : '❌';
+  console.log(`${ide}: ${cap} ${status}`);
+});
+console.log();
+
+// ============================================================
+// Example 6: Get tool name mapping
+// ============================================================
+console.log('6. TOOL NAME MAPPINGS (IDE-specific equivalents)\n');
+
+const toolAlias = 'bash';
+console.log(`Standard tool alias: "${toolAlias}"`);
+console.log('IDE-specific names:');
+available.forEach(ide => {
+  const toolName = loader.getToolName(ide, toolAlias);
+  console.log(`  ${ide}: ${toolName || '(not available)'}`);
+});
+console.log();
+
+// ============================================================
+// Example 7: Get all capabilities for an IDE
+// ============================================================
+console.log('7. ALL CAPABILITIES FOR CURSOR\n');
+
+const cursorCaps = loader.getAllCapabilities('cursor');
+const enabledCaps = Object.entries(cursorCaps)
+  .filter(([_, enabled]) => enabled)
+  .map(([name, _]) => name);
+
+console.log(`Cursor has ${enabledCaps.length} capabilities enabled:`);
+enabledCaps.slice(0, 8).forEach(cap => console.log(`  ✓ ${cap}`));
+console.log(`  ... and ${enabledCaps.length - 8} more`);
+console.log();
+
+// ============================================================
+// Example 8: Find IDEs with a capability
+// ============================================================
+console.log('8. FIND IDEs WITH SPECIFIC CAPABILITY\n');
+
+const idsWithPlanMode = loader.findIDEsWithCapability('planning', 'planMode');
+console.log(`IDEs with plan mode: ${idsWithPlanMode.join(', ')}`);
+
+const idsWithTasks = loader.findIDEsWithCapability('collaboration', 'taskTracking');
+console.log(`IDEs with task tracking: ${idsWithTasks.join(', ')}`);
+
+const idsWithMCP = loader.findIDEsWithCapability('external', 'mcp');
+console.log(`IDEs with MCP: ${idsWithMCP.join(', ')}`);
+console.log();
+
+// ============================================================
+// Example 9: Compare capability across IDEs
+// ============================================================
+console.log('9. COMPARE CAPABILITY ACROSS ALL IDEs\n');
+
+const subAgentComparison = loader.compareCapability('core', 'subAgents');
+console.log('Sub-agent support:');
+Object.entries(subAgentComparison).forEach(([ide, supported]) => {
+  console.log(`  ${ide}: ${supported ? '✅' : '❌'}`);
+});
+console.log();
+
+// ============================================================
+// Example 10: Design pattern - Feature detection in installer
+// ============================================================
+console.log('10. DESIGN PATTERN: FEATURE-BASED INSTALLATION\n');
+
+function installForIDE(ideId) {
+  console.log(`Installing for ${ideId}...\n`);
+
+  const profile = loader.load(ideId);
+
+  // Install commands if supported
+  if (profile.paths.commands) {
+    console.log(`  → Install commands to: ${profile.paths.commands}`);
+  }
+
+  // Install hooks if supported
+  if (loader.hasCapability(ideId, 'lifecycle', 'hooks')) {
+    console.log(`  → Install lifecycle hooks (${profile.capabilities.lifecycle.hookEvents.length} events)`);
+  }
+
+  // Install MCP if supported
+  if (loader.hasCapability(ideId, 'external', 'mcp')) {
+    const limit = profile.capabilities.external.mcpToolLimit;
+    if (limit === 0) {
+      console.log(`  → Install MCP tools (unlimited)`);
+    } else {
+      console.log(`  → Install MCP tools (cap: ${limit})`);
+    }
+  }
+
+  // Install plan mode prompts if supported
+  if (loader.hasCapability(ideId, 'planning', 'planMode')) {
+    console.log(`  → Install plan mode instructions`);
+  }
+
+  console.log();
+}
+
+installForIDE('claude-code');
+installForIDE('windsurf');
+installForIDE('codex');
+
+// ============================================================
+// Example 11: Design pattern - Capability fallback chain
+// ============================================================
+console.log('11. DESIGN PATTERN: CAPABILITY FALLBACK\n');
+
+function getInteractiveInputMethod(ideId) {
+  const profile = loader.load(ideId);
+
+  if (loader.hasCapability(ideId, 'core', 'interactiveInput')) {
+    if (loader.getToolName(ideId, 'askUser') === 'AskUserQuestion') {
+      return 'Structured menus (AskUserQuestion)';
+    } else if (loader.getToolName(ideId, 'askUser')) {
+      return `Text input (${loader.getToolName(ideId, 'askUser')})`;
+    }
+  }
+
+  return 'Conversational clarification';
+}
+
+console.log('Interactive input methods by IDE:');
+available.forEach(ide => {
+  const method = getInteractiveInputMethod(ide);
+  console.log(`  ${ide}: ${method}`);
+});
+console.log();
+
+// ============================================================
+// Example 12: Design pattern - Multi-IDE constraint analysis
+// ============================================================
+console.log('12. DESIGN PATTERN: MULTI-IDE CONSTRAINT ANALYSIS\n');
+
+console.log('Planning a multi-IDE deployment...\n');
+
+const allCaps = loader.loadAll();
+const mpcConstraints = [];
+
+available.forEach(ide => {
+  const limit = allCaps[ide].capabilities.external.mcpToolLimit;
+  if (limit > 0) {
+    mpcConstraints.push({ ide, limit });
+  }
+});
+
+mpcConstraints.sort((a, b) => a.limit - b.limit);
+
+if (mpcConstraints.length > 0) {
+  const minLimit = mpcConstraints[0].limit;
+  console.log(`Binding constraint (most restrictive IDE): ${minLimit} MCP tools`);
+  console.log(`Affected IDEs:`);
+  mpcConstraints.forEach(({ ide, limit }) => {
+    const marker = limit === minLimit ? '🔴 (CONSTRAINT)' : '🟢';
+    console.log(`  ${marker} ${ide}: ${limit} tools`);
+  });
+}
+console.log();
+
+// ============================================================
+// Summary
+// ============================================================
+console.log('='.repeat(60));
+console.log('Profile System Ready for Use');
+console.log('='.repeat(60));
+console.log(`
+Available utilities:
+  loader.load(ideId)                      - Load single profile
+  loader.loadAll()                        - Load all profiles
+  loader.listAvailable()                  - List IDE names
+  loader.isSupported(ideId)               - Check if IDE supported
+  loader.hasCapability(ideId, group, cap) - Check feature support
+  loader.getToolName(ideId, alias)        - Get IDE-specific tool name
+  loader.getAllCapabilities(ideId)        - Get all IDE capabilities
+  loader.findIDEsWithCapability(group, cap) - Find IDEs with feature
+  loader.compareCapability(group, cap)    - Compare across all IDEs
+  loader.clearCache()                     - Clear cached profiles
+`);

package/src/core/profiles/loader.js

@@ -0,0 +1,235 @@
+/**
+ * IDE Capability Profile Loader
+ *
+ * Loads YAML capability profiles with validation and caching.
+ * Used by installers, generators, and feature-detection code.
+ *
+ * Usage:
+ *   const loader = require('./profiles/loader');
+ *   const profile = loader.load('claude-code');
+ *   if (profile.capabilities.core.planMode) { ... }
+ */
+
+const yaml = require('js-yaml');
+const fs = require('fs');
+const path = require('path');
+
+const PROFILES_DIR = __dirname;
+const CACHE = {};
+
+/**
+ * Load a profile by IDE name
+ * @param {string} ideId - IDE identifier (claude-code, cursor, windsurf, codex)
+ * @returns {Object} Profile object
+ * @throws {Error} If profile not found or invalid YAML
+ */
+function load(ideId) {
+  if (CACHE[ideId]) {
+    return CACHE[ideId];
+  }
+
+  const filePath = path.join(PROFILES_DIR, `${ideId}.yaml`);
+
+  if (!fs.existsSync(filePath)) {
+    throw new Error(`Profile not found: ${ideId}`);
+  }
+
+  try {
+    const content = fs.readFileSync(filePath, 'utf8');
+    const profile = yaml.load(content);
+
+    // Validate profile structure
+    validateProfile(profile, ideId);
+
+    CACHE[ideId] = profile;
+    return profile;
+  } catch (e) {
+    if (e instanceof yaml.YAMLException) {
+      throw new Error(`Invalid YAML in profile ${ideId}: ${e.message}`);
+    }
+    throw e;
+  }
+}
+
+/**
+ * Load all available profiles
+ * @returns {Object} Map of IDE ID to profile
+ */
+function loadAll() {
+  const profiles = {};
+  const files = fs.readdirSync(PROFILES_DIR)
+    .filter(f => f.endsWith('.yaml'));
+
+  files.forEach(file => {
+    const ideId = file.replace('.yaml', '');
+    try {
+      profiles[ideId] = load(ideId);
+    } catch (e) {
+      console.error(`Failed to load profile ${ideId}: ${e.message}`);
+    }
+  });
+
+  return profiles;
+}
+
+/**
+ * Get list of available profiles
+ * @returns {Array<string>} List of IDE IDs
+ */
+function listAvailable() {
+  return fs.readdirSync(PROFILES_DIR)
+    .filter(f => f.endsWith('.yaml'))
+    .map(f => f.replace('.yaml', ''))
+    .sort();
+}
+
+/**
+ * Check if IDE is supported
+ * @param {string} ideId - IDE identifier
+ * @returns {boolean} True if IDE profile exists
+ */
+function isSupported(ideId) {
+  return fs.existsSync(path.join(PROFILES_DIR, `${ideId}.yaml`));
+}
+
+/**
+ * Validate profile structure
+ * @private
+ * @param {Object} profile - Profile object
+ * @param {string} ideId - IDE identifier
+ * @throws {Error} If validation fails
+ */
+function validateProfile(profile, ideId) {
+  const required = ['ide', 'paths', 'capabilities', 'toolNames'];
+
+  for (const field of required) {
+    if (!profile[field]) {
+      throw new Error(`Missing required field: ${field}`);
+    }
+  }
+
+  // Validate ide object
+  if (!profile.ide.id || !profile.ide.name) {
+    throw new Error('ide object must have id and name fields');
+  }
+
+  // Validate capabilities structure
+  const validCapGroups = ['core', 'planning', 'lifecycle', 'external', 'collaboration'];
+  for (const group of Object.keys(profile.capabilities)) {
+    if (!validCapGroups.includes(group)) {
+      console.warn(`Unknown capability group in ${ideId}: ${group}`);
+    }
+  }
+}
+
+/**
+ * Get capability status for an IDE
+ * @param {string} ideId - IDE identifier
+ * @param {string} group - Capability group (core, planning, lifecycle, external, collaboration)
+ * @param {string} capability - Capability name
+ * @returns {boolean|null} True if supported, false if not, null if unknown
+ */
+function hasCapability(ideId, group, capability) {
+  const profile = load(ideId);
+  const groupCapabilities = profile.capabilities[group];
+
+  if (!groupCapabilities) {
+    return null;
+  }
+
+  return groupCapabilities[capability] === true;
+}
+
+/**
+ * Get tool name for an IDE
+ * Returns the tool name used by the IDE, or null if not supported
+ *
+ * @param {string} ideId - IDE identifier
+ * @param {string} toolAlias - Standard tool alias (askUser, bash, read, etc.)
+ * @returns {string|null} IDE-specific tool name or null
+ */
+function getToolName(ideId, toolAlias) {
+  const profile = load(ideId);
+  return profile.toolNames[toolAlias] || null;
+}
+
+/**
+ * Get all capabilities for an IDE (flattened)
+ * @param {string} ideId - IDE identifier
+ * @returns {Object} Map of capability name to boolean
+ */
+function getAllCapabilities(ideId) {
+  const profile = load(ideId);
+  const capabilities = {};
+
+  for (const [group, groupCaps] of Object.entries(profile.capabilities)) {
+    if (typeof groupCaps === 'object' && !Array.isArray(groupCaps)) {
+      for (const [cap, value] of Object.entries(groupCaps)) {
+        if (typeof value === 'boolean') {
+          capabilities[`${group}.${cap}`] = value;
+        }
+      }
+    }
+  }
+
+  return capabilities;
+}
+
+/**
+ * Find all IDEs supporting a capability
+ * @param {string} group - Capability group
+ * @param {string} capability - Capability name
+ * @returns {Array<string>} List of IDE IDs that support this capability
+ */
+function findIDEsWithCapability(group, capability) {
+  const ides = [];
+  const all = loadAll();
+
+  for (const [ideId, profile] of Object.entries(all)) {
+    if (profile.capabilities[group] && profile.capabilities[group][capability] === true) {
+      ides.push(ideId);
+    }
+  }
+
+  return ides.sort();
+}
+
+/**
+ * Get comparison table for a specific capability across all IDEs
+ * @param {string} group - Capability group
+ * @param {string} capability - Capability name
+ * @returns {Object} Map of IDE ID to boolean
+ */
+function compareCapability(group, capability) {
+  const result = {};
+  const all = loadAll();
+
+  for (const [ideId, profile] of Object.entries(all)) {
+    result[ideId] = profile.capabilities[group] && profile.capabilities[group][capability] === true;
+  }
+
+  return result;
+}
+
+/**
+ * Clear profile cache
+ * Useful for testing or reloading profiles after updates
+ */
+function clearCache() {
+  for (const key of Object.keys(CACHE)) {
+    delete CACHE[key];
+  }
+}
+
+module.exports = {
+  load,
+  loadAll,
+  listAvailable,
+  isSupported,
+  hasCapability,
+  getToolName,
+  getAllCapabilities,
+  findIDEsWithCapability,
+  compareCapability,
+  clearCache,
+};