agileflow 2.60.0 → 2.62.0

package/tools/cli/lib/content-injector.js

@@ -1,13 +1,36 @@
 /**
- * Content Injector - Dynamic content injection for command files
+ * Content Injector - Dynamic content injection for AgileFlow files
  *
- * Generates agent lists and command lists from source directories
- * and injects them into command files during installation.
+ * Supports template variables that get replaced at install time:
+ *
+ * COUNTS:
+ *   {{COMMAND_COUNT}}  - Total number of commands
+ *   {{AGENT_COUNT}}    - Total number of agents
+ *   {{SKILL_COUNT}}    - Total number of skills
+ *
+ * LISTS:
+ *   <!-- {{AGENT_LIST}} -->   - Full formatted agent list
+ *   <!-- {{COMMAND_LIST}} --> - Full formatted command list
+ *
+ * METADATA:
+ *   {{VERSION}}        - AgileFlow version from package.json
+ *   {{INSTALL_DATE}}   - Date of installation (YYYY-MM-DD)
+ *
+ * FOLDER REFERENCES:
+ *   {agileflow_folder} - Name of the agileflow folder (e.g., .agileflow)
+ *   {project-root}     - Project root reference
  */
 
 const fs = require('fs');
 const path = require('path');
+
+// Use shared modules
 const { parseFrontmatter, normalizeTools } = require('../../../scripts/lib/frontmatter-parser');
+const { countCommands, countAgents, countSkills, getCounts } = require('../../../scripts/lib/counter');
+
+// =============================================================================
+// List Generation Functions
+// =============================================================================
 
 /**
  * Scan agents directory and generate formatted agent list
@@ -15,17 +38,16 @@ const { parseFrontmatter, normalizeTools } = require('../../../scripts/lib/front
  * @returns {string} Formatted agent list
  */
 function generateAgentList(agentsDir) {
+  if (!fs.existsSync(agentsDir)) return '';
+
   const files = fs.readdirSync(agentsDir).filter(f => f.endsWith('.md'));
   const agents = [];
 
   for (const file of files) {
     const filePath = path.join(agentsDir, file);
     const content = fs.readFileSync(filePath, 'utf8');
-
-    // Parse frontmatter using shared parser
     const frontmatter = parseFrontmatter(content);
 
-    // Skip if no frontmatter found
     if (!frontmatter || Object.keys(frontmatter).length === 0) {
       continue;
     }
@@ -38,17 +60,15 @@ function generateAgentList(agentsDir) {
     });
   }
 
-  // Sort alphabetically by name
   agents.sort((a, b) => a.name.localeCompare(b.name));
 
-  // Generate formatted output
   let output = `**AVAILABLE AGENTS (${agents.length} total)**:\n\n`;
 
   agents.forEach((agent, index) => {
     output += `${index + 1}. **${agent.name}** (model: ${agent.model})\n`;
     output += `   - **Purpose**: ${agent.description}\n`;
     output += `   - **Tools**: ${agent.tools.join(', ')}\n`;
-    output += `   - **Usage**: \`subagent_type: "AgileFlow:${agent.name}"\`\n`;
+    output += `   - **Usage**: \`subagent_type: "agileflow-${agent.name}"\`\n`;
     output += `\n`;
   });
 
@@ -61,18 +81,18 @@ function generateAgentList(agentsDir) {
  * @returns {string} Formatted command list
  */
 function generateCommandList(commandsDir) {
-  const files = fs.readdirSync(commandsDir).filter(f => f.endsWith('.md'));
+  if (!fs.existsSync(commandsDir)) return '';
+
   const commands = [];
 
-  for (const file of files) {
+  // Scan main commands
+  const mainFiles = fs.readdirSync(commandsDir).filter(f => f.endsWith('.md'));
+  for (const file of mainFiles) {
     const filePath = path.join(commandsDir, file);
     const content = fs.readFileSync(filePath, 'utf8');
-
-    // Parse frontmatter using shared parser
     const frontmatter = parseFrontmatter(content);
     const cmdName = path.basename(file, '.md');
 
-    // Skip if no frontmatter found
     if (!frontmatter || Object.keys(frontmatter).length === 0) {
       continue;
     }
@@ -84,10 +104,34 @@ function generateCommandList(commandsDir) {
     });
   }
 
-  // Sort alphabetically by name
+  // Scan subdirectories (e.g., session/)
+  const entries = fs.readdirSync(commandsDir, { withFileTypes: true });
+  for (const entry of entries) {
+    if (entry.isDirectory()) {
+      const subDir = path.join(commandsDir, entry.name);
+      const subFiles = fs.readdirSync(subDir).filter(f => f.endsWith('.md'));
+
+      for (const file of subFiles) {
+        const filePath = path.join(subDir, file);
+        const content = fs.readFileSync(filePath, 'utf8');
+        const frontmatter = parseFrontmatter(content);
+        const cmdName = `${entry.name}:${path.basename(file, '.md')}`;
+
+        if (!frontmatter || Object.keys(frontmatter).length === 0) {
+          continue;
+        }
+
+        commands.push({
+          name: cmdName,
+          description: frontmatter.description || '',
+          argumentHint: frontmatter['argument-hint'] || '',
+        });
+      }
+    }
+  }
+
   commands.sort((a, b) => a.name.localeCompare(b.name));
 
-  // Generate formatted output
   let output = `Available commands (${commands.length} total):\n`;
 
   commands.forEach(cmd => {
@@ -98,33 +142,120 @@ function generateCommandList(commandsDir) {
   return output;
 }
 
+// =============================================================================
+// Main Injection Function
+// =============================================================================
+
 /**
- * Inject dynamic content into a template file
- * @param {string} templateContent - Template file content with placeholders
- * @param {string} agentsDir - Path to agents directory
- * @param {string} commandsDir - Path to commands directory
- * @returns {string} Content with placeholders replaced
+ * Inject all template variables into content
+ * @param {string} content - Template content with placeholders
+ * @param {Object} context - Context for replacements
+ * @param {string} context.coreDir - Path to core directory (commands/, agents/, skills/)
+ * @param {string} context.agileflowFolder - AgileFlow folder name
+ * @param {string} context.version - AgileFlow version
+ * @returns {string} Content with all placeholders replaced
  */
-function injectContent(templateContent, agentsDir, commandsDir) {
-  let result = templateContent;
+function injectContent(content, context = {}) {
+  const { coreDir, agileflowFolder = '.agileflow', version = 'unknown' } = context;
+
+  let result = content;
 
-  // Replace {{AGENT_LIST}} placeholder
-  if (result.includes('{{AGENT_LIST}}')) {
-    const agentList = generateAgentList(agentsDir);
-    result = result.replace(/<!-- {{AGENT_LIST}} -->/g, agentList);
+  // Get counts if core directory is available
+  let counts = { commands: 0, agents: 0, skills: 0 };
+  if (coreDir && fs.existsSync(coreDir)) {
+    counts = getCounts(coreDir);
   }
 
-  // Replace {{COMMAND_LIST}} placeholder
-  if (result.includes('{{COMMAND_LIST}}')) {
-    const commandList = generateCommandList(commandsDir);
-    result = result.replace(/<!-- {{COMMAND_LIST}} -->/g, commandList);
+  // Replace count placeholders (both formats: {{X}} and <!-- {{X}} -->)
+  result = result.replace(/\{\{COMMAND_COUNT\}\}/g, String(counts.commands));
+  result = result.replace(/\{\{AGENT_COUNT\}\}/g, String(counts.agents));
+  result = result.replace(/\{\{SKILL_COUNT\}\}/g, String(counts.skills));
+
+  // Replace metadata placeholders
+  result = result.replace(/\{\{VERSION\}\}/g, version);
+  result = result.replace(/\{\{INSTALL_DATE\}\}/g, new Date().toISOString().split('T')[0]);
+
+  // Replace list placeholders (only if core directory available)
+  if (coreDir && fs.existsSync(coreDir)) {
+    if (result.includes('{{AGENT_LIST}}')) {
+      const agentList = generateAgentList(path.join(coreDir, 'agents'));
+      result = result.replace(/<!-- \{\{AGENT_LIST\}\} -->/g, agentList);
+      result = result.replace(/\{\{AGENT_LIST\}\}/g, agentList);
+    }
+
+    if (result.includes('{{COMMAND_LIST}}')) {
+      const commandList = generateCommandList(path.join(coreDir, 'commands'));
+      result = result.replace(/<!-- \{\{COMMAND_LIST\}\} -->/g, commandList);
+      result = result.replace(/\{\{COMMAND_LIST\}\}/g, commandList);
+    }
   }
 
+  // Replace folder placeholders
+  result = result.replace(/\{agileflow_folder\}/g, agileflowFolder);
+  result = result.replace(/\{project-root\}/g, '{project-root}'); // Keep as-is for runtime
+
   return result;
 }
 
+/**
+ * Check if content has any template variables
+ * @param {string} content - Content to check
+ * @returns {boolean} True if content has placeholders
+ */
+function hasPlaceholders(content) {
+  const patterns = [
+    /\{\{COMMAND_COUNT\}\}/,
+    /\{\{AGENT_COUNT\}\}/,
+    /\{\{SKILL_COUNT\}\}/,
+    /\{\{VERSION\}\}/,
+    /\{\{INSTALL_DATE\}\}/,
+    /\{\{AGENT_LIST\}\}/,
+    /\{\{COMMAND_LIST\}\}/,
+    /\{agileflow_folder\}/,
+  ];
+
+  return patterns.some(pattern => pattern.test(content));
+}
+
+/**
+ * List all supported placeholders
+ * @returns {Object} Placeholder documentation
+ */
+function getPlaceholderDocs() {
+  return {
+    counts: {
+      '{{COMMAND_COUNT}}': 'Total number of slash commands',
+      '{{AGENT_COUNT}}': 'Total number of specialized agents',
+      '{{SKILL_COUNT}}': 'Total number of skills',
+    },
+    lists: {
+      '<!-- {{AGENT_LIST}} -->': 'Full formatted agent list with details',
+      '<!-- {{COMMAND_LIST}} -->': 'Full formatted command list',
+    },
+    metadata: {
+      '{{VERSION}}': 'AgileFlow version from package.json',
+      '{{INSTALL_DATE}}': 'Installation date (YYYY-MM-DD)',
+    },
+    folders: {
+      '{agileflow_folder}': 'Name of the AgileFlow folder',
+      '{project-root}': 'Project root reference (kept as-is)',
+    },
+  };
+}
+
 module.exports = {
+  // Count functions
+  countCommands,
+  countAgents,
+  countSkills,
+  getCounts,
+
+  // List generation
   generateAgentList,
   generateCommandList,
+
+  // Main injection
   injectContent,
+  hasPlaceholders,
+  getPlaceholderDocs,
 };

package/tools/cli/lib/utils.js

@@ -0,0 +1,87 @@
+/**
+ * Shared Utilities Module
+ *
+ * Common utility functions used across the CLI.
+ * Consolidates duplicated code from installer.js, doctor.js, etc.
+ */
+
+const crypto = require('crypto');
+const path = require('path');
+
+/**
+ * Calculate SHA256 hash of data and return as hex string
+ * @param {string|Buffer} data - Data to hash
+ * @returns {string} Hex-encoded SHA256 hash
+ */
+function sha256Hex(data) {
+  return crypto.createHash('sha256').update(data).digest('hex');
+}
+
+/**
+ * Convert a file path to POSIX format (forward slashes)
+ * @param {string} filePath - Path to convert
+ * @returns {string} POSIX-style path
+ */
+function toPosixPath(filePath) {
+  return filePath.split(path.sep).join('/');
+}
+
+/**
+ * Generate a safe timestamp string for use in file/folder names
+ * @param {Date} date - Date to format (defaults to now)
+ * @returns {string} Timestamp like "2025-12-27T10-30-45-123Z"
+ */
+function safeTimestampForPath(date = new Date()) {
+  return date.toISOString().replace(/[:.]/g, '-');
+}
+
+/**
+ * Compare two semantic version strings
+ * @param {string} v1 - First version (e.g., "2.61.0")
+ * @param {string} v2 - Second version (e.g., "2.60.0")
+ * @returns {number} -1 if v1 < v2, 0 if equal, 1 if v1 > v2
+ */
+function compareVersions(v1, v2) {
+  const parts1 = v1.replace(/^v/, '').split('.').map(Number);
+  const parts2 = v2.replace(/^v/, '').split('.').map(Number);
+
+  for (let i = 0; i < Math.max(parts1.length, parts2.length); i++) {
+    const p1 = parts1[i] || 0;
+    const p2 = parts2[i] || 0;
+    if (p1 < p2) return -1;
+    if (p1 > p2) return 1;
+  }
+  return 0;
+}
+
+/**
+ * Create a debug logger function
+ * @param {boolean} enabled - Whether debug logging is enabled
+ * @param {string} prefix - Optional prefix for log messages
+ * @returns {Function} Debug log function
+ */
+function createDebugLogger(enabled, prefix = '') {
+  return (...args) => {
+    if (enabled) {
+      if (prefix) {
+        console.log(`[${prefix}]`, ...args);
+      } else {
+        console.log(...args);
+      }
+    }
+  };
+}
+
+/**
+ * Brand color for AgileFlow (burnt orange/terracotta)
+ */
+const BRAND_COLOR = '#e8683a';
+
+module.exports = {
+  sha256Hex,
+  toPosixPath,
+  safeTimestampForPath,
+  compareVersions,
+  createDebugLogger,
+  BRAND_COLOR,
+};

package/src/core/skills/acceptance-criteria-generator/SKILL.md

@@ -1,46 +0,0 @@
----
-name: acceptance-criteria-generator
-description: Generate properly-formatted Given/When/Then acceptance criteria for user stories
----
-
-# acceptance-criteria-generator
-
-Generate properly-formatted Given/When/Then acceptance criteria.
-
-## Activation Keywords
-- "AC", "acceptance criteria", "Given When Then", "given when then", "acceptance", "criteria"
-
-## When to Use
-- User is writing acceptance criteria
-- Need to format AC in proper Given/When/Then structure
-- Ensuring clarity and testability of requirements
-
-## What This Does
-Takes user's plain English requirements and converts to structured Given/When/Then format:
-- **Given**: Initial state/preconditions
-- **When**: User action or trigger
-- **Then**: Expected outcome/result
-
-Generates multiple AC items if needed (typically 2-5 per story).
-
-Ensures each criterion is:
-- Testable (not vague)
-- Independent (doesn't depend on other AC)
-- Clear (unambiguous language)
-- Measurable (has a clear success/failure)
-
-## Output
-Well-formatted acceptance criteria ready to add to story.
-
-## Example Activation
-User: "User should be able to log in with email and password, and receive a JWT token"
-Skill: Generates:
-```
-- **Given** a registered user with valid email and password
-  **When** user POSTs to /api/auth/login with credentials
-  **Then** they receive a 200 response with JWT token (24h expiration)
-
-- **Given** a user enters wrong password
-  **When** they attempt login
-  **Then** they receive 401 Unauthorized and rate limit applied
-```

package/src/core/skills/adr-template/SKILL.md

@@ -1,62 +0,0 @@
----
-name: adr-template
-description: Generate Architecture Decision Record structure with context/decision/consequences
----
-
-# adr-template
-
-Generate Architecture Decision Record structure with context/decision/consequences.
-
-## Activation Keywords
-- "ADR", "architecture decision", "decision record", "adr template"
-
-## When to Use
-- Major architectural decisions made during implementation
-- Documenting why a technology/pattern was chosen
-- Recording decision trade-offs and alternatives considered
-
-## What This Does
-Generates complete ADR structure with:
-- **Title**: Clear, concise decision title
-- **Status**: Proposed, Accepted, Deprecated, Superseded
-- **Context**: Why this decision was needed, what problem does it solve
-- **Decision**: What was decided and why
-- **Consequences**: Positive outcomes and risks introduced
-- **Alternatives**: Other options considered and why rejected
-- **Related Stories**: Links to affected user stories
-
-Includes proper YAML frontmatter for integration with status.json.
-
-## Output
-Ready-to-use ADR file in docs/03-decisions/adr-XXXX.md format
-
-## Example Activation
-User: "We decided to use JWT for authentication instead of sessions"
-Skill: Generates:
-```
----
-adr_id: ADR-0042
-title: Use JWT for stateless authentication
-status: accepted
-date: 2025-10-28
----
-
-## Context
-Application needs scalable authentication across microservices.
-Session-based auth requires shared state/cache.
-
-## Decision
-Adopt JWT (JSON Web Tokens) for stateless authentication.
-
-## Consequences
-✅ Benefits: Scalable, distributed, microservice-friendly
-❌ Risks: Token revocation requires blacklist, larger payload
-
-## Alternatives Considered
-1. Session + Redis: Requires shared state
-2. OAuth2: Overkill for internal auth
-
-## Related Stories
-- US-0001: User Login API
-- US-0002: Password Reset
-```

package/src/core/skills/agileflow-acceptance-criteria/SKILL.md

@@ -1,156 +0,0 @@
----
-name: agileflow-acceptance-criteria
-description: Generates detailed Given/When/Then acceptance criteria when user describes feature behavior or requirements. Enhances user stories with testable scenarios.
----
-
-# AgileFlow Acceptance Criteria
-
-Automatically generates detailed, testable acceptance criteria in Given/When/Then (Gherkin) format from feature discussions and requirements.
-
-## When to Use
-
-This skill activates when:
-- User describes how a feature should behave
-- Discussing user workflows or interactions
-- Keywords: "acceptance criteria", "test scenarios", "should work like"
-- Creating or reviewing user stories
-- User describes "when user does X, then Y should happen"
-
-## What This Does
-
-1. Extracts feature behavior from user discussions
-2. Identifies different scenarios (happy path, errors, edge cases)
-3. Generates criteria in Given/When/Then format
-4. Ensures criteria are specific, testable, and independent
-5. Enhances story's AC section
-
-## Instructions
-
-1. **Listen for behavior descriptions**: User explains "when X happens, Y should occur"
-
-2. **Extract scenarios**:
-   - Happy path (normal use)
-   - Error cases (what goes wrong)
-   - Edge cases (boundary conditions)
-   - Permission-based scenarios
-
-3. **Generate criteria**:
-   - One AC per distinct scenario
-   - Clear, unambiguous language
-   - Make it testable (observable outcome)
-   - Include edge cases
-
-4. **Add to story**: If working on a story, enhance its AC section
-
-## Given/When/Then Format
-
-```markdown
-### AC#: [Criterion Name]
-**Given** [initial context or precondition]
-**When** [user action or trigger event]
-**Then** [expected outcome or system behavior]
-```
-
-**Given** (Precondition):
-- User's current state, system state, data that exists, permissions/roles
-- Example: "Given I am logged in as an admin"
-
-**When** (Action):
-- What the user does, event that occurs, API call made
-- Example: "When I click the 'Add to Cart' button"
-
-**Then** (Outcome):
-- What the user sees, system state changes, data modifications, error messages
-- Example: "Then the item is added to my cart"
-
-## Common Patterns
-
-**Happy Path**:
-```markdown
-### AC1: Successful Login
-**Given** I am on the login page
-**When** I enter valid credentials and click "Login"
-**Then** I am redirected to my dashboard
-**And** I see a welcome message with my name
-```
-
-**Error Handling**:
-```markdown
-### AC2: Invalid Password
-**Given** I am on the login page
-**When** I enter a valid email but incorrect password
-**Then** I see an error message "Invalid credentials"
-**And** I remain on the login page
-```
-
-**Edge Cases**:
-```markdown
-### AC3: Account Locked After Failed Attempts
-**Given** I have failed to login 4 times
-**When** I attempt to login with incorrect password again
-**Then** my account is locked for 30 minutes
-**And** an email is sent to my registered address
-```
-
-**Permission-Based**:
-```markdown
-### AC4: Admin-Only Feature Access
-**Given** I am logged in as a regular user
-**When** I try to access the admin dashboard
-**Then** I see a 403 Forbidden error
-```
-
-**Form Validation**:
-```markdown
-### AC1: Email Format Validation
-**Given** I am filling out the registration form
-**When** I enter an invalid email format (missing @)
-**Then** I see an error "Please enter a valid email address"
-**And** the submit button remains disabled
-```
-
-## Multiple Conditions
-
-Use **And** for additional conditions:
-```markdown
-**Given** I am logged in
-**And** I have items in my cart
-**When** I click "Checkout"
-**Then** I am redirected to payment page
-**And** I see my cart summary
-```
-
-Use **But** for contrasting outcomes:
-```markdown
-**Given** I am on the search page
-**When** I search for "nonexistent product"
-**Then** I see "No results found" message
-**But** I see suggested categories
-```
-
-## Quality Checklist
-
-Good acceptance criteria are:
-- [ ] **Specific**: Clearly describes one scenario
-- [ ] **Testable**: Can be verified with a test
-- [ ] **Independent**: Doesn't depend on order of execution
-- [ ] **Unambiguous**: Only one interpretation possible
-- [ ] **Complete**: Covers happy path, errors, and edge cases
-- [ ] **User-focused**: Written from user's perspective
-- [ ] **3-7 criteria per story**: Enough coverage, not excessive
-
-## Integration
-
-- **agileflow-story-writer**: Automatically enhances story AC sections
-- **agileflow-sprint-planner**: Helps estimate story complexity from AC count
-- **agileflow-tech-debt**: Identifies missing test coverage from AC
-
-## Notes
-
-- Aim for 3-7 acceptance criteria per story
-- Too few = incomplete requirements
-- Too many = story should be split
-- Cover at least one error case per story
-- Include accessibility criteria when relevant
-- Consider mobile vs desktop differences
-- Think about internationalization if applicable