agileflow 2.61.0 → 2.62.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/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';
+    }
   }
 
   /**

package/tools/cli/installers/ide/claude-code.js

@@ -63,22 +63,11 @@ class ClaudeCodeSetup extends BaseIdeSetup {
     await this.installCommandsRecursive(agentsSource, spawnableAgentsDir, agileflowDir, false);
     console.log(chalk.dim(`    - Spawnable agents: .claude/agents/agileflow/`));
 
-    // Install skills (.claude/skills/)
-    const skillsSource = path.join(agileflowDir, 'skills');
+    // Create skills directory for user-generated skills (.claude/skills/)
+    // AgileFlow no longer ships static skills - users generate them via /agileflow:skill:create
     const skillsTargetDir = path.join(claudeDir, 'skills');
-    let skillCount = 0;
-    if (await this.exists(skillsSource)) {
-      const skillResult = await this.installCommandsRecursive(
-        skillsSource,
-        skillsTargetDir,
-        agileflowDir,
-        false
-      );
-      skillCount = skillResult.commands + skillResult.subdirs;
-      if (skillCount > 0) {
-        console.log(chalk.dim(`    - Skills: .claude/skills/`));
-      }
-    }
+    await this.ensureDir(skillsTargetDir);
+    console.log(chalk.dim(`    - Skills directory: .claude/skills/ (for user-generated skills)`));
 
     const totalCommands = commandResult.commands + agentResult.commands;
     const totalSubdirs =

package/tools/cli/installers/ide/codex.js

@@ -16,6 +16,7 @@ const fs = require('fs-extra');
 const chalk = require('chalk');
 const yaml = require('js-yaml');
 const { BaseIdeSetup } = require('./_base-ide');
+const { parseFrontmatter } = require('../../../../scripts/lib/frontmatter-parser');
 
 /**
  * OpenAI Codex CLI setup handler
@@ -59,22 +60,17 @@ class CodexSetup extends BaseIdeSetup {
    * @returns {string} Codex SKILL.md content
    */
   convertAgentToSkill(content, agentName) {
-    // Extract frontmatter if present
+    // Extract frontmatter using shared parser
     let description = `AgileFlow ${agentName} agent`;
     let model = 'default';
 
-    const frontmatterMatch = content.match(/^---\n([\s\S]*?)\n---/);
-    if (frontmatterMatch) {
-      try {
-        const frontmatter = yaml.load(frontmatterMatch[1]);
-        if (frontmatter.description) {
-          description = frontmatter.description;
-        }
-        if (frontmatter.model) {
-          model = frontmatter.model;
-        }
-      } catch (e) {
-        // Ignore YAML parse errors
+    const frontmatter = parseFrontmatter(content);
+    if (frontmatter && Object.keys(frontmatter).length > 0) {
+      if (frontmatter.description) {
+        description = frontmatter.description;
+      }
+      if (frontmatter.model) {
+        model = frontmatter.model;
       }
     }