ai-sprint-kit 1.3.1 → 2.0.1

package/templates/.claude/workflows/orchestration-protocol.md

@@ -1,194 +0,0 @@
-# Orchestration Protocol
-
-How agents coordinate and work together.
-
-## Agent Hierarchy
-
-```
-Main Agent (Orchestrator)
-├── planner     → Creates implementation plans
-├── implementer → Writes production code
-├── tester      → Generates and runs tests
-├── reviewer    → Reviews code quality
-├── security    → Scans for vulnerabilities
-├── devops      → Handles CI/CD and deployment
-├── docs        → Creates documentation
-├── debugger    → Investigates and fixes bugs
-└── researcher  → Researches technologies
-```
-
-## Delegation Pattern
-
-### 1. Task Analysis
-Main agent analyzes request to determine:
-- Complexity (simple/medium/complex)
-- Required agents
-- Execution order (sequential/parallel)
-
-### 2. Agent Selection
-```
-Plan feature      → planner
-Write code        → implementer
-Generate tests    → tester
-Review quality    → reviewer
-Security scan     → security
-Deploy            → devops
-Write docs        → docs
-Debug issue       → debugger
-Research topic    → researcher
-```
-
-### 3. Context Passing
-Each agent receives:
-- Task description
-- Relevant files
-- Memory context (`ai_context/memory/learning.md`)
-- Quality requirements
-
-### 4. Result Collection
-Main agent:
-- Collects agent outputs
-- Validates quality gates passed
-- Aggregates reports
-- Updates memory
-
-## Workflow Patterns
-
-### Sequential Workflow (Default)
-```
-User Request
-    ↓
-Plan → Code → Test → Review → Secure
-    ↓
-Complete
-```
-
-### Parallel Workflow (Independent Tasks)
-```
-User Request
-    ↓
-┌───────────┬───────────┐
-│ Research  │ Planning  │
-└─────┬─────┴─────┬─────┘
-      ↓           ↓
-   Combine Results
-```
-
-### Iterative Workflow (Fix Loop)
-```
-Test → Fail → Debug → Fix → Test → Pass
-```
-
-## Quality Gates
-
-Before proceeding to next stage:
-
-### After Planning
-- [ ] Plan reviewed
-- [ ] Risks identified
-- [ ] Architecture approved
-
-### After Implementation
-- [ ] Code follows standards
-- [ ] No obvious bugs
-- [ ] Error handling present
-
-### After Testing
-- [ ] All tests pass
-- [ ] >80% coverage
-- [ ] Edge cases covered
-
-### After Review
-- [ ] No critical issues
-- [ ] Security checks passed
-- [ ] Code quality approved
-
-### After Security Scan
-- [ ] No critical vulnerabilities
-- [ ] No secrets exposed
-- [ ] Dependencies safe
-
-## Error Handling
-
-### Agent Failure
-1. Log error to `ai_context/reports/`
-2. Attempt self-correction (up to 3 times)
-3. Escalate to main agent
-4. Report to user if unresolved
-
-### Quality Gate Failure
-1. Identify failing checks
-2. Route to appropriate agent (debugger/implementer)
-3. Re-run quality checks
-4. Proceed when passed
-
-## Memory Sharing
-
-All agents share context via:
-```
-ai_context/memory/
-├── learning.md   # Lessons learned (read before, update after)
-├── decisions.md  # Key decisions (append only)
-├── active.md     # Current session state
-└── summary.md    # Session summaries
-```
-
-### Before Task
-```
-1. Read learning.md for past mistakes
-2. Read decisions.md for relevant decisions
-3. Check active.md for current context
-```
-
-### After Task
-```
-1. Update learning.md with new lessons
-2. Append to decisions.md if made decisions
-3. Update active.md with new state
-4. Write report to reports/ folder
-```
-
-## Communication Protocol
-
-### Main → Agent
-```markdown
-## Task: [description]
-
-## Context
-- Files: [relevant files]
-- Memory: [past lessons]
-- Requirements: [quality gates]
-
-## Expected Output
-- [specific deliverables]
-```
-
-### Agent → Main
-```markdown
-## Result: [success/failure]
-
-## Deliverables
-- [files created/modified]
-
-## Issues Encountered
-- [any problems]
-
-## Recommendations
-- [suggestions for improvement]
-```
-
-## Escalation Path
-
-1. Agent self-correction (3 attempts)
-2. Alternative approach
-3. Main agent intervention
-4. User consultation
-
-## Human-in-the-Loop
-
-Pause for user approval:
-- Before production deployment
-- Before infrastructure changes
-- Before database migrations
-- When critical security issues found
-- When blocking issues encountered

package/templates/.mcp.json.example

@@ -1,36 +0,0 @@
-{
-  "mcpServers": {
-    "exa": {
-      "command": "npx",
-      "args": ["-y", "exa-mcp-server"],
-      "env": {
-        "EXA_API_KEY": "YOUR_EXA_API_KEY"
-      }
-    },
-    "context7": {
-      "command": "npx",
-      "args": ["-y", "@upstash/context7-mcp", "--api-key", "YOUR_CONTEXT7_API_KEY"]
-    },
-    "human-mcp": {
-      "command": "npx",
-      "args": ["@goonnguyen/human-mcp"],
-      "env": {
-        "GOOGLE_GEMINI_API_KEY": "YOUR_GEMINI_API_KEY"
-      }
-    },
-    "chrome-devtools": {
-      "command": "npx",
-      "args": ["-y", "chrome-devtools-mcp@latest"]
-    },
-    "sequential-thinking": {
-      "command": "npx",
-      "args": ["-y", "@modelcontextprotocol/server-sequential-thinking"]
-    },
-    "time": {
-      "type": "stdio",
-      "command": "uvx",
-      "args": ["mcp-server-time", "--local-timezone=UTC"],
-      "env": {}
-    }
-  }
-}

package/templates/CLAUDE.md

@@ -1,412 +0,0 @@
-# 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
-/ai-sprint-auto "implement user registration with email verification"
-```
-Executes: plan → code → test → review → security → docs
-
-### Manual Workflow
-```bash
-/ai-sprint-plan "feature description"        # 1. Create architecture
-/ai-sprint-code "implement the plan"         # 2. Generate code
-/ai-sprint-test                              # 3. Test + coverage
-/ai-sprint-review                            # 4. Code quality
-/ai-sprint-secure                            # 5. Security scan
-/ai-sprint-deploy                            # 6. CI/CD setup
-/ai-sprint-docs                              # 7. Documentation
-```
-
-### Quick Validation
-```bash
-/ai-sprint-validate                          # Tests + review + security (before commit)
-```
-
-### Debugging Issues
-```bash
-/ai-sprint-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 `/ai-sprint-validate` before pushing:
-```bash
-/ai-sprint-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 (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
-│   │   └── 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 `/ai-sprint-scan` after major changes to update the codebase index.
-
-## Commands Reference
-
-All commands have detailed docs in `.claude/commands/`:
-
-| Command | Purpose | Usage |
-|---------|---------|-------|
-| `/ai-sprint-plan` | Architecture | `/ai-sprint-plan "implement feature"` |
-| `/ai-sprint-code` | Generate | `/ai-sprint-code "write implementation"` |
-| `/ai-sprint-test` | Testing | `/ai-sprint-test` (generates & runs) |
-| `/ai-sprint-review` | Quality | `/ai-sprint-review` (analyzes code) |
-| `/ai-sprint-secure` | Security | `/ai-sprint-secure src/` (scans directory) |
-| `/ai-sprint-deploy` | CI/CD | `/ai-sprint-deploy` (sets up pipeline) |
-| `/ai-sprint-docs` | Docs | `/ai-sprint-docs` (generates documentation) |
-| `/ai-sprint-debug` | Debugging | `/ai-sprint-debug "issue description"` |
-| `/ai-sprint-scan` | Codebase | `/ai-sprint-scan` (update AI context) |
-| `/ai-sprint-validate` | Gate | `/ai-sprint-validate` (before commit) |
-| `/ai-sprint-auto` | Full Cycle | `/ai-sprint-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 `/ai-sprint-test` to validate coverage
-3. Run `/ai-sprint-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
-/ai-sprint-plan "describe feature"
-/ai-sprint-code "implement based on plan"
-/ai-sprint-test
-/ai-sprint-validate
-# If passes → merge
-# If fails → /ai-sprint-debug "issue" → fix → rerun
-```
-
-### Bug Fix
-```bash
-/ai-sprint-debug "describe the bug and symptoms"
-# Review root cause analysis
-/ai-sprint-code "implement the fix"
-/ai-sprint-test
-/ai-sprint-validate
-```
-
-### Security Audit
-```bash
-/ai-sprint-secure .
-# Review findings in ai_context/reports/security-*.md
-/ai-sprint-code "fix high/critical issues"
-/ai-sprint-test
-```
-
-### Performance Optimization
-```bash
-/ai-sprint-plan "performance improvement"
-/ai-sprint-code "optimize based on plan"
-/ai-sprint-test "ensure no regressions"
-/ai-sprint-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...
-```