ai-sprint-kit 1.1.0

package/templates/.claude/commands/review.md

@@ -0,0 +1,412 @@
+---
+description: Comprehensive code quality review and best practices analysis
+argument-hint: [optional: specific file or directory to review]
+---
+
+## Command: /review
+
+Perform comprehensive code quality review focusing on security, maintainability, performance, and best practices.
+
+## Usage
+
+```
+/review
+/review src/
+/review src/auth/login.ts
+```
+
+## Workflow
+
+### 1. Code Analysis
+- Review code structure
+- Check for code smells
+- Identify security issues
+- Analyze performance
+
+### 2. Security Review (Critical)
+- OWASP Top 10 compliance
+- SQL injection vulnerabilities
+- XSS vulnerabilities
+- Auth/authorization issues
+- Secret exposure
+- Input validation
+
+### 3. Quality Check
+- Code maintainability
+- Proper error handling
+- Type safety
+- Performance optimization
+- Best practices
+
+### 4. Generate Report
+- Critical issues (must fix)
+- High priority issues
+- Medium priority suggestions
+- Low priority improvements
+- Positive observations
+
+## Review Categories
+
+### 🔴 Critical Issues (Must Fix)
+- Security vulnerabilities
+- Data loss potential
+- Crash bugs
+- Performance killers
+
+### 🟠 High Priority
+- Logic errors
+- Missing error handling
+- Performance problems
+- Maintainability issues
+
+### 🟡 Medium Priority
+- Code smells
+- Refactoring opportunities
+- Documentation gaps
+
+### 🟢 Low Priority
+- Style improvements
+- Minor optimizations
+- Naming suggestions
+
+## Example Review Report
+
+```markdown
+# Code Review Report
+
+**Date:** 2025-12-24
+**Scope:** src/auth/
+**Overall Assessment:** Needs Improvement
+
+**Summary:**
+- 2 Critical issues
+- 4 High priority issues
+- 6 Medium priority issues
+- 3 Low priority suggestions
+
+**Recommendation:** Fix critical issues before deployment
+
+---
+
+## Critical Issues
+
+### 1. SQL Injection Vulnerability
+**File:** `auth/login.ts:45`
+**Severity:** 🔴 Critical
+
+**Issue:**
+```typescript
+const query = `SELECT * FROM users WHERE email = '${email}'`;
+const user = await db.query(query);
+```
+
+**Problem:** Direct string interpolation allows SQL injection attacks.
+
+**Fix:**
+```typescript
+const user = await db.users.findUnique({
+  where: { email }
+});
+```
+
+**Rationale:** Parameterized queries prevent SQL injection by separating code from data.
+
+---
+
+### 2. Exposed API Keys
+**File:** `config/api.ts:12`
+**Severity:** 🔴 Critical
+
+**Issue:**
+```typescript
+const STRIPE_KEY = "sk_live_abc123";
+```
+
+**Problem:** Hardcoded production secret in source code.
+
+**Fix:**
+```typescript
+const STRIPE_KEY = process.env.STRIPE_SECRET_KEY;
+if (!STRIPE_KEY) {
+  throw new Error('STRIPE_SECRET_KEY not configured');
+}
+```
+
+---
+
+## High Priority Issues
+
+### 3. Missing Error Handling
+**File:** `api/payment.ts:78`
+**Severity:** 🟠 High
+
+**Issue:**
+```typescript
+async function processPayment(amount: number) {
+  const result = await stripe.charges.create({ amount });
+  return result;
+}
+```
+
+**Problem:** No error handling for payment failures.
+
+**Fix:**
+```typescript
+async function processPayment(amount: number) {
+  try {
+    const result = await stripe.charges.create({ amount });
+    return { success: true, data: result };
+  } catch (error) {
+    logger.error('Payment failed', { error, amount });
+    throw new PaymentError('Payment processing failed');
+  }
+}
+```
+
+---
+
+### 4. N+1 Query Problem
+**File:** `api/posts.ts:34`
+**Severity:** 🟠 High
+
+**Issue:**
+```typescript
+const posts = await db.posts.findMany();
+for (const post of posts) {
+  post.author = await db.users.findUnique({
+    where: { id: post.authorId }
+  });
+}
+```
+
+**Problem:** Executes N+1 database queries (very slow).
+
+**Fix:**
+```typescript
+const posts = await db.posts.findMany({
+  include: { author: true }
+});
+```
+
+**Impact:** 10-100x performance improvement.
+
+---
+
+## Medium Priority
+
+### 5. Long Function (120 lines)
+**File:** `utils/validation.ts:15`
+**Severity:** 🟡 Medium
+
+**Recommendation:** Split into smaller functions:
+- `validateEmail()`
+- `validatePassword()`
+- `validateUserData()`
+
+**Benefits:** Easier to test, understand, and maintain.
+
+---
+
+### 6. Magic Numbers
+**File:** `cache.ts:23`
+**Severity:** 🟡 Medium
+
+**Issue:**
+```typescript
+cache.set(key, value, 3600);
+```
+
+**Fix:**
+```typescript
+const CACHE_TTL_SECONDS = 60 * 60; // 1 hour
+cache.set(key, value, CACHE_TTL_SECONDS);
+```
+
+---
+
+## Positive Observations
+
+✅ Good error messages with context
+✅ Comprehensive input validation in auth
+✅ Well-structured database schema
+✅ Good test coverage (87%)
+
+## Refactoring Opportunities
+
+### Duplicate Logic
+Similar validation in:
+- `api/users.ts:45-67`
+- `api/products.ts:34-56`
+- `api/orders.ts:23-45`
+
+**Recommendation:** Create shared `validateRequest()` utility.
+
+---
+
+## Testing Gaps
+
+**Files lacking tests:**
+- ⚠️  `api/webhooks.ts` (0% coverage)
+- ⚠️  `utils/legacy.ts` (45%)
+
+**Recommendation:** Prioritize webhook testing (security-critical).
+
+---
+
+## Security Score: 6/10
+
+**Strengths:**
+- ✅ Password hashing (bcrypt)
+- ✅ HTTPS enforced
+- ✅ CORS configured
+
+**Weaknesses:**
+- ❌ SQL injection vulnerability
+- ❌ Exposed API keys
+- ❌ Missing rate limiting
+- ❌ No CSRF protection
+
+---
+
+## Next Steps
+
+### Immediate (Critical)
+1. Fix SQL injection in `auth/login.ts:45`
+2. Move API keys to environment variables
+3. Add rate limiting
+
+### Short Term (High)
+1. Fix N+1 queries
+2. Add error handling to payments
+3. Implement CSRF protection
+
+### Long Term (Medium)
+1. Refactor long functions
+2. Extract duplicate logic
+3. Add missing tests
+```
+
+## Review Checklist
+
+### Security
+- ✅ No SQL injection vulnerabilities
+- ✅ No XSS vulnerabilities
+- ✅ No hardcoded secrets
+- ✅ Proper authentication/authorization
+- ✅ Input validation everywhere
+- ✅ Error messages don't leak data
+- ✅ OWASP Top 10 compliance
+
+### Code Quality
+- ✅ Functions < 50 lines
+- ✅ Clear naming
+- ✅ Single responsibility
+- ✅ Proper error handling
+- ✅ Type safety
+- ✅ No code duplication
+
+### Performance
+- ✅ No N+1 queries
+- ✅ Efficient algorithms
+- ✅ Appropriate caching
+- ✅ No memory leaks
+- ✅ Database indexes exist
+
+### Testing
+- ✅ >80% coverage
+- ✅ Critical paths 100% covered
+- ✅ Security tests exist
+
+### Documentation
+- ✅ Public APIs documented
+- ✅ Complex logic commented
+- ✅ README up to date
+
+## Integration with Other Commands
+
+**/code** → **/review**
+- After code generation, review for quality
+
+**/review** → **/secure**
+- Review identifies issues, security scan validates
+
+**/review** → **/test**
+- Review suggests missing tests
+
+## Common Code Smells
+
+### Long Functions
+```typescript
+// ❌ Bad - 200 lines
+function processOrder() {
+  // Too much logic
+}
+
+// ✅ Good - Split up
+function processOrder() {
+  validateOrder();
+  calculateTotal();
+  processPayment();
+  sendConfirmation();
+}
+```
+
+### Deep Nesting
+```typescript
+// ❌ Bad - 4 levels deep
+if (user) {
+  if (user.isActive) {
+    if (user.hasPermission) {
+      if (user.credits > 0) {
+        // Do something
+      }
+    }
+  }
+}
+
+// ✅ Good - Early returns
+if (!user) return;
+if (!user.isActive) return;
+if (!user.hasPermission) return;
+if (user.credits <= 0) return;
+// Do something
+```
+
+### God Objects
+```typescript
+// ❌ Bad - Does everything
+class UserManager {
+  createUser() {}
+  deleteUser() {}
+  sendEmail() {}
+  processPayment() {}
+  generateReport() {}
+}
+
+// ✅ Good - Single responsibility
+class UserService {}
+class EmailService {}
+class PaymentService {}
+class ReportService {}
+```
+
+## Success Criteria
+
+Review is successful when:
+- ✅ All critical issues identified
+- ✅ Specific fixes provided
+- ✅ Security thoroughly checked
+- ✅ Performance analyzed
+- ✅ Actionable recommendations
+- ✅ Positive feedback included
+
+## Remember
+
+**Code review is collaborative:**
+- Make code better
+- Share knowledge
+- Maintain quality
+- Prevent bugs
+- Team alignment
+
+**Be respectful, specific, and constructive.**

package/templates/.claude/commands/scan.md

@@ -0,0 +1,146 @@
+---
+description: Scan codebase and update AI context documents
+argument-hint: [--full]
+---
+
+# /scan Command
+
+Scan the codebase and generate/update AI context documents for agent reference.
+
+## What It Does
+
+1. **Detects source code** - Finds src/, app/, lib/, and other code directories
+2. **Runs Repomix** - Packages codebase into token-efficient format
+3. **Generates structure** - Creates directory tree overview
+4. **Updates metadata** - Records file count, token stats, timestamp
+
+## Output 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)
+    └── .repomixignore        # Custom exclude patterns
+```
+
+## Usage
+
+```bash
+# Quick scan (default)
+/scan
+
+# Full rescan (regenerate all files)
+/scan --full
+```
+
+## When to Use
+
+- **After major changes** - New features, refactoring, file reorganization
+- **Before starting work** - Ensure agents have current codebase context
+- **After pulling changes** - Update context with team's changes
+- **Debugging agent confusion** - Refresh stale context
+
+## Workflow
+
+Execute the following steps:
+
+### Step 1: Check Current State
+
+```bash
+# Check if ai_context/codebase/ exists
+ls -la ai_context/codebase/ 2>/dev/null || echo "No existing scan found"
+```
+
+### Step 2: Run Codebase Scan
+
+Use the `ai-sprint scan` CLI command or run repomix directly:
+
+```bash
+# Option A: Use AI Sprint CLI (if available)
+ai-sprint scan
+
+# Option B: Run repomix directly
+npx repomix --compress --style xml -o ai_context/codebase/repomix-output.xml
+npx repomix --compress --style markdown -o ai_context/codebase/overview.md
+```
+
+### Step 3: Generate Structure
+
+```bash
+# Generate directory tree
+tree -I 'node_modules|.git|.venv|__pycache__|dist|build' -L 4 > ai_context/codebase/structure.md 2>/dev/null || \
+  find . -type f -name "*.ts" -o -name "*.js" -o -name "*.py" | head -50 > ai_context/codebase/structure.md
+```
+
+### Step 4: Update Metadata
+
+Create `ai_context/codebase/scan-metadata.json` with:
+- scanDate: Current timestamp
+- totalFiles: Number of files scanned
+- scanDuration: Time taken
+
+### Step 5: Report Results
+
+Provide summary:
+- Files scanned
+- Token count (if available)
+- Output location
+- Any warnings or errors
+
+## Customization
+
+### Exclude Patterns
+
+Edit `ai_context/codebase/.repomixignore` to exclude files:
+
+```
+# Add custom patterns
+docs/archive/
+*.generated.ts
+legacy/
+```
+
+### Include Specific Directories
+
+For large monorepos, scan specific directories:
+
+```bash
+npx repomix src/ lib/ --compress -o ai_context/codebase/repomix-output.xml
+```
+
+## Token Efficiency
+
+Repomix compression achieves ~70% token reduction:
+- Removes implementation details, keeps signatures
+- Preserves semantic structure (classes, functions, types)
+- Uses Tree-sitter AST analysis
+
+**Example:**
+- Raw codebase: 100,000 tokens
+- Compressed: ~30,000 tokens
+- Savings: 70,000 tokens per agent context load
+
+## Security
+
+Repomix includes Secretlint for credential detection:
+- Scans for API keys, tokens, passwords
+- Warns if secrets detected
+- Prevents accidental exposure in AI context
+
+## Troubleshooting
+
+| Issue | Solution |
+|-------|----------|
+| "repomix not found" | Install: `npm install -g repomix` |
+| Scan takes too long | Add exclusions to .repomixignore |
+| Large output file | Use `--compress` flag or exclude directories |
+| Missing files | Check .gitignore and .repomixignore patterns |
+
+## Related Commands
+
+- `/plan` - Create implementation plans using scanned context
+- `/code` - Generate code with codebase awareness
+- `/debug` - Investigate issues with full context

package/templates/.claude/commands/secure.md

@@ -0,0 +1,88 @@
+---
+description: Run comprehensive security scan (SAST + secrets + dependencies)
+argument-hint: [path or scope]
+---
+
+## Command: /secure
+
+Run security scans to detect vulnerabilities, secrets, and dependency issues.
+
+## Usage
+
+```
+/secure
+/secure src/
+/secure --full
+```
+
+## Scan Types
+
+### 1. SAST (Static Application Security Testing)
+- Code vulnerabilities
+- Security anti-patterns
+- Injection flaws
+- Authentication issues
+
+### 2. Secret Detection
+- Hardcoded API keys
+- Passwords
+- Private keys
+- Tokens
+- Connection strings
+
+### 3. Dependency Check
+- Known CVEs
+- Vulnerable packages
+- Outdated dependencies
+- Security advisories
+
+### 4. OWASP Top 10 Compliance
+- Broken Access Control
+- Cryptographic Failures
+- Injection vulnerabilities
+- Security misconfigurations
+
+## Workflow
+
+1. **Delegate** to security agent
+2. **Run** all security scans
+3. **Analyze** findings
+4. **Prioritize** by severity
+5. **Report** results with remediation
+
+## Output
+
+```markdown
+# Security Scan Report
+
+## Summary
+- Critical: X findings
+- High: X findings
+- Medium: X findings
+- Low: X findings
+
+## Critical Issues
+[File:Line] - [Description]
+[Remediation steps]
+
+## Secrets Found
+[File:Line] - [Type of secret]
+[How to fix]
+
+## Vulnerable Dependencies
+[Package] - [CVE]
+[Update command]
+```
+
+## Exit Codes
+
+- `0` - No issues found
+- `1` - Low/Medium severity found
+- `2` - High severity found
+- `3` - Critical severity found
+
+## Next Steps
+
+1. Fix critical issues immediately
+2. Address high severity before deployment
+3. Plan medium/low fixes for next sprint