ai-sprint-kit 1.1.0

package/templates/CLAUDE.md

@@ -0,0 +1,409 @@
+# CLAUDE.md
+
+Guidance for Claude Code when using AI Sprint Framework.
+
+## Framework Overview
+
+**AI Sprint** - Security-first, production-grade autonomous development powered by 9 specialized agents and 10 core commands.
+
+## Available Agents
+
+| Agent | Model | Purpose |
+|-------|-------|---------|
+| planner | opus | Architecture & implementation planning |
+| implementer | sonnet | Code generation & refactoring |
+| tester | sonnet | Test generation & coverage automation |
+| reviewer | sonnet | Code quality & best practices |
+| security | sonnet | SAST, secrets, dependencies |
+| devops | sonnet | CI/CD pipelines & deployment |
+| docs | sonnet | Technical documentation |
+| debugger | sonnet | Root cause analysis |
+| researcher | sonnet | Technology research & web search |
+
+## Core Principles
+
+- **YAGNI** - You Aren't Gonna Need It (no over-engineering)
+- **KISS** - Keep It Simple, Stupid (clarity over cleverness)
+- **DRY** - Don't Repeat Yourself (avoid duplication)
+- **Security-First** - Every feature scanned and validated
+
+## Development Workflows
+
+### Full Automation (Recommended)
+```bash
+/auto "implement user registration with email verification"
+```
+Executes: plan → code → test → review → security → docs
+
+### Manual Workflow
+```bash
+/plan "feature description"        # 1. Create architecture
+/code "implement the plan"         # 2. Generate code
+/test                              # 3. Test + coverage
+/review                            # 4. Code quality
+/secure                            # 5. Security scan
+/deploy                            # 6. CI/CD setup
+/docs                              # 7. Documentation
+```
+
+### Quick Validation
+```bash
+/validate                          # Tests + review + security (before commit)
+```
+
+### Debugging Issues
+```bash
+/debug "describe the problem"      # Root cause analysis
+```
+
+## Mandatory Security Requirements
+
+### Code Standards
+- ✅ No hardcoded secrets (credentials, tokens, API keys)
+- ✅ Input validation on ALL user-facing inputs
+- ✅ Proper error handling (no silent failures)
+- ✅ OWASP Top 10 compliance
+- ✅ Secure defaults (fail-safe configuration)
+
+### Testing Standards
+- ✅ 80%+ code coverage required
+- ✅ All tests must pass before commit
+- ✅ Unit tests for business logic
+- ✅ Integration tests for APIs
+- ✅ Edge case coverage
+
+### Pre-Commit Gate
+Always run `/validate` before pushing:
+```bash
+/validate
+# Runs: tests + code review + security scan
+# Blocks commit if: tests fail | coverage < 80% | security issues found
+```
+
+## Quality Assurance
+
+### Code Review Checklist
+- ✅ Follows framework principles (YAGNI, KISS, DRY)
+- ✅ Has test coverage (>80%)
+- ✅ No security vulnerabilities
+- ✅ No hardcoded secrets
+- ✅ Error handling complete
+- ✅ Self-documenting code
+
+### Security Scanning
+- **SAST** - Static analysis for code vulnerabilities
+- **Secret Detection** - Hardcoded credentials, API keys
+- **Dependency Check** - Vulnerable packages
+- **OWASP Top 10** - Common web vulnerabilities
+
+### Human-in-the-Loop Gates
+Requires explicit approval for:
+- Production deployments
+- Infrastructure/environment changes
+- Critical/high severity vulnerability fixes
+- Database schema migrations
+- Permission/access changes
+
+## File Organization
+
+```
+project/
+├── .claude/
+│   ├── agents/              # 9 specialized agents
+│   ├── commands/            # 10 slash commands
+│   ├── workflows/           # Development rules
+│   ├── skills/              # Python utilities
+│   ├── settings.json        # Configuration
+│   └── .env.example         # Environment template
+├── 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
+│   └── memory/
+│   │   ├── learning.md      # Lessons learned
+│   │   ├── decisions.md     # Key decisions
+│   │   └── active.md        # Current context
+├── docs/                    # User-facing documentation
+├── src/                     # Source code
+├── tests/                   # Test files
+├── README.md                # Framework overview
+└── CLAUDE.md                # This file
+```
+
+## Context Engineering
+
+Store all AI context under `ai_context/` to:
+- **Avoid conflicts** with project-level `docs/` folder
+- **Centralize artifacts** for easy discovery
+- **Persist memory** across development sessions
+- **Track decisions** and lessons learned
+
+### Memory System
+- **learning.md** - Retrospective lessons (mistakes to avoid)
+- **decisions.md** - Key architecture & design decisions
+- **active.md** - Current session focus & context
+- **reports/** - Timestamped outputs from agents
+
+## Configuration
+
+### `.claude/settings.json`
+Control agent behavior, security settings, approval gates:
+```json
+{
+  "security": {
+    "enableSAST": true,
+    "enableSecretDetection": true,
+    "enableDependencyCheck": true,
+    "owasp_check": true
+  },
+  "testing": {
+    "minimumCoverage": 80,
+    "require_all_pass": true
+  },
+  "approval_gates": {
+    "production_deploy": true,
+    "infrastructure_change": true,
+    "critical_security_fix": true
+  }
+}
+```
+
+### `.env` (Optional)
+```bash
+# Security scanning (if using premium versions)
+SNYK_TOKEN=your_token
+SEMGREP_APP_TOKEN=your_token
+
+# API overrides (optional)
+ANTHROPIC_API_KEY=your_key
+```
+
+## MCP Tools (Optional)
+
+MCP (Model Context Protocol) servers provide enhanced capabilities for agents.
+
+### Setup
+
+1. Copy the example configuration:
+   ```bash
+   cp .mcp.json.example .mcp.json
+   ```
+
+2. Add your API keys:
+   - **exa**: Get key from https://exa.ai (clean web search, less tokens)
+   - **context7**: Get key from https://context7.com
+   - **human-mcp**: Get Gemini key from https://makersuite.google.com/app/apikey
+
+3. Install dependencies:
+   ```bash
+   # context7 (library docs)
+   npx -y @upstash/context7-mcp --help
+
+   # chrome-devtools (browser debugging)
+   npx -y chrome-devtools-mcp@latest --help
+
+   # sequential-thinking (complex reasoning)
+   npx -y @modelcontextprotocol/server-sequential-thinking --help
+
+   # time (timezone ops)
+   uvx mcp-server-time --help
+   ```
+
+### Available MCP Tools
+
+| Server | Tools | Use Case |
+|--------|-------|----------|
+| **exa** | web_search_exa, get_code_context_exa, deep_search_exa | Web search (clean results, less tokens) |
+| **context7** | resolve-library-id, get-library-docs | Library documentation |
+| **chrome-devtools** | take_snapshot, list_console_messages, evaluate_script | Browser debugging |
+| **sequential-thinking** | sequentialthinking | Complex reasoning |
+| **time** | get_current_time, convert_time | Timezone operations |
+| **human-mcp** | eyes_analyze, gemini_gen_image, mouth_speak | Multimodal AI |
+
+### Agent-MCP Mapping
+
+| Agent | Primary MCP Tools |
+|-------|-------------------|
+| researcher | exa, context7, time |
+| planner | exa, context7, sequential-thinking |
+| implementer | context7, sequential-thinking |
+| tester | chrome-devtools |
+| reviewer | sequential-thinking |
+| security | exa, sequential-thinking |
+| devops | time |
+| docs | context7 |
+| debugger | chrome-devtools, sequential-thinking |
+
+### Security Note
+
+⚠️ **Never commit `.mcp.json`** - it contains API keys. Only commit `.mcp.json.example` with placeholders.
+
+## Codebase Context
+
+When working on an existing codebase, AI Sprint can scan and index the code for efficient agent understanding.
+
+### Scanned Context Location
+
+```
+ai_context/
+└── codebase/
+    ├── overview.md           # Human-readable compressed codebase
+    ├── structure.md          # Directory tree
+    ├── repomix-output.xml    # Token-efficient XML for AI consumption
+    └── scan-metadata.json    # Stats (files, tokens, timestamp)
+```
+
+### When to Read Codebase Context
+
+Before starting work on an existing project, read:
+1. `ai_context/codebase/structure.md` - Understand project layout
+2. `ai_context/codebase/overview.md` - Review compressed code overview
+
+### Refreshing Context
+
+Run `/scan` after major changes to update the codebase index.
+
+## Commands Reference
+
+All commands have detailed docs in `.claude/commands/`:
+
+| Command | Purpose | Usage |
+|---------|---------|-------|
+| `/plan` | Architecture | `/plan "implement feature"` |
+| `/code` | Generate | `/code "write implementation"` |
+| `/test` | Testing | `/test` (generates & runs) |
+| `/review` | Quality | `/review` (analyzes code) |
+| `/secure` | Security | `/secure src/` (scans directory) |
+| `/deploy` | CI/CD | `/deploy` (sets up pipeline) |
+| `/docs` | Docs | `/docs` (generates documentation) |
+| `/debug` | Debugging | `/debug "issue description"` |
+| `/scan` | Codebase | `/scan` (update AI context) |
+| `/validate` | Gate | `/validate` (before commit) |
+| `/auto` | Full Cycle | `/auto "feature description"` |
+
+## Workflows Reference
+
+- **development-rules.md** - Core coding principles & standards
+- **orchestration-protocol.md** - How agents coordinate
+
+## Date Handling
+
+**CRITICAL**: Never guess dates. Always use bash:
+```bash
+date "+%Y-%m-%d"     # ISO format: 2025-12-24
+date "+%y%m%d-%H%M"  # Filename format: 251224-2153
+```
+
+Use this in reports and file naming consistently.
+
+## Memory Integration
+
+### Before Starting a Task
+Check learning from past sessions:
+```bash
+cat ai_context/memory/learning.md
+cat ai_context/memory/decisions.md
+```
+
+### After Completing a Task
+Update collective knowledge:
+1. Add new lessons to `ai_context/memory/learning.md`
+2. Document key decisions in `ai_context/memory/decisions.md`
+3. Save reports to `ai_context/reports/{timestamp}-{type}.md`
+4. Update `ai_context/memory/active.md` with session summary
+
+## Best Practices
+
+### When Using Agents
+1. Provide clear, specific descriptions
+2. Include relevant context from `ai_context/`
+3. Review agent outputs before accepting
+4. Ask follow-up questions if needed
+5. Document decisions in memory system
+
+### Code Generation
+1. Review generated code before merging
+2. Run `/test` to validate coverage
+3. Run `/secure` before commit
+4. Address all security findings
+5. Update docs with changes
+
+### Testing & Review
+1. Aim for >80% coverage
+2. Include edge cases
+3. Test error paths
+4. Verify security assumptions
+5. Check performance critical sections
+
+### Documentation
+1. Keep docs synchronized with code
+2. Use AI docs agent for auto-generation
+3. Include usage examples
+4. Document security considerations
+5. Maintain decision rationale
+
+## Common Patterns
+
+### Feature Implementation
+```bash
+/plan "describe feature"
+/code "implement based on plan"
+/test
+/validate
+# If passes → merge
+# If fails → /debug "issue" → fix → rerun
+```
+
+### Bug Fix
+```bash
+/debug "describe the bug and symptoms"
+# Review root cause analysis
+/code "implement the fix"
+/test
+/validate
+```
+
+### Security Audit
+```bash
+/secure .
+# Review findings in ai_context/reports/security-*.md
+/code "fix high/critical issues"
+/test
+```
+
+### Performance Optimization
+```bash
+/plan "performance improvement"
+/code "optimize based on plan"
+/test "ensure no regressions"
+/review "check for best practices"
+```
+
+## Customization
+
+### Add Custom Agent
+Create `.claude/agents/custom-name.md`:
+```markdown
+---
+name: custom-name
+description: Agent purpose
+model: sonnet
+---
+
+System prompt and instructions...
+```
+
+### Add Custom Command
+Create `.claude/commands/custom-name.md`:
+```markdown
+---
+description: Command description
+argument-hint: [optional-args]
+---
+
+Workflow steps and orchestration...
+```