ai-sprint-kit 1.1.0

package/templates/docs/user-guide.md

@@ -0,0 +1,595 @@
+# AI Sprint User Guide
+
+Complete guide to using the autonomous development framework with Claude Code.
+
+## Table of Contents
+
+1. [Getting Started](#getting-started)
+2. [Workflow Tutorials](#workflow-tutorials)
+3. [Command Reference](#command-reference)
+4. [MCP Tools Setup](#mcp-tools-setup)
+5. [Best Practices](#best-practices)
+6. [Troubleshooting](#troubleshooting)
+
+---
+
+## Getting Started
+
+### Prerequisites
+
+- Claude Code CLI installed
+- Node.js 18+
+- Python 3.8+ (optional, for security scanning)
+
+### First Steps After Installation
+
+```bash
+# 1. Start Claude Code
+claude
+
+# 2. Try the /auto command for full automation
+/auto "create a hello world API endpoint"
+
+# 3. Or step-by-step approach
+/plan "create REST API endpoint"
+/code "implement the plan"
+/test
+/validate
+```
+
+### Project Structure
+
+After installation, your project has:
+
+```
+your-project/
+├── .claude/
+│   ├── agents/          # 9 AI agents
+│   ├── commands/        # 10 slash commands
+│   ├── workflows/       # Development rules
+│   └── settings.json    # Configuration
+├── ai_context/
+│   ├── plans/           # Implementation plans
+│   ├── reports/         # Agent outputs
+│   └── memory/          # Learning system
+├── docs/                # This guide
+├── CLAUDE.md            # Framework instructions
+└── .mcp.json.example    # MCP configuration template
+```
+
+---
+
+## Workflow Tutorials
+
+### Tutorial 1: Building a New Feature (Full Auto)
+
+The simplest way - let the framework handle everything:
+
+```bash
+/auto "implement user registration with email and password"
+```
+
+This automatically runs: plan → code → test → review → security → docs
+
+**When to use:** New features, prototypes, straightforward implementations.
+
+### Tutorial 2: Building a Feature (Step-by-Step)
+
+For more control over each phase:
+
+```bash
+# Step 1: Create the plan
+/plan "implement user registration with email verification"
+# Review the plan in ai_context/plans/
+
+# Step 2: Generate code
+/code "implement the registration feature from the plan"
+
+# Step 3: Generate and run tests
+/test
+
+# Step 4: Review code quality
+/review
+
+# Step 5: Security scan
+/secure
+
+# Step 6: Generate documentation
+/docs
+```
+
+**When to use:** Complex features, learning the framework, when you need review at each step.
+
+### Tutorial 3: Fixing a Bug
+
+```bash
+# Step 1: Investigate the issue
+/debug "users getting 500 error when submitting registration form"
+# Review the analysis in ai_context/reports/
+
+# Step 2: Implement the fix
+/code "fix the registration error based on debug analysis"
+
+# Step 3: Verify fix
+/test
+/validate
+```
+
+### Tutorial 4: Security Audit
+
+```bash
+# Scan entire codebase
+/secure
+
+# Scan specific directory
+/secure src/auth/
+
+# Review findings in ai_context/reports/security-*.md
+```
+
+### Tutorial 5: Pre-Commit Validation
+
+Always run before pushing code:
+
+```bash
+/validate
+```
+
+This runs: tests + code review + security scan. Blocks if:
+- Tests fail
+- Coverage < 80%
+- Security issues found
+
+### Tutorial 6: Adding to Existing Project
+
+```bash
+# Install framework
+npx ai-sprint init
+
+# Scan existing code for issues
+/secure
+
+# Review code quality
+/review
+
+# Generate missing documentation
+/docs
+```
+
+---
+
+## Command Reference
+
+### /plan - Architecture & Planning
+
+Creates implementation plans with architecture decisions.
+
+```bash
+# Basic usage
+/plan "implement feature description"
+
+# Examples
+/plan "add OAuth2 authentication with Google and GitHub"
+/plan "create microservices architecture for order processing"
+/plan "implement real-time notifications using WebSockets"
+```
+
+**Output:** `ai_context/plans/{timestamp}-{feature}/plan.md`
+
+**Best for:** New features, architectural changes, complex implementations.
+
+---
+
+### /code - Code Generation
+
+Generates or refactors code based on plans or descriptions.
+
+```bash
+# Basic usage
+/code "what to implement"
+
+# Examples
+/code "implement the authentication plan"
+/code "refactor the user service to use dependency injection"
+/code "add input validation to all API endpoints"
+```
+
+**Best for:** Implementation, refactoring, adding functionality.
+
+---
+
+### /test - Testing
+
+Generates tests and runs them with coverage.
+
+```bash
+# Basic usage
+/test
+
+# With specific focus
+/test "focus on edge cases for user registration"
+/test "add integration tests for payment API"
+```
+
+**Output:** `ai_context/reports/test-*.md`
+
+**Requirements:** 80%+ coverage required.
+
+---
+
+### /review - Code Review
+
+Analyzes code quality and best practices.
+
+```bash
+# Review all recent changes
+/review
+
+# Review specific files or directories
+/review src/services/
+/review src/auth/login.ts
+```
+
+**Output:** `ai_context/reports/review-*.md`
+
+**Checks:**
+- Code quality and patterns
+- Error handling
+- Performance issues
+- Security concerns
+- Documentation gaps
+
+---
+
+### /secure - Security Scanning
+
+Comprehensive security analysis.
+
+```bash
+# Scan entire project
+/secure
+
+# Scan specific directory
+/secure src/
+/secure src/auth/
+```
+
+**Output:** `ai_context/reports/security-*.md`
+
+**Scans:**
+- SAST (static analysis)
+- Secret detection
+- Dependency vulnerabilities
+- OWASP Top 10 compliance
+
+---
+
+### /deploy - CI/CD Setup
+
+Configures deployment pipelines.
+
+```bash
+# Basic setup
+/deploy
+
+# Platform-specific
+/deploy --platform github
+/deploy --platform gitlab
+/deploy --platform azure
+```
+
+**Creates:** CI/CD configuration files for your platform.
+
+---
+
+### /docs - Documentation
+
+Generates technical documentation.
+
+```bash
+# Generate all docs
+/docs
+
+# Focus on specific areas
+/docs "API documentation"
+/docs "update README with new features"
+```
+
+**Output:** `ai_context/docs/` and project `docs/`
+
+---
+
+### /debug - Debugging
+
+Investigates issues and bugs.
+
+```bash
+# Describe the problem
+/debug "500 error when user submits form"
+/debug "memory leak in background job processor"
+/debug "slow API response times on /users endpoint"
+```
+
+**Output:** `ai_context/reports/debug-*.md`
+
+**Provides:**
+- Root cause analysis
+- Code path investigation
+- Fix recommendations
+
+---
+
+### /validate - Pre-Commit Gate
+
+Runs comprehensive validation before commit.
+
+```bash
+/validate
+```
+
+**Runs:** tests + review + security
+
+**Blocks if:**
+- Any tests fail
+- Coverage < 80%
+- Critical security issues
+
+**Always run before pushing code.**
+
+---
+
+### /auto - Full Automation
+
+Complete development cycle in one command.
+
+```bash
+/auto "feature description"
+
+# Examples
+/auto "implement shopping cart with add, remove, checkout"
+/auto "create admin dashboard for user management"
+/auto "add rate limiting to all API endpoints"
+```
+
+**Runs:** plan → code → test → review → security → docs
+
+**Best for:** New features with clear requirements.
+
+---
+
+## MCP Tools Setup
+
+MCP (Model Context Protocol) servers enhance agent capabilities with external tools.
+
+### Quick Setup
+
+```bash
+# 1. Copy the example config
+cp .mcp.json.example .mcp.json
+
+# 2. Edit .mcp.json and add your API keys
+```
+
+### Available MCP Tools
+
+| Tool | Purpose | Get API Key |
+|------|---------|-------------|
+| **exa** | Clean web search (fewer tokens) | https://exa.ai |
+| **context7** | Library documentation | https://context7.com |
+| **chrome-devtools** | Browser debugging | No key needed |
+| **sequential-thinking** | Complex reasoning | No key needed |
+| **time** | Timezone operations | No key needed |
+| **human-mcp** | Image/video/audio AI | https://makersuite.google.com |
+
+### Configuration Example
+
+Edit `.mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "exa": {
+      "command": "npx",
+      "args": ["-y", "exa-mcp-server"],
+      "env": {
+        "EXA_API_KEY": "your-actual-exa-key"
+      }
+    },
+    "context7": {
+      "command": "npx",
+      "args": ["-y", "@upstash/context7-mcp", "--api-key", "your-actual-context7-key"]
+    }
+  }
+}
+```
+
+### Which Agents Use Which Tools?
+
+| Agent | Primary MCP Tools | Use Case |
+|-------|-------------------|----------|
+| researcher | exa, context7 | Web search, library docs |
+| planner | exa, context7, sequential-thinking | Research, complex planning |
+| security | exa, sequential-thinking | CVE lookup, vulnerability analysis |
+| tester | chrome-devtools | Browser testing |
+| debugger | chrome-devtools, sequential-thinking | Browser debugging, root cause |
+| reviewer | sequential-thinking | Complex code analysis |
+| docs | context7 | Library documentation |
+| devops | time | Timestamps, scheduling |
+| implementer | context7, sequential-thinking | Docs lookup, complex logic |
+
+### Benefits of MCP Tools
+
+**Exa Search:**
+- Returns clean, structured results
+- Uses fewer tokens than raw HTML parsing
+- Better for technical research
+
+**Context7:**
+- Up-to-date library documentation
+- API references and examples
+- Version-specific information
+
+**Chrome DevTools:**
+- Real browser debugging
+- DOM inspection
+- Network monitoring
+
+---
+
+## Best Practices
+
+### 1. Start with /plan
+
+Always plan before coding for complex features:
+
+```bash
+/plan "describe your feature"
+# Review the plan
+/code "implement the plan"
+```
+
+### 2. Use /validate Before Every Commit
+
+```bash
+# Before git commit
+/validate
+git add .
+git commit -m "feat: your feature"
+```
+
+### 3. Check Memory for Context
+
+The framework learns from past sessions:
+
+```bash
+# View lessons learned
+cat ai_context/memory/learning.md
+
+# View past decisions
+cat ai_context/memory/decisions.md
+```
+
+### 4. Review Security Reports
+
+After every `/secure` scan:
+
+```bash
+# Check reports
+ls ai_context/reports/security-*.md
+cat ai_context/reports/security-latest.md
+```
+
+### 5. Configure MCP Tools
+
+Set up at least:
+- **exa** - For better web search
+- **context7** - For library documentation
+
+### 6. Use /auto for Simple Features
+
+For straightforward features, use full automation:
+
+```bash
+/auto "add logout button to navbar"
+```
+
+### 7. Use Step-by-Step for Complex Features
+
+For complex features, maintain control:
+
+```bash
+/plan "complex feature"
+# Review plan
+/code "implement phase 1"
+/test
+/code "implement phase 2"
+/test
+/validate
+```
+
+---
+
+## Troubleshooting
+
+### Tests Failing
+
+```bash
+# Run tests to see errors
+/test
+
+# Debug specific failures
+/debug "test X is failing with error Y"
+```
+
+### Low Coverage
+
+```bash
+# Generate more tests
+/test "increase coverage for uncovered functions"
+```
+
+### Security Issues Found
+
+```bash
+# View the report
+cat ai_context/reports/security-*.md
+
+# Fix issues
+/code "fix security issues from the security scan"
+
+# Rescan
+/secure
+```
+
+### Agent Not Responding
+
+```bash
+# Restart Claude Code
+exit
+claude
+```
+
+### MCP Tools Not Working
+
+```bash
+# Verify .mcp.json exists
+cat .mcp.json
+
+# Check for valid API keys (not placeholders)
+grep "YOUR_" .mcp.json  # Should return nothing
+```
+
+### Commands Not Found
+
+Ensure you're in a project with `.claude/` directory:
+
+```bash
+ls .claude/commands/
+```
+
+If missing, reinstall:
+
+```bash
+npx ai-sprint init --force
+```
+
+---
+
+## Quick Reference
+
+| Task | Command |
+|------|---------|
+| Full automation | `/auto "feature"` |
+| Plan feature | `/plan "feature"` |
+| Write code | `/code "what to build"` |
+| Run tests | `/test` |
+| Code review | `/review` |
+| Security scan | `/secure` |
+| Setup CI/CD | `/deploy` |
+| Generate docs | `/docs` |
+| Debug issue | `/debug "problem"` |
+| Pre-commit check | `/validate` |
+
+---
+
+**Need help?** Check `CLAUDE.md` for detailed framework instructions.