agileflow 3.1.0 → 3.2.0

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,
+};

package/src/core/profiles/windsurf.yaml

@@ -0,0 +1,159 @@
+# Windsurf IDE Capability Profile
+# Wave 13+ - Most comprehensive hooks but no true sub-agent spawning
+# Reference: Cross-IDE Compatibility Findings (20260220)
+
+ide:
+  id: windsurf
+  name: Windsurf
+  displayName: Windsurf
+  description: Codeium's AI editor with native worktrees and 11 lifecycle hooks
+  configDir: .windsurf
+  configDirGlobal: ~/.codeium/windsurf
+  instructionsFile: WINDSURF.md
+  fileFormat: markdown
+  commandPrefix: "/"
+  agentPrefix: "agileflow-"
+
+paths:
+  commands: .windsurf/workflows/
+  agents: null                # Uses workflows + cascades instead
+  skills: .windsurf/skills/*/SKILL.md
+  rules: .windsurf/rules/
+  workflows: .windsurf/workflows/
+  hooks: .windsurf/hooks.json
+  hooksGlobal: ~/.codeium/windsurf/hooks.json
+  mcp: ~/.codeium/windsurf/mcp_config.json
+  mcpGlobal: true             # MCP config is global-only
+
+capabilities:
+  core:
+    fileOperations: true      # Native file read/write
+    shell: true               # Native shell (4-level auto-execution)
+    fileSearch: true          # Native search + analyze tools
+    interactiveInput: true    # Conversational only (no structured menus)
+    subAgents: false          # No true sub-agent spawning
+    nestedSubAgents: false    # Parallel Cascades via worktrees instead
+  planning:
+    planMode: true            # Native via "megaplan" keyword
+    planModeEditable: true    # Editable plans in ~/.windsurf/plans/
+  lifecycle:
+    hooks: true               # 9 lifecycle events (per official docs Feb 2026)
+    hookEvents:
+      - 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
+  external:
+    webSearch: true           # Web Search tool
+    webFetch: true            # URL Read and View Chunk
+    mcp: true                 # Full MCP support
+    mcpToolLimit: 100         # 100-tool cap
+    browser: true             # Browser Preview (in-IDE)
+  collaboration:
+    taskTracking: false       # Conversation-embedded only (not persistent)
+    persistentTasks: false
+    worktrees: true           # Native worktrees (up to 20 per workspace)
+    maxWorktrees: 20
+
+toolNames:
+  # Interactive
+  askUser: null               # Conversational only
+  # Delegation
+  spawnAgent: null            # Use workflows + cascades instead
+  # Planning
+  planModeEnter: null         # Native, use "megaplan" keyword
+  planModeExit: null          # Native
+  # Execution
+  bash: run_command
+  # Files
+  read: read_file
+  write: write_file
+  edit: edit_file
+  # Search
+  glob: search_files
+  grep: search_codebase
+  # Web
+  webSearch: web_search
+  webFetch: url_read
+  # Cascades
+  cascade: null               # Use /workflow-name chaining
+
+workflowModel:
+  format: markdown
+  maxCharacters: 12000        # Hard limit per workflow file
+  splitStrategy: "Split large workflows into multiple files"
+  chaining: "Use /workflow-name in instructions to chain workflows"
+  cascades: "Use @cascade to run multiple workflows in parallel"
+
+skillModel:
+  format: markdown
+  frontmatterFormat: yaml
+  spec: "agentskills.io"
+  fields:
+    - name
+    - description
+    - model
+    - requiredCapabilities
+
+frontmatter:
+  workflows:
+    format: null              # Workflows are commands, not structured prompts
+  rules:
+    format: markdown
+    fields:
+      - description
+      - globs
+      - alwaysApply
+  skills:
+    format: yaml
+    fields:
+      - name
+      - description
+      - model
+      - requiredCapabilities
+
+limits:
+  maxFileSize: 0              # 0 = unlimited
+  maxCommandLength: 0         # 0 = unlimited
+  maxWorkflowSize: 12000      # Hard limit per workflow file
+  maxToolsPerMCP: 100         # MCP tool limit
+  maxWorktreesPerWorkspace: 20
+  autoExecutionLevels: 4      # Shell auto-execution levels
+
+installation:
+  supportsFileOps: true
+  supportsHooks: true         # Native
+  supportsMCP: true           # Global-only config
+  commandsRequireApproval: false
+  skillsCanBeNestedDirs: true
+  projectLevelMCP: false      # MCP config is global-only
+
+worktreeModel:
+  supported: true
+  maxConcurrent: 20
+  useCase: "Parallel feature branches or multi-task execution"
+  gitIntegration: "Native git worktree support"
+  hostedOn: "Wave 13+"
+
+cascadeModel:
+  description: "Run multiple workflows in parallel"
+  syntax: "@cascade /workflow1 /workflow2"
+  useCase: "Execute independent tasks without blocking"
+  limitSubstitution: "Use cascades instead of Task tool"
+
+notes:
+  - "Windsurf has the most comprehensive hooks (11 events)"
+  - "NO true sub-agent spawning; use workflow chaining or cascades"
+  - "12,000 character limit per workflow - split large commands"
+  - "MCP config is global-only (in ~/.codeium/windsurf/mcp_config.json)"
+  - "Conversational input, no structured menus"
+  - "Native worktrees enable parallel development (up to 20 per workspace)"
+  - "Skills follow agentskills.io specification"
+  - "Use 'megaplan' keyword for advanced planning"
+  - "100-tool MCP limit; good balance between capability and performance"
+  - "Plan files stored in ~/.windsurf/plans/ (user's home, not project)"

package/src/core/teams/logic-audit.json

@@ -20,6 +20,12 @@
       "domain": "control-flow",
       "description": "Analyzes dead code, unreachable branches, and missing returns"
     },
+    {
+      "agent": "agileflow-logic-analyzer-invariant",
+      "role": "analyzer",
+      "domain": "invariants",
+      "description": "Analyzes pre/post conditions, state consistency, and contract violations"
+    },
     {
       "agent": "agileflow-logic-analyzer-race",
       "role": "analyzer",