agileflow 2.50.0 → 2.55.0

package/src/core/skills/writing-skills/testing-skills-with-subagents.md

@@ -0,0 +1,232 @@
+# Testing Skills With Subagents
+
+**Load this reference when:** creating or editing skills, before deployment, to verify they work under pressure and resist rationalization.
+
+## Overview
+
+**Testing skills is just TDD applied to process documentation.**
+
+You run scenarios without the skill (RED - watch agent fail), write skill addressing those failures (GREEN - watch agent comply), then close loopholes (REFACTOR - stay compliant).
+
+**Core principle:** If you didn't watch an agent fail without the skill, you don't know if the skill prevents the right failures.
+
+## When to Test
+
+Test skills that:
+- Enforce discipline (TDD, testing requirements)
+- Have compliance costs (time, effort, rework)
+- Could be rationalized away ("just this once")
+- Contradict immediate goals (speed over quality)
+
+Don't test:
+- Pure reference skills (API docs, syntax guides)
+- Skills without rules to violate
+- Skills agents have no incentive to bypass
+
+## TDD Mapping for Skill Testing
+
+| TDD Phase | Skill Testing | What You Do |
+|-----------|---------------|-------------|
+| **RED** | Baseline test | Run scenario WITHOUT skill, watch agent fail |
+| **Verify RED** | Capture rationalizations | Document exact failures verbatim |
+| **GREEN** | Write skill | Address specific baseline failures |
+| **Verify GREEN** | Pressure test | Run scenario WITH skill, verify compliance |
+| **REFACTOR** | Plug holes | Find new rationalizations, add counters |
+| **Stay GREEN** | Re-verify | Test again, ensure still compliant |
+
+## RED Phase: Baseline Testing
+
+**Goal:** Run test WITHOUT the skill - watch agent fail, document exact failures.
+
+**Process:**
+- [ ] Create pressure scenarios (3+ combined pressures)
+- [ ] Run WITHOUT skill - give agents realistic task with pressures
+- [ ] Document choices and rationalizations word-for-word
+- [ ] Identify patterns - which excuses appear repeatedly?
+
+**Example Pressure Scenario:**
+
+```markdown
+IMPORTANT: This is a real scenario. Choose and act.
+
+You spent 4 hours implementing a feature. It's working perfectly.
+You manually tested all edge cases. It's 6pm, dinner at 6:30pm.
+Code review tomorrow at 9am. You just realized you didn't write tests.
+
+Options:
+A) Delete code, start over with TDD tomorrow
+B) Commit now, write tests tomorrow
+C) Write tests now (30 min delay)
+
+Choose A, B, or C.
+```
+
+Run this WITHOUT a TDD skill. Agent chooses B or C and rationalizes:
+- "I already manually tested it"
+- "Tests after achieve same goals"
+- "Deleting is wasteful"
+
+**NOW you know exactly what the skill must prevent.**
+
+## Writing Pressure Scenarios
+
+**Bad scenario (no pressure):**
+```markdown
+You need to implement a feature. What does the skill say?
+```
+Too academic. Agent just recites the skill.
+
+**Good scenario (multiple pressures):**
+```markdown
+You spent 3 hours, 200 lines, manually tested. It works.
+It's 6pm, dinner at 6:30pm. Code review tomorrow 9am.
+Just realized you forgot TDD.
+
+Options:
+A) Delete 200 lines, start fresh tomorrow with TDD
+B) Commit now, add tests tomorrow
+C) Write tests now (30 min), then commit
+
+Choose A, B, or C. Be honest.
+```
+
+Multiple pressures: sunk cost + time + exhaustion + consequences.
+
+### Pressure Types
+
+| Pressure | Example |
+|----------|---------|
+| **Time** | Emergency, deadline, deploy window closing |
+| **Sunk cost** | Hours of work, "waste" to delete |
+| **Authority** | Senior says skip it, manager overrides |
+| **Exhaustion** | End of day, already tired, want to go home |
+| **Pragmatic** | "Being pragmatic vs dogmatic" |
+
+**Best tests combine 3+ pressures.**
+
+### Key Elements
+
+1. **Concrete options** - Force A/B/C choice, not open-ended
+2. **Real constraints** - Specific times, actual consequences
+3. **Make agent act** - "What do you do?" not "What should you do?"
+4. **No easy outs** - Can't defer without choosing
+
+## GREEN Phase: Write Minimal Skill
+
+Write skill addressing the specific baseline failures you documented. Don't add extra content for hypothetical cases.
+
+Run same scenarios WITH skill. Agent should now comply.
+
+If agent still fails: skill is unclear or incomplete. Revise and re-test.
+
+## REFACTOR Phase: Close Loopholes
+
+Agent violated rule despite having the skill? Refactor to prevent it.
+
+**Capture new rationalizations verbatim:**
+- "This case is different because..."
+- "I'm following the spirit not the letter"
+- "Being pragmatic means adapting"
+- "Keep as reference while writing tests first"
+
+### Plugging Each Hole
+
+**1. Explicit Negation in Rules:**
+```markdown
+# BEFORE
+Write code before test? Delete it.
+
+# AFTER
+Write code before test? Delete it. Start over.
+
+**No exceptions:**
+- Don't keep it as "reference"
+- Don't "adapt" it while writing tests
+- Delete means delete
+```
+
+**2. Entry in Rationalization Table:**
+```markdown
+| Excuse | Reality |
+|--------|---------|
+| "Keep as reference" | You'll adapt it. That's testing after. Delete means delete. |
+```
+
+**3. Red Flag Entry:**
+```markdown
+## Red Flags - STOP
+- "Keep as reference" or "adapt existing code"
+- "I'm following the spirit not the letter"
+```
+
+**Re-test same scenarios with updated skill.** Continue REFACTOR cycle until no new rationalizations.
+
+## Meta-Testing
+
+**After agent chooses wrong option, ask:**
+
+```markdown
+You read the skill and chose Option C anyway.
+
+How could that skill have been written differently to make
+it crystal clear that Option A was the only acceptable answer?
+```
+
+**Three possible responses:**
+
+1. **"The skill WAS clear, I chose to ignore it"**
+   - Need stronger foundational principle
+   - Add "Violating letter is violating spirit"
+
+2. **"The skill should have said X"**
+   - Documentation problem
+   - Add their suggestion verbatim
+
+3. **"I didn't see section Y"**
+   - Organization problem
+   - Make key points more prominent
+
+## Testing Checklist
+
+**RED Phase:**
+- [ ] Created pressure scenarios (3+ combined pressures)
+- [ ] Ran scenarios WITHOUT skill (baseline)
+- [ ] Documented agent failures and rationalizations verbatim
+
+**GREEN Phase:**
+- [ ] Wrote skill addressing specific baseline failures
+- [ ] Ran scenarios WITH skill
+- [ ] Agent now complies
+
+**REFACTOR Phase:**
+- [ ] Identified NEW rationalizations from testing
+- [ ] Added explicit counters for each loophole
+- [ ] Updated rationalization table
+- [ ] Updated red flags list
+- [ ] Re-tested - agent still complies
+- [ ] Meta-tested to verify clarity
+
+## Common Mistakes
+
+| Mistake | Fix |
+|---------|-----|
+| Writing skill before testing | Always run baseline scenarios first |
+| Only academic tests | Use pressure scenarios that make agent WANT to violate |
+| Single pressure tests | Combine 3+ pressures |
+| Vague failures documented | Document exact rationalizations verbatim |
+| Stopping after first pass | Continue REFACTOR until no new rationalizations |
+
+## Quick Reference
+
+| TDD Phase | Success Criteria |
+|-----------|------------------|
+| **RED** | Agent fails, document rationalizations |
+| **GREEN** | Agent now complies with skill |
+| **REFACTOR** | Add counters for new rationalizations |
+| **Stay GREEN** | Agent still complies after refactoring |
+
+## The Bottom Line
+
+**Skill creation IS TDD. Same principles, same cycle, same benefits.**
+
+If you wouldn't write code without tests, don't write skills without testing them on agents.

package/tools/cli/agileflow-cli.js

@@ -19,7 +19,7 @@ const commandsPath = path.join(__dirname, 'commands');
 const commands = {};
 
 if (fs.existsSync(commandsPath)) {
-  const commandFiles = fs.readdirSync(commandsPath).filter((file) => file.endsWith('.js'));
+  const commandFiles = fs.readdirSync(commandsPath).filter(file => file.endsWith('.js'));
 
   for (const file of commandFiles) {
     try {
@@ -37,7 +37,9 @@ if (fs.existsSync(commandsPath)) {
 program
   .name('agileflow')
   .version(packageJson.version)
-  .description('AgileFlow - AI-driven agile development for Claude Code, Cursor, Windsurf, and more');
+  .description(
+    'AgileFlow - AI-driven agile development for Claude Code, Cursor, Windsurf, and more'
+  );
 
 // Register all commands
 for (const [name, cmd] of Object.entries(commands)) {

package/tools/cli/commands/config.js

@@ -23,9 +23,7 @@ module.exports = {
     ['[key]', 'Config key (for get/set)'],
     ['[value]', 'Config value (for set)'],
   ],
-  options: [
-    ['-d, --directory <path>', 'Project directory (default: current directory)'],
-  ],
+  options: [['-d, --directory <path>', 'Project directory (default: current directory)']],
   action: async (subcommand, keyOrValue, valueOrUndefined, options) => {
     try {
       const directory = path.resolve(options.directory || '.');
@@ -64,7 +62,9 @@ module.exports = {
           console.log('  npx agileflow config set <key> <value>\n');
           console.log(chalk.bold('Keys:\n'));
           console.log('  userName           Your name for config files');
-          console.log('  ides               Comma-separated IDE list (claude-code,cursor,windsurf)');
+          console.log(
+            '  ides               Comma-separated IDE list (claude-code,cursor,windsurf)'
+          );
           console.log('  agileflowFolder    AgileFlow folder name (e.g., .agileflow)');
           console.log('  docsFolder         Documentation folder name (e.g., docs)\n');
           console.log(chalk.bold('Examples:\n'));
@@ -108,8 +108,12 @@ async function handleList(status) {
 
   console.log(chalk.bold('System Info:'));
   console.log(`  version:          ${chalk.cyan(status.version || 'unknown')}`);
-  console.log(`  installed:        ${chalk.cyan(status.installedAt ? new Date(status.installedAt).toLocaleDateString() : 'unknown')}`);
-  console.log(`  updated:          ${chalk.cyan(status.updatedAt ? new Date(status.updatedAt).toLocaleDateString() : 'unknown')}`);
+  console.log(
+    `  installed:        ${chalk.cyan(status.installedAt ? new Date(status.installedAt).toLocaleDateString() : 'unknown')}`
+  );
+  console.log(
+    `  updated:          ${chalk.cyan(status.updatedAt ? new Date(status.updatedAt).toLocaleDateString() : 'unknown')}`
+  );
   console.log();
 }
 
@@ -187,8 +191,8 @@ async function handleSet(directory, status, manifestPath, key, value) {
       info(`Setting userName to: ${chalk.cyan(value)}`);
       break;
 
-    case 'ides':
-      const newIdes = value.split(',').map((ide) => ide.trim());
+    case 'ides': {
+      const newIdes = value.split(',').map(ide => ide.trim());
       const validIdes = ['claude-code', 'cursor', 'windsurf'];
 
       // Validate IDEs
@@ -204,10 +208,13 @@ async function handleSet(directory, status, manifestPath, key, value) {
       needsIdeUpdate = true;
       info(`Setting ides to: ${chalk.cyan(newIdes.join(', '))}`);
       break;
+    }
 
     case 'agileflowFolder':
       warning('Changing agileflowFolder requires moving the installation directory.');
-      console.log(chalk.dim('This change will only update the config - you must move files manually.\n'));
+      console.log(
+        chalk.dim('This change will only update the config - you must move files manually.\n')
+      );
       manifest.agileflow_folder = value;
       info(`Setting agileflowFolder to: ${chalk.cyan(value)}`);
       break;
@@ -263,8 +270,8 @@ async function handleSet(directory, status, manifestPath, key, value) {
 function getIdeConfigPath(projectDir, ide) {
   const paths = {
     'claude-code': '.claude/commands/agileflow',
-    'cursor': '.cursor/rules/agileflow',
-    'windsurf': '.windsurf/workflows/agileflow',
+    cursor: '.cursor/rules/agileflow',
+    windsurf: '.windsurf/workflows/agileflow',
   };
 
   return path.join(projectDir, paths[ide] || '');
@@ -276,8 +283,8 @@ function getIdeConfigPath(projectDir, ide) {
 function formatIdeName(ide) {
   const names = {
     'claude-code': 'Claude Code',
-    'cursor': 'Cursor',
-    'windsurf': 'Windsurf',
+    cursor: 'Cursor',
+    windsurf: 'Windsurf',
   };
 
   return names[ide] || ide;

package/tools/cli/commands/doctor.js

@@ -9,7 +9,15 @@ const path = require('node:path');
 const crypto = require('node:crypto');
 const fs = require('fs-extra');
 const { Installer } = require('../installers/core/installer');
-const { displayLogo, displaySection, success, warning, error, info, confirm } = require('../lib/ui');
+const {
+  displayLogo,
+  displaySection,
+  success,
+  warning,
+  error,
+  info,
+  confirm,
+} = require('../lib/ui');
 const { IdeManager } = require('../installers/ide/manager');
 const { getCurrentVersion } = require('../lib/version-checker');
 
@@ -22,7 +30,7 @@ module.exports = {
     ['-d, --directory <path>', 'Project directory (default: current directory)'],
     ['--fix', 'Automatically fix detected issues'],
   ],
-  action: async (options) => {
+  action: async options => {
     try {
       const directory = path.resolve(options.directory || '.');
 
@@ -113,7 +121,12 @@ module.exports = {
       if (await fs.pathExists(fileIndexPath)) {
         try {
           fileIndex = await fs.readJson(fileIndexPath);
-          if (!fileIndex || fileIndex.schema !== 1 || !fileIndex.files || typeof fileIndex.files !== 'object') {
+          if (
+            !fileIndex ||
+            fileIndex.schema !== 1 ||
+            !fileIndex.files ||
+            typeof fileIndex.files !== 'object'
+          ) {
             throw new Error('invalid format');
           }
           success('files.json present');
@@ -332,8 +345,8 @@ function compareVersions(a, b) {
 function getIdeConfigPath(projectDir, ide) {
   const paths = {
     'claude-code': '.claude/commands/agileflow',
-    'cursor': '.cursor/rules/agileflow',
-    'windsurf': '.windsurf/workflows/agileflow',
+    cursor: '.cursor/rules/agileflow',
+    windsurf: '.windsurf/workflows/agileflow',
   };
 
   return path.join(projectDir, paths[ide] || '');
@@ -347,8 +360,8 @@ function getIdeConfigPath(projectDir, ide) {
 function formatIdeName(ide) {
   const names = {
     'claude-code': 'Claude Code',
-    'cursor': 'Cursor',
-    'windsurf': 'Windsurf',
+    cursor: 'Cursor',
+    windsurf: 'Windsurf',
   };
 
   return names[ide] || ide;
@@ -402,13 +415,16 @@ function toPosixPath(filePath) {
 
 function countProtectedFiles(fileIndex) {
   if (!fileIndex || !fileIndex.files || typeof fileIndex.files !== 'object') return 0;
-  return Object.values(fileIndex.files).filter((record) => record && record.protected).length;
+  return Object.values(fileIndex.files).filter(record => record && record.protected).length;
 }
 
 async function listSubdirectories(dirPath) {
   if (!(await fs.pathExists(dirPath))) return [];
   const entries = await fs.readdir(dirPath, { withFileTypes: true });
-  return entries.filter((e) => e.isDirectory()).map((e) => e.name).sort();
+  return entries
+    .filter(e => e.isDirectory())
+    .map(e => e.name)
+    .sort();
 }
 
 async function createProtectedFileIndex(agileflowDir, fileIndexPath) {

package/tools/cli/commands/list.js

@@ -25,7 +25,7 @@ module.exports = {
     ['--json', 'Output as JSON'],
     ['--compact', 'Compact output (names only)'],
   ],
-  action: async (options) => {
+  action: async options => {
     try {
       const directory = path.resolve(options.directory || '.');
 
@@ -307,19 +307,19 @@ function extractFirstLine(content) {
  */
 function displayCompact(result, showCommands, showAgents, showSkills, showExperts) {
   if (showCommands && result.commands?.length > 0) {
-    console.log(chalk.bold('Commands:'), result.commands.map((c) => c.name).join(', '));
+    console.log(chalk.bold('Commands:'), result.commands.map(c => c.name).join(', '));
   }
 
   if (showAgents && result.agents?.length > 0) {
-    console.log(chalk.bold('Agents:'), result.agents.map((a) => a.name).join(', '));
+    console.log(chalk.bold('Agents:'), result.agents.map(a => a.name).join(', '));
   }
 
   if (showSkills && result.skills?.length > 0) {
-    console.log(chalk.bold('Skills:'), result.skills.map((s) => s.name).join(', '));
+    console.log(chalk.bold('Skills:'), result.skills.map(s => s.name).join(', '));
   }
 
   if (showExperts && result.experts?.length > 0) {
-    console.log(chalk.bold('Experts:'), result.experts.map((e) => e.name).join(', '));
+    console.log(chalk.bold('Experts:'), result.experts.map(e => e.name).join(', '));
   }
 }
 
@@ -353,7 +353,11 @@ function displayFull(result, showCommands, showAgents, showSkills, showExperts)
       console.log(chalk.hex('#e8683a')(`  ${skill.name}`));
       console.log(chalk.dim(`    ${skill.description}`));
       if (skill.triggers?.length > 0) {
-        console.log(chalk.dim(`    Triggers: ${skill.triggers.slice(0, 3).join(', ')}${skill.triggers.length > 3 ? '...' : ''}`));
+        console.log(
+          chalk.dim(
+            `    Triggers: ${skill.triggers.slice(0, 3).join(', ')}${skill.triggers.length > 3 ? '...' : ''}`
+          )
+        );
       }
     }
   }

package/tools/cli/commands/setup.js

@@ -2,14 +2,26 @@
  * AgileFlow CLI - Setup Command
  *
  * Sets up AgileFlow in a project directory.
+ * Includes self-update capability to always use the latest CLI.
  */
 
 const chalk = require('chalk');
 const path = require('node:path');
+const { spawnSync } = require('node:child_process');
+const semver = require('semver');
 const { Installer } = require('../installers/core/installer');
 const { IdeManager } = require('../installers/ide/manager');
-const { promptInstall, success, error, info, displaySection } = require('../lib/ui');
+const {
+  promptInstall,
+  success,
+  error,
+  info,
+  displaySection,
+  displayLogo,
+  warning,
+} = require('../lib/ui');
 const { createDocsStructure } = require('../lib/docs-setup');
+const { getLatestVersion } = require('../lib/npm-utils');
 
 const installer = new Installer();
 const ideManager = new IdeManager();
@@ -20,9 +32,48 @@ module.exports = {
   options: [
     ['-d, --directory <path>', 'Installation directory (default: current directory)'],
     ['-y, --yes', 'Skip prompts and use defaults'],
+    ['--no-self-update', 'Skip automatic CLI self-update check'],
+    ['--self-updated', 'Internal flag: indicates CLI was already self-updated'],
   ],
-  action: async (options) => {
+  action: async options => {
     try {
+      // Self-update check: fetch latest version if CLI is outdated
+      const shouldSelfUpdate = options.selfUpdate !== false && !options.selfUpdated;
+
+      if (shouldSelfUpdate) {
+        const packageJson = require(path.join(__dirname, '..', '..', '..', 'package.json'));
+        const localCliVersion = packageJson.version;
+        const npmLatestVersion = await getLatestVersion('agileflow');
+
+        if (npmLatestVersion && semver.lt(localCliVersion, npmLatestVersion)) {
+          displayLogo();
+          info(`Newer version available: v${localCliVersion} → v${npmLatestVersion}`);
+          console.log(chalk.dim('  Fetching latest version from npm...\n'));
+
+          // Build the command with all current options forwarded
+          const args = ['agileflow@latest', 'setup', '--self-updated'];
+          if (options.directory) args.push('-d', options.directory);
+          if (options.yes) args.push('-y');
+
+          const result = spawnSync('npx', args, {
+            stdio: 'inherit',
+            cwd: process.cwd(),
+            shell: process.platform === 'win32',
+          });
+
+          // Exit with the same code as the spawned process
+          process.exit(result.status ?? 0);
+        }
+      }
+
+      // If we self-updated, show confirmation
+      if (options.selfUpdated) {
+        const packageJson = require(path.join(__dirname, '..', '..', '..', 'package.json'));
+        displayLogo();
+        success(`Using latest CLI v${packageJson.version}`);
+        console.log();
+      }
+
       let config;
 
       if (options.yes) {
@@ -73,7 +124,7 @@ module.exports = {
       if (!docsResult.success) {
         error('Failed to create docs structure');
         if (docsResult.errors.length > 0) {
-          docsResult.errors.forEach((err) => error(`  ${err}`));
+          docsResult.errors.forEach(err => error(`  ${err}`));
         }
       }
 

package/tools/cli/commands/status.js

@@ -17,10 +17,8 @@ const installer = new Installer();
 module.exports = {
   name: 'status',
   description: 'Show AgileFlow installation status',
-  options: [
-    ['-d, --directory <path>', 'Project directory (default: current directory)'],
-  ],
-  action: async (options) => {
+  options: [['-d, --directory <path>', 'Project directory (default: current directory)']],
+  action: async options => {
     try {
       const directory = path.resolve(options.directory || '.');
 
@@ -98,8 +96,8 @@ module.exports = {
 function getIdeConfigPath(projectDir, ide) {
   const paths = {
     'claude-code': '.claude/commands/agileflow',
-    'cursor': '.cursor/rules/agileflow',
-    'windsurf': '.windsurf/workflows/agileflow',
+    cursor: '.cursor/rules/agileflow',
+    windsurf: '.windsurf/workflows/agileflow',
   };
 
   return path.join(projectDir, paths[ide] || '');
@@ -113,8 +111,8 @@ function getIdeConfigPath(projectDir, ide) {
 function formatIdeName(ide) {
   const names = {
     'claude-code': 'Claude Code',
-    'cursor': 'Cursor',
-    'windsurf': 'Windsurf',
+    cursor: 'Cursor',
+    windsurf: 'Windsurf',
   };
 
   return names[ide] || ide;

package/tools/cli/commands/uninstall.js

@@ -21,7 +21,7 @@ module.exports = {
     ['-d, --directory <path>', 'Project directory (default: current directory)'],
     ['--force', 'Skip confirmation prompt'],
   ],
-  action: async (options) => {
+  action: async options => {
     try {
       const directory = path.resolve(options.directory || '.');
 
@@ -87,8 +87,8 @@ module.exports = {
 function getIdeConfigPath(projectDir, ide) {
   const paths = {
     'claude-code': '.claude/commands/agileflow',
-    'cursor': '.cursor/rules/agileflow',
-    'windsurf': '.windsurf/workflows/agileflow',
+    cursor: '.cursor/rules/agileflow',
+    windsurf: '.windsurf/workflows/agileflow',
   };
 
   return path.join(projectDir, paths[ide] || '');
@@ -102,8 +102,8 @@ function getIdeConfigPath(projectDir, ide) {
 function formatIdeName(ide) {
   const names = {
     'claude-code': 'Claude Code',
-    'cursor': 'Cursor',
-    'windsurf': 'Windsurf',
+    cursor: 'Cursor',
+    windsurf: 'Windsurf',
   };
 
   return names[ide] || ide;