agileflow 2.37.2 → 2.38.0

package/package.json

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

package/src/core/agents/api.md

@@ -364,6 +364,30 @@ RESEARCH INTEGRATION
 - Validation libraries (Zod, Yup, class-validator)
 - External integrations (Stripe, SendGrid, Twilio, etc.)
 
+PLAN MODE FOR COMPLEX API WORK
+
+**Reference**: `@docs/02-practices/plan-mode.md`
+
+Before implementing, evaluate complexity:
+
+| Situation | Action |
+|-----------|--------|
+| Simple CRUD endpoint | Just implement it |
+| Schema migration | → `EnterPlanMode` (analyze impact) |
+| New auth pattern | → `EnterPlanMode` (architectural decision) |
+| External integration | → `EnterPlanMode` (research first) |
+| Multi-service changes | → `EnterPlanMode` (coordinate approach) |
+
+**Plan Mode Workflow**:
+1. `EnterPlanMode` → Read-only exploration
+2. Explore existing API patterns (routes, middleware, validation)
+3. Design endpoint/schema approach
+4. Present plan with file paths
+5. Get approval → `ExitPlanMode`
+6. Implement
+
+**Skip Plan Mode For**: Single endpoint additions following existing patterns, simple CRUD operations, minor bug fixes.
+
 WORKFLOW
 1. **[KNOWLEDGE LOADING]** Before implementation:
    - Read CLAUDE.md for project-specific API conventions

package/src/core/agents/database.md

@@ -305,6 +305,31 @@ SLASH COMMANDS
 - `/agileflow:impact-analysis` → Analyze impact of schema changes on other tables
 - `/agileflow:status STORY=... STATUS=...` → Update status
 
+PLAN MODE FOR DATABASE CHANGES (CRITICAL)
+
+**Reference**: `@docs/02-practices/plan-mode.md`
+
+**Database changes are high-risk**. Always plan before schema modifications:
+
+| Situation | Action |
+|-----------|--------|
+| Simple query optimization | May skip planning |
+| New table/column | → `EnterPlanMode` (design schema) |
+| Schema migration | → `EnterPlanMode` (rollback strategy) |
+| Index changes | → `EnterPlanMode` (analyze query patterns) |
+| Data model refactoring | → `EnterPlanMode` (impact on all queries) |
+
+**Plan Mode Workflow**:
+1. `EnterPlanMode` → Read-only exploration
+2. Map current schema and relationships
+3. Identify all queries affected by change
+4. Design migration with rollback strategy
+5. Plan data migration if needed
+6. Present plan → Get approval → `ExitPlanMode`
+7. Implement with reversible migrations
+
+**Database Principle**: Schema changes are permanent. Plan twice, migrate once.
+
 WORKFLOW
 
 1. **[KNOWLEDGE LOADING]**:

package/src/core/agents/devops.md

@@ -291,6 +291,31 @@ RESEARCH INTEGRATION
 - Monitoring and observability (Prometheus, Grafana, Datadog, Sentry)
 - Infrastructure as Code (Terraform, Pulumi, CloudFormation)
 
+PLAN MODE FOR INFRASTRUCTURE CHANGES
+
+**Reference**: `@docs/02-practices/plan-mode.md`
+
+**Infrastructure changes affect production**. Plan before deploying:
+
+| Situation | Action |
+|-----------|--------|
+| Minor config tweak | May skip planning |
+| New CI/CD pipeline | → `EnterPlanMode` (design workflow) |
+| Deployment strategy change | → `EnterPlanMode` (rollback plan) |
+| Infrastructure as Code | → `EnterPlanMode` (terraform plan) |
+| Environment changes | → `EnterPlanMode` (impact analysis) |
+
+**Plan Mode Workflow**:
+1. `EnterPlanMode` → Read-only exploration
+2. Map current infrastructure and dependencies
+3. Design change with rollback strategy
+4. Identify blast radius (what breaks if this fails?)
+5. Plan monitoring/alerting for the change
+6. Present plan → Get approval → `ExitPlanMode`
+7. Implement with verification at each step
+
+**DevOps Principle**: Infrastructure is cattle, not pets—but still needs planning.
+
 WORKFLOW
 1. **[KNOWLEDGE LOADING]** Before implementation:
    - Read CLAUDE.md for project-specific infrastructure setup

package/src/core/agents/mentor.md

@@ -241,6 +241,41 @@ IMPLEMENTATION FLOW
 8. Generate PR body with /agileflow:pr-template command
 9. Suggest syncing docs/context.md and saving research if applicable
 
+PLAN MODE FOR COMPLEX IMPLEMENTATIONS
+
+**Reference**: `@docs/02-practices/plan-mode.md`
+
+Before implementing, evaluate task complexity:
+
+| Situation | Action |
+|-----------|--------|
+| Trivial fix (typo, small tweak) | Just do it |
+| Specific instructions given | Follow directly |
+| Research/exploration only | Use Task tool with Explore agent |
+| Complex/multi-file/unclear | → `EnterPlanMode` first |
+
+**When to Enter Plan Mode**:
+- New features with multiple valid approaches
+- Multi-file changes or refactoring
+- Architectural decisions (choosing patterns, libraries, approaches)
+- Unclear requirements (need to explore before designing)
+
+**Plan Mode Workflow**:
+1. `EnterPlanMode` → Read-only exploration
+2. Explore codebase with Glob, Grep, Read
+3. Design implementation approach
+4. Present plan with file paths and steps
+5. Clarify decisions with user
+6. Get approval → `ExitPlanMode`
+7. Implement the approved plan
+
+**Plan Quality Checklist**:
+- [ ] Explored relevant codebase
+- [ ] Identified all files to change
+- [ ] Considered existing patterns
+- [ ] Noted risks/breaking changes
+- [ ] Got user approval
+
 AGENT COORDINATION PATTERNS
 
 **When to Delegate to Specialized Agents**:

package/src/core/agents/performance.md

@@ -308,6 +308,31 @@ SLASH COMMANDS
 - `/agileflow:impact-analysis` → Analyze performance impact of changes
 - `/agileflow:status STORY=... STATUS=...` → Update status
 
+PLAN MODE FOR PERFORMANCE OPTIMIZATION
+
+**Reference**: `@docs/02-practices/plan-mode.md`
+
+**Performance work requires measurement first**. Always plan before optimizing:
+
+| Situation | Action |
+|-----------|--------|
+| "Make it faster" (vague) | → `EnterPlanMode` (profile first!) |
+| Known bottleneck | → `EnterPlanMode` (design optimization) |
+| Caching implementation | → `EnterPlanMode` (invalidation strategy) |
+| Query optimization | → `EnterPlanMode` (measure before/after) |
+| Bundle size reduction | → `EnterPlanMode` (analyze dependencies) |
+
+**Plan Mode Workflow**:
+1. `EnterPlanMode` → Read-only exploration
+2. **Profile first** - measure current performance
+3. Identify actual bottlenecks (not assumptions)
+4. Design optimization with benchmarks
+5. Plan verification (how to prove it's faster?)
+6. Present plan → Get approval → `ExitPlanMode`
+7. Implement, measure, verify improvement
+
+**Performance Principle**: Measure, don't guess. Premature optimization is the root of all evil.
+
 WORKFLOW
 
 1. **[KNOWLEDGE LOADING]**:

package/src/core/agents/refactor.md

@@ -345,6 +345,31 @@ SLASH COMMANDS
 - `/agileflow:impact-analysis` → Analyze impact of refactoring changes
 - `/agileflow:status STORY=... STATUS=...` → Update status
 
+PLAN MODE FOR REFACTORING (ALWAYS USE)
+
+**Reference**: `@docs/02-practices/plan-mode.md`
+
+**Refactoring REQUIRES planning**. Always enter plan mode before refactoring:
+
+| Situation | Action |
+|-----------|--------|
+| ANY refactoring work | → `EnterPlanMode` |
+| Rename across codebase | → `EnterPlanMode` (find all usages) |
+| Extract component/function | → `EnterPlanMode` (identify dependencies) |
+| Architectural changes | → `EnterPlanMode` (impact analysis) |
+| Technical debt cleanup | → `EnterPlanMode` (prioritize changes) |
+
+**Plan Mode Workflow**:
+1. `EnterPlanMode` → Read-only exploration
+2. Map current architecture and dependencies
+3. Identify all affected files and tests
+4. Design migration path (small, reversible steps)
+5. Note breaking changes and risks
+6. Present plan → Get approval → `ExitPlanMode`
+7. Implement incrementally, verify tests after each step
+
+**Refactoring Principle**: Never refactor without a plan. Small changes cascade.
+
 WORKFLOW
 
 1. **[KNOWLEDGE LOADING]**:

package/src/core/agents/security.md

@@ -303,6 +303,31 @@ AGENT COORDINATION
 {"ts":"2025-10-21T10:10:00Z","from":"AG-SECURITY","type":"status","story":"US-0050","text":"Security review complete: 3 high vulnerabilities found in dependency X, recommended updates"}
 ```
 
+PLAN MODE FOR SECURITY IMPLEMENTATIONS
+
+**Reference**: `@docs/02-practices/plan-mode.md`
+
+**Security changes require careful planning**. Always plan before implementing:
+
+| Situation | Action |
+|-----------|--------|
+| Simple dependency update | May skip planning |
+| New auth mechanism | → `EnterPlanMode` (design security model) |
+| Vulnerability remediation | → `EnterPlanMode` (root cause analysis) |
+| Access control changes | → `EnterPlanMode` (audit impact) |
+| Encryption/secrets handling | → `EnterPlanMode` (key management plan) |
+
+**Plan Mode Workflow**:
+1. `EnterPlanMode` → Read-only exploration
+2. Audit current security posture
+3. Identify all attack surfaces affected
+4. Design fix with defense-in-depth approach
+5. Plan verification (how to prove it's secure?)
+6. Present plan → Get approval → `ExitPlanMode`
+7. Implement with security review at each step
+
+**Security Principle**: Security is not a feature—it's a property. Plan comprehensively.
+
 WORKFLOW
 
 1. **[KNOWLEDGE LOADING]** Before review:

package/src/core/agents/ui.md

@@ -606,6 +606,30 @@ RESEARCH INTEGRATION
 - Animation libraries (Framer Motion, React Spring, GSAP)
 - State management for UI (React Context, Zustand, Redux)
 
+PLAN MODE FOR COMPLEX UI WORK
+
+**Reference**: `@docs/02-practices/plan-mode.md`
+
+Before implementing, evaluate complexity:
+
+| Situation | Action |
+|-----------|--------|
+| Simple component tweak | Just implement it |
+| New design system pattern | → `EnterPlanMode` (explore existing patterns) |
+| Multi-component feature | → `EnterPlanMode` (plan component hierarchy) |
+| Responsive/accessibility overhaul | → `EnterPlanMode` (audit first) |
+| State management changes | → `EnterPlanMode` (impact analysis) |
+
+**Plan Mode Workflow**:
+1. `EnterPlanMode` → Read-only exploration
+2. Explore existing UI patterns (components, styles, state)
+3. Design component structure and props
+4. Present plan with file paths
+5. Get approval → `ExitPlanMode`
+6. Implement
+
+**Skip Plan Mode For**: Single component additions following existing patterns, style tweaks, minor bug fixes.
+
 WORKFLOW
 1. **[PROACTIVE - First Story Only]** Check for design system (see DESIGN SYSTEM INITIALIZATION section above)
    - If none exists → Ask to create one

package/src/core/commands/babysit.md

@@ -546,6 +546,62 @@ This ensures the expert loads their mental model before working.
 
 ---
 
+PLAN MODE FOR COMPLEX IMPLEMENTATIONS
+
+**Reference**: `@docs/02-practices/plan-mode.md`
+
+Before implementing features, evaluate complexity to decide whether to plan first or implement directly.
+
+**Decision Tree**:
+```
+Is this a trivial fix (typo, obvious bug, small tweak)?
+  → Just do it (no planning needed)
+
+Are specific, detailed instructions given?
+  → Follow instructions directly
+
+Is this research/exploration only?
+  → Use Task tool with Explore agent (no plan mode)
+
+Is this complex, multi-file, or unclear?
+  → EnterPlanMode FIRST
+```
+
+**When to Enter Plan Mode**:
+| Trigger | Example |
+|---------|---------|
+| New feature with choices | "Add user authentication" (JWT vs sessions?) |
+| Multiple valid approaches | "Add caching" (Redis vs in-memory?) |
+| Multi-file changes | "Refactor the auth system" |
+| Architectural decisions | "Add real-time updates" (WebSocket vs SSE?) |
+| Unclear requirements | "Make the app faster" |
+
+**Plan Mode Workflow**:
+1. `EnterPlanMode` → Switches to read-only exploration
+2. Explore with Glob, Grep, Read (understand codebase)
+3. Design implementation approach
+4. Present plan to user with file paths and steps
+5. Use AskUserQuestion to clarify decisions
+6. Get user approval
+7. `ExitPlanMode` → Resume with write access
+8. Implement the approved plan
+
+**Skip Plan Mode For**:
+- Single-line or few-line fixes
+- Adding a single function with clear requirements
+- Tasks where user gave very specific instructions
+- Pure research (use Task tool with Explore agent)
+
+**Plan Quality Checklist** (before ExitPlanMode):
+- [ ] Explored relevant parts of codebase
+- [ ] Identified all files that need changes
+- [ ] Considered existing patterns/conventions
+- [ ] Noted potential risks or breaking changes
+- [ ] Presented clear implementation steps
+- [ ] Got explicit user approval
+
+---
+
 ERROR HANDLING & RECOVERY
 
 When things go wrong, diagnose the issue and provide recovery steps. Follow the general recovery pattern:

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

@@ -91,10 +91,13 @@ class BaseIdeSetup {
    */
   async cleanup(projectDir) {
     if (this.configDir) {
-      const agileflowPath = path.join(projectDir, this.configDir, 'agileflow');
-      if (await fs.pathExists(agileflowPath)) {
-        await fs.remove(agileflowPath);
-        console.log(chalk.dim(`  Removed old AgileFlow configuration from ${this.displayName}`));
+      // Clean up both old (AgileFlow) and new (agileflow) folder names
+      for (const folderName of ['agileflow', 'AgileFlow']) {
+        const agileflowPath = path.join(projectDir, this.configDir, 'commands', folderName);
+        if (await fs.pathExists(agileflowPath)) {
+          await fs.remove(agileflowPath);
+          console.log(chalk.dim(`  Removed old ${folderName} configuration from ${this.displayName}`));
+        }
       }
     }
   }

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

@@ -20,80 +20,111 @@ class ClaudeCodeSetup extends BaseIdeSetup {
   }
 
   /**
-   * Setup Claude Code IDE configuration
-   * @param {string} projectDir - Project directory
-   * @param {string} agileflowDir - AgileFlow installation directory
-   * @param {Object} options - Setup options
+   * Recursively install commands from a source directory
+   * @param {string} sourceDir - Source directory path
+   * @param {string} targetDir - Target directory path
+   * @param {string} agileflowDir - AgileFlow installation directory (for dynamic content)
+   * @param {boolean} injectDynamic - Whether to inject dynamic content (only for top-level commands)
+   * @returns {Promise<{commands: number, subdirs: number}>} Count of installed items
    */
-  async setup(projectDir, agileflowDir, options = {}) {
-    console.log(chalk.hex('#e8683a')(`  Setting up ${this.displayName}...`));
-
-    // Clean up old installation first
-    await this.cleanup(projectDir);
+  async installCommandsRecursive(sourceDir, targetDir, agileflowDir, injectDynamic = false) {
+    let commandCount = 0;
+    let subdirCount = 0;
 
-    // Create .claude/commands/agileflow directory
-    const claudeDir = path.join(projectDir, this.configDir);
-    const commandsDir = path.join(claudeDir, this.commandsDir);
-    const agileflowCommandsDir = path.join(commandsDir, 'AgileFlow');
+    if (!(await this.exists(sourceDir))) {
+      return { commands: 0, subdirs: 0 };
+    }
 
-    await this.ensureDir(agileflowCommandsDir);
+    await this.ensureDir(targetDir);
 
-    // Get commands from AgileFlow installation
-    const commandsSource = path.join(agileflowDir, 'commands');
-    let commandCount = 0;
+    const entries = await fs.readdir(sourceDir, { withFileTypes: true });
 
-    if (await this.exists(commandsSource)) {
-      const commands = await this.scanDirectory(commandsSource, '.md');
+    for (const entry of entries) {
+      const sourcePath = path.join(sourceDir, entry.name);
+      const targetPath = path.join(targetDir, entry.name);
 
-      for (const command of commands) {
-        // Read the original command content
-        let content = await this.readFile(command.path);
+      if (entry.isFile() && entry.name.endsWith('.md')) {
+        // Read and process .md file
+        let content = await this.readFile(sourcePath);
 
-        // Inject dynamic content (agent lists, command lists)
-        content = this.injectDynamicContent(content, agileflowDir);
+        // Inject dynamic content if enabled (for top-level commands)
+        if (injectDynamic) {
+          content = this.injectDynamicContent(content, agileflowDir);
+        }
 
         // Replace docs/ references with custom folder name
         content = this.replaceDocsReferences(content);
 
-        const targetPath = path.join(agileflowCommandsDir, `${command.name}.md`);
         await this.writeFile(targetPath, content);
         commandCount++;
+      } else if (entry.isDirectory()) {
+        // Recursively process subdirectory
+        const subResult = await this.installCommandsRecursive(
+          sourcePath,
+          targetPath,
+          agileflowDir,
+          false // Don't inject dynamic content in subdirectories
+        );
+        commandCount += subResult.commands;
+        subdirCount += 1 + subResult.subdirs;
       }
     }
 
-    // Create agents subdirectory
-    const agileflowAgentsDir = path.join(agileflowCommandsDir, 'agents');
-    await this.ensureDir(agileflowAgentsDir);
+    return { commands: commandCount, subdirs: subdirCount };
+  }
 
-    // Get agents from AgileFlow installation
-    const agentsSource = path.join(agileflowDir, 'agents');
-    let agentCount = 0;
+  /**
+   * Setup Claude Code IDE configuration
+   * @param {string} projectDir - Project directory
+   * @param {string} agileflowDir - AgileFlow installation directory
+   * @param {Object} options - Setup options
+   */
+  async setup(projectDir, agileflowDir, options = {}) {
+    console.log(chalk.hex('#e8683a')(`  Setting up ${this.displayName}...`));
 
-    if (await this.exists(agentsSource)) {
-      const agents = await this.scanDirectory(agentsSource, '.md');
+    // Clean up old installation first
+    await this.cleanup(projectDir);
 
-      for (const agent of agents) {
-        // Read the original agent content
-        let content = await this.readFile(agent.path);
+    // Create .claude/commands/agileflow directory
+    const claudeDir = path.join(projectDir, this.configDir);
+    const commandsDir = path.join(claudeDir, this.commandsDir);
+    const agileflowCommandsDir = path.join(commandsDir, 'agileflow');
 
-        // Replace docs/ references with custom folder name
-        content = this.replaceDocsReferences(content);
+    await this.ensureDir(agileflowCommandsDir);
 
-        const targetPath = path.join(agileflowAgentsDir, `${agent.name}.md`);
-        await this.writeFile(targetPath, content);
-        agentCount++;
-      }
-    }
+    // Recursively install all commands (including subdirectories like agents/, session/)
+    const commandsSource = path.join(agileflowDir, 'commands');
+    const commandResult = await this.installCommandsRecursive(
+      commandsSource,
+      agileflowCommandsDir,
+      agileflowDir,
+      true // Inject dynamic content for top-level commands
+    );
+
+    // Also install agents (they're in a separate directory in agileflowDir)
+    const agentsSource = path.join(agileflowDir, 'agents');
+    const agentsTargetDir = path.join(agileflowCommandsDir, 'agents');
+    const agentResult = await this.installCommandsRecursive(
+      agentsSource,
+      agentsTargetDir,
+      agileflowDir,
+      false // No dynamic content for agents
+    );
+
+    const totalCommands = commandResult.commands + agentResult.commands;
+    const totalSubdirs = commandResult.subdirs + (agentResult.commands > 0 ? 1 : 0) + agentResult.subdirs;
 
     console.log(chalk.green(`  ✓ ${this.displayName} configured:`));
-    console.log(chalk.dim(`    - ${commandCount} commands installed`));
-    console.log(chalk.dim(`    - ${agentCount} agents installed`));
+    console.log(chalk.dim(`    - ${totalCommands} commands installed`));
+    if (totalSubdirs > 0) {
+      console.log(chalk.dim(`    - ${totalSubdirs} subdirectories`));
+    }
     console.log(chalk.dim(`    - Path: ${path.relative(projectDir, agileflowCommandsDir)}`));
 
     return {
       success: true,
-      commands: commandCount,
-      agents: agentCount,
+      commands: totalCommands,
+      subdirs: totalSubdirs,
     };
   }
 }