ai-sprint-kit 1.1.0

package/README.md

@@ -0,0 +1,299 @@
+# AI Sprint
+
+**One-command installer for Claude Code autonomous development framework**
+
+## Features
+
+- 🤖 **9 Specialized Agents** - Planner, Implementer, Tester, Reviewer, Security, DevOps, Docs, Debugger, Researcher
+- ⚡ **11 Essential Commands** - `/plan`, `/code`, `/test`, `/review`, `/secure`, `/deploy`, `/docs`, `/debug`, `/scan`, `/validate`, `/auto`
+- 🔒 **Security-First** - Built-in SAST, secret detection, dependency scanning
+- 🚀 **Production-Ready** - OWASP Top 10 compliance, security best practices
+- 🎯 **Autonomous** - Full development cycle with human-in-the-loop gates
+- 🧠 **Context Engineering** - Memory system for learning across sessions
+- 📁 **Codebase Scanning** - Auto-scan existing code with 70% token compression
+- 📊 **Custom Statusline** - Real-time context, cost, and session tracking
+
+## Installation
+
+### Quick Start (Recommended)
+
+```bash
+npx ai-sprint init
+```
+
+### Global Installation
+
+```bash
+npm install -g ai-sprint
+ai-sprint init
+```
+
+### Options
+
+```bash
+# Install in specific directory
+npx ai-sprint init --dir /path/to/project
+
+# Force overwrite existing .claude/
+npx ai-sprint init --force
+
+# Skip Python dependencies
+npx ai-sprint init --skip-install
+
+# Scan existing codebase (auto-detected if source exists)
+npx ai-sprint init --scan
+
+# Skip codebase scanning
+npx ai-sprint init --no-scan
+```
+
+## What Gets Installed
+
+```
+your-project/
+├── .claude/
+│   ├── agents/          # 9 specialized agents
+│   ├── commands/        # 11 slash commands
+│   ├── skills/          # Security scanning scripts
+│   ├── workflows/       # Development rules
+│   ├── settings.json    # Configuration
+│   ├── statusline.sh    # Terminal statusline script
+│   └── .env.example     # Environment template
+├── ai_context/          # AI context & artifacts
+│   ├── plans/           # Implementation plans
+│   ├── docs/            # AI-generated docs
+│   ├── reports/         # Agent outputs
+│   ├── codebase/        # Scanned codebase context (if --scan)
+│   └── memory/          # Learning & decisions
+├── CLAUDE.md            # Framework instructions
+└── README.md            # User guide
+```
+
+## Usage After Installation
+
+```bash
+# Start Claude Code
+claude
+
+# Use commands
+/plan "implement user authentication"
+/code "build the authentication system"
+/test "generate and run tests"
+/secure "run security scans"
+/auto "full autonomous cycle"
+```
+
+## Agents
+
+| Agent | Purpose |
+|-------|---------|
+| **planner** | Research & create implementation plans |
+| **implementer** | Generate production-grade code |
+| **tester** | Create and run automated tests |
+| **reviewer** | Code quality and best practices review |
+| **security** | SAST, secret detection, dependency scanning |
+| **devops** | CI/CD setup and deployment |
+| **docs** | Generate documentation |
+| **debugger** | Root cause analysis and fixes |
+| **researcher** | Technology research with web search |
+
+## Commands
+
+| Command | Description | Example |
+|---------|-------------|---------|
+| `/plan` | Create implementation plan | `/plan "add payment processing"` |
+| `/code` | Generate/refactor code | `/code "implement OAuth2 login"` |
+| `/test` | Generate and run tests | `/test` |
+| `/review` | Code quality review | `/review src/` |
+| `/secure` | Security scan | `/secure` |
+| `/deploy` | CI/CD setup | `/deploy --platform github` |
+| `/docs` | Generate documentation | `/docs` |
+| `/debug` | Investigate issues | `/debug "500 error on login"` |
+| `/scan` | Scan codebase for AI context | `/scan` |
+| `/validate` | Pre-commit validation | `/validate` |
+| `/auto` | Automatic full cycle | `/auto "build user dashboard"` |
+
+## Security Features
+
+### Built-in Scans
+- ✅ **SAST** - Static application security testing
+- ✅ **Secret Detection** - Find hardcoded credentials
+- ✅ **Dependency Check** - Vulnerable packages
+- ✅ **OWASP Top 10** - Compliance validation
+
+### Security Tools (Optional)
+```bash
+# Install security scanning tools
+pip install snyk semgrep detect-secrets safety
+```
+
+### Configuration
+Set API tokens in `.env`:
+```bash
+SNYK_TOKEN=your_token
+SEMGREP_APP_TOKEN=your_token
+```
+
+## CLI Commands
+
+### `ai-sprint init`
+Install framework in current or specified directory
+
+```bash
+# Current directory
+ai-sprint init
+
+# Specific directory
+ai-sprint init --dir /path/to/project
+
+# Force overwrite
+ai-sprint init --force
+
+# Skip Python dependencies
+ai-sprint init --skip-install
+```
+
+### `ai-sprint scan`
+Scan codebase and generate AI context documents
+
+```bash
+# Current directory
+ai-sprint scan
+
+# Specific directory
+ai-sprint scan --dir /path/to/project
+```
+
+**Output:** `ai_context/codebase/` with overview.md, structure.md, repomix-output.xml
+
+### `ai-sprint list`
+Show available agents and commands
+
+```bash
+ai-sprint list
+```
+
+## Development
+
+### Local Testing
+
+```bash
+# Clone repository
+git clone https://github.com/yourusername/ai-sprint
+cd ai-sprint
+
+# Install dependencies
+npm install
+
+# Link locally
+npm link
+
+# Test installation
+mkdir test-project
+cd test-project
+ai-sprint init
+
+# Test with Claude Code
+claude
+/plan "test feature"
+```
+
+### Package Structure
+
+```
+ai-sprint/
+├── bin/
+│   └── cli.js           # CLI entry point
+├── lib/
+│   ├── installer.js     # Installation logic
+│   └── scanner.js       # Codebase scanning logic
+├── templates/
+│   ├── .claude/         # Framework templates
+│   ├── CLAUDE.md       # Instructions
+│   └── README.md       # User guide
+├── package.json
+└── README.md           # This file
+```
+
+## Requirements
+
+- Node.js >= 18.0.0
+- Claude Code CLI
+- Python 3.8+ (optional, for security skills)
+
+## Examples
+
+### Example 1: New Project Setup
+```bash
+mkdir my-project
+cd my-project
+npx ai-sprint init
+claude
+/auto "build REST API for todo app"
+```
+
+### Example 2: Add to Existing Project
+```bash
+cd existing-project
+npx ai-sprint init
+claude
+/secure  # Scan existing code
+/review  # Review code quality
+```
+
+### Example 3: Security-Focused Development
+```bash
+npx ai-sprint init
+claude
+/plan "implement payment processing"
+/code "implement with PCI DSS compliance"
+/secure  # Comprehensive security scan
+/review  # Security-focused review
+```
+
+## Troubleshooting
+
+### "Command not found: ai-sprint"
+```bash
+# Use npx instead
+npx ai-sprint init
+
+# Or install globally
+npm install -g ai-sprint
+```
+
+### ".claude/ already exists"
+```bash
+# Use --force to overwrite
+npx ai-sprint init --force
+```
+
+### "Python dependencies failed"
+```bash
+# Install manually
+cd .claude/skills
+python3 -m venv .venv
+source .venv/bin/activate  # or .venv\Scripts\activate on Windows
+pip install -r requirements.txt
+```
+
+## Contributing
+
+Contributions welcome! Please:
+1. Fork the repository
+2. Create a feature branch
+3. Make your changes
+4. Submit a pull request
+
+## License
+
+MIT License - see LICENSE file
+
+## Support
+
+- Issues: [GitHub Issues](https://github.com/yourusername/ai-sprint/issues)
+- Documentation: [Framework README](./templates/README.md)
+
+---
+
+**Made with ❤️ for autonomous developers**

package/bin/cli.js

@@ -0,0 +1,135 @@
+#!/usr/bin/env node
+
+const { program } = require('commander');
+const chalk = require('chalk');
+const { install, checkExisting } = require('../lib/installer');
+const { scanCodebase, detectSourceCode } = require('../lib/scanner');
+const packageJson = require('../package.json');
+
+program
+  .name('ai-sprint')
+  .description('AI Sprint - Autonomous development framework for Claude Code')
+  .version(packageJson.version);
+
+program
+  .command('init')
+  .description('Initialize .claude/ directory with agents, commands, and skills')
+  .option('-d, --dir <directory>', 'Target directory (default: current directory)', process.cwd())
+  .option('-f, --force', 'Overwrite existing .claude/ directory', false)
+  .option('--skip-install', 'Skip npm install for skill dependencies', false)
+  .option('-s, --scan', 'Scan existing codebase after init', false)
+  .option('--no-scan', 'Skip automatic codebase scanning')
+  .action(async (options) => {
+    console.log(chalk.blue.bold('\n🚀 AI Sprint Installer\n'));
+
+    const targetDir = options.dir;
+
+    // Check if .claude/ already exists
+    const existing = await checkExisting(targetDir);
+    if (existing && !options.force) {
+      console.log(chalk.yellow('⚠️  .claude/ directory already exists!'));
+      console.log(chalk.gray('Use --force to overwrite\n'));
+      process.exit(1);
+    }
+
+    try {
+      await install(targetDir, {
+        force: options.force,
+        skipInstall: options.skipInstall
+      });
+
+      console.log(chalk.green.bold('\n✅ Installation complete!\n'));
+
+      // Handle codebase scanning
+      let shouldScan = options.scan;
+
+      // Auto-detect if neither --scan nor --no-scan specified
+      if (!options.scan && options.scan !== false) {
+        const hasSource = await detectSourceCode(targetDir);
+        if (hasSource) {
+          console.log(chalk.cyan('📁 Source code detected. Scanning codebase...\n'));
+          shouldScan = true;
+        }
+      }
+
+      if (shouldScan) {
+        const result = await scanCodebase(targetDir);
+        if (result.success) {
+          console.log(chalk.gray(`   Output: ai_context/codebase/\n`));
+        }
+      }
+
+      console.log(chalk.cyan('Next steps:'));
+      console.log(chalk.gray('  1. Review .claude/README.md for framework overview'));
+      console.log(chalk.gray('  2. Start Claude Code: claude'));
+      console.log(chalk.gray('  3. Try commands: /plan, /code, /test, /secure'));
+      if (!shouldScan) {
+        console.log(chalk.gray('  4. Run /scan to analyze existing codebase\n'));
+      } else {
+        console.log('');
+      }
+    } catch (error) {
+      console.error(chalk.red.bold('\n❌ Installation failed:\n'));
+      console.error(chalk.red(error.message));
+      console.error(chalk.gray('\nStack trace:'));
+      console.error(chalk.gray(error.stack));
+      process.exit(1);
+    }
+  });
+
+program
+  .command('scan')
+  .description('Scan codebase and generate AI context documents')
+  .option('-d, --dir <directory>', 'Target directory (default: current directory)', process.cwd())
+  .action(async (options) => {
+    console.log(chalk.blue.bold('\n📁 AI Sprint Codebase Scanner\n'));
+
+    const targetDir = options.dir;
+
+    const result = await scanCodebase(targetDir);
+
+    if (result.success) {
+      console.log(chalk.green.bold('\n✅ Scan complete!\n'));
+      console.log(chalk.gray(`   Files: ${result.stats.totalFiles}`));
+      console.log(chalk.gray(`   Duration: ${result.stats.scanDuration}s`));
+      console.log(chalk.gray(`   Output: ai_context/codebase/\n`));
+    } else if (result.skipped) {
+      console.log(chalk.yellow(`\n⚠️  Scan skipped: ${result.reason}\n`));
+    } else {
+      console.error(chalk.red.bold('\n❌ Scan failed\n'));
+      process.exit(1);
+    }
+  });
+
+program
+  .command('list')
+  .description('List available agents and commands')
+  .action(() => {
+    console.log(chalk.blue.bold('\n🚀 AI Sprint Framework\n'));
+
+    console.log(chalk.cyan('Agents (9):'));
+    console.log(chalk.gray('  • planner      - Research & architecture'));
+    console.log(chalk.gray('  • implementer  - Code generation & refactoring'));
+    console.log(chalk.gray('  • tester       - Test generation & automation'));
+    console.log(chalk.gray('  • reviewer     - Code quality review'));
+    console.log(chalk.gray('  • security     - SAST, secrets, dependencies'));
+    console.log(chalk.gray('  • devops       - CI/CD & deployment'));
+    console.log(chalk.gray('  • docs         - Documentation generation'));
+    console.log(chalk.gray('  • debugger     - Root cause analysis'));
+    console.log(chalk.gray('  • researcher   - Technology research'));
+
+    console.log(chalk.cyan('\nCommands (11):'));
+    console.log(chalk.gray('  • /plan        - Create implementation plan'));
+    console.log(chalk.gray('  • /code        - Generate/refactor code'));
+    console.log(chalk.gray('  • /test        - Generate and run tests'));
+    console.log(chalk.gray('  • /review      - Code quality review'));
+    console.log(chalk.gray('  • /secure      - Security scan (SAST + secrets + deps)'));
+    console.log(chalk.gray('  • /deploy      - CI/CD setup and deployment'));
+    console.log(chalk.gray('  • /docs        - Generate/update documentation'));
+    console.log(chalk.gray('  • /debug       - Investigate issues'));
+    console.log(chalk.gray('  • /scan        - Scan codebase for AI context'));
+    console.log(chalk.gray('  • /validate    - Pre-commit validation'));
+    console.log(chalk.gray('  • /auto        - Automatic full development cycle\n'));
+  });
+
+program.parse();

package/lib/installer.js

@@ -0,0 +1,205 @@
+const fs = require('fs-extra');
+const path = require('path');
+const ora = require('ora');
+const chalk = require('chalk');
+const execa = require('execa');
+
+/**
+ * Check if .claude/ directory exists in target
+ */
+async function checkExisting(targetDir) {
+  const claudeDir = path.join(targetDir, '.claude');
+  return await fs.pathExists(claudeDir);
+}
+
+/**
+ * Install autonomous agent framework
+ */
+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');
+  }
+
+  // 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 });
+    }
+
+    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;
+  }
+}
+
+/**
+ * Install Python dependencies for skills
+ */
+async function installSkillDependencies(claudeDir) {
+  const skillsDir = path.join(claudeDir, 'skills');
+  const requirementsPath = path.join(skillsDir, 'requirements.txt');
+
+  if (!await fs.pathExists(requirementsPath)) {
+    return;
+  }
+
+  const spinner = ora('Installing skill dependencies...').start();
+
+  try {
+    // Check if Python 3 is available
+    try {
+      await execa('python3', ['--version']);
+    } catch (error) {
+      spinner.warn('Python 3 not found. Skipping skill dependencies.');
+      return;
+    }
+
+    // Create virtual environment
+    const venvDir = path.join(skillsDir, '.venv');
+    if (!await fs.pathExists(venvDir)) {
+      await execa('python3', ['-m', 'venv', '.venv'], {
+        cwd: skillsDir
+      });
+    }
+
+    // Install requirements
+    const pythonPath = process.platform === 'win32'
+      ? path.join(venvDir, 'Scripts', 'python.exe')
+      : path.join(venvDir, 'bin', 'python3');
+
+    await execa(pythonPath, ['-m', 'pip', 'install', '-r', 'requirements.txt'], {
+      cwd: skillsDir
+    });
+
+    spinner.succeed('Skill dependencies installed');
+  } catch (error) {
+    spinner.warn('Failed to install skill dependencies. You can install manually later.');
+  }
+}
+
+/**
+ * Create initial project directories
+ */
+async function createInitialDirs(targetDir) {
+  const dirs = [
+    'ai_context',
+    'ai_context/plans',
+    'ai_context/docs',
+    'ai_context/reports',
+    'ai_context/memory',
+    'docs',
+    'plans',
+    'plans/reports'
+  ];
+
+  for (const dir of dirs) {
+    const dirPath = path.join(targetDir, dir);
+    await fs.ensureDir(dirPath);
+  }
+
+  // Create initial memory files
+  const memoryFiles = {
+    'ai_context/memory/learning.md': `# Learning Log
+
+Lessons learned from past development sessions.
+
+## Format
+
+\`\`\`markdown
+### [Date] - Lesson Title
+**Context:** What happened
+**Lesson:** What we learned
+**Action:** How to avoid/apply in future
+\`\`\`
+
+---
+
+_No lessons recorded yet._
+`,
+    'ai_context/memory/decisions.md': `# Architecture Decisions
+
+Key technical and design decisions made during development.
+
+## Format
+
+\`\`\`markdown
+### [Date] - Decision Title
+**Context:** Why this decision was needed
+**Decision:** What was decided
+**Consequences:** Trade-offs and implications
+\`\`\`
+
+---
+
+_No decisions recorded yet._
+`,
+    'ai_context/memory/active.md': `# Active Session Context
+
+Current development focus and session state.
+
+## Current Focus
+_Not set_
+
+## Recent Actions
+_None_
+
+## Next Steps
+_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 = {
+  install,
+  checkExisting
+};