agileflow 2.61.0 → 2.63.0

package/src/core/commands/skill/test.md

@@ -0,0 +1,249 @@
+---
+description: Verify a skill works correctly by testing its activation and functionality
+argument-hint: [SKILL_NAME] (optional)
+---
+
+# /agileflow:skill:test
+
+Test a skill to verify it activates correctly and produces expected results.
+
+---
+
+## Workflow
+
+### STEP 1: Select skill to test
+
+If SKILL_NAME not provided, list available skills:
+
+```bash
+ls -d .claude/skills/*/ 2>/dev/null | xargs -I {} basename {}
+```
+
+Then ask user:
+
+```xml
+<invoke name="AskUserQuestion">
+<parameter name="questions">[{
+  "question": "Which skill would you like to test?",
+  "header": "Select Skill",
+  "multiSelect": false,
+  "options": [
+    {"label": "<skill-1>", "description": "<description from frontmatter>"},
+    {"label": "<skill-2>", "description": "<description from frontmatter>"},
+    {"label": "<skill-3>", "description": "<description from frontmatter>"}
+  ]
+}]</parameter>
+</invoke>
+```
+
+### STEP 2: Read skill metadata
+
+Read SKILL.md and extract:
+- Name and description
+- "When to Use" section (activation triggers)
+- Cookbook entries (if any)
+- Quick reference section
+
+### STEP 3: Run validation checks
+
+```
+🧪 Testing: supabase-swift
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+Structure Validation:
+  ✅ SKILL.md exists
+  ✅ Frontmatter has name and description
+  ✅ references.md exists
+  ✅ cookbook/ directory found (2 entries)
+  ⚠️ No .mcp.json (MCP not configured)
+
+Content Validation:
+  ✅ "When to Use" section present
+  ✅ Description under 1024 characters
+  ✅ SKILL.md under 500 lines (current: 287)
+  ✅ All cookbook files referenced in SKILL.md
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+```
+
+### STEP 4: Test activation (optional)
+
+```xml
+<invoke name="AskUserQuestion">
+<parameter name="questions">[{
+  "question": "Would you like to test skill activation with a sample prompt?",
+  "header": "Activation Test",
+  "multiSelect": false,
+  "options": [
+    {"label": "Yes, test activation (Recommended)", "description": "I'll simulate using the skill"},
+    {"label": "Skip activation test", "description": "Structure validation is enough"},
+    {"label": "View SKILL.md content", "description": "Read the full skill instructions"}
+  ]
+}]</parameter>
+</invoke>
+```
+
+If user wants activation test:
+
+1. **Extract sample triggers** from "When to Use" section
+2. **Present test prompts** based on triggers:
+   ```
+   Sample prompts that should activate this skill:
+
+   1. "Help me set up Supabase authentication in Swift"
+   2. "Create CRUD operations for my database"
+   3. "How do I query Supabase from iOS?"
+   ```
+3. **Ask user to pick one** or provide custom prompt
+4. **Execute the skill** by reading SKILL.md and following instructions
+5. **Report results**
+
+### STEP 5: Show test results
+
+```
+🧪 Test Results: supabase-swift
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+Structure:     ✅ PASS (5/5 checks)
+Content:       ✅ PASS (4/4 checks)
+Activation:    ✅ PASS (skill triggered correctly)
+MCP Config:    ⚠️ NOT CONFIGURED
+
+Overall: ✅ SKILL IS FUNCTIONAL
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+```
+
+### STEP 6: Offer next actions
+
+```xml
+<invoke name="AskUserQuestion">
+<parameter name="questions">[{
+  "question": "What would you like to do?",
+  "header": "Next Action",
+  "multiSelect": false,
+  "options": [
+    {"label": "Test another skill", "description": "Validate a different skill"},
+    {"label": "Edit this skill", "description": "Fix issues or improve"},
+    {"label": "Use this skill now", "description": "Start working with it"},
+    {"label": "Done", "description": "Exit skill testing"}
+  ]
+}]</parameter>
+</invoke>
+```
+
+---
+
+## Validation Checks
+
+### Structure Checks
+
+| Check | Pass Condition |
+|-------|----------------|
+| SKILL.md exists | File present in skill directory |
+| Frontmatter valid | Has `name:` and `description:` |
+| references.md | File exists (optional but recommended) |
+| cookbook/ | Directory exists if referenced in SKILL.md |
+| .mcp.json | Valid JSON if present |
+
+### Content Checks
+
+| Check | Pass Condition |
+|-------|----------------|
+| When to Use | Section present with activation triggers |
+| Description length | Under 1024 characters |
+| SKILL.md size | Under 500 lines |
+| Cookbook references | All referenced files exist |
+| No broken links | All local file references valid |
+
+### MCP Checks (if .mcp.json exists)
+
+| Check | Pass Condition |
+|-------|----------------|
+| Valid JSON | Parses without errors |
+| Has mcpServers | Contains mcpServers object |
+| Command exists | Command is npx or valid executable |
+| Env vars documented | Any ${VAR} has comments |
+
+---
+
+## Test Report Format
+
+```
+🧪 Skill Test Report: <skill-name>
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+STRUCTURE VALIDATION
+  [✅|❌] SKILL.md exists
+  [✅|❌] Frontmatter valid (name, description)
+  [✅|⚠️] references.md exists
+  [✅|⚠️] cookbook/ directory
+  [✅|⚠️] .mcp.json present
+
+CONTENT VALIDATION
+  [✅|❌] "When to Use" section
+  [✅|❌] Description < 1024 chars (<current> chars)
+  [✅|❌] SKILL.md < 500 lines (<current> lines)
+  [✅|❌] All cookbook files exist
+
+ACTIVATION TEST
+  [✅|❌] Skill triggered on test prompt
+  [✅|❌] Produced expected output format
+
+ISSUES FOUND
+  - <issue 1>
+  - <issue 2>
+
+RECOMMENDATIONS
+  - <suggestion 1>
+  - <suggestion 2>
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+Overall: [✅ PASS | ⚠️ WARNINGS | ❌ FAIL]
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+```
+
+---
+
+## Error Handling
+
+### Skill Not Found
+```
+❌ Skill "<name>" not found.
+
+Available skills:
+  - ui-components
+  - api-integration
+
+Use /agileflow:skill:list to see all skills.
+```
+
+### No Skills Installed
+```
+❌ No skills to test.
+
+Create a skill first: /agileflow:skill:create
+```
+
+### Validation Failed
+```
+❌ Skill "<name>" has issues:
+
+  ❌ Missing SKILL.md frontmatter
+  ❌ Description exceeds 1024 characters (1523)
+  ⚠️ No "When to Use" section
+
+Fix with: /agileflow:skill:edit <name>
+```
+
+---
+
+## Usage
+
+```bash
+# Interactive mode
+/agileflow:skill:test
+
+# Test specific skill
+/agileflow:skill:test supabase-swift
+```

package/src/core/commands/template.md

@@ -1,5 +1,6 @@
 ---
 description: Create and manage custom document templates
+argument-hint: (no arguments)
 ---
 
 # custom-template

package/src/core/commands/tests.md

@@ -1,5 +1,6 @@
 ---
 description: Set up automated testing infrastructure
+argument-hint: (no arguments)
 ---
 
 # setup-tests

package/src/core/commands/update.md

@@ -1,5 +1,6 @@
 ---
 description: Generate stakeholder progress report
+argument-hint: (no arguments)
 ---
 
 # stakeholder-update

package/src/core/commands/velocity.md

@@ -1,5 +1,6 @@
 ---
 description: Track velocity and forecast sprint capacity
+argument-hint: (no arguments)
 model: haiku
 ---
 

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

@@ -26,22 +26,22 @@ files:
   core_content:
     - path: packages/cli/src/core/commands/
       purpose: Slash command markdown files
-      count: 41
+      count: "{{COMMAND_COUNT}}"
       pattern: "<command>.md with frontmatter"
 
     - path: packages/cli/src/core/agents/
       purpose: Agent prompt markdown files
-      count: 26
+      count: "{{AGENT_COUNT}}"
       pattern: "<agent>.md with frontmatter (name, description, tools, model)"
 
     - path: packages/cli/src/core/experts/
       purpose: Expert knowledge files
-      count: 25
+      count: "{{SKILL_COUNT}}"
       pattern: "<domain>/expertise.yaml, question.md, self-improve.md, workflow.md"
 
     - path: packages/cli/src/core/skills/
       purpose: Auto-activating skills
-      count: 23
+      count: "{{SKILL_COUNT}}"
       pattern: "<skill>/SKILL.md"
 
   scripts:
@@ -67,10 +67,10 @@ relationships:
 
   - name: content_structure
     locations:
-      - "commands/ - 41 .md files"
-      - "agents/ - 26 .md files"
-      - "experts/ - 25 directories"
-      - "skills/ - 23 directories"
+      - "commands/ - {{COMMAND_COUNT}} .md files"
+      - "agents/ - {{AGENT_COUNT}} .md files"
+      - "experts/ - {{SKILL_COUNT}} directories"
+      - "skills/ - {{SKILL_COUNT}} directories"
     observation: "Consistent patterns across all content types"
 
 patterns:
@@ -78,9 +78,14 @@ patterns:
     description: "Placeholders replaced at install time"
     location: "lib/content-injector.js"
     placeholders:
-      - "<!-- {{AGENT_LIST}} -->"
-      - "<!-- {{COMMAND_LIST}} -->"
-    benefit: "Zero maintenance for lists"
+      - "{{COMMAND_COUNT}} - Number of commands"
+      - "{{AGENT_COUNT}} - Number of agents"
+      - "{{SKILL_COUNT}} - Number of skills"
+      - "{{VERSION}} - AgileFlow version"
+      - "{{INSTALL_DATE}} - Installation date"
+      - "<!-- {{AGENT_LIST}} --> - Full agent list"
+      - "<!-- {{COMMAND_LIST}} --> - Full command list"
+    benefit: "Zero maintenance for lists and counts"
 
   - name: IDE-Specific Installers
     description: "Separate installer per IDE"
@@ -116,7 +121,7 @@ learnings:
 
   - date: 2025-12-21
     context: "Analyzed content structure"
-    insight: "Consistent patterns: 41 commands, 26 agents, 25 experts, 23 skills - all use frontmatter markdown"
+    insight: "Consistent patterns: {{COMMAND_COUNT}} commands, {{AGENT_COUNT}} agents, {{SKILL_COUNT}} experts, {{SKILL_COUNT}} skills - all use frontmatter markdown"
     source: "packages/cli/src/core/"
 
   - date: 2025-12-21

package/src/core/templates/claude-settings.advanced.example.json

@@ -6,7 +6,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "echo '🚀 AgileFlow v2.19.0 loaded - Type /agileflow:help for commands'"
+            "command": "echo '🚀 AgileFlow v{{VERSION}} loaded - Type /agileflow:help for commands'"
           },
           {
             "type": "command",

package/src/core/templates/claude-settings.example.json

@@ -6,7 +6,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "echo '🚀 AgileFlow v2.19.0 loaded - Use /agileflow:help to see available commands'"
+            "command": "echo '🚀 AgileFlow v{{VERSION}} loaded - Use /agileflow:help to see available commands'"
           }
         ]
       },

package/tools/cli/commands/list.js

@@ -10,6 +10,7 @@ const fs = require('fs-extra');
 const yaml = require('js-yaml');
 const { Installer } = require('../installers/core/installer');
 const { displayLogo, displaySection, success, warning, info } = require('../lib/ui');
+const { parseFrontmatter: parseYamlFrontmatter } = require('../../../scripts/lib/frontmatter-parser');
 
 const installer = new Installer();
 
@@ -255,23 +256,17 @@ async function listExperts(agileflowPath) {
 }
 
 /**
- * Parse YAML frontmatter from markdown
+ * Parse YAML frontmatter from markdown (wrapper for shared parser)
  * @param {string} content - File content
  * @returns {{ frontmatter: Object|null, content: string }}
  */
 function parseFrontmatter(content) {
-  const match = content.match(/^---\n([\s\S]*?)\n---\n?([\s\S]*)$/);
-
-  if (!match) {
-    return { frontmatter: null, content };
-  }
-
-  try {
-    const frontmatter = yaml.load(match[1]);
-    return { frontmatter, content: match[2] };
-  } catch {
-    return { frontmatter: null, content };
-  }
+  const frontmatter = parseYamlFrontmatter(content);
+  const body = content.replace(/^---\n[\s\S]*?\n---\n?/, '');
+  return {
+    frontmatter: Object.keys(frontmatter).length > 0 ? frontmatter : null,
+    content: body,
+  };
 }
 
 /**

package/tools/cli/commands/uninstall.js

@@ -19,6 +19,7 @@ module.exports = {
   description: 'Remove AgileFlow from a project',
   options: [
     ['-d, --directory <path>', 'Project directory (default: current directory)'],
+    ['--ide <name>', 'Remove only a specific IDE (e.g., windsurf, cursor)'],
     ['--force', 'Skip confirmation prompt'],
   ],
   action: async options => {
@@ -35,6 +36,68 @@ module.exports = {
         process.exit(0);
       }
 
+      // Check if removing just one IDE
+      if (options.ide) {
+        const ideName = options.ide.toLowerCase();
+        displaySection('Removing IDE Configuration', `IDE: ${formatIdeName(ideName)}`);
+
+        if (!status.ides || !status.ides.includes(ideName)) {
+          warning(`${formatIdeName(ideName)} is not configured in this installation`);
+          console.log(chalk.dim(`Configured IDEs: ${(status.ides || []).join(', ') || 'none'}\n`));
+          process.exit(0);
+        }
+
+        // Confirm removal
+        if (!options.force) {
+          const proceed = await confirm(
+            `Remove ${formatIdeName(ideName)} configuration?`,
+            false
+          );
+          if (!proceed) {
+            console.log(chalk.dim('\nCancelled\n'));
+            process.exit(0);
+          }
+        }
+
+        console.log();
+
+        // Remove the IDE configuration
+        const configPath = getIdeConfigPath(directory, ideName);
+        if (await fs.pathExists(configPath)) {
+          await fs.remove(configPath);
+          success(`Removed ${formatIdeName(ideName)} configuration`);
+        }
+
+        // Also remove spawnable agents for claude-code
+        if (ideName === 'claude-code') {
+          const agentsPath = path.join(directory, '.claude', 'agents', 'agileflow');
+          if (await fs.pathExists(agentsPath)) {
+            await fs.remove(agentsPath);
+            success('Removed spawnable agents');
+          }
+        }
+
+        // Update the manifest to remove this IDE
+        const manifestPath = path.join(status.path, '_cfg', 'manifest.yaml');
+        if (await fs.pathExists(manifestPath)) {
+          const yaml = require('js-yaml');
+          const manifestContent = await fs.readFile(manifestPath, 'utf8');
+          const manifest = yaml.load(manifestContent);
+          manifest.ides = (manifest.ides || []).filter(ide => ide !== ideName);
+          manifest.updated_at = new Date().toISOString();
+          await fs.writeFile(manifestPath, yaml.dump(manifest), 'utf8');
+          success('Updated manifest');
+        }
+
+        console.log(chalk.green(`\n${formatIdeName(ideName)} has been removed.\n`));
+        if (status.ides.length > 1) {
+          console.log(chalk.dim(`Remaining IDEs: ${status.ides.filter(i => i !== ideName).join(', ')}\n`));
+        }
+
+        process.exit(0);
+      }
+
+      // Full uninstall
       displaySection('Uninstalling AgileFlow', `Location: ${status.path}`);
 
       // Confirm uninstall
@@ -56,6 +119,13 @@ module.exports = {
             await fs.remove(configPath);
             success(`Removed ${formatIdeName(ide)} configuration`);
           }
+          // Also remove spawnable agents for claude-code
+          if (ide === 'claude-code') {
+            const agentsPath = path.join(directory, '.claude', 'agents', 'agileflow');
+            if (await fs.pathExists(agentsPath)) {
+              await fs.remove(agentsPath);
+            }
+          }
         }
       }
 

package/tools/cli/commands/update.js

@@ -32,6 +32,7 @@ module.exports = {
   options: [
     ['-d, --directory <path>', 'Project directory (default: current directory)'],
     ['--force', 'Force reinstall (skip prompts; overwrites local changes)'],
+    ['--ides <list>', 'Comma-separated list of IDEs to update (overrides manifest)'],
     ['--no-self-update', 'Skip automatic CLI self-update check'],
     ['--self-updated', 'Internal flag: indicates CLI was already self-updated'],
   ],
@@ -56,6 +57,7 @@ module.exports = {
         const args = ['agileflow@latest', 'update', '--self-updated'];
         if (options.directory) args.push('-d', options.directory);
         if (options.force) args.push('--force');
+        if (options.ides) args.push('--ides', options.ides);
 
         const result = spawnSync('npx', args, {
           stdio: 'inherit',
@@ -88,10 +90,10 @@ module.exports = {
 
       const latestVersion = npmLatestVersion || localCliVersion;
 
-      console.log(chalk.bold('Installed:   '), status.version);
-      console.log(chalk.bold('CLI version: '), localCliVersion);
+      console.log(chalk.bold('Currently installed:'), status.version);
+      console.log(chalk.bold('CLI version:        '), localCliVersion);
       if (npmLatestVersion) {
-        console.log(chalk.bold('Latest (npm):'), npmLatestVersion);
+        console.log(chalk.bold('Latest (npm):       '), npmLatestVersion);
       }
 
       // If we self-updated, show confirmation
@@ -136,10 +138,25 @@ module.exports = {
       // Get docs folder name from metadata (or default to 'docs')
       const docsFolder = await getDocsFolderName(directory);
 
+      // Determine which IDEs to update
+      let idesToUpdate;
+      if (options.ides) {
+        // User explicitly specified IDEs via --ides flag
+        idesToUpdate = options.ides.split(',').map(ide => ide.trim().toLowerCase());
+        console.log(chalk.dim(`Updating specified IDEs: ${idesToUpdate.join(', ')}`));
+      } else {
+        // Use IDEs from manifest
+        idesToUpdate = status.ides || ['claude-code'];
+        if (idesToUpdate.length > 1) {
+          console.log(chalk.dim(`IDEs to update (from manifest): ${idesToUpdate.join(', ')}`));
+          console.log(chalk.dim(`  Tip: Use --ides=claude-code to update only specific IDEs\n`));
+        }
+      }
+
       // Re-run installation with existing config from manifest
       const config = {
         directory,
-        ides: status.ides || ['claude-code'],
+        ides: idesToUpdate,
         userName: status.userName || 'Developer',
         agileflowFolder: status.agileflowFolder || path.basename(status.path),
         docsFolder: status.docsFolder || docsFolder,

package/tools/cli/installers/core/installer.js

@@ -5,26 +5,15 @@
  */
 
 const path = require('node:path');
-const crypto = require('node:crypto');
 const fs = require('fs-extra');
 const chalk = require('chalk');
 const ora = require('ora');
 const yaml = require('js-yaml');
+const { injectContent } = require('../../lib/content-injector');
+const { sha256Hex, toPosixPath, safeTimestampForPath } = require('../../lib/utils');
 
 const TEXT_EXTENSIONS = new Set(['.md', '.yaml', '.yml', '.txt', '.json']);
 
-function sha256Hex(data) {
-  return crypto.createHash('sha256').update(data).digest('hex');
-}
-
-function toPosixPath(filePath) {
-  return filePath.split(path.sep).join('/');
-}
-
-function safeTimestampForPath(date = new Date()) {
-  return date.toISOString().replace(/[:.]/g, '-');
-}
-
 /**
  * Get the source path for AgileFlow content
  * @returns {string} Path to src directory
@@ -48,6 +37,11 @@ class Installer {
   constructor() {
     this.sourcePath = getSourcePath();
     this.packageRoot = getPackageRoot();
+    this.coreDir = path.join(this.sourcePath, 'core');
+
+    // Load version from package.json
+    const packageJson = require(path.join(this.packageRoot, 'package.json'));
+    this.version = packageJson.version;
   }
 
   /**
@@ -260,7 +254,7 @@ class Installer {
   }
 
   /**
-   * Copy a file with placeholder replacements
+   * Copy a file with placeholder replacements using content injector
    * @param {string} source - Source file path
    * @param {string} dest - Destination file path
    * @param {string} agileflowFolder - AgileFlow folder name
@@ -271,9 +265,12 @@ class Installer {
     if (TEXT_EXTENSIONS.has(ext)) {
       let content = await fs.readFile(source, 'utf8');
 
-      // Replace placeholders
-      content = content.replace(/\{agileflow_folder\}/g, agileflowFolder);
-      content = content.replace(/\{project-root\}/g, '{project-root}'); // Keep as-is for runtime
+      // Use content injector for all placeholder replacements
+      content = injectContent(content, {
+        coreDir: this.coreDir,
+        agileflowFolder,
+        version: this.version,
+      });
 
       await fs.writeFile(dest, content, 'utf8');
     } else {
@@ -304,8 +301,12 @@ class Installer {
     let newContent;
     if (isText) {
       let content = await fs.readFile(source, 'utf8');
-      content = content.replace(/\{agileflow_folder\}/g, agileflowFolder);
-      content = content.replace(/\{project-root\}/g, '{project-root}');
+      // Use content injector for all placeholder replacements
+      content = injectContent(content, {
+        coreDir: this.coreDir,
+        agileflowFolder,
+        version: this.version,
+      });
       newContent = content;
     } else {
       newContent = await fs.readFile(source);

package/tools/cli/installers/ide/_base-ide.js

@@ -68,11 +68,25 @@ class BaseIdeSetup {
   injectDynamicContent(content, agileflowDir) {
     const { injectContent } = require('../../lib/content-injector');
     // agileflowDir is the user's .agileflow installation directory
-    // which has agents/ and commands/ at the root level (not src/core/)
-    const agentsDir = path.join(agileflowDir, 'agents');
-    const commandsDir = path.join(agileflowDir, 'commands');
+    // which has agents/, commands/, skills/ at the root level
+    return injectContent(content, {
+      coreDir: agileflowDir,
+      agileflowFolder: this.agileflowFolder,
+      version: this.getVersion(),
+    });
+  }
 
-    return injectContent(content, agentsDir, commandsDir);
+  /**
+   * Get the current AgileFlow version
+   * @returns {string} Version string
+   */
+  getVersion() {
+    try {
+      const packageJson = require('../../../../package.json');
+      return packageJson.version || 'unknown';
+    } catch {
+      return 'unknown';
+    }
   }
 
   /**