agileflow 2.30.1 → 2.31.0

package/package.json

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

package/tools/cli/commands/install.js

@@ -9,6 +9,7 @@ const path = require('node:path');
 const { Installer } = require('../installers/core/installer');
 const { IdeManager } = require('../installers/ide/manager');
 const { promptInstall, success, error, info, displaySection } = require('../lib/ui');
+const { createDocsStructure } = require('../lib/docs-setup');
 
 const installer = new Installer();
 const ideManager = new IdeManager();
@@ -31,6 +32,7 @@ module.exports = {
           ides: ['claude-code'],
           userName: 'Developer',
           agileflowFolder: '.agileflow',
+          docsFolder: 'docs',
         };
       } else {
         // Interactive prompts
@@ -55,11 +57,23 @@ module.exports = {
       displaySection('Configuring IDEs');
 
       ideManager.setAgileflowFolder(config.agileflowFolder);
+      ideManager.setDocsFolder(config.docsFolder);
 
       for (const ide of config.ides) {
         await ideManager.setup(ide, config.directory, coreResult.path);
       }
 
+      // Create docs structure
+      displaySection('Creating Documentation Structure', `Folder: ${config.docsFolder}/`);
+      const docsResult = await createDocsStructure(config.directory, config.docsFolder);
+
+      if (!docsResult.success) {
+        error('Failed to create docs structure');
+        if (docsResult.errors.length > 0) {
+          docsResult.errors.forEach((err) => error(`  ${err}`));
+        }
+      }
+
       // Final summary
       console.log(chalk.green('\n✨ Installation complete!\n'));
 

package/tools/cli/commands/update.js

@@ -9,6 +9,7 @@ const path = require('node:path');
 const { Installer } = require('../installers/core/installer');
 const { IdeManager } = require('../installers/ide/manager');
 const { displayLogo, displaySection, success, warning, error, info, confirm } = require('../lib/ui');
+const { createDocsStructure, getDocsFolderName } = require('../lib/docs-setup');
 
 const installer = new Installer();
 const ideManager = new IdeManager();
@@ -60,12 +61,16 @@ module.exports = {
 
       console.log();
 
+      // Get docs folder name from metadata (or default to 'docs')
+      const docsFolder = await getDocsFolderName(directory);
+
       // Re-run installation with existing config
       const config = {
         directory,
         ides: status.ides || ['claude-code'],
         userName: 'Developer', // Could read from existing config
         agileflowFolder: path.basename(status.path),
+        docsFolder,
       };
 
       // Run core installation
@@ -80,11 +85,23 @@ module.exports = {
 
       // Re-setup IDEs
       ideManager.setAgileflowFolder(config.agileflowFolder);
+      ideManager.setDocsFolder(config.docsFolder);
 
       for (const ide of config.ides) {
         await ideManager.setup(ide, directory, status.path);
       }
 
+      // Create/update docs structure (idempotent - only creates missing files)
+      displaySection('Updating Documentation Structure', `Folder: ${docsFolder}/`);
+      const docsResult = await createDocsStructure(directory, docsFolder);
+
+      if (!docsResult.success) {
+        warning('Failed to update docs structure');
+        if (docsResult.errors.length > 0) {
+          docsResult.errors.forEach((err) => error(`  ${err}`));
+        }
+      }
+
       console.log(chalk.green(`\n✨ Update complete! (${status.version} → ${newVersion})\n`));
 
       process.exit(0);

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

@@ -19,6 +19,7 @@ class BaseIdeSetup {
     this.preferred = preferred;
     this.configDir = null; // Override in subclasses
     this.agileflowFolder = '.agileflow';
+    this.docsFolder = 'docs';
   }
 
   /**
@@ -29,6 +30,35 @@ class BaseIdeSetup {
     this.agileflowFolder = folderName;
   }
 
+  /**
+   * Set the docs folder name
+   * @param {string} folderName - The docs folder name
+   */
+  setDocsFolder(folderName) {
+    this.docsFolder = folderName;
+  }
+
+  /**
+   * Replace docs/ references in content with custom folder name
+   * @param {string} content - File content
+   * @returns {string} Updated content
+   */
+  replaceDocsReferences(content) {
+    if (this.docsFolder === 'docs') {
+      return content; // No replacement needed
+    }
+
+    // Replace all variations of docs/ references
+    return content
+      .replace(/docs\//g, `${this.docsFolder}/`)
+      .replace(/`docs\//g, `\`${this.docsFolder}/`)
+      .replace(/"docs\//g, `"${this.docsFolder}/`)
+      .replace(/'docs\//g, `'${this.docsFolder}/`)
+      .replace(/\(docs\//g, `(${this.docsFolder}/`)
+      .replace(/docs\/\)/g, `${this.docsFolder}/)`)
+      .replace(/\bdocs\b(?!\.)/g, this.docsFolder); // Replace standalone "docs" word
+  }
+
   /**
    * Main setup method - must be implemented by subclasses
    * @param {string} projectDir - Project directory

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

@@ -46,11 +46,14 @@ class ClaudeCodeSetup extends BaseIdeSetup {
       const commands = await this.scanDirectory(commandsSource, '.md');
 
       for (const command of commands) {
-        // Create launcher file that references the command
-        const launcherContent = await this.createCommandLauncher(command, agileflowDir, projectDir);
-        const targetPath = path.join(agileflowCommandsDir, `${command.name}.md`);
+        // Read the original command content
+        let content = await this.readFile(command.path);
+
+        // Replace docs/ references with custom folder name
+        content = this.replaceDocsReferences(content);
 
-        await this.writeFile(targetPath, launcherContent);
+        const targetPath = path.join(agileflowCommandsDir, `${command.name}.md`);
+        await this.writeFile(targetPath, content);
         commandCount++;
       }
     }
@@ -67,11 +70,14 @@ class ClaudeCodeSetup extends BaseIdeSetup {
       const agents = await this.scanDirectory(agentsSource, '.md');
 
       for (const agent of agents) {
-        // Create launcher file that references the agent
-        const launcherContent = await this.createAgentLauncher(agent, agileflowDir, projectDir);
-        const targetPath = path.join(agileflowAgentsDir, `${agent.name}.md`);
+        // Read the original agent content
+        let content = await this.readFile(agent.path);
+
+        // Replace docs/ references with custom folder name
+        content = this.replaceDocsReferences(content);
 
-        await this.writeFile(targetPath, launcherContent);
+        const targetPath = path.join(agileflowAgentsDir, `${agent.name}.md`);
+        await this.writeFile(targetPath, content);
         agentCount++;
       }
     }
@@ -87,88 +93,6 @@ class ClaudeCodeSetup extends BaseIdeSetup {
       agents: agentCount,
     };
   }
-
-  /**
-   * Create a command launcher file
-   * @param {Object} command - Command info
-   * @param {string} agileflowDir - AgileFlow directory
-   * @param {string} projectDir - Project directory
-   * @returns {Promise<string>} Launcher content
-   */
-  async createCommandLauncher(command, agileflowDir, projectDir) {
-    // Read the original command file
-    const content = await this.readFile(command.path);
-
-    // Extract description from frontmatter if present
-    const frontmatterMatch = content.match(/^---\n([\s\S]*?)\n---/);
-    let description = command.name;
-
-    if (frontmatterMatch) {
-      const descMatch = frontmatterMatch[1].match(/description:\s*["']?([^"'\n]+)["']?/);
-      if (descMatch) {
-        description = descMatch[1];
-      }
-    }
-
-    // Create launcher that loads the full command
-    const relativePath = path.relative(projectDir, command.path);
-
-    return `---
-description: "${description}"
----
-
-# ${command.name}
-
-Load and execute the AgileFlow command.
-
-\`\`\`
-Read and follow the instructions in: ${relativePath}
-\`\`\`
-`;
-  }
-
-  /**
-   * Create an agent launcher file
-   * @param {Object} agent - Agent info
-   * @param {string} agileflowDir - AgileFlow directory
-   * @param {string} projectDir - Project directory
-   * @returns {Promise<string>} Launcher content
-   */
-  async createAgentLauncher(agent, agileflowDir, projectDir) {
-    // Read the original agent file
-    const content = await this.readFile(agent.path);
-
-    // Extract metadata from frontmatter
-    const frontmatterMatch = content.match(/^---\n([\s\S]*?)\n---/);
-    let description = agent.name;
-    let name = agent.name;
-
-    if (frontmatterMatch) {
-      const descMatch = frontmatterMatch[1].match(/description:\s*["']?([^"'\n]+)["']?/);
-      const nameMatch = frontmatterMatch[1].match(/name:\s*["']?([^"'\n]+)["']?/);
-
-      if (descMatch) description = descMatch[1];
-      if (nameMatch) name = nameMatch[1];
-    }
-
-    // Create launcher that loads the full agent
-    const relativePath = path.relative(projectDir, agent.path);
-
-    return `---
-description: "${description}"
----
-
-# ${name}
-
-Activate the AgileFlow agent.
-
-\`\`\`
-Read and fully embody the agent defined in: ${relativePath}
-
-Follow all instructions, adopt the persona, and use the specified tools.
-\`\`\`
-`;
-  }
 }
 
 module.exports = { ClaudeCodeSetup };

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

@@ -1,8 +1,8 @@
 /**
  * AgileFlow CLI - Cursor IDE Installer
  *
- * Installs AgileFlow rules for Cursor IDE.
- * Cursor uses .mdc (Markdown with Context) files in .cursor/rules/
+ * Installs AgileFlow commands for Cursor IDE.
+ * Cursor uses plain Markdown files in .cursor/commands/
  */
 
 const path = require('node:path');
@@ -15,9 +15,9 @@ const { BaseIdeSetup } = require('./_base-ide');
  */
 class CursorSetup extends BaseIdeSetup {
   constructor() {
-    super('cursor', 'Cursor', true);
+    super('cursor', 'Cursor', false);
     this.configDir = '.cursor';
-    this.rulesDir = 'rules';
+    this.commandsDir = 'commands';
   }
 
   /**
@@ -32,12 +32,12 @@ class CursorSetup extends BaseIdeSetup {
     // Clean up old installation first
     await this.cleanup(projectDir);
 
-    // Create .cursor/rules/agileflow directory
+    // Create .cursor/commands/AgileFlow directory
     const cursorDir = path.join(projectDir, this.configDir);
-    const rulesDir = path.join(cursorDir, this.rulesDir);
-    const agileflowRulesDir = path.join(rulesDir, 'agileflow');
+    const commandsDir = path.join(cursorDir, this.commandsDir);
+    const agileflowCommandsDir = path.join(commandsDir, 'AgileFlow');
 
-    await this.ensureDir(agileflowRulesDir);
+    await this.ensureDir(agileflowCommandsDir);
 
     // Get commands from AgileFlow installation
     const commandsSource = path.join(agileflowDir, 'commands');
@@ -47,17 +47,20 @@ class CursorSetup extends BaseIdeSetup {
       const commands = await this.scanDirectory(commandsSource, '.md');
 
       for (const command of commands) {
-        // Create .mdc file with MDC format
-        const mdcContent = await this.createCommandMdc(command, agileflowDir, projectDir);
-        const targetPath = path.join(agileflowRulesDir, `${command.name}.mdc`);
+        // Read the original command content
+        let content = await this.readFile(command.path);
 
-        await this.writeFile(targetPath, mdcContent);
+        // 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++;
       }
     }
 
     // Create agents subdirectory
-    const agileflowAgentsDir = path.join(agileflowRulesDir, 'agents');
+    const agileflowAgentsDir = path.join(agileflowCommandsDir, 'agents');
     await this.ensureDir(agileflowAgentsDir);
 
     // Get agents from AgileFlow installation
@@ -68,19 +71,22 @@ class CursorSetup extends BaseIdeSetup {
       const agents = await this.scanDirectory(agentsSource, '.md');
 
       for (const agent of agents) {
-        // Create .mdc file with MDC format
-        const mdcContent = await this.createAgentMdc(agent, agileflowDir, projectDir);
-        const targetPath = path.join(agileflowAgentsDir, `${agent.name}.mdc`);
+        // Read the original agent content
+        let content = await this.readFile(agent.path);
+
+        // Replace docs/ references with custom folder name
+        content = this.replaceDocsReferences(content);
 
-        await this.writeFile(targetPath, mdcContent);
+        const targetPath = path.join(agileflowAgentsDir, `${agent.name}.md`);
+        await this.writeFile(targetPath, content);
         agentCount++;
       }
     }
 
     console.log(chalk.green(`  ✓ ${this.displayName} configured:`));
-    console.log(chalk.dim(`    - ${commandCount} rules installed`));
-    console.log(chalk.dim(`    - ${agentCount} agent rules installed`));
-    console.log(chalk.dim(`    - Path: ${path.relative(projectDir, agileflowRulesDir)}`));
+    console.log(chalk.dim(`    - ${commandCount} commands installed`));
+    console.log(chalk.dim(`    - ${agentCount} agents installed`));
+    console.log(chalk.dim(`    - Path: ${path.relative(projectDir, agileflowCommandsDir)}`));
 
     return {
       success: true,
@@ -94,95 +100,18 @@ class CursorSetup extends BaseIdeSetup {
    * @param {string} projectDir - Project directory
    */
   async cleanup(projectDir) {
-    const agileflowPath = path.join(projectDir, this.configDir, this.rulesDir, 'agileflow');
-    if (await this.exists(agileflowPath)) {
-      await fs.remove(agileflowPath);
+    // Remove old .cursor/rules/agileflow (deprecated)
+    const oldRulesPath = path.join(projectDir, this.configDir, 'rules', 'agileflow');
+    if (await this.exists(oldRulesPath)) {
+      await fs.remove(oldRulesPath);
       console.log(chalk.dim(`    Removed old AgileFlow rules from ${this.displayName}`));
     }
-  }
-
-  /**
-   * Create an MDC file for a command
-   * @param {Object} command - Command info
-   * @param {string} agileflowDir - AgileFlow directory
-   * @param {string} projectDir - Project directory
-   * @returns {Promise<string>} MDC content
-   */
-  async createCommandMdc(command, agileflowDir, projectDir) {
-    // Read the original command file
-    const content = await this.readFile(command.path);
-
-    // Extract description from frontmatter if present
-    const frontmatterMatch = content.match(/^---\n([\s\S]*?)\n---/);
-    let description = command.name;
-
-    if (frontmatterMatch) {
-      const descMatch = frontmatterMatch[1].match(/description:\s*["']?([^"'\n]+)["']?/);
-      if (descMatch) {
-        description = descMatch[1];
-      }
-    }
-
-    // Create MDC format with metadata
-    const relativePath = path.relative(projectDir, command.path);
-
-    return `---
-description: "${description}"
-globs: []
-alwaysApply: false
----
-
-# AgileFlow: ${command.name}
-
-Load and execute the AgileFlow command from: ${relativePath}
 
-When this rule is activated, read the full command file and follow its instructions.
-`;
-  }
-
-  /**
-   * Create an MDC file for an agent
-   * @param {Object} agent - Agent info
-   * @param {string} agileflowDir - AgileFlow directory
-   * @param {string} projectDir - Project directory
-   * @returns {Promise<string>} MDC content
-   */
-  async createAgentMdc(agent, agileflowDir, projectDir) {
-    // Read the original agent file
-    const content = await this.readFile(agent.path);
-
-    // Extract metadata from frontmatter
-    const frontmatterMatch = content.match(/^---\n([\s\S]*?)\n---/);
-    let description = agent.name;
-    let name = agent.name;
-
-    if (frontmatterMatch) {
-      const descMatch = frontmatterMatch[1].match(/description:\s*["']?([^"'\n]+)["']?/);
-      const nameMatch = frontmatterMatch[1].match(/name:\s*["']?([^"'\n]+)["']?/);
-
-      if (descMatch) description = descMatch[1];
-      if (nameMatch) name = nameMatch[1];
+    // Remove .cursor/commands/AgileFlow (for re-installation)
+    const commandsPath = path.join(projectDir, this.configDir, this.commandsDir, 'AgileFlow');
+    if (await this.exists(commandsPath)) {
+      await fs.remove(commandsPath);
     }
-
-    // Create MDC format
-    const relativePath = path.relative(projectDir, agent.path);
-
-    return `---
-description: "${description}"
-globs: []
-alwaysApply: false
----
-
-# AgileFlow Agent: ${name}
-
-Activate the AgileFlow agent from: ${relativePath}
-
-When this rule is activated:
-1. Read the full agent file
-2. Adopt the agent's persona and communication style
-3. Follow all instructions and use specified tools
-4. Stay in character until given an exit command
-`;
   }
 }
 

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

@@ -15,6 +15,7 @@ class IdeManager {
   constructor() {
     this.handlers = new Map();
     this.agileflowFolder = '.agileflow';
+    this.docsFolder = 'docs';
     this.loadHandlers();
   }
 
@@ -31,6 +32,19 @@ class IdeManager {
     }
   }
 
+  /**
+   * Set the docs folder name for all IDE handlers
+   * @param {string} folderName - The docs folder name
+   */
+  setDocsFolder(folderName) {
+    this.docsFolder = folderName;
+    for (const handler of this.handlers.values()) {
+      if (typeof handler.setDocsFolder === 'function') {
+        handler.setDocsFolder(folderName);
+      }
+    }
+  }
+
   /**
    * Dynamically load all IDE handlers from directory
    */

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

@@ -47,11 +47,14 @@ class WindsurfSetup extends BaseIdeSetup {
       const commands = await this.scanDirectory(commandsSource, '.md');
 
       for (const command of commands) {
-        // Create workflow file
-        const workflowContent = await this.createCommandWorkflow(command, agileflowDir, projectDir);
-        const targetPath = path.join(agileflowWorkflowsDir, `${command.name}.md`);
+        // Read the original command content
+        let content = await this.readFile(command.path);
+
+        // Replace docs/ references with custom folder name
+        content = this.replaceDocsReferences(content);
 
-        await this.writeFile(targetPath, workflowContent);
+        const targetPath = path.join(agileflowWorkflowsDir, `${command.name}.md`);
+        await this.writeFile(targetPath, content);
         commandCount++;
       }
     }
@@ -68,11 +71,14 @@ class WindsurfSetup extends BaseIdeSetup {
       const agents = await this.scanDirectory(agentsSource, '.md');
 
       for (const agent of agents) {
-        // Create workflow file
-        const workflowContent = await this.createAgentWorkflow(agent, agileflowDir, projectDir);
-        const targetPath = path.join(agileflowAgentsDir, `${agent.name}.md`);
+        // Read the original agent content
+        let content = await this.readFile(agent.path);
+
+        // Replace docs/ references with custom folder name
+        content = this.replaceDocsReferences(content);
 
-        await this.writeFile(targetPath, workflowContent);
+        const targetPath = path.join(agileflowAgentsDir, `${agent.name}.md`);
+        await this.writeFile(targetPath, content);
         agentCount++;
       }
     }
@@ -100,93 +106,6 @@ class WindsurfSetup extends BaseIdeSetup {
       console.log(chalk.dim(`    Removed old AgileFlow workflows from ${this.displayName}`));
     }
   }
-
-  /**
-   * Create a workflow file for a command
-   * @param {Object} command - Command info
-   * @param {string} agileflowDir - AgileFlow directory
-   * @param {string} projectDir - Project directory
-   * @returns {Promise<string>} Workflow content
-   */
-  async createCommandWorkflow(command, agileflowDir, projectDir) {
-    // Read the original command file
-    const content = await this.readFile(command.path);
-
-    // Extract description from frontmatter if present
-    const frontmatterMatch = content.match(/^---\n([\s\S]*?)\n---/);
-    let description = command.name;
-
-    if (frontmatterMatch) {
-      const descMatch = frontmatterMatch[1].match(/description:\s*["']?([^"'\n]+)["']?/);
-      if (descMatch) {
-        description = descMatch[1];
-      }
-    }
-
-    // Create Windsurf workflow format
-    const relativePath = path.relative(projectDir, command.path);
-
-    return `---
-description: ${description}
-auto_execution_mode: 2
----
-
-# AgileFlow: ${command.name}
-
-Load and execute the AgileFlow command.
-
-## Instructions
-
-Read and follow the full command from: \`${relativePath}\`
-
-Execute the command according to its specifications.
-`;
-  }
-
-  /**
-   * Create a workflow file for an agent
-   * @param {Object} agent - Agent info
-   * @param {string} agileflowDir - AgileFlow directory
-   * @param {string} projectDir - Project directory
-   * @returns {Promise<string>} Workflow content
-   */
-  async createAgentWorkflow(agent, agileflowDir, projectDir) {
-    // Read the original agent file
-    const content = await this.readFile(agent.path);
-
-    // Extract metadata from frontmatter
-    const frontmatterMatch = content.match(/^---\n([\s\S]*?)\n---/);
-    let description = agent.name;
-    let name = agent.name;
-
-    if (frontmatterMatch) {
-      const descMatch = frontmatterMatch[1].match(/description:\s*["']?([^"'\n]+)["']?/);
-      const nameMatch = frontmatterMatch[1].match(/name:\s*["']?([^"'\n]+)["']?/);
-
-      if (descMatch) description = descMatch[1];
-      if (nameMatch) name = nameMatch[1];
-    }
-
-    // Create Windsurf workflow format
-    const relativePath = path.relative(projectDir, agent.path);
-
-    return `---
-description: ${description}
-auto_execution_mode: 3
----
-
-# AgileFlow Agent: ${name}
-
-Activate the AgileFlow agent.
-
-## Instructions
-
-1. Read the full agent definition from: \`${relativePath}\`
-2. Adopt the agent's persona and communication style
-3. Follow all instructions and use the specified tools
-4. Maintain the agent's character throughout the session
-`;
-  }
 }
 
 module.exports = { WindsurfSetup };

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

@@ -0,0 +1,425 @@
+/**
+ * AgileFlow CLI - Docs Structure Setup
+ *
+ * Creates the complete AgileFlow docs/ directory structure with README files.
+ * Idempotent - checks for existing files and only creates missing ones.
+ */
+
+const fs = require('fs-extra');
+const path = require('node:path');
+const chalk = require('chalk');
+
+/**
+ * Directory structure to create
+ * @param {string} docsFolder - Name of the docs folder (default: "docs")
+ */
+function getDirectoryStructure(docsFolder = 'docs') {
+  return [
+    `${docsFolder}/00-meta/templates`,
+    `${docsFolder}/00-meta/guides`,
+    `${docsFolder}/00-meta/scripts`,
+    `${docsFolder}/01-brainstorming/ideas`,
+    `${docsFolder}/01-brainstorming/sketches`,
+    `${docsFolder}/02-practices/prompts/agents`,
+    `${docsFolder}/03-decisions`,
+    `${docsFolder}/04-architecture`,
+    `${docsFolder}/05-epics`,
+    `${docsFolder}/06-stories`,
+    `${docsFolder}/07-testing/acceptance`,
+    `${docsFolder}/07-testing/test-cases`,
+    `${docsFolder}/08-project`,
+    `${docsFolder}/09-agents/bus`,
+    `${docsFolder}/10-research`,
+  ];
+}
+
+/**
+ * README content templates
+ * @param {string} docsFolder - Name of the docs folder
+ */
+function getReadmeTemplates(docsFolder = 'docs') {
+  return {
+    [`${docsFolder}/README.md`]: `# AgileFlow Documentation
+
+This directory contains all AgileFlow documentation and project management files.
+
+## Directory Structure
+
+- **00-meta/**: System metadata, templates, and guides
+- **01-brainstorming/**: Ideas and sketches for features
+- **02-practices/**: Project practices, conventions, and standards
+- **03-decisions/**: Architecture Decision Records (ADRs)
+- **04-architecture/**: System architecture documentation
+- **05-epics/**: Epic definitions and planning
+- **06-stories/**: User stories and implementation details
+- **07-testing/**: Test cases and acceptance criteria
+- **08-project/**: Project management (roadmap, backlog, milestones)
+- **09-agents/**: Agent status tracking and communication
+- **10-research/**: Research notes and findings
+
+## Getting Started
+
+Use AgileFlow slash commands to work with these directories:
+- \`/AgileFlow:epic\` - Create a new epic
+- \`/AgileFlow:story\` - Create a user story
+- \`/AgileFlow:status\` - Update story status
+- \`/AgileFlow:help\` - See all available commands
+`,
+
+    [`${docsFolder}/00-meta/README.md`]: `# Meta Documentation
+
+System metadata, templates, and guides for AgileFlow.
+
+## Contents
+
+- **templates/**: Document templates (story, epic, ADR, etc.)
+- **guides/**: How-to guides and best practices
+- **scripts/**: Utility scripts for automation
+- **agileflow-metadata.json**: System configuration and settings
+- **glossary.md**: Project terminology and definitions
+- **conventions.md**: Coding and documentation conventions
+`,
+
+    [`${docsFolder}/01-brainstorming/README.md`]: `# Brainstorming
+
+Ideas and sketches for future features and improvements.
+
+## Contents
+
+- **ideas/**: Feature ideas and proposals
+- **sketches/**: UI/UX sketches and mockups
+
+Use this space to capture thoughts before they become formal stories.
+`,
+
+    [`${docsFolder}/02-practices/README.md`]: `# Project Practices
+
+Project-specific practices, conventions, and standards for YOUR codebase.
+
+## Contents
+
+- **testing.md**: Testing strategies and patterns
+- **git-branching.md**: Git workflow and branching strategy
+- **releasing.md**: Release process and versioning
+- **security.md**: Security practices and guidelines
+- **ci.md**: CI/CD configuration and workflows
+- **prompts/agents/**: Custom agent prompts for this project
+
+**Note**: This is for YOUR project's practices (styling, typography, component patterns, API conventions), NOT AgileFlow system practices (those go in 00-meta/).
+`,
+
+    [`${docsFolder}/03-decisions/README.md`]: `# Architecture Decision Records (ADRs)
+
+Technical decisions, trade-offs, and alternatives considered.
+
+## Format
+
+Use \`/AgileFlow:adr\` to create new decision records.
+
+Each ADR should include:
+- **Context**: What problem are we solving?
+- **Decision**: What did we decide?
+- **Consequences**: What are the impacts?
+`,
+
+    [`${docsFolder}/04-architecture/README.md`]: `# Architecture Documentation
+
+System architecture, data models, API specifications, and technical designs.
+
+## Contents
+
+- Data models and schemas
+- API specifications
+- Component architecture
+- File/directory structure
+- Testing architecture
+- Technical constraints
+
+Use this documentation to maintain architectural context for development.
+`,
+
+    [`${docsFolder}/05-epics/README.md`]: `# Epics
+
+Large features broken down into user stories.
+
+## Format
+
+Use \`/AgileFlow:epic\` to create new epics.
+
+Each epic includes:
+- Epic ID (EP-XXXX)
+- Description and goals
+- Related stories
+- Milestones and timeline
+`,
+
+    [`${docsFolder}/06-stories/README.md`]: `# User Stories
+
+Implementation tasks with acceptance criteria and technical details.
+
+## Format
+
+Use \`/AgileFlow:story\` to create new stories.
+
+Each story includes:
+- Story ID (US-XXXX)
+- Description
+- Acceptance criteria (Given/When/Then)
+- Architecture context
+- Testing strategy
+- Implementation notes
+`,
+
+    [`${docsFolder}/07-testing/README.md`]: `# Testing Documentation
+
+Test cases, acceptance criteria, and testing strategies.
+
+## Contents
+
+- **acceptance/**: Acceptance test definitions
+- **test-cases/**: Detailed test case documentation
+
+Use \`/AgileFlow:tests\` to set up testing infrastructure.
+`,
+
+    [`${docsFolder}/08-project/README.md`]: `# Project Management
+
+Project-level planning and tracking.
+
+## Contents
+
+- **roadmap.md**: Product roadmap and vision
+- **backlog.md**: Prioritized backlog
+- **milestones.md**: Release milestones
+- **risks.md**: Project risks and mitigation strategies
+`,
+
+    [`${docsFolder}/09-agents/README.md`]: `# Agent Status Tracking
+
+Real-time status of stories being worked on by agents.
+
+## Files
+
+- **status.json**: Active stories and recent completions
+- **status-archive.json**: Archived completed stories
+- **bus/log.jsonl**: Agent communication log
+
+Use \`/AgileFlow:status\` to update story status.
+`,
+
+    [`${docsFolder}/10-research/README.md`]: `# Research Notes
+
+Research findings, investigations, and technical explorations.
+
+## Format
+
+Use \`/AgileFlow:research\` to create new research notes.
+
+| Date | Topic | Path | Summary |
+|------|-------|------|---------|
+| | | | |
+`,
+  };
+}
+
+/**
+ * Create docs structure with README files
+ * @param {string} targetDir - Target directory for installation
+ * @param {string} docsFolder - Name of the docs folder (default: "docs")
+ * @returns {Promise<Object>} Result object with counts
+ */
+async function createDocsStructure(targetDir, docsFolder = 'docs') {
+  const result = {
+    success: false,
+    counts: {
+      directoriesCreated: 0,
+      filesCreated: 0,
+      filesSkipped: 0,
+    },
+    errors: [],
+  };
+
+  try {
+    console.log(chalk.cyan(`\nCreating ${docsFolder}/ structure...`));
+
+    // Create directories
+    const directories = getDirectoryStructure(docsFolder);
+    for (const dir of directories) {
+      const fullPath = path.join(targetDir, dir);
+      if (!fs.existsSync(fullPath)) {
+        await fs.ensureDir(fullPath);
+        result.counts.directoriesCreated++;
+      }
+    }
+
+    // Create README files
+    const readmes = getReadmeTemplates(docsFolder);
+    for (const [filePath, content] of Object.entries(readmes)) {
+      const fullPath = path.join(targetDir, filePath);
+      if (!fs.existsSync(fullPath)) {
+        await fs.writeFile(fullPath, content, 'utf8');
+        result.counts.filesCreated++;
+        console.log(chalk.green(`  ✓ Created ${filePath}`));
+      } else {
+        result.counts.filesSkipped++;
+        console.log(chalk.dim(`  ⊘ Skipped ${filePath} (already exists)`));
+      }
+    }
+
+    // Create agileflow-metadata.json
+    const metadataPath = path.join(targetDir, docsFolder, '00-meta', 'agileflow-metadata.json');
+    if (!fs.existsSync(metadataPath)) {
+      const metadata = {
+        version: '2.30.1',
+        created: new Date().toISOString(),
+        updated: new Date().toISOString(),
+        docsFolder: docsFolder,
+        archival: {
+          threshold_days: 30,
+          enabled: true,
+        },
+      };
+      await fs.writeFile(metadataPath, JSON.stringify(metadata, null, 2), 'utf8');
+      result.counts.filesCreated++;
+      console.log(chalk.green(`  ✓ Created ${docsFolder}/00-meta/agileflow-metadata.json`));
+    } else {
+      // Update existing metadata with docsFolder if missing
+      try {
+        const existing = JSON.parse(await fs.readFile(metadataPath, 'utf8'));
+        if (!existing.docsFolder) {
+          existing.docsFolder = docsFolder;
+          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)`));
+        }
+      } catch (err) {
+        console.log(chalk.yellow(`  ⚠ Could not update metadata: ${err.message}`));
+      }
+      result.counts.filesSkipped++;
+    }
+
+    // Create status.json
+    const statusPath = path.join(targetDir, docsFolder, '09-agents', 'status.json');
+    if (!fs.existsSync(statusPath)) {
+      const status = {
+        updated: new Date().toISOString(),
+        stories: {},
+      };
+      await fs.writeFile(statusPath, JSON.stringify(status, null, 2), 'utf8');
+      result.counts.filesCreated++;
+      console.log(chalk.green(`  ✓ Created ${docsFolder}/09-agents/status.json`));
+    } else {
+      result.counts.filesSkipped++;
+      console.log(chalk.dim(`  ⊘ Skipped ${docsFolder}/09-agents/status.json (already exists)`));
+    }
+
+    // Create empty bus log
+    const busLogPath = path.join(targetDir, docsFolder, '09-agents', 'bus', 'log.jsonl');
+    if (!fs.existsSync(busLogPath)) {
+      await fs.writeFile(busLogPath, '', 'utf8');
+      result.counts.filesCreated++;
+      console.log(chalk.green(`  ✓ Created ${docsFolder}/09-agents/bus/log.jsonl`));
+    } else {
+      result.counts.filesSkipped++;
+    }
+
+    // Create basic practice files
+    const practiceFiles = {
+      [`${docsFolder}/02-practices/testing.md`]: `# Testing Practices
+
+Document your testing strategies and patterns here.
+`,
+      [`${docsFolder}/02-practices/git-branching.md`]: `# Git Branching Strategy
+
+Document your git workflow and branching strategy here.
+`,
+      [`${docsFolder}/02-practices/releasing.md`]: `# Release Process
+
+Document your release process and versioning strategy here.
+`,
+      [`${docsFolder}/02-practices/security.md`]: `# Security Practices
+
+Document your security guidelines and practices here.
+`,
+      [`${docsFolder}/02-practices/ci.md`]: `# CI/CD Configuration
+
+Document your CI/CD workflows and configuration here.
+`,
+    };
+
+    for (const [filePath, content] of Object.entries(practiceFiles)) {
+      const fullPath = path.join(targetDir, filePath);
+      if (!fs.existsSync(fullPath)) {
+        await fs.writeFile(fullPath, content, 'utf8');
+        result.counts.filesCreated++;
+        console.log(chalk.green(`  ✓ Created ${filePath}`));
+      } else {
+        result.counts.filesSkipped++;
+      }
+    }
+
+    // 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`));
+    }
+
+    result.success = true;
+    console.log(
+      chalk.green(
+        `\n✨ Docs structure created: ${result.counts.directoriesCreated} directories, ${result.counts.filesCreated} files`
+      )
+    );
+    if (result.counts.filesSkipped > 0) {
+      console.log(chalk.dim(`   ${result.counts.filesSkipped} files skipped (already exist)`));
+    }
+  } catch (err) {
+    result.errors.push(err.message);
+    console.error(chalk.red(`\n✗ Failed to create docs structure: ${err.message}`));
+  }
+
+  return result;
+}
+
+/**
+ * Get the docs folder name from metadata or default
+ * @param {string} targetDir - Target directory
+ * @returns {Promise<string>} Docs folder name
+ */
+async function getDocsFolderName(targetDir) {
+  try {
+    const metadataPath = path.join(targetDir, 'docs', '00-meta', 'agileflow-metadata.json');
+    if (fs.existsSync(metadataPath)) {
+      const metadata = JSON.parse(await fs.readFile(metadataPath, 'utf8'));
+      return metadata.docsFolder || 'docs';
+    }
+  } catch (err) {
+    // Ignore errors, return default
+  }
+  return 'docs';
+}
+
+module.exports = {
+  createDocsStructure,
+  getDocsFolderName,
+};

package/tools/cli/lib/ui.js

@@ -18,12 +18,12 @@ const packageJson = require(packageJsonPath);
  */
 function displayLogo() {
   const logo = `
-   _____         _ __    ________
-  /  _  \\   ____/  |  \\_/   ____/
- /  /_\\  \\ / ___\\  |  |\\____  \\  ____  _  __
-/    |    \\  \\___|__|__/       \\/ __ \\/ \\/ /
-\\____|____/\\____/____ /_______/\\____/ \\__/
-                                              `;
+     _         _ _      _____ _
+    / \\   __ _(_) | ___|  ___| | _____      __
+   / _ \\ / _\` | | |/ _ \\ |_  | |/ _ \\ \\ /\\ / /
+  / ___ \\ (_| | | |  __/  _| | | (_) \\ V  V /
+ /_/   \\_\\__, |_|_|\\___|_|   |_|\\___/ \\_/\\_/
+         |___/                                `;
   console.log(chalk.cyan(logo));
   console.log(chalk.dim(`  AgileFlow v${packageJson.version} - AI-Driven Agile Development\n`));
 }
@@ -152,6 +152,18 @@ async function promptInstall() {
         return true;
       },
     },
+    {
+      type: 'input',
+      name: 'docsFolder',
+      message: 'Documentation folder name:',
+      default: 'docs',
+      validate: (input) => {
+        if (!/^[a-zA-Z0-9._-]+$/.test(input)) {
+          return 'Folder name can only contain letters, numbers, dots, underscores, and hyphens';
+        }
+        return true;
+      },
+    },
   ]);
 
   return {
@@ -159,6 +171,7 @@ async function promptInstall() {
     ides: answers.ides,
     userName: answers.userName,
     agileflowFolder: answers.agileflowFolder,
+    docsFolder: answers.docsFolder,
   };
 }