agileflow 2.33.1 → 2.35.0

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

@@ -27,7 +27,7 @@ class CursorSetup extends BaseIdeSetup {
    * @param {Object} options - Setup options
    */
   async setup(projectDir, agileflowDir, options = {}) {
-    console.log(chalk.hex('#C15F3C')(`  Setting up ${this.displayName}...`));
+    console.log(chalk.hex('#e8683a')(`  Setting up ${this.displayName}...`));
 
     // Clean up old installation first
     await this.cleanup(projectDir);

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

@@ -27,7 +27,7 @@ class WindsurfSetup extends BaseIdeSetup {
    * @param {Object} options - Setup options
    */
   async setup(projectDir, agileflowDir, options = {}) {
-    console.log(chalk.hex('#C15F3C')(`  Setting up ${this.displayName}...`));
+    console.log(chalk.hex('#e8683a')(`  Setting up ${this.displayName}...`));
 
     // Clean up old installation first
     await this.cleanup(projectDir);

package/tools/cli/lib/docs-setup.js

@@ -9,6 +9,10 @@ const fs = require('fs-extra');
 const path = require('node:path');
 const chalk = require('chalk');
 
+// Load AgileFlow version from package.json (used for docs metadata)
+const packageJsonPath = path.join(__dirname, '..', '..', '..', 'package.json');
+const packageJson = require(packageJsonPath);
+
 /**
  * Directory structure to create
  * @param {string} docsFolder - Name of the docs folder (default: "docs")
@@ -226,9 +230,12 @@ Use \`/AgileFlow:research\` to create new research notes.
  * Create docs structure with README files
  * @param {string} targetDir - Target directory for installation
  * @param {string} docsFolder - Name of the docs folder (default: "docs")
+ * @param {Object} options - Options
+ * @param {boolean} options.updateGitignore - Whether to create/update .gitignore (default: true)
  * @returns {Promise<Object>} Result object with counts
  */
-async function createDocsStructure(targetDir, docsFolder = 'docs') {
+async function createDocsStructure(targetDir, docsFolder = 'docs', options = {}) {
+  const { updateGitignore = true } = options;
   const result = {
     success: false,
     counts: {
@@ -240,7 +247,7 @@ async function createDocsStructure(targetDir, docsFolder = 'docs') {
   };
 
   try {
-    console.log(chalk.hex('#C15F3C')(`\nCreating ${docsFolder}/ structure...`));
+    console.log(chalk.hex('#e8683a')(`\nCreating ${docsFolder}/ structure...`));
 
     // Create directories
     const directories = getDirectoryStructure(docsFolder);
@@ -270,7 +277,7 @@ async function createDocsStructure(targetDir, docsFolder = 'docs') {
     const metadataPath = path.join(targetDir, docsFolder, '00-meta', 'agileflow-metadata.json');
     if (!fs.existsSync(metadataPath)) {
       const metadata = {
-        version: '2.30.1',
+        version: packageJson.version,
         created: new Date().toISOString(),
         updated: new Date().toISOString(),
         docsFolder: docsFolder,
@@ -283,14 +290,29 @@ async function createDocsStructure(targetDir, docsFolder = 'docs') {
       result.counts.filesCreated++;
       console.log(chalk.green(`  ✓ Created ${docsFolder}/00-meta/agileflow-metadata.json`));
     } else {
-      // Update existing metadata with docsFolder if missing
+      // Update existing metadata (keep docsFolder and version in sync)
       try {
         const existing = JSON.parse(await fs.readFile(metadataPath, 'utf8'));
+        const updates = [];
+
         if (!existing.docsFolder) {
           existing.docsFolder = docsFolder;
+          updates.push('docsFolder');
+        }
+
+        if (existing.version !== packageJson.version) {
+          existing.version = packageJson.version;
+          updates.push('version');
+        }
+
+        if (updates.length > 0) {
           existing.updated = new Date().toISOString();
           await fs.writeFile(metadataPath, JSON.stringify(existing, null, 2), 'utf8');
-          console.log(chalk.yellow(`  ↻ Updated ${docsFolder}/00-meta/agileflow-metadata.json (added docsFolder)`));
+          console.log(
+            chalk.yellow(
+              `  ↻ Updated ${docsFolder}/00-meta/agileflow-metadata.json (${updates.join(', ')})`
+            )
+          );
         }
       } catch (err) {
         console.log(chalk.yellow(`  ⚠ Could not update metadata: ${err.message}`));
@@ -358,30 +380,32 @@ Document your CI/CD workflows and configuration here.
       }
     }
 
-    // Create .gitignore additions for docs folder
-    const gitignorePath = path.join(targetDir, '.gitignore');
-    const gitignoreEntries = [
-      '.env',
-      '.env.*',
-      '!.env.example',
-      '.DS_Store',
-      'node_modules/',
-      'dist/',
-      'build/',
-      'coverage/',
-    ];
-
-    if (fs.existsSync(gitignorePath)) {
-      const existingGitignore = await fs.readFile(gitignorePath, 'utf8');
-      const newEntries = gitignoreEntries.filter(entry => !existingGitignore.includes(entry));
-      if (newEntries.length > 0) {
-        await fs.appendFile(gitignorePath, '\n' + newEntries.join('\n') + '\n', 'utf8');
-        console.log(chalk.yellow(`  ↻ Updated .gitignore with ${newEntries.length} entries`));
+    if (updateGitignore) {
+      // Create .gitignore additions for docs folder
+      const gitignorePath = path.join(targetDir, '.gitignore');
+      const gitignoreEntries = [
+        '.env',
+        '.env.*',
+        '!.env.example',
+        '.DS_Store',
+        'node_modules/',
+        'dist/',
+        'build/',
+        'coverage/',
+      ];
+
+      if (fs.existsSync(gitignorePath)) {
+        const existingGitignore = await fs.readFile(gitignorePath, 'utf8');
+        const newEntries = gitignoreEntries.filter((entry) => !existingGitignore.includes(entry));
+        if (newEntries.length > 0) {
+          await fs.appendFile(gitignorePath, '\n' + newEntries.join('\n') + '\n', 'utf8');
+          console.log(chalk.yellow(`  ↻ Updated .gitignore with ${newEntries.length} entries`));
+        }
+      } else {
+        await fs.writeFile(gitignorePath, gitignoreEntries.join('\n') + '\n', 'utf8');
+        result.counts.filesCreated++;
+        console.log(chalk.green(`  ✓ Created .gitignore`));
       }
-    } else {
-      await fs.writeFile(gitignorePath, gitignoreEntries.join('\n') + '\n', 'utf8');
-      result.counts.filesCreated++;
-      console.log(chalk.green(`  ✓ Created .gitignore`));
     }
 
     result.success = true;

package/tools/cli/lib/npm-utils.js

@@ -0,0 +1,62 @@
+/**
+ * AgileFlow CLI - npm Registry Utilities
+ *
+ * Utilities for interacting with the npm registry.
+ */
+
+const https = require('https');
+
+/**
+ * Get the latest version of a package from npm registry
+ * @param {string} packageName - Name of the package
+ * @returns {Promise<string|null>} Latest version or null if error
+ */
+async function getLatestVersion(packageName) {
+  return new Promise((resolve) => {
+    const options = {
+      hostname: 'registry.npmjs.org',
+      port: 443,
+      path: `/${packageName}/latest`,
+      method: 'GET',
+      headers: {
+        'User-Agent': 'agileflow-cli',
+      },
+    };
+
+    const req = https.request(options, (res) => {
+      let data = '';
+
+      res.on('data', (chunk) => {
+        data += chunk;
+      });
+
+      res.on('end', () => {
+        try {
+          if (res.statusCode === 200) {
+            const json = JSON.parse(data);
+            resolve(json.version || null);
+          } else {
+            resolve(null);
+          }
+        } catch (err) {
+          resolve(null);
+        }
+      });
+    });
+
+    req.on('error', () => {
+      resolve(null);
+    });
+
+    req.setTimeout(5000, () => {
+      req.destroy();
+      resolve(null);
+    });
+
+    req.end();
+  });
+}
+
+module.exports = {
+  getLatestVersion,
+};

package/tools/cli/lib/ui.js

@@ -24,7 +24,7 @@ function displayLogo() {
 ██╔══██║██║   ██║██║██║     ██╔══╝  ██╔══╝  ██║     ██║   ██║██║███╗██║
 ██║  ██║╚██████╔╝██║███████╗███████╗██║     ███████╗╚██████╔╝╚███╔███╔╝
 ╚═╝  ╚═╝ ╚═════╝ ╚═╝╚══════╝╚══════╝╚═╝     ╚══════╝ ╚═════╝  ╚══╝╚══╝ `;
-  console.log(chalk.hex('#C15F3C')(logo));
+  console.log(chalk.hex('#e8683a')(logo));
   console.log(chalk.dim(`  AgileFlow v${packageJson.version} - AI-Driven Agile Development\n`));
 }
 
@@ -34,7 +34,7 @@ function displayLogo() {
  * @param {string} subtitle - Optional subtitle
  */
 function displaySection(title, subtitle = null) {
-  console.log(chalk.bold.hex('#C15F3C')(`\n${title}`));
+  console.log(chalk.bold.hex('#e8683a')(`\n${title}`));
   if (subtitle) {
     console.log(chalk.dim(subtitle));
   }
@@ -164,6 +164,12 @@ async function promptInstall() {
         return true;
       },
     },
+    {
+      type: 'confirm',
+      name: 'updateGitignore',
+      message: 'Create/update .gitignore with recommended entries?',
+      default: true,
+    },
   ]);
 
   return {
@@ -172,6 +178,7 @@ async function promptInstall() {
     userName: answers.userName,
     agileflowFolder: answers.agileflowFolder,
     docsFolder: answers.docsFolder,
+    updateGitignore: answers.updateGitignore,
   };
 }
 

package/tools/postinstall.js

@@ -31,6 +31,19 @@ function shouldSkipInstall() {
     return true;
   }
 
+  // Skip in CI environments
+  if (process.env.CI === 'true' || process.env.CI === '1') {
+    log('ℹ️  Skipping auto-install (CI environment detected)', 'dim');
+    return true;
+  }
+
+  // Skip if installed globally
+  if (process.env.npm_config_global === 'true') {
+    log('ℹ️  Skipping auto-install (global installation)', 'dim');
+    log('   Run "agileflow setup" in your project directory instead', 'dim');
+    return true;
+  }
+
   // Skip if running in npm cache or npx temp directory
   if (__dirname.includes('_npx') || __dirname.includes('.npm')) {
     log('ℹ️  Skipping auto-install (npm cache or npx temp directory)', 'dim');
@@ -90,7 +103,7 @@ function shouldSkipInstall() {
   return false;
 }
 
-function runAutoInstall() {
+async function runAutoInstall() {
   try {
     console.log(''); // Blank line for spacing
     log('━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━', 'blue');
@@ -98,9 +111,6 @@ function runAutoInstall() {
     log('━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━', 'blue');
     console.log('');
 
-    log('🚀 Setting up AgileFlow in your project...', 'green');
-    console.log('');
-
     // Path to the CLI
     const cliPath = path.join(__dirname, 'cli', 'agileflow-cli.js');
 
@@ -109,11 +119,57 @@ function runAutoInstall() {
       return;
     }
 
-    // Run setup command with --yes flag (non-interactive)
-    execSync(`node "${cliPath}" setup --yes`, {
-      stdio: 'inherit',
-      cwd: process.cwd(),
-    });
+    // Check if running in interactive mode (TTY)
+    const isInteractive = process.stdin.isTTY && process.stdout.isTTY;
+
+    if (isInteractive) {
+      // Interactive mode: ask for confirmation
+      console.log('AgileFlow can set up automatically in your project now.');
+      console.log('');
+      console.log('Options:');
+      console.log('  1) Run setup now (recommended)');
+      console.log('  2) Skip setup for now (run "npx agileflow setup" later)');
+      console.log('');
+
+      // Use readline for simple input
+      const readline = require('readline').createInterface({
+        input: process.stdin,
+        output: process.stdout,
+      });
+
+      const answer = await new Promise((resolve) => {
+        readline.question('Choose an option (1 or 2): ', (ans) => {
+          readline.close();
+          resolve(ans.trim());
+        });
+      });
+
+      console.log('');
+
+      if (answer !== '1') {
+        log('ℹ️  Setup skipped. Run "npx agileflow setup" when ready.', 'dim');
+        console.log('');
+        return;
+      }
+
+      log('🚀 Setting up AgileFlow in your project...', 'green');
+      console.log('');
+
+      // Run setup command (interactive mode, no --yes flag)
+      execSync(`node "${cliPath}" setup`, {
+        stdio: 'inherit',
+        cwd: process.cwd(),
+      });
+    } else {
+      // Non-interactive mode (e.g., npm install in scripts): run with --yes
+      log('🚀 Setting up AgileFlow in your project...', 'green');
+      console.log('');
+
+      execSync(`node "${cliPath}" setup --yes`, {
+        stdio: 'inherit',
+        cwd: process.cwd(),
+      });
+    }
 
     console.log('');
     log('✨ AgileFlow is ready to use!', 'green');
@@ -134,8 +190,10 @@ function runAutoInstall() {
 }
 
 // Main execution
-if (shouldSkipInstall()) {
-  process.exit(0);
-}
+(async () => {
+  if (shouldSkipInstall()) {
+    process.exit(0);
+  }
 
-runAutoInstall();
+  await runAutoInstall();
+})();

package/src/core/agents/context7.md

@@ -1,164 +0,0 @@
----
-name: context7
-description: Use this agent when you need to fetch and utilize documentation from Context7 for specific libraries or frameworks to get current, accurate documentation without consuming main context tokens.
-tools: Read, Write, Edit, Bash
-color: yellow
-model: haiku
----
-
-# AgileFlow Context7 Documentation Specialist
-
-## Purpose
-
-This agent specializes in fetching and presenting current, accurate documentation for libraries and frameworks through Context7. It keeps your main conversation context clean by handling documentation lookups in isolation, ensuring you get the most up-to-date guidance without token bloat from MCP calls.
-
-## When to Use This Agent
-
-**Use context7 when you need**:
-- Current documentation for a specific library or framework
-- Implementation guidance based on latest docs (React, Vue, Express, MongoDB, etc.)
-- Multi-library integration help with accurate documentation
-- Best practices and current API reference information
-- Code examples reflecting current versions
-
-**Examples of When to Invoke**:
-
-```
-User: "I need to implement authentication with JWT in Express.js"
-Assistant: "Use the context7 agent to fetch the latest Express.js and authentication documentation"
-
-User: "How do I use React Server Components in Next.js?"
-Assistant: "Use the context7 agent to get current Next.js Server Component documentation"
-
-User: "What's the best way to set up MongoDB with Mongoose?"
-Assistant: "Use the context7 agent to fetch the latest MongoDB and Mongoose setup guides"
-```
-
-## Agent Responsibilities
-
-### 1. Identify Required Documentation
-- Parse user requests to identify all relevant libraries/frameworks
-- Recognize technology stack and dependencies
-- Understand the specific problem or use case
-
-### 2. Resolve and Fetch Documentation
-- Convert library names to Context7-compatible identifiers
-- Use targeted topic parameters for focused queries
-- Fetch with appropriate token limits (default 10000, increase for complex topics)
-
-### 3. Provide Comprehensive Guidance
-- Deliver clear, actionable explanations based on current docs
-- Include code examples reflecting current best practices
-- Provide step-by-step implementation guidance
-- Highlight relevant warnings and considerations
-
-### 4. Handle Multiple Libraries
-- Prioritize the primary library first
-- Fetch each library's documentation separately
-- Show integrated guidance for multi-library workflows
-
-### 5. Optimize Queries
-- Be specific about required functionality
-- Focus on actual use cases
-- Structure requests for accuracy
-
-## How Subagents Work with Context7
-
-**Before (Main Context Heavy)**:
-```
-User → Main Agent (fetches docs via MCP) → Main context bloated with doc tokens
-```
-
-**After (Isolated Context)**:
-```
-User → Main Agent → "Use context7" → Context7 Agent (isolated docs lookup)
-       ↓
-Returns focused documentation guidance without consuming main context
-```
-
-## Communication Protocol
-
-When the Context7 agent completes its work, it will:
-
-1. **Return Documentation Summary**:
-   - Key findings from Context7 lookup
-   - Relevant code examples
-   - Implementation steps
-
-2. **Highlight Warnings**:
-   - Breaking changes in recent versions
-   - Deprecated patterns
-   - Best practices to follow
-
-3. **Provide Next Steps**:
-   - Clear action items for the user
-   - References to documentation
-   - Suggestions for further learning
-
-## Quality Checklist
-
-Your documentation research is complete when:
-- [ ] All relevant libraries identified and documented
-- [ ] Code examples included and current
-- [ ] Step-by-step implementation provided
-- [ ] Warnings and considerations listed
-- [ ] Links to official documentation included
-- [ ] Use case clearly addressed
-- [ ] Alternative approaches mentioned if applicable
-
-## Examples
-
-### Single Library Query
-**User Request**: "How do I set up authentication in Express?"
-
-**Agent Process**:
-1. Identify Express.js as primary library
-2. Resolve to Context7 identifier
-3. Fetch documentation for "authentication" topic
-4. Return setup steps and code examples from current Express docs
-
-### Multi-Library Query
-**User Request**: "How do I connect my React app to a Node/Express backend with authentication?"
-
-**Agent Process**:
-1. Identify React + Express + Authentication
-2. Fetch React docs (state management, API calls)
-3. Fetch Express docs (authentication middleware)
-4. Fetch OAuth/JWT documentation
-5. Provide integrated implementation guide
-
-### Framework-Specific Query
-**User Request**: "What's the best way to handle forms in Next.js 14?"
-
-**Agent Process**:
-1. Identify Next.js 14 as specific version requirement
-2. Fetch Server Actions documentation
-3. Fetch Form handling best practices
-4. Provide Next.js-specific implementation with current APIs
-
-## Integration with AgileFlow
-
-This agent works with other AgileFlow agents:
-
-- **mentor**: References Context7 agent for accurate implementation guidance
-- **epic-planner**: Uses for estimating complexity based on documentation
-- **research**: Complements research notes with current documentation
-- **devops**: References for dependency management and version guidance
-
-## Notes
-
-- Always mention you're using Context7 to ensure documentation accuracy
-- If documentation seems incomplete, suggest refining queries with more targeted keywords
-- Break complex requests into smaller, focused documentation lookups
-- Keep main conversation focused on implementation, not documentation lookup overhead
-- Document findings in `docs/10-research/` for team reference
-
-## Why This Matters
-
-By isolating Context7 documentation fetches:
-- ✅ Main conversation stays focused on implementation
-- ✅ Token budget preserved for actual coding work
-- ✅ Documentation lookups don't clutter decision history
-- ✅ Multiple docs can be fetched without context explosion
-- ✅ Users get focused, accurate guidance on each library
-- ✅ Clear separation of concerns (docs vs. implementation)