agileflow 2.73.0 → 2.75.0

package/README.md

@@ -3,7 +3,7 @@
 </p>
 
 [![npm version](https://img.shields.io/npm/v/agileflow?color=brightgreen)](https://www.npmjs.com/package/agileflow)
-[![Commands](https://img.shields.io/badge/commands-53-blue)](docs/04-architecture/commands.md)
+[![Commands](https://img.shields.io/badge/commands-58-blue)](docs/04-architecture/commands.md)
 [![Agents/Experts](https://img.shields.io/badge/agents%2Fexperts-27-orange)](docs/04-architecture/subagents.md)
 [![Skills](https://img.shields.io/badge/skills-dynamic-purple)](docs/04-architecture/skills.md)
 
@@ -65,7 +65,7 @@ AgileFlow combines three proven methodologies:
 
 | Component | Count | Description |
 |-----------|-------|-------------|
-| [Commands](docs/04-architecture/commands.md) | 53 | Slash commands for agile workflows |
+| [Commands](docs/04-architecture/commands.md) | 58 | Slash commands for agile workflows |
 | [Agents/Experts](docs/04-architecture/subagents.md) | 27 | Specialized agents with self-improving knowledge bases |
 | [Skills](docs/04-architecture/skills.md) | Dynamic | Generated on-demand with `/agileflow:skill:create` |
 
@@ -76,7 +76,7 @@ AgileFlow combines three proven methodologies:
 Full documentation lives in [`docs/04-architecture/`](docs/04-architecture/):
 
 ### Reference
-- [Commands](docs/04-architecture/commands.md) - All 53 slash commands
+- [Commands](docs/04-architecture/commands.md) - All 58 slash commands
 - [Agents/Experts](docs/04-architecture/subagents.md) - 27 specialized agents with self-improving knowledge
 - [Skills](docs/04-architecture/skills.md) - Dynamic skill generator with MCP integration
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agileflow",
-  "version": "2.73.0",
+  "version": "2.75.0",
   "description": "AI-driven agile development system for Claude Code, Cursor, Windsurf, and more",
   "keywords": [
     "agile",

package/scripts/agileflow-configure.js

@@ -77,6 +77,34 @@ const FEATURES = {
   autoupdate: { metadataOnly: true }, // Stored in metadata.updates.autoUpdate
 };
 
+// Complete registry of all scripts that may need repair
+const ALL_SCRIPTS = {
+  // Core feature scripts (linked to FEATURES)
+  'agileflow-welcome.js': { feature: 'sessionstart', required: true },
+  'precompact-context.sh': { feature: 'precompact', required: true },
+  'archive-completed-stories.sh': { feature: 'archival', required: true },
+  'agileflow-statusline.sh': { feature: 'statusline', required: true },
+
+  // Support scripts (used by commands/agents)
+  'obtain-context.js': { usedBy: ['/babysit', '/mentor', '/sprint'] },
+  'session-manager.js': { usedBy: ['/session:new', '/session:resume'] },
+  'check-update.js': { usedBy: ['SessionStart hook'] },
+  'get-env.js': { usedBy: ['SessionStart hook'] },
+  'clear-active-command.js': { usedBy: ['session commands'] },
+
+  // Utility scripts
+  'compress-status.sh': { usedBy: ['/compress'] },
+  'validate-expertise.sh': { usedBy: ['/validate-expertise'] },
+  'expertise-metrics.sh': { usedBy: ['agent experts'] },
+  'session-coordinator.sh': { usedBy: ['session management'] },
+  'validate-tokens.sh': { usedBy: ['token validation'] },
+  'worktree-create.sh': { usedBy: ['/session:new'] },
+  'resume-session.sh': { usedBy: ['/session:resume'] },
+  'init.sh': { usedBy: ['/session:init'] },
+  'agileflow-configure.js': { usedBy: ['/configure'] },
+  'generate-all.sh': { usedBy: ['content generation'] },
+};
+
 // Statusline component names
 const STATUSLINE_COMPONENTS = [
   'agileflow',
@@ -811,6 +839,240 @@ function listStatuslineComponents() {
   log(`Components: ${STATUSLINE_COMPONENTS.join(', ')}`, c.dim);
 }
 
+// ============================================================================
+// REPAIR & DIAGNOSTICS
+// ============================================================================
+
+const crypto = require('crypto');
+
+/**
+ * Calculate SHA256 hash of a file
+ */
+function sha256(data) {
+  return crypto.createHash('sha256').update(data).digest('hex');
+}
+
+/**
+ * Get the source scripts directory (from npm package)
+ */
+function getSourceScriptsDir() {
+  // When running from installed package, __dirname is .agileflow/scripts
+  // The source is the same directory since it was copied during install
+  // But for repair, we need the npm package source
+
+  // Try to find the npm package (when run via npx or global install)
+  const possiblePaths = [
+    path.join(__dirname, '..', '..', 'scripts'), // npm package structure
+    path.join(__dirname), // Same directory (for development)
+  ];
+
+  for (const p of possiblePaths) {
+    if (fs.existsSync(p) && fs.existsSync(path.join(p, 'agileflow-welcome.js'))) {
+      return p;
+    }
+  }
+
+  return null;
+}
+
+/**
+ * List all scripts with their status (present/missing/modified)
+ */
+function listScripts() {
+  header('📋 Installed Scripts');
+
+  const scriptsDir = path.join(process.cwd(), '.agileflow', 'scripts');
+  const fileIndexPath = path.join(process.cwd(), '.agileflow', '_cfg', 'files.json');
+  const fileIndex = readJSON(fileIndexPath);
+
+  let missing = 0;
+  let modified = 0;
+  let present = 0;
+
+  Object.entries(ALL_SCRIPTS).forEach(([script, info]) => {
+    const scriptPath = path.join(scriptsDir, script);
+    const exists = fs.existsSync(scriptPath);
+
+    // Check if modified (compare to file index hash)
+    let isModified = false;
+    if (exists && fileIndex?.files?.[`scripts/${script}`]) {
+      try {
+        const currentHash = sha256(fs.readFileSync(scriptPath));
+        const indexHash = fileIndex.files[`scripts/${script}`].sha256;
+        isModified = currentHash !== indexHash;
+      } catch {}
+    }
+
+    // Print status
+    if (!exists) {
+      log(`  ❌ ${script}: MISSING`, c.red);
+      if (info.usedBy) log(`     └─ Used by: ${info.usedBy.join(', ')}`, c.dim);
+      if (info.feature) log(`     └─ Feature: ${info.feature}`, c.dim);
+      missing++;
+    } else if (isModified) {
+      log(`  ⚠️  ${script}: modified (local changes)`, c.yellow);
+      modified++;
+    } else {
+      log(`  ✅ ${script}: present`, c.green);
+      present++;
+    }
+  });
+
+  // Summary
+  log('');
+  log(`Summary: ${present} present, ${modified} modified, ${missing} missing`, c.dim);
+
+  if (missing > 0) {
+    log('\n💡 Run with --repair to restore missing scripts', c.yellow);
+  }
+}
+
+/**
+ * Show version information
+ */
+function showVersionInfo() {
+  header('📊 Version Information');
+
+  const meta = readJSON('docs/00-meta/agileflow-metadata.json') || {};
+  const manifest = readJSON('.agileflow/_cfg/manifest.yaml');
+
+  const installedVersion = meta.version || 'unknown';
+
+  log(`Installed:  v${installedVersion}`);
+  log(`CLI:        v${VERSION}`);
+
+  // Check npm for latest
+  let latestVersion = null;
+  try {
+    latestVersion = execSync('npm view agileflow version 2>/dev/null', { encoding: 'utf8' }).trim();
+    log(`Latest:     v${latestVersion}`);
+
+    if (installedVersion !== 'unknown' && latestVersion && installedVersion !== latestVersion) {
+      const installed = installedVersion.split('.').map(Number);
+      const latest = latestVersion.split('.').map(Number);
+
+      if (latest[0] > installed[0] ||
+          (latest[0] === installed[0] && latest[1] > installed[1]) ||
+          (latest[0] === installed[0] && latest[1] === installed[1] && latest[2] > installed[2])) {
+        log('\n🔄 Update available! Run: npx agileflow update', c.yellow);
+      }
+    }
+  } catch {
+    log('Latest:     (could not check npm)', c.dim);
+  }
+
+  // Show per-feature versions
+  if (meta.features && Object.keys(meta.features).length > 0) {
+    header('Feature Versions:');
+    Object.entries(meta.features).forEach(([feature, data]) => {
+      if (!data) return;
+      const featureVersion = data.version || 'unknown';
+      const enabled = data.enabled !== false;
+      const outdated = featureVersion !== VERSION && enabled;
+
+      let icon = '❌';
+      let color = c.dim;
+      let statusText = `v${featureVersion}`;
+
+      if (!enabled) {
+        statusText = 'disabled';
+      } else if (outdated) {
+        icon = '🔄';
+        color = c.yellow;
+        statusText = `v${featureVersion} → v${VERSION}`;
+      } else {
+        icon = '✅';
+        color = c.green;
+      }
+
+      log(`  ${icon} ${feature}: ${statusText}`, color);
+    });
+  }
+
+  // Show installation metadata
+  if (meta.created || meta.updated) {
+    header('Installation:');
+    if (meta.created) log(`  Created:  ${new Date(meta.created).toLocaleDateString()}`, c.dim);
+    if (meta.updated) log(`  Updated:  ${new Date(meta.updated).toLocaleDateString()}`, c.dim);
+  }
+}
+
+/**
+ * Repair missing or corrupted scripts
+ */
+function repairScripts(targetFeature = null) {
+  header('🔧 Repairing Scripts...');
+
+  const scriptsDir = path.join(process.cwd(), '.agileflow', 'scripts');
+  const sourceDir = getSourceScriptsDir();
+
+  if (!sourceDir) {
+    warn('Could not find source scripts directory');
+    info('Try running: npx agileflow@latest update');
+    return false;
+  }
+
+  let repaired = 0;
+  let errors = 0;
+  let skipped = 0;
+
+  // Determine which scripts to check
+  const scriptsToCheck = targetFeature
+    ? Object.entries(ALL_SCRIPTS).filter(([_, info]) => info.feature === targetFeature)
+    : Object.entries(ALL_SCRIPTS);
+
+  if (scriptsToCheck.length === 0 && targetFeature) {
+    error(`Unknown feature: ${targetFeature}`);
+    log(`Available features: ${Object.keys(FEATURES).join(', ')}`, c.dim);
+    return false;
+  }
+
+  // Ensure scripts directory exists
+  ensureDir(scriptsDir);
+
+  for (const [script, info] of scriptsToCheck) {
+    const destPath = path.join(scriptsDir, script);
+    const srcPath = path.join(sourceDir, script);
+
+    if (!fs.existsSync(destPath)) {
+      // Script is missing - reinstall from source
+      if (fs.existsSync(srcPath)) {
+        try {
+          fs.copyFileSync(srcPath, destPath);
+          // Make executable
+          try {
+            fs.chmodSync(destPath, 0o755);
+          } catch {}
+          success(`Restored ${script}`);
+          repaired++;
+        } catch (err) {
+          error(`Failed to restore ${script}: ${err.message}`);
+          errors++;
+        }
+      } else {
+        warn(`Source not found for ${script}`);
+        errors++;
+      }
+    } else {
+      skipped++;
+    }
+  }
+
+  // Summary
+  log('');
+  if (repaired === 0 && errors === 0) {
+    info('All scripts present - nothing to repair');
+  } else {
+    log(`Repaired: ${repaired}, Errors: ${errors}, Skipped: ${skipped}`, c.dim);
+  }
+
+  if (errors > 0) {
+    log('\n💡 For comprehensive repair, run: npx agileflow update --force', c.yellow);
+  }
+
+  return repaired > 0;
+}
+
 // ============================================================================
 // PROFILES
 // ============================================================================
@@ -907,6 +1169,12 @@ ${c.cyan}Maintenance:${c.reset}
   --validate          Check for issues (same as --detect)
   --detect            Show current configuration
 
+${c.cyan}Repair & Diagnostics:${c.reset}
+  --repair              Check for and restore missing scripts
+  --repair=<feature>    Repair scripts for a specific feature (e.g., statusline)
+  --version             Show installed vs latest version info
+  --list-scripts        List all scripts with their status (missing/present/modified)
+
 ${c.cyan}Examples:${c.reset}
   # Quick setup with all features
   node .agileflow/scripts/agileflow-configure.js --profile=full
@@ -934,6 +1202,18 @@ ${c.cyan}Examples:${c.reset}
 
   # Upgrade outdated scripts to latest version
   node .agileflow/scripts/agileflow-configure.js --upgrade
+
+  # List all scripts with status
+  node .agileflow/scripts/agileflow-configure.js --list-scripts
+
+  # Show version information
+  node .agileflow/scripts/agileflow-configure.js --version
+
+  # Repair missing scripts
+  node .agileflow/scripts/agileflow-configure.js --repair
+
+  # Repair scripts for a specific feature
+  node .agileflow/scripts/agileflow-configure.js --repair=statusline
 `);
 }
 
@@ -956,6 +1236,10 @@ function main() {
   let upgrade = false;
   let components = false;
   let help = false;
+  let repair = false;
+  let repairFeature = null;
+  let showVersion = false;
+  let listScriptsMode = false;
 
   args.forEach(arg => {
     if (arg.startsWith('--profile=')) profile = arg.split('=')[1];
@@ -985,6 +1269,13 @@ function main() {
     else if (arg === '--upgrade') upgrade = true;
     else if (arg === '--components') components = true;
     else if (arg === '--help' || arg === '-h') help = true;
+    else if (arg === '--repair') repair = true;
+    else if (arg.startsWith('--repair=')) {
+      repair = true;
+      repairFeature = arg.split('=')[1].trim().toLowerCase();
+    }
+    else if (arg === '--version' || arg === '-v') showVersion = true;
+    else if (arg === '--list-scripts' || arg === '--scripts') listScriptsMode = true;
   });
 
   if (help) {
@@ -992,6 +1283,30 @@ function main() {
     return;
   }
 
+  // List scripts mode (standalone, doesn't need detection)
+  if (listScriptsMode) {
+    listScripts();
+    return;
+  }
+
+  // Version info mode (standalone, doesn't need detection)
+  if (showVersion) {
+    showVersionInfo();
+    return;
+  }
+
+  // Repair mode (standalone, doesn't need detection)
+  if (repair) {
+    const needsRestart = repairScripts(repairFeature);
+    if (needsRestart) {
+      log('\n' + '═'.repeat(55), c.red);
+      log('🔴 RESTART CLAUDE CODE NOW!', c.red + c.bold);
+      log('   Quit completely, wait 5 seconds, restart', c.red);
+      log('═'.repeat(55), c.red);
+    }
+    return;
+  }
+
   // Components list mode
   if (components && show.length === 0 && hide.length === 0) {
     listStatuslineComponents();

package/src/core/agents/accessibility.md

@@ -428,7 +428,7 @@ COORDINATION WITH OTHER AGENTS
 
 SLASH COMMANDS
 
-- `/agileflow:context MODE=research TOPIC=...` → Research accessibility best practices
+- `/agileflow:research:ask TOPIC=...` → Research accessibility best practices
 - `/agileflow:ai-code-review` → Review code for accessibility issues
 - `/agileflow:adr-new` → Document accessibility decisions
 - `/agileflow:status STORY=... STATUS=...` → Update status

package/src/core/agents/adr-writer.md

@@ -43,7 +43,7 @@ node .agileflow/scripts/obtain-context.js adr-writer
 
 **Workflow**:
 1. Load expertise: `packages/cli/src/core/experts/adr-writer/expertise.yaml`
-2. Check docs/10-research/ for existing research (or invoke `/agileflow:context MODE=research`)
+2. Check docs/10-research/ for existing research (or invoke `/agileflow:research:ask`)
 3. Check docs/03-decisions/ for related ADRs
 4. Get next ADR number from docs/03-decisions/README.md (sequential: 0001, 0002, etc.)
 5. Gather decision context and alternatives
@@ -135,13 +135,13 @@ Create an ADR when deciding:
 SLASH COMMANDS (Proactive Use)
 
 **Research**:
-- `/agileflow:context MODE=research TOPIC=...` → Generate research for alternatives before writing ADR
+- `/agileflow:research:ask TOPIC=...` → Generate research for alternatives before writing ADR
 
 RESEARCH INTEGRATION
 
 **Before Writing ADR**:
 1. Check docs/10-research/ for existing research on the decision topic
-2. If research is missing or stale, invoke `/agileflow:context MODE=research TOPIC=...`
+2. If research is missing or stale, invoke `/agileflow:research:ask TOPIC=...`
 3. Research should cover all alternatives with pros/cons, benchmarks, trade-offs
 
 **After User Provides Research**:
@@ -151,7 +151,7 @@ RESEARCH INTEGRATION
 
 WORKFLOW
 1. **[KNOWLEDGE LOADING]** Before writing:
-   - Check docs/10-research/ for relevant research (or invoke `/agileflow:context MODE=research`)
+   - Check docs/10-research/ for relevant research (or invoke `/agileflow:research:ask`)
    - Check existing ADRs in docs/03-decisions/ for related decisions
    - Check CLAUDE.md for current architecture context
 2. Ask for decision context (what's being decided and why now?)
@@ -268,7 +268,7 @@ This contains your mental model of:
 **Then Output**:
 1. ADR context: "Next ADR: ADR-<NUMBER>, recent decisions: <list of last 3 ADRs>"
 2. If research exists: "Found research: <topic> (docs/10-research/<file>)"
-3. If no research: "No research found. I can invoke `/agileflow:context MODE=research` to gather alternatives."
+3. If no research: "No research found. I can invoke `/agileflow:research:ask` to gather alternatives."
 4. Ask: "What technical decision would you like to document?"
 5. Clarify: "I'll document context, alternatives considered, decision, and consequences."
 
@@ -288,7 +288,7 @@ This updates your expertise with what you learned, so you're faster next time.
 
 **After User Describes Decision**:
 1. Clarify context (why now? what forces?)
-2. Check docs/10-research/ for supporting research (or invoke `/agileflow:context MODE=research`)
+2. Check docs/10-research/ for supporting research (or invoke `/agileflow:research:ask`)
 3. Identify 2-5 alternatives with pros/cons
 4. Propose ADR structure (show preview)
 5. Get approval (YES/NO)

package/src/core/agents/analytics.md

@@ -514,7 +514,7 @@ COORDINATION WITH OTHER AGENTS
 
 SLASH COMMANDS
 
-- `/agileflow:context MODE=research TOPIC=...` → Research analytics best practices
+- `/agileflow:research:ask TOPIC=...` → Research analytics best practices
 - `/agileflow:ai-code-review` → Review analytics implementation for data quality
 - `/agileflow:adr-new` → Document analytics decisions
 - `/agileflow:status STORY=... STATUS=...` → Update status

package/src/core/agents/api.md

@@ -369,7 +369,7 @@ SLASH COMMANDS (Proactive Use)
 AG-API can directly invoke AgileFlow commands to streamline workflows:
 
 **Research & Planning**:
-- `/agileflow:context MODE=research TOPIC=...` → Research API patterns, database strategies, integration approaches
+- `/agileflow:research:ask TOPIC=...` → Research API patterns, database strategies, integration approaches
 
 **Quality & Review**:
 - `/agileflow:ai-code-review` → Review API code before marking in-review
@@ -407,7 +407,7 @@ AGENT COORDINATION
   - Performance issues → Request impact analysis
 
 - **RESEARCH** (Technical research):
-  - Unfamiliar pattern → Request research via `/agileflow:context MODE=research`
+  - Unfamiliar pattern → Request research via `/agileflow:research:ask`
   - Check docs/10-research/ for existing API/database research before starting
 
 - **MENTOR** (Guidance):
@@ -424,7 +424,7 @@ RESEARCH INTEGRATION
 **Before Starting Implementation**:
 1. Check docs/10-research/ for relevant API/database/integration research
 2. Search for topics: API patterns, database design, ORM usage, authentication, external integrations
-3. If no research exists or research is stale (>90 days), suggest: `/agileflow:context MODE=research TOPIC=...`
+3. If no research exists or research is stale (>90 days), suggest: `/agileflow:research:ask TOPIC=...`
 
 **After User Provides Research**:
 - Offer to save to docs/10-research/<YYYYMMDD>-<slug>.md
@@ -530,49 +530,138 @@ AG-UI stories frequently block waiting for API endpoints. Always check for block
 
 FIRST ACTION
 
-**CRITICAL: Load Expertise First (Agent Expert Protocol)**
-
-Before ANY work, read your expertise file:
-```
-packages/cli/src/core/experts/api/expertise.yaml
-```
-
-This contains your mental model of:
-- Route/controller file locations
-- Middleware structure
-- Endpoint registry
-- Auth and validation patterns
-- Recent learnings from past work
-
-**Validate expertise against actual code** - expertise is your memory, code is the source of truth.
-
-**Proactive Knowledge Loading** (do this BEFORE asking user):
-1. **READ EXPERTISE FILE FIRST** (packages/cli/src/core/experts/api/expertise.yaml)
+**Proactive Knowledge Loading** (before asking user):
+1. Read `packages/cli/src/core/experts/api/expertise.yaml` - your persistent memory
 2. Read docs/09-agents/status.json → Find READY stories where owner==AG-API
-3. **CRITICAL**: Search for blocked AG-UI stories waiting on AG-API endpoints
+3. Search for blocked AG-UI stories waiting on AG-API endpoints
 4. Read docs/09-agents/bus/log.jsonl (last 10 messages) → Check for API requests from AG-UI
 5. Check CLAUDE.md for API architecture (REST, GraphQL, auth pattern)
 
 **Then Output**:
 1. Status summary: "<N> API stories ready, <N> in progress"
-2. **CRITICAL - AG-UI Blockers**: "⚠️ <N> AG-UI stories blocked waiting for API endpoints: <list>"
-   - If AG-UI blockers exist, prioritize those API stories first
-3. Auto-suggest 2-3 stories from status.json:
-   - **Prioritize** stories that unblock AG-UI
-   - Format: `US-####: <title> (estimate: <time>, unblocks: <US-IDs>, AC: <count> criteria)`
-4. Ask: "Which API story should I implement? (Prioritizing AG-UI unblocking)"
-5. Explain autonomy: "I'll automatically notify AG-UI when endpoints are ready."
-
-**For Complete Features - Use Workflow**:
-For implementing complete API features, use the three-step workflow:
-```
-packages/cli/src/core/experts/api/workflow.md
-```
-This chains Plan → Build → Self-Improve automatically.
+2. **AG-UI Blockers**: "⚠️ <N> AG-UI stories blocked waiting for API endpoints: <list>"
+3. Auto-suggest 2-3 stories (prioritize stories that unblock AG-UI)
+4. Ask: "Which API story should I implement?"
 
-**After Completing Work - Self-Improve**:
-After ANY API changes (new endpoints, middleware, validation), run self-improve:
-```
-packages/cli/src/core/experts/api/self-improve.md
+---
+
+## MANDATORY EXECUTION PROTOCOL
+
+**CRITICAL: Every implementation follows Plan → Build → Self-Improve. NO EXCEPTIONS.**
+
+This protocol ensures your expertise grows with every task. Skipping any step is a violation.
+
+### Protocol Overview
+
+| Step | Action | Gate |
+|------|--------|------|
+| **1. PLAN** | Load expertise → Validate → Design | User approval required |
+| **2. BUILD** | Execute plan → Capture diff | Tests must pass |
+| **3. SELF-IMPROVE** | Update expertise → Add learnings | Entry required |
+
+---
+
+### Step 1: PLAN (Expertise-Informed)
+
+**Before ANY implementation:**
+
+1. **Load expertise**: Read `packages/cli/src/core/experts/api/expertise.yaml`
+2. **Extract knowledge**:
+   - Route/controller file locations
+   - Middleware structure and auth patterns
+   - Endpoint registry (existing endpoints)
+   - Validation patterns (Zod, Yup, etc.)
+   - Recent learnings from past work
+3. **Validate against code**: Expertise is your memory, code is the source of truth
+4. **Create detailed plan**: Endpoint path, method, request/response schema, middleware chain
+5. **Get user approval**: Present plan, wait for confirmation before proceeding
+
+**Example Plan Output**:
+```markdown
+## API Implementation Plan
+
+### Endpoint
+- Method: GET
+- Path: /api/users/:id
+- Auth: JWT required (use authMiddleware)
+
+### Request/Response
+- Request: params.id (uuid)
+- Response: { user: UserSchema }
+
+### Files to Modify
+- src/routes/users.ts (add route)
+- src/schemas/user.ts (add response schema)
+
+### Pattern to Follow
+Using existing authMiddleware pattern from /api/profile
+
+Proceed with this plan? (YES/NO)
 ```
-This updates your expertise with what you learned, so you're faster next time.
+
+---
+
+### Step 2: BUILD (Execute Plan)
+
+**After user approves plan:**
+
+1. Execute the approved plan (create routes, controllers, schemas)
+2. Write tests (unit + integration)
+3. Capture all changes: `git diff HEAD`
+4. Verify: Tests pass, endpoint responds correctly
+
+**On failure**: STOP immediately. Do NOT proceed to Step 3. Report error and await guidance.
+
+---
+
+### Step 3: SELF-IMPROVE (Update Expertise) ← MANDATORY
+
+**ONLY after successful build (Step 2 passed). NEVER skip this step.**
+
+1. **Read**: `packages/cli/src/core/experts/api/expertise.yaml`
+2. **Analyze the diff** - what changed?
+3. **Update expertise sections**:
+   - **files**: Add new route/controller file paths discovered
+   - **endpoints**: Register new endpoint in endpoint list
+   - **patterns**: Document new patterns used (auth, validation, error handling)
+   - **conventions**: Note new naming conventions applied
+4. **Add learnings entry** (REQUIRED):
+   ```yaml
+   learnings:
+     - date: 2025-12-30
+       insight: "Added GET /api/users/:id endpoint with JWT auth"
+       files_affected:
+         - src/routes/users.ts
+         - src/schemas/user.ts
+       context: "Feature: User profile API"
+   ```
+5. **Write** the updated expertise file
+
+**VIOLATION**: Completing Step 2 without running Step 3 = CRITICAL ERROR. You MUST update expertise after every successful build.
+
+---
+
+### Execution Gate
+
+Before marking ANY story complete, verify ALL boxes:
+- [ ] Step 1: Expertise loaded, plan presented and approved
+- [ ] Step 2: Build succeeded, tests pass
+- [ ] Step 3: Expertise file updated with new learnings entry
+
+**Missing any checkbox → Story remains in-progress**
+
+---
+
+### When to Skip Protocol
+
+**ONLY skip the full protocol for:**
+- Answering questions (no implementation)
+- Pure research/exploration tasks
+- Status updates without code changes
+
+**NEVER skip for:**
+- New endpoints
+- New middleware
+- Validation changes
+- Auth pattern changes
+- Any code modification