ai-sprint-kit 1.3.0 → 1.3.1

package/lib/installer.js

@@ -17,64 +17,72 @@ async function checkExisting(targetDir) {
  */
 async function install(targetDir, options = {}) {
   const { force = false, skipInstall = false } = options;
-
   const templateDir = path.join(__dirname, '../templates');
   const claudeDir = path.join(targetDir, '.claude');
 
-  // Remove existing if force flag
-  if (force && await fs.pathExists(claudeDir)) {
-    const spinner = ora('Removing existing .claude/ directory...').start();
-    await fs.remove(claudeDir);
-    spinner.succeed('Removed existing .claude/ directory');
-  }
+  await removeExistingIfForce(claudeDir, force);
 
-  // Copy template directory
   const spinner = ora('Installing framework...').start();
-
   try {
-    // Copy .claude/ directory
-    await fs.copy(
-      path.join(templateDir, '.claude'),
-      claudeDir,
-      { overwrite: force }
-    );
-
-    // Copy root files (including MCP config template)
-    const rootFiles = ['CLAUDE.md', 'README.md', '.mcp.json.example'];
-    for (const file of rootFiles) {
-      const srcPath = path.join(templateDir, file);
-      const destPath = path.join(targetDir, file);
-
-      if (await fs.pathExists(srcPath)) {
-        // Only copy if doesn't exist or force flag
-        if (!await fs.pathExists(destPath) || force) {
-          await fs.copy(srcPath, destPath);
-        }
-      }
-    }
-
-    // Copy docs directory (user guide)
-    const docsDir = path.join(templateDir, 'docs');
-    if (await fs.pathExists(docsDir)) {
-      await fs.copy(docsDir, path.join(targetDir, 'docs'), { overwrite: force });
-    }
-
+    await copyTemplateFiles(templateDir, targetDir, claudeDir, force);
     spinner.succeed('Framework installed');
 
-    // Install skill dependencies
     if (!skipInstall) {
       await installSkillDependencies(claudeDir);
     }
-
-    // Create initial directories
     await createInitialDirs(targetDir);
-
   } catch (error) {
     spinner.fail('Installation failed');
     throw error;
   }
 }
 
+/**
+ * Remove existing .claude/ directory if force flag is set
+ */
+async function removeExistingIfForce(claudeDir, force) {
+  if (force && await fs.pathExists(claudeDir)) {
+    const spinner = ora('Removing existing .claude/ directory...').start();
+    await fs.remove(claudeDir);
+    spinner.succeed('Removed existing .claude/ directory');
+  }
+}
+
+/**
+ * Copy template files to target directory
+ */
+async function copyTemplateFiles(templateDir, targetDir, claudeDir, force) {
+  // Copy .claude/ directory
+  await fs.copy(path.join(templateDir, '.claude'), claudeDir, { overwrite: force });
+
+  // Copy root files
+  await copyRootFiles(templateDir, targetDir, force);
+
+  // Copy user guide to .claude/docs (avoid overwriting user's docs/)
+  const docsDir = path.join(templateDir, 'docs');
+  if (await fs.pathExists(docsDir)) {
+    await fs.copy(docsDir, path.join(claudeDir, 'docs'), { overwrite: force });
+  }
+}
+
+/**
+ * Copy root template files (CLAUDE.md, README.md, etc.)
+ */
+async function copyRootFiles(templateDir, targetDir, force) {
+  const rootFiles = ['CLAUDE.md', 'README.md', '.mcp.json.example'];
+
+  for (const file of rootFiles) {
+    const srcPath = path.join(templateDir, file);
+    const destPath = path.join(targetDir, file);
+
+    if (await fs.pathExists(srcPath)) {
+      if (!await fs.pathExists(destPath) || force) {
+        await fs.copy(srcPath, destPath);
+      }
+    }
+  }
+}
+
 /**
  * Install Python dependencies for skills
  */
@@ -129,19 +137,42 @@ async function createInitialDirs(targetDir) {
     'ai_context/plans',
     'ai_context/docs',
     'ai_context/reports',
-    'ai_context/memory',
-    'docs',
-    'plans',
-    'plans/reports'
+    'ai_context/reports/research',
+    'ai_context/reports/review',
+    'ai_context/reports/security',
+    'ai_context/reports/test',
+    'ai_context/reports/debug',
+    'ai_context/reports/deploy',
+    'ai_context/reports/docs',
+    'ai_context/memory'
   ];
 
   for (const dir of dirs) {
-    const dirPath = path.join(targetDir, dir);
-    await fs.ensureDir(dirPath);
+    await fs.ensureDir(path.join(targetDir, dir));
+  }
+
+  await createMemoryFiles(targetDir);
+}
+
+/**
+ * Create initial memory template files
+ */
+async function createMemoryFiles(targetDir) {
+  const memoryFiles = getMemoryFileTemplates();
+
+  for (const [file, content] of Object.entries(memoryFiles)) {
+    const filePath = path.join(targetDir, file);
+    if (!await fs.pathExists(filePath)) {
+      await fs.writeFile(filePath, content);
+    }
   }
+}
 
-  // Create initial memory files
-  const memoryFiles = {
+/**
+ * Get memory file templates
+ */
+function getMemoryFileTemplates() {
+  return {
     'ai_context/memory/learning.md': `# Learning Log
 
 Lessons learned from past development sessions.
@@ -190,13 +221,6 @@ _None_
 _None_
 `
   };
-
-  for (const [file, content] of Object.entries(memoryFiles)) {
-    const filePath = path.join(targetDir, file);
-    if (!await fs.pathExists(filePath)) {
-      await fs.writeFile(filePath, content);
-    }
-  }
 }
 
 module.exports = {

package/lib/scanner.js

@@ -65,60 +65,43 @@ async function checkRepomix() {
 
 /**
  * Run repomix scan on target directory
- * @param {string} targetDir - Directory to scan
- * @param {string} outputDir - Output directory for scan results
- * @param {object} options - Scan options
- * @returns {Promise<object>} - Scan results
  */
 async function runRepomixScan(targetDir, outputDir, options = {}) {
   const { useNpx = false } = options;
-
-  // Create output directory
   await fs.ensureDir(outputDir);
 
   const xmlOutput = path.join(outputDir, 'repomix-output.xml');
   const mdOutput = path.join(outputDir, 'overview.md');
 
-  // Build base command
-  const baseCmd = useNpx ? 'npx' : 'repomix';
-  const baseArgs = useNpx ? ['repomix'] : [];
+  await runRepomixCommand(targetDir, xmlOutput, 'xml', useNpx);
+  await runRepomixCommand(targetDir, mdOutput, 'markdown', useNpx);
 
-  // Generate XML output (for AI consumption)
-  const xmlArgs = [
-    ...baseArgs,
-    '--compress',
-    '--style', 'xml',
-    '-o', xmlOutput
-  ];
+  return parseRepomixStats(xmlOutput);
+}
 
-  await execa(baseCmd, xmlArgs, {
-    cwd: targetDir,
-    timeout: 300000 // 5 minute timeout
-  });
+/**
+ * Execute repomix command with specified style
+ */
+async function runRepomixCommand(targetDir, outputPath, style, useNpx) {
+  const baseCmd = useNpx ? 'npx' : 'repomix';
+  const baseArgs = useNpx ? ['repomix'] : [];
 
-  // Generate Markdown output (for human reading)
-  const mdArgs = [
-    ...baseArgs,
-    '--compress',
-    '--style', 'markdown',
-    '-o', mdOutput
-  ];
+  const args = [...baseArgs, '--compress', '--style', style, '-o', outputPath];
 
-  await execa(baseCmd, mdArgs, {
+  await execa(baseCmd, args, {
     cwd: targetDir,
     timeout: 300000
   });
+}
 
-  // Parse XML to get stats
-  let stats = {
-    totalFiles: 0,
-    totalTokens: 0,
-    compressedTokens: 0
-  };
+/**
+ * Parse repomix XML output for statistics
+ */
+async function parseRepomixStats(xmlPath) {
+  const stats = { totalFiles: 0, totalTokens: 0, compressedTokens: 0 };
 
   try {
-    const xmlContent = await fs.readFile(xmlOutput, 'utf-8');
-    // Count file entries in XML
+    const xmlContent = await fs.readFile(xmlPath, 'utf-8');
     const fileMatches = xmlContent.match(/<file path="/g);
     if (fileMatches) {
       stats.totalFiles = fileMatches.length;
@@ -256,25 +239,36 @@ async function writeMetadata(outputDir, stats) {
 
 /**
  * Main entry point for codebase scanning
- * @param {string} targetDir - Directory to scan
- * @param {object} options - Scan options
- * @returns {Promise<object>} - Scan results
  */
 async function scanCodebase(targetDir, options = {}) {
   const { silent = false } = options;
   const outputDir = path.join(targetDir, 'ai_context', 'codebase');
-  const startTime = Date.now();
 
-  // Check for source code
+  // Pre-flight checks
+  const preflight = await runPreflightChecks(targetDir, silent);
+  if (preflight.skipped) return preflight;
+
+  const spinner = silent ? null : ora('Scanning codebase...').start();
+
+  try {
+    const result = await executeScan(targetDir, outputDir, preflight.command, spinner);
+    if (spinner) spinner.succeed(`Codebase scanned (${result.stats.totalFiles} files, ${result.stats.duration}s)`);
+    return result;
+  } catch (error) {
+    return handleScanError(error, spinner, silent);
+  }
+}
+
+/**
+ * Run pre-flight checks before scanning
+ */
+async function runPreflightChecks(targetDir, silent) {
   const hasSource = await detectSourceCode(targetDir);
   if (!hasSource) {
-    if (!silent) {
-      console.log(chalk.gray('   No source code detected. Skipping scan.'));
-    }
+    if (!silent) console.log(chalk.gray('   No source code detected. Skipping scan.'));
     return { skipped: true, reason: 'no-source' };
   }
 
-  // Check repomix availability
   const { available, command } = await checkRepomix();
   if (!available) {
     if (!silent) {
@@ -284,54 +278,40 @@ async function scanCodebase(targetDir, options = {}) {
     return { skipped: true, reason: 'no-repomix' };
   }
 
-  const spinner = silent ? null : ora('Scanning codebase...').start();
-
-  try {
-    // Create output directory
-    await fs.ensureDir(outputDir);
-
-    // Create default ignore file
-    await createRepomixIgnore(outputDir);
-
-    // Run repomix scan
-    const useNpx = command.includes('npx');
-    const stats = await runRepomixScan(targetDir, outputDir, { useNpx });
-
-    // Generate structure
-    if (spinner) spinner.text = 'Generating structure...';
-    await generateStructure(targetDir, outputDir);
+  return { skipped: false, command };
+}
 
-    // Calculate duration
-    stats.duration = Math.round((Date.now() - startTime) / 1000 * 10) / 10;
+/**
+ * Execute the actual scan operation
+ */
+async function executeScan(targetDir, outputDir, command, spinner) {
+  const startTime = Date.now();
 
-    // Write metadata
-    const metadata = await writeMetadata(outputDir, stats);
+  await fs.ensureDir(outputDir);
+  await createRepomixIgnore(outputDir);
 
-    if (spinner) {
-      spinner.succeed(`Codebase scanned (${stats.totalFiles} files, ${stats.duration}s)`);
-    }
+  const useNpx = command.includes('npx');
+  const stats = await runRepomixScan(targetDir, outputDir, { useNpx });
 
-    return {
-      success: true,
-      outputDir,
-      stats: metadata
-    };
+  if (spinner) spinner.text = 'Generating structure...';
+  await generateStructure(targetDir, outputDir);
 
-  } catch (error) {
-    if (spinner) {
-      spinner.fail('Codebase scan failed');
-    }
+  stats.duration = Math.round((Date.now() - startTime) / 1000 * 10) / 10;
+  const metadata = await writeMetadata(outputDir, stats);
 
-    if (!silent) {
-      console.log(chalk.yellow(`   ⚠️  ${error.message}`));
-      console.log(chalk.gray('   Run /scan manually after fixing the issue.'));
-    }
+  return { success: true, outputDir, stats: metadata };
+}
 
-    return {
-      success: false,
-      error: error.message
-    };
+/**
+ * Handle scan errors
+ */
+function handleScanError(error, spinner, silent) {
+  if (spinner) spinner.fail('Codebase scan failed');
+  if (!silent) {
+    console.log(chalk.yellow(`   ⚠️  ${error.message}`));
+    console.log(chalk.gray('   Run /scan manually after fixing the issue.'));
   }
+  return { success: false, error: error.message };
 }
 
 module.exports = {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ai-sprint-kit",
-  "version": "1.3.0",
+  "version": "1.3.1",
   "description": "CLI installer for autonomous coding agent framework - security-first, production-grade Claude Code setup",
   "main": "lib/installer.js",
   "bin": {

package/templates/.claude/agents/debugger.md

@@ -80,7 +80,8 @@ ai_context/
 │   ├── learning.md  # Bug patterns to watch for
 │   └── decisions.md # Fix decisions log
 └── reports/
-    └── debug-251224-login-bug.md
+    └── debug/
+        └── debug-251224-login-bug.md
 ```
 
 ## Workflow
@@ -111,7 +112,7 @@ ai_context/
 
 ### Phase 4: Document
 ```
-1. Call Write: ai_context/reports/ai-sprint-debug-{timestamp}-{slug}.md
+1. Call Write: ai_context/reports/debug/ai-sprint-debug-{timestamp}-{slug}.md
 2. Update ai_context/memory/learning.md with new pattern
 ```
 

package/templates/.claude/agents/devops.md

@@ -76,7 +76,8 @@ ai_context/
 │   ├── learning.md  # DevOps lessons learned
 │   └── decisions.md # Infrastructure decisions
 └── reports/
-    └── deploy-251224.md
+    └── deploy/
+        └── deploy-251224.md
 ```
 
 ## Workflow
@@ -108,7 +109,7 @@ ai_context/
 
 ### Phase 4: Documentation
 ```
-1. Call Write: ai_context/reports/ai-sprint-deploy-{timestamp}.md
+1. Call Write: ai_context/reports/deploy/ai-sprint-deploy-{timestamp}.md
 2. Document rollback procedures
 3. Update ai_context/memory/decisions.md
 ```

package/templates/.claude/agents/docs.md

@@ -77,7 +77,8 @@ ai_context/
 ├── memory/
 │   └── learning.md # Documentation lessons
 └── reports/
-    └── docs-audit-251224.md
+    └── docs/
+        └── docs-audit-251224.md
 ```
 
 ## Workflow
@@ -107,7 +108,7 @@ ai_context/
 
 ### Phase 4: Report
 ```
-1. Call Write: ai_context/reports/ai-sprint-docs-audit-{timestamp}.md
+1. Call Write: ai_context/reports/docs/ai-sprint-docs-audit-{timestamp}.md
 2. Document what was updated
 ```
 

package/templates/.claude/agents/researcher.md

@@ -82,7 +82,8 @@ ai_context/
 ├── memory/
 │   └── learning.md # Research lessons learned
 └── reports/
-    └── research-{topic}-251224.md
+    └── research/
+        └── research-{topic}-251224.md
 ```
 
 ## Workflow
@@ -110,7 +111,7 @@ ai_context/
 
 ### Phase 4: Report
 ```
-1. Call Write: ai_context/reports/research-{topic}-{timestamp}.md
+1. Call Write: ai_context/reports/research/research-{topic}-{timestamp}.md
 2. Include all citations with links
 3. Provide actionable recommendations
 ```

package/templates/.claude/agents/reviewer.md

@@ -107,7 +107,8 @@ ai_context/
 │   ├── learning.md  # Review lessons learned
 │   └── decisions.md # Code decisions log
 └── reports/
-    └── review-251224.md
+    └── review/
+        └── review-251224.md
 ```
 
 ## Workflow
@@ -131,7 +132,7 @@ ai_context/
 
 ### Phase 3: Reporting
 ```
-1. Call Write: ai_context/reports/ai-sprint-review-{timestamp}.md
+1. Call Write: ai_context/reports/review/ai-sprint-review-{timestamp}.md
 2. Categorize by severity (Critical/High/Medium/Low)
 3. Provide before/after code examples
 4. Include rationale for each suggestion

package/templates/.claude/agents/security.md

@@ -77,7 +77,8 @@ ai_context/
 │   ├── learning.md   # Past security issues to watch for
 │   └── decisions.md  # Security decisions log
 └── reports/
-    └── security-251224-2115.md  # Security scan results
+    └── security/
+        └── security-251224-2115.md  # Security scan results
 ```
 
 ## Workflow
@@ -100,7 +101,7 @@ ai_context/
 
 ### Phase 3: Reporting
 ```
-1. Call Write: ai_context/reports/security-{timestamp}.md
+1. Call Write: ai_context/reports/security/security-{timestamp}.md
 2. Include severity ratings and fixes
 3. Update ai_context/memory/learning.md if new patterns found
 ```

package/templates/.claude/agents/tester.md

@@ -119,7 +119,8 @@ ai_context/
 ├── memory/
 │   └── learning.md # Testing lessons learned
 └── reports/
-    └── test-coverage-251224.md
+    └── test/
+        └── test-coverage-251224.md
 ```
 
 ## Workflow
@@ -150,7 +151,7 @@ ai_context/
 
 ### Phase 4: Reporting
 ```
-1. Call Write: ai_context/reports/ai-sprint-test-coverage-{timestamp}.md
+1. Call Write: ai_context/reports/test/ai-sprint-test-coverage-{timestamp}.md
 2. Document coverage metrics
 3. Note gaps and recommendations
 ```

package/templates/.claude/commands/ai-sprint-debug.md

@@ -252,11 +252,11 @@ Before debugging:
 
 After debugging:
 - Update `ai_context/memory/learning.md` with new bug pattern
-- Save report to `ai_context/reports/ai-sprint-debug-{timestamp}-{slug}.md`
+- Save report to `ai_context/reports/debug/ai-sprint-debug-{timestamp}-{slug}.md`
 
 ## Debug Report
 
-Save to: `ai_context/reports/ai-sprint-debug-YYMMDD-slug.md`
+Save to: `ai_context/reports/debug/ai-sprint-debug-YYMMDD-slug.md`
 
 ```markdown
 # Bug Fix Report

package/templates/CLAUDE.md

@@ -118,11 +118,14 @@ project/
 ├── ai_context/              # AI artifacts (not project code)
 │   ├── plans/               # Implementation plans
 │   ├── docs/                # AI-generated documentation
-│   ├── reports/             # Agent outputs
-│   │   ├── review-*.md      # Code review reports
-│   │   ├── test-*.md        # Test coverage reports
-│   │   ├── security-*.md    # Security scan results
-│   │   └── debug-*.md       # Debugging analysis
+│   ├── reports/             # Agent outputs (organized by type)
+│   │   ├── research/        # Research reports
+│   │   ├── review/          # Code review reports
+│   │   ├── security/        # Security scan results
+│   │   ├── test/            # Test coverage reports
+│   │   ├── debug/           # Debugging analysis
+│   │   ├── deploy/          # Deployment reports
+│   │   └── docs/            # Documentation audit reports
 │   └── memory/
 │   │   ├── learning.md      # Lessons learned
 │   │   ├── decisions.md     # Key decisions

package/templates/docs/user-guide-th.md

@@ -337,11 +337,11 @@ git commit -m "เพิ่มฟีเจอร์ใหม่"
 
 ### 3. อ่านรายงานที่ AI สร้าง
 
-AI จะบันทึกผลการทำงานไว้ใน `ai_context/reports/`
+AI จะบันทึกผลการทำงานไว้ใน `ai_context/reports/` (แยกโฟลเดอร์ตามประเภท)
 
 ```bash
 # ดูรายงานความปลอดภัย
-cat ai_context/reports/security-*.md
+cat ai_context/reports/security/
 ```
 
 ### 4. ใช้ /ai-sprint-auto สำหรับงานง่ายๆ
@@ -391,7 +391,7 @@ cat ai_context/reports/security-*.md
 
 ```bash
 # ดูรายงาน
-cat ai_context/reports/security-*.md
+cat ai_context/reports/security/
 
 # แก้ไข
 /ai-sprint-code "แก้ไขปัญหาความปลอดภัยตามรายงาน"

package/templates/docs/user-guide.md

@@ -105,7 +105,7 @@ For more control over each phase:
 ```bash
 # Step 1: Investigate the issue
 /ai-sprint-debug "users getting 500 error when submitting registration form"
-# Review the analysis in ai_context/reports/
+# Review the analysis in ai_context/reports/debug/
 
 # Step 2: Implement the fix
 /ai-sprint-code "fix the registration error based on debug analysis"
@@ -124,7 +124,7 @@ For more control over each phase:
 # Scan specific directory
 /ai-sprint-secure src/auth/
 
-# Review findings in ai_context/reports/security-*.md
+# Review findings in ai_context/reports/security/
 ```
 
 ### Tutorial 5: Pre-Commit Validation
@@ -211,7 +211,7 @@ Generates tests and runs them with coverage.
 /ai-sprint-test "add integration tests for payment API"
 ```
 
-**Output:** `ai_context/reports/test-*.md`
+**Output:** `ai_context/reports/test/`
 
 **Requirements:** 80%+ coverage required.
 
@@ -230,7 +230,7 @@ Analyzes code quality and best practices.
 /ai-sprint-review src/auth/login.ts
 ```
 
-**Output:** `ai_context/reports/review-*.md`
+**Output:** `ai_context/reports/review/`
 
 **Checks:**
 - Code quality and patterns
@@ -254,7 +254,7 @@ Comprehensive security analysis.
 /ai-sprint-secure src/auth/
 ```
 
-**Output:** `ai_context/reports/security-*.md`
+**Output:** `ai_context/reports/security/`
 
 **Scans:**
 - SAST (static analysis)
@@ -310,7 +310,7 @@ Investigates issues and bugs.
 /ai-sprint-debug "slow API response times on /users endpoint"
 ```
 
-**Output:** `ai_context/reports/debug-*.md`
+**Output:** `ai_context/reports/debug/`
 
 **Provides:**
 - Root cause analysis
@@ -475,8 +475,8 @@ After every `/ai-sprint-secure` scan:
 
 ```bash
 # Check reports
-ls ai_context/reports/security-*.md
-cat ai_context/reports/security-latest.md
+ls ai_context/reports/security/
+cat ai_context/reports/security/security-*.md
 ```
 
 ### 5. Configure MCP Tools
@@ -532,7 +532,7 @@ For complex features, maintain control:
 
 ```bash
 # View the report
-cat ai_context/reports/security-*.md
+cat ai_context/reports/security/
 
 # Fix issues
 /ai-sprint-code "fix security issues from the security scan"