ai-sprint-kit 1.1.0

package/templates/README.md

@@ -0,0 +1,331 @@
+# AI Sprint Framework
+
+**Security-first, production-grade autonomous development with Claude Code**
+
+## Overview
+
+This framework provides 9 specialized AI agents and 10 essential commands for autonomous software development with integrated security scanning. Build, test, review, and deploy with confidence using AI-driven workflows.
+
+## Quick Start
+
+```bash
+# Full automation (recommended)
+/auto "build user authentication system"
+
+# Or step-by-step
+/plan "implement JWT authentication"
+/code "implement the plan"
+/test
+/review
+/secure
+/deploy
+```
+
+## MCP Tools (Optional)
+
+Enhance agent capabilities with MCP (Model Context Protocol) servers.
+
+### Quick Setup
+
+```bash
+# Copy example config
+cp .mcp.json.example .mcp.json
+
+# Edit .mcp.json and add your API keys:
+# - exa: Clean web search (https://exa.ai) - less tokens than HTML
+# - context7: Library documentation (https://context7.com)
+# - human-mcp: Multimodal AI (Gemini API key)
+```
+
+### Available Tools
+
+- **exa** - Clean web search results (less tokens than WebSearch)
+- **context7** - Up-to-date library documentation
+- **chrome-devtools** - Browser debugging and inspection
+- **sequential-thinking** - Complex multi-step reasoning
+- **time** - Timezone operations
+- **human-mcp** - Image/video/audio generation
+
+### Which Agents Use Which Tools?
+
+| Need | Agent | MCP Tool |
+|------|-------|----------|
+| Web search | researcher, planner, security | exa |
+| Library docs | researcher, docs | context7 |
+| Browser debugging | tester, debugger | chrome-devtools |
+| Complex reasoning | planner, reviewer | sequential-thinking |
+| Timestamps | devops | time |
+
+See `CLAUDE.md` for detailed MCP configuration.
+
+## Key Components
+
+### Agents (9)
+- **planner** - Architecture & implementation planning
+- **implementer** - Code generation & refactoring
+- **tester** - Test generation & coverage automation
+- **reviewer** - Code quality & best practices analysis
+- **security** - SAST, secrets, dependencies (OWASP Top 10)
+- **devops** - CI/CD pipelines & deployment
+- **docs** - Technical documentation generation
+- **debugger** - Root cause analysis & troubleshooting
+- **researcher** - Technology research with web search
+
+### Commands (11)
+- `/plan` - Create implementation architecture
+- `/code` - Generate or refactor code
+- `/test` - Generate and run tests (80%+ coverage required)
+- `/review` - Analyze code quality
+- `/secure` - Scan for vulnerabilities, secrets, dependencies
+- `/deploy` - Configure CI/CD & deployment
+- `/docs` - Generate documentation
+- `/debug` - Investigate bugs & errors
+- `/scan` - Scan codebase and update AI context
+- `/validate` - Comprehensive check (tests + review + security)
+- `/auto` - Full autonomous cycle
+
+### Skills (5)
+Skills enhance agent capabilities with specialized knowledge:
+
+| Skill | Purpose | Used By |
+|-------|---------|---------|
+| `planning` | Architecture methodology | planner |
+| `implementation` | Secure coding patterns | implementer |
+| `quality-assurance` | Testing + review | tester, reviewer |
+| `memory` | Cross-session learning | all |
+| `codebase-context` | Efficient code understanding | all |
+
+Skills are activated automatically when relevant.
+
+## Security by Design
+
+### Scanning
+- **SAST** - Static analysis for vulnerabilities
+- **Secret Detection** - Prevents credential leaks
+- **Dependency Check** - Identifies vulnerable packages
+- **OWASP Top 10** - Compliance validation
+
+### Approval Gates (Human-in-the-Loop)
+- Production deployments
+- Infrastructure changes
+- High/critical vulnerability fixes
+
+## Codebase Scanning
+
+AI Sprint can scan existing codebases to help agents understand the project quickly.
+
+### Automatic Scanning
+When you run `ai-sprint init` on a project with existing source code, it automatically scans and generates context documents.
+
+### Manual Scanning
+```bash
+# Update codebase context after changes
+/scan
+
+# Or use CLI directly
+ai-sprint scan
+```
+
+### Output
+```
+ai_context/
+└── codebase/
+    ├── overview.md           # Compressed codebase overview
+    ├── structure.md          # Directory tree
+    ├── repomix-output.xml    # Token-efficient XML for AI
+    └── scan-metadata.json    # Scan statistics
+```
+
+### Benefits
+- **70% token reduction** - Compressed code fits more context
+- **Security scanning** - Detects credentials before AI exposure
+- **Structure awareness** - Agents understand project layout immediately
+
+## Directory Structure
+
+```
+templates/
+├── .claude/
+│   ├── agents/              # 9 specialized agents
+│   ├── commands/            # 11 slash commands
+│   ├── workflows/           # Development rules
+│   ├── settings.json        # Security & testing config
+│   └── .env.example         # Environment template
+├── ai_context/              # AI context & artifacts
+│   ├── plans/               # Implementation plans
+│   ├── docs/                # AI-generated docs
+│   ├── reports/             # Agent outputs
+│   ├── codebase/            # Scanned codebase context
+│   └── memory/
+│   │   ├── learning.md      # Lessons learned
+│   │   └── decisions.md     # Key decisions
+├── CLAUDE.md                # Claude Code guidance
+└── README.md                # This file
+```
+
+## Statusline
+
+AI Sprint includes a custom statusline displaying real-time development metrics.
+
+### Features
+
+| Indicator | Description |
+|-----------|-------------|
+| 📁 | Current directory (with ~ expansion) |
+| 🌿 | Git branch |
+| 🤖 | Claude model (Opus/Sonnet) |
+| 🟢🟡🔴 | Context window usage (progress bar) |
+| 💵 | API cost tracking |
+| 📝 | Lines changed (+added -removed) |
+
+### Example Output
+```
+📁 ~/my-project  🌿 main  🤖 Opus  🟢 ▰▰▰▱▱▱▱▱▱▱▱▱ 25%  💵 $0.0523  📝 +42 -8
+```
+
+### Requirements (Optional)
+
+Install `jq` for full statusline features:
+
+| Platform | Command |
+|----------|---------|
+| macOS | `brew install jq` |
+| Ubuntu/Debian | `sudo apt-get install jq` |
+| Windows | `choco install jq` |
+
+Without jq, statusline shows basic "🚀 AI Sprint" text.
+
+## Workflows
+
+### Recommended: Full Automation
+```bash
+/auto "feature description"
+```
+Executes: plan → code → test → review → security → docs
+
+### Manual Step-by-Step
+```bash
+/plan "implement registration system"       # Architecture
+/code "implement the plan"                  # Generate code
+/test                                       # Tests + coverage
+/review                                     # Quality analysis
+/secure                                     # Security scan
+/deploy                                     # CI/CD setup
+```
+
+### Validation Before Commit
+```bash
+/validate                                   # tests + review + security
+```
+
+## Configuration
+
+### Settings (`.claude/settings.json`)
+```json
+{
+  "security": {
+    "enableSAST": true,
+    "enableSecretDetection": true,
+    "enableDependencyCheck": true
+  },
+  "testing": {
+    "minimumCoverage": 80
+  }
+}
+```
+
+### Environment Variables (`.env`)
+```bash
+# Optional: Security scanning tokens
+SNYK_TOKEN=your_token
+SEMGREP_APP_TOKEN=your_token
+
+# Optional: Claude API override
+ANTHROPIC_API_KEY=your_key
+```
+
+## Code Standards
+
+### Must-Have
+- 80%+ test coverage
+- All tests passing
+- No hardcoded secrets
+- Input validation on all user inputs
+- Error handling throughout
+- OWASP Top 10 compliance
+
+### Pre-Commit Gate
+Run `/validate` before committing. Fixes all issues before pushing.
+
+## Examples
+
+### Example 1: Complete Feature
+```bash
+/auto "implement password reset with email verification"
+```
+
+### Example 2: Step-by-Step with Review
+```bash
+/plan "design GraphQL API for posts"
+/code "implement GraphQL schema and resolvers"
+/test "generate integration tests"
+/review
+/secure src/
+```
+
+### Example 3: Security Audit
+```bash
+/secure .
+```
+Scans codebase for vulnerabilities, secrets, dependencies.
+
+## Customization
+
+### Custom Agent
+Create `.claude/agents/custom-name.md`:
+```markdown
+---
+name: custom-name
+description: Purpose of agent
+model: sonnet
+---
+
+Agent system prompt and instructions...
+```
+
+### Custom Command
+Create `.claude/commands/custom-name.md`:
+```markdown
+---
+description: What this command does
+argument-hint: [optional-args]
+---
+
+Command workflow steps...
+```
+
+## Troubleshooting
+
+| Issue | Solution |
+|-------|----------|
+| Security scan fails | Install: `pip install snyk semgrep detect-secrets`. Get API tokens. Update `.env` |
+| Tests don't run | Verify test framework installed. Check test file patterns. Ensure coverage tools available |
+| Agent not found | Verify `.claude/agents/` directory. Check agent name in frontmatter. Restart Claude |
+| Low code coverage | Use `/test` to auto-generate tests for uncovered code |
+| Deployment blocked | Check approval gates in `.claude/settings.json`. Review security findings |
+
+## Key Principles
+
+- **Security First** - Every feature scanned for vulnerabilities
+- **Automated Testing** - 80%+ coverage enforced
+- **Code Review** - Quality gates before merge
+- **Human Control** - Approve critical deployments
+- **Documentation** - Auto-generated for all changes
+
+## Next Steps
+
+1. Copy this template to your project
+2. Update `.claude/settings.json` for your stack
+3. Configure environment variables in `.env`
+4. Start with `/auto "your first feature"`
+5. Monitor `ai_context/memory/learning.md` for lessons

package/templates/ai_context/memory/active.md

@@ -0,0 +1,15 @@
+# Active Session Context
+
+Current session state (overwritten each session).
+
+## Current Focus
+
+<!-- What you're working on -->
+
+## Recent Changes
+
+<!-- What was just modified -->
+
+## Blockers
+
+<!-- Any issues or questions -->

package/templates/ai_context/memory/decisions.md

@@ -0,0 +1,18 @@
+# Decisions Log
+
+Record key architectural and design decisions.
+
+## Format
+
+```
+## [YYYY-MM-DD] - [Decision Title]
+
+**Context**: Why decision needed
+**Options**: What was considered
+**Decision**: What was chosen
+**Rationale**: Why this choice
+```
+
+---
+
+<!-- Add entries below -->

package/templates/ai_context/memory/learning.md

@@ -0,0 +1,22 @@
+# Learning Log
+
+Record lessons learned to avoid repeating mistakes.
+
+## Format
+
+```
+## [YYYY-MM-DD] - [Category]
+
+**Context**: What happened
+**Mistake**: What went wrong
+**Lesson**: What to do differently
+**Prevention**: How to avoid in future
+```
+
+## Categories
+
+- Security, Performance, Testing, Architecture, Process, Dependencies
+
+---
+
+<!-- Add entries below -->