ai-sprint-kit 1.1.0

package/templates/.claude/statusline.sh

@@ -0,0 +1,126 @@
+#!/usr/bin/env bash
+# AI Sprint Statusline
+# Displays: directory, git branch, model, context usage, cost
+# Requires: jq (optional - graceful fallback without it)
+
+set -euo pipefail
+
+# Check for jq
+HAS_JQ=false
+command -v jq >/dev/null 2>&1 && HAS_JQ=true
+
+# Read JSON from stdin
+INPUT=$(cat)
+
+# Fallback without jq
+if ! $HAS_JQ; then
+    echo "🚀 AI Sprint"
+    exit 0
+fi
+
+# --- Helper Functions ---
+
+# Expand home directory to ~
+expand_home() {
+    local path="$1"
+    echo "${path/#$HOME/~}"
+}
+
+# Get git branch
+get_git_branch() {
+    if git rev-parse --git-dir >/dev/null 2>&1; then
+        git branch --show-current 2>/dev/null || git rev-parse --short HEAD 2>/dev/null || echo ""
+    fi
+}
+
+# Progress bar (12 chars): ▰▰▰▱▱▱▱▱▱▱▱▱
+progress_bar() {
+    local percent=${1:-0}
+    local width=12
+
+    # Clamp to 0-100
+    (( percent < 0 )) && percent=0
+    (( percent > 100 )) && percent=100
+
+    local filled=$((percent * width / 100))
+    local empty=$((width - filled))
+
+    local bar=""
+    for ((i=0; i<filled; i++)); do bar+="▰"; done
+    for ((i=0; i<empty; i++)); do bar+="▱"; done
+
+    echo "$bar"
+}
+
+# Severity emoji based on percentage
+severity_emoji() {
+    local percent=${1:-0}
+    if (( percent >= 90 )); then echo "🔴"
+    elif (( percent >= 70 )); then echo "🟡"
+    else echo "🟢"
+    fi
+}
+
+# --- Parse JSON ---
+
+# Directory
+CWD=$(echo "$INPUT" | jq -r '.workspace.current_dir // .cwd // "unknown"')
+CWD=$(expand_home "$CWD")
+
+# Model
+MODEL=$(echo "$INPUT" | jq -r '.model.display_name // "Claude"')
+
+# Context window
+INPUT_TOKENS=$(echo "$INPUT" | jq -r '.context_window.total_input_tokens // 0')
+OUTPUT_TOKENS=$(echo "$INPUT" | jq -r '.context_window.total_output_tokens // 0')
+CONTEXT_SIZE=$(echo "$INPUT" | jq -r '.context_window.context_window_size // 0')
+
+CONTEXT_PCT=0
+if (( CONTEXT_SIZE > 0 )); then
+    TOTAL_TOKENS=$((INPUT_TOKENS + OUTPUT_TOKENS))
+    CONTEXT_PCT=$((TOTAL_TOKENS * 100 / CONTEXT_SIZE))
+fi
+
+# Cost (optional)
+COST=$(echo "$INPUT" | jq -r '.cost.total_cost_usd // empty')
+
+# Lines changed
+LINES_ADDED=$(echo "$INPUT" | jq -r '.cost.total_lines_added // 0')
+LINES_REMOVED=$(echo "$INPUT" | jq -r '.cost.total_lines_removed // 0')
+
+# --- Build Output ---
+
+OUTPUT=""
+
+# Directory
+OUTPUT+="📁 $CWD"
+
+# Git branch
+GIT_BRANCH=$(get_git_branch)
+if [[ -n "$GIT_BRANCH" ]]; then
+    OUTPUT+="  🌿 $GIT_BRANCH"
+fi
+
+# Model
+OUTPUT+="  🤖 $MODEL"
+
+# Context usage
+if (( CONTEXT_PCT > 0 )); then
+    EMOJI=$(severity_emoji "$CONTEXT_PCT")
+    BAR=$(progress_bar "$CONTEXT_PCT")
+    OUTPUT+="  $EMOJI $BAR ${CONTEXT_PCT}%"
+fi
+
+# Cost (only show if non-zero)
+if [[ -n "$COST" && "$COST" != "null" && "$COST" != "0" ]]; then
+    # Format to 4 decimal places
+    COST_FMT=$(printf "%.4f" "$COST" 2>/dev/null || echo "$COST")
+    OUTPUT+="  💵 \$$COST_FMT"
+fi
+
+# Lines changed
+if (( LINES_ADDED > 0 || LINES_REMOVED > 0 )); then
+    OUTPUT+="  📝 +$LINES_ADDED -$LINES_REMOVED"
+fi
+
+echo "$OUTPUT"

package/templates/.claude/workflows/development-rules.md

@@ -0,0 +1,97 @@
+# Development Rules
+
+Core principles enforced across all agents and commands.
+
+## Core Principles
+
+1. **YAGNI** - You Aren't Gonna Need It
+2. **KISS** - Keep It Simple, Stupid
+3. **DRY** - Don't Repeat Yourself
+4. **Security-First** - Security in every layer
+
+## Date Handling
+
+**CRITICAL**: Never guess dates. Always use bash:
+```bash
+date "+%Y-%m-%d"     # For reports: 2025-12-24
+date "+%y%m%d-%H%M"  # For filenames: 251224-2115
+```
+
+## Context Engineering
+
+All AI context stored under `ai_context/`:
+```
+ai_context/
+├── plans/         # Implementation plans
+├── docs/          # AI-specific documentation
+├── refs/          # Reference materials
+├── memory/        # Session memory
+│   ├── learning.md    # Retrospective lessons
+│   ├── decisions.md   # Key decisions log
+│   └── active.md      # Current session state
+└── reports/       # Agent reports
+```
+
+## Memory Integration
+
+Before any task:
+- Check `ai_context/memory/learning.md` for past lessons
+
+After any task:
+- Update `ai_context/memory/learning.md` with new lessons
+- Record decisions in `ai_context/memory/decisions.md`
+
+## Quality Gates
+
+### Code Quality
+- [ ] All tests passing
+- [ ] >80% code coverage
+- [ ] No linting errors
+- [ ] Types complete (TypeScript)
+
+### Security
+- [ ] No hardcoded secrets
+- [ ] Input validation present
+- [ ] OWASP Top 10 compliant
+- [ ] Security scan passed
+
+### Documentation
+- [ ] Code comments where needed
+- [ ] API documented
+- [ ] README updated
+
+## Agent DO NOT Directives
+
+Every agent must follow:
+- DO NOT guess dates - use bash date command
+- DO NOT hardcode secrets
+- DO NOT skip security checks
+- DO NOT leave failing tests
+- DO NOT modify code without reading it first
+
+## Output Standards
+
+### Reports
+- Save to `ai_context/reports/` with timestamped filename
+- Use format: `{type}-{YYMMDD}-{slug}.md`
+- Include date from bash command
+
+### Plans
+- Save to `ai_context/plans/` with timestamped folder
+- Use format: `{YYMMDD-HHMM}-{feature}/`
+- Include phase files if complex
+
+## Review Before Commit
+
+All code changes must pass:
+1. `/test` - All tests pass
+2. `/review` - Code quality check
+3. `/secure` - Security scan
+
+## Human-in-the-Loop Gates
+
+Require user approval for:
+- Production deployments
+- Infrastructure changes
+- Database migrations
+- Security vulnerability fixes

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

@@ -0,0 +1,194 @@
+# 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

@@ -0,0 +1,36 @@
+{
+  "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": {}
+    }
+  }
+}