azclaude-copilot 0.1.0

package/templates/hooks/user-prompt.js

@@ -0,0 +1,96 @@
+#!/usr/bin/env node
+'use strict';
+/**
+ * AZCLAUDE — UserPromptSubmit hook
+ * Runs on every session's first prompt.
+ * Injects goals.md into context so Claude always knows the current thread.
+ * If previous session was interrupted (In progress entries remain), warns Claude.
+ * Works on: Windows (PowerShell/CMD/Git Bash), macOS, Linux.
+ */
+const fs   = require('fs');
+const path = require('path');
+const os   = require('os');
+
+// ── Hook profile gate ───────────────────────────────────────────────────────
+// AZCLAUDE_HOOK_PROFILE=minimal|standard|strict (default: standard)
+const HOOK_PROFILE = process.env.AZCLAUDE_HOOK_PROFILE || 'standard';
+
+// Fire once per session only — keyed by parent PID
+const marker = path.join(os.tmpdir(), `.azclaude-session-${process.ppid || process.pid}`);
+if (fs.existsSync(marker)) process.exit(0);
+try { fs.writeFileSync(marker, ''); } catch (_) {}
+
+// Only proceed if this is an AZCLAUDE project (goals.md exists)
+const goalsPath = path.join('.claude', 'memory', 'goals.md');
+if (!fs.existsSync(goalsPath)) process.exit(0);
+
+// Ensure required directories exist — only in AZCLAUDE projects
+for (const d of ['.claude/memory', '.claude/memory/checkpoints']) {
+  try { fs.mkdirSync(d, { recursive: true }); } catch (_) {}
+}
+
+// Strip prompt-injection attempts before outputting into context
+const INJECTION = /ignore.{0,20}previous.{0,20}instructions|curl.{0,10}\|.{0,10}bash|wget.{0,10}\|.{0,10}sh|you are now|system prompt/i;
+const content   = fs.readFileSync(goalsPath, 'utf8');
+const filtered  = content.split('\n').filter(l => !INJECTION.test(l)).join('\n');
+
+// Warn if previous session was interrupted (In progress entries survived)
+const ipMatch = filtered.match(/^## In progress\n((?:- .+\n?)+)/m);
+if (ipMatch) {
+  console.log('⚠ PREVIOUS SESSION INTERRUPTED — files were being edited:');
+  console.log(ipMatch[1].trimEnd());
+  console.log('Resume or discard before starting new work.');
+  console.log('');
+}
+
+// Cap "Done this session" to last 20 entries — older entries are still on disk
+const doneHeading = '## Done this session';
+const doneIdx     = filtered.indexOf(doneHeading);
+let output = filtered;
+if (doneIdx !== -1) {
+  const before    = filtered.slice(0, doneIdx);
+  const afterDone = filtered.slice(doneIdx + doneHeading.length);
+  const doneLines = afterDone.split('\n');
+  const entries   = [];
+  const rest      = [];
+  let   pastDone  = false;
+  for (const line of doneLines) {
+    if (pastDone) { rest.push(line); continue; }
+    if (line.startsWith('## ') && line.trim() !== '') { pastDone = true; rest.push(line); continue; }
+    entries.push(line);
+  }
+  const MAX_DONE = 20;
+  const entryLines = entries.filter(l => l.startsWith('- '));
+  if (entryLines.length > MAX_DONE) {
+    const trimmed = entryLines.slice(0, MAX_DONE);
+    const nonEntries = entries.filter(l => !l.startsWith('- '));
+    const omitted = entryLines.length - MAX_DONE;
+    output = before + doneHeading + '\n' + trimmed.join('\n') + `\n- ... ${omitted} earlier entries (on disk)\n` + nonEntries.filter(l => l.trim()).join('\n') + '\n' + rest.join('\n');
+  }
+}
+
+console.log('--- ACTIVE GOALS ---');
+console.log(output);
+console.log('--- END GOALS ---');
+
+// Inject latest checkpoint if one exists — captures mid-session reasoning
+const checkpointDir = path.join('.claude', 'memory', 'checkpoints');
+if (fs.existsSync(checkpointDir)) {
+  const files = fs.readdirSync(checkpointDir)
+    .filter(f => f.endsWith('.md'))
+    .sort()
+    .reverse(); // latest first
+  if (files.length > 0) {
+    const latest = path.join(checkpointDir, files[0]);
+    const cpContent = fs.readFileSync(latest, 'utf8');
+    const cpLines    = cpContent.split('\n').filter(l => !INJECTION.test(l));
+    const MAX_CP     = 50;
+    const cpTrimmed  = cpLines.length > MAX_CP
+      ? cpLines.slice(0, MAX_CP).concat([`... ${cpLines.length - MAX_CP} more lines (on disk)`])
+      : cpLines;
+    console.log('');
+    console.log(`--- LAST CHECKPOINT (${files[0]}) ---`);
+    console.log(cpTrimmed.join('\n').trim());
+    console.log('--- END CHECKPOINT ---');
+  }
+}

package/templates/scripts/env-scan.sh

@@ -0,0 +1,46 @@
+#!/bin/bash
+# AZCLAUDE Environment Scanner
+# Runs as a single script — output (JSON) is what enters Claude's context.
+# Not 15 separate tool calls. One script, one result, ~200 tokens.
+
+FILE_COUNT=$(find . \
+  -not -path './node_modules/*' \
+  -not -path './.git/*' \
+  -not -path './.claude/*' \
+  \( -name '*.md' -o -name '*.json' -o -name '*.js' -o -name '*.ts' \
+     -o -name '*.py' -o -name '*.rs' -o -name '*.go' \) \
+  2>/dev/null | wc -l | tr -d ' ')
+
+has_file() { [ -f "$1" ] && echo true || echo false; }
+has_dir()  { [ -d "$1" ] && echo true || echo false; }
+count_files() { ls "$1"/*.md 2>/dev/null | wc -l | tr -d ' ' || echo 0; }
+
+cat <<EOF
+{
+  "file_count": $FILE_COUNT,
+  "scale": $(
+    if   [ "$FILE_COUNT" -lt 100  ]; then echo '"STANDARD"'
+    elif [ "$FILE_COUNT" -lt 500  ]; then echo '"SKIM"'
+    elif [ "$FILE_COUNT" -lt 2000 ]; then echo '"MINIMAL"'
+    else echo '"STRUCTURE-ONLY"'
+    fi
+  ),
+  "signals": {
+    "has_package_json":    $(has_file package.json),
+    "has_requirements":    $(has_file requirements.txt),
+    "has_cargo":           $(has_file Cargo.toml),
+    "has_gomod":           $(has_file go.mod),
+    "has_pyproject":       $(has_file pyproject.toml),
+    "has_knowledge_dir":   $(has_dir knowledge),
+    "has_claude_md":       $(has_file CLAUDE.md),
+    "claude_md_count":     $(find . -name 'CLAUDE.md' 2>/dev/null | wc -l | tr -d ' '),
+    "has_git":             $(has_dir .git),
+    "has_mcp":             $(has_file .mcp.json),
+    "has_memory":          $(has_file .claude/memory/goals.md),
+    "commands_count":      $(count_files .claude/commands 2>/dev/null),
+    "agents_count":        $(count_files .claude/agents 2>/dev/null)
+  },
+  "git_log": "$(git log --oneline -5 2>/dev/null | head -5 | tr '\n' '|' | sed 's/"/\\"/g' || echo 'none')",
+  "readme_head": "$(head -10 README.md 2>/dev/null | tr '\n' '|' | sed 's/"/\\"/g' || echo 'none')"
+}
+EOF

package/templates/scripts/import-graph.sh

@@ -0,0 +1,88 @@
+#!/usr/bin/env bash
+set -euo pipefail
+# import-graph.sh — Lightweight dependency mapper
+# Purpose: Build import/dependency graph from grep, detect circular deps
+# Usage: bash .claude/scripts/import-graph.sh [project-dir]
+# Output: structured text showing imports per file + circular dependencies
+# Zero dependencies — just grep. No ast-grep, no vector DB, no Docker.
+
+ROOT="${1:-.}"
+cd "$ROOT"
+
+echo "## Import Graph — $(basename "$(pwd)")"
+echo ""
+
+# ── Detect language ──────────────────────────────────────────────────────────
+HAS_TS=$(find . -name "*.ts" -o -name "*.tsx" -not -path "*/node_modules/*" 2>/dev/null | head -1)
+HAS_PY=$(find . -name "*.py" -not -path "*/__pycache__/*" -not -path "*/venv/*" 2>/dev/null | head -1)
+HAS_GO=$(find . -name "*.go" -not -path "*/vendor/*" 2>/dev/null | head -1)
+
+# ── Extract imports ──────────────────────────────────────────────────────────
+TMPFILE=$(mktemp)
+trap 'rm -f "$TMPFILE"' EXIT
+
+if [ -n "$HAS_TS" ]; then
+  echo "Language: TypeScript/JavaScript"
+  grep -rn "^import\|^const.*require(" --include="*.ts" --include="*.tsx" --include="*.js" --include="*.jsx" \
+    --exclude-dir=node_modules --exclude-dir=.git --exclude-dir=dist . 2>/dev/null | \
+    sed 's/:.*//' | sort | uniq -c | sort -rn | head -20 > "$TMPFILE"
+fi
+
+if [ -n "$HAS_PY" ]; then
+  echo "Language: Python"
+  grep -rn "^import\|^from.*import" --include="*.py" \
+    --exclude-dir=__pycache__ --exclude-dir=venv --exclude-dir=.git . 2>/dev/null | \
+    sed 's/:.*//' | sort | uniq -c | sort -rn | head -20 > "$TMPFILE"
+fi
+
+if [ -n "$HAS_GO" ]; then
+  echo "Language: Go"
+  grep -rn "^import" --include="*.go" \
+    --exclude-dir=vendor --exclude-dir=.git . 2>/dev/null | \
+    sed 's/:.*//' | sort | uniq -c | sort -rn | head -20 > "$TMPFILE"
+fi
+
+echo ""
+echo "### Most-imported files (by import count)"
+if [ -s "$TMPFILE" ]; then
+  cat "$TMPFILE"
+else
+  echo "(no imports detected)"
+fi
+
+# ── Circular dependency detection ────────────────────────────────────────────
+echo ""
+echo "### Circular dependency check"
+
+CIRCULARS=0
+if [ -n "$HAS_TS" ]; then
+  # Find files that import each other (A imports B AND B imports A)
+  grep -roh "from ['\"]\..*['\"]" --include="*.ts" --include="*.tsx" --include="*.js" . 2>/dev/null | \
+    sed "s/from ['\"]//;s/['\"]//g" | sort | uniq -d | while read -r imp; do
+      # Check if the target imports back
+      target_file=$(find . -path "*${imp}*" -name "*.ts" -o -path "*${imp}*" -name "*.tsx" 2>/dev/null | head -1)
+      if [ -n "$target_file" ]; then
+        source_dir=$(dirname "$target_file")
+        back_imports=$(grep -l "from.*${source_dir}" "$target_file" 2>/dev/null || true)
+        if [ -n "$back_imports" ]; then
+          echo "  ⚠ Possible circular: $imp ↔ $source_dir"
+          CIRCULARS=$((CIRCULARS + 1))
+        fi
+      fi
+    done
+fi
+
+if [ "$CIRCULARS" -eq 0 ]; then
+  echo "  ✓ No circular dependencies detected"
+fi
+
+# ── File co-change analysis (for /evolve) ────────────────────────────────────
+echo ""
+echo "### Co-change clusters (files that always commit together)"
+if command -v git &>/dev/null && [ -d .git ]; then
+  git log --name-only --format="" --diff-filter=M -50 2>/dev/null | \
+    sort | uniq -c | sort -rn | head -15 | \
+    awk '{if ($1 >= 3) print "  " $1 "x — " $2}'
+else
+  echo "  (not a git repo — skipping)"
+fi

package/templates/scripts/validate-boundaries.sh

@@ -0,0 +1,180 @@
+#!/usr/bin/env bash
+set -euo pipefail
+# validate-boundaries.sh — Detect overlap between commands, skills, capabilities, agents
+# Run by: /evolve Cycle 3, doctor --audit, or manually
+# Output: warnings for overlapping descriptions, stale manifest entries, orphaned files
+
+ROOT="${1:-.claude}"
+PASS=0
+WARN=0
+
+echo "## Boundary Validation"
+echo ""
+
+# ── 1. Manifest completeness: every capability file is listed ────────────────
+echo "### Manifest completeness"
+if [ -f "$ROOT/capabilities/manifest.md" ]; then
+  for cap in "$ROOT"/capabilities/shared/*.md; do
+    [ -f "$cap" ] || continue
+    name=$(basename "$cap")
+    if ! grep -q "$name" "$ROOT/capabilities/manifest.md" 2>/dev/null; then
+      echo "  ⚠ $name exists but not in manifest.md"
+      WARN=$((WARN + 1))
+    else
+      PASS=$((PASS + 1))
+    fi
+  done
+  echo "  Checked: $((PASS + WARN)) capabilities, $WARN missing from manifest"
+else
+  echo "  ⚠ No manifest.md found"
+  WARN=$((WARN + 1))
+fi
+
+# ── 2. Description overlap: same trigger words in multiple extensions ────────
+echo ""
+echo "### Description overlap detection"
+OVERLAP_FOUND=0
+
+# Extract all description fields from commands, skills, agents
+TMPDIR_V=$(mktemp -d)
+trap 'rm -rf "$TMPDIR_V"' EXIT
+
+for cmd in "$ROOT"/commands/*.md; do
+  [ -f "$cmd" ] || continue
+  name=$(basename "$cmd" .md)
+  grep -i "description\|triggers on\|use when" "$cmd" 2>/dev/null | tr '[:upper:]' '[:lower:]' > "$TMPDIR_V/cmd-$name.txt"
+done
+
+for skill_dir in "$ROOT"/skills/*/; do
+  [ -f "${skill_dir}SKILL.md" ] || continue
+  name=$(basename "$skill_dir")
+  grep -i "description\|triggers on\|use when" "${skill_dir}SKILL.md" 2>/dev/null | tr '[:upper:]' '[:lower:]' > "$TMPDIR_V/skill-$name.txt"
+done
+
+for agent in "$ROOT"/agents/*.md; do
+  [ -f "$agent" ] || continue
+  name=$(basename "$agent" .md)
+  grep -i "description\|triggers on\|use when" "$agent" 2>/dev/null | tr '[:upper:]' '[:lower:]' > "$TMPDIR_V/agent-$name.txt"
+done
+
+# Check for files with highly similar trigger words
+for f1 in "$TMPDIR_V"/*; do
+  [ -f "$f1" ] || continue
+  for f2 in "$TMPDIR_V"/*; do
+    [ -f "$f2" ] || continue
+    [ "$f1" = "$f2" ] && continue
+    # Count shared significant words (> 5 chars)
+    shared=$(comm -12 \
+      <(tr ' ,.:;|' '\n' < "$f1" | grep -E '^.{5,}$' | sort -u) \
+      <(tr ' ,.:;|' '\n' < "$f2" | grep -E '^.{5,}$' | sort -u) \
+      2>/dev/null | wc -l | tr -d ' ')
+    if [ "$shared" -gt 8 ]; then
+      n1=$(basename "$f1" .txt)
+      n2=$(basename "$f2" .txt)
+      # Only report each pair once (alphabetical order)
+      if [ "$n1" \< "$n2" ]; then
+        echo "  ⚠ Possible overlap: $n1 ↔ $n2 ($shared shared trigger words)"
+        OVERLAP_FOUND=$((OVERLAP_FOUND + 1))
+      fi
+    fi
+  done
+done
+
+if [ "$OVERLAP_FOUND" -eq 0 ]; then
+  echo "  ✓ No significant overlaps detected"
+  PASS=$((PASS + 1))
+else
+  WARN=$((WARN + OVERLAP_FOUND))
+fi
+
+# ── 3. Orphaned files: extensions not referenced anywhere ────────────────────
+echo ""
+echo "### Orphan detection"
+ORPHANS=0
+
+for agent in "$ROOT"/agents/*.md; do
+  [ -f "$agent" ] || continue
+  name=$(basename "$agent" .md)
+  # Check if agent is referenced in any command, skill, or CLAUDE.md
+  refs=$(grep -rl "$name" "$ROOT/commands/" "$ROOT/capabilities/" CLAUDE.md 2>/dev/null | wc -l | tr -d ' ')
+  if [ "$refs" -eq 0 ]; then
+    echo "  ⚠ Agent $name.md not referenced in any command or capability"
+    ORPHANS=$((ORPHANS + 1))
+  fi
+done
+
+if [ "$ORPHANS" -eq 0 ]; then
+  echo "  ✓ No orphaned agents"
+  PASS=$((PASS + 1))
+else
+  WARN=$((WARN + ORPHANS))
+fi
+
+# ── 4. Command name collision with Claude Code built-ins ─────────────────────
+echo ""
+echo "### Claude Code collision check"
+BUILTINS="clear reset new compact config settings context copy cost desktop app diff doctor effort exit quit export fast feedback bug branch fork help hooks ide init insights keybindings login logout mcp memory model passes permissions plan plugin pr-comments release-notes review rewind checkpoint sandbox security-review skills stats status statusline stickers tasks terminal-setup theme upgrade usage vim voice"
+
+COLLISIONS=0
+for cmd in "$ROOT"/commands/*.md; do
+  [ -f "$cmd" ] || continue
+  name=$(basename "$cmd" .md)
+  if echo "$BUILTINS" | tr ' ' '\n' | grep -qx "$name"; then
+    echo "  ⚠ /$name collides with Claude Code built-in"
+    COLLISIONS=$((COLLISIONS + 1))
+  fi
+done
+
+if [ "$COLLISIONS" -eq 0 ]; then
+  echo "  ✓ No collisions with Claude Code built-ins"
+  PASS=$((PASS + 1))
+else
+  WARN=$((WARN + COLLISIONS))
+fi
+
+# ── Summary ──────────────────────────────────────────────────────────────────
+echo ""
+echo "### Summary: $PASS passed, $WARN warnings"
+if [ "$WARN" -gt 0 ]; then
+  echo "  Run /evolve to auto-fix overlaps and orphans"
+fi
+
+# ── Machine-readable output (last line, always) ─────────────────────────────
+# Format: BOUNDARY_RESULT:pass=N:warn=N
+# Parsed by doctor --audit instead of counting ⚠ symbols
+echo ""
+echo "BOUNDARY_RESULT:pass=$PASS:warn=$WARN"
+
+# ── JSON report (structured, diffable, CI-friendly) ─────────────────────────
+REPORT_DIR="$ROOT/memory/metrics"
+mkdir -p "$REPORT_DIR" 2>/dev/null || true
+REPORT_PATH="$REPORT_DIR/boundaries.json"
+TIMESTAMP=$(date -u +"%Y-%m-%dT%H:%M:%SZ")
+
+cat > "$REPORT_PATH" << JSONEOF
+{
+  "timestamp": "$TIMESTAMP",
+  "pass": $PASS,
+  "warn": $WARN,
+  "manifest_gaps": $([ -f "$ROOT/capabilities/manifest.md" ] && {
+    gaps=0
+    for cap in "$ROOT"/capabilities/shared/*.md; do
+      [ -f "$cap" ] || continue
+      grep -q "$(basename "$cap")" "$ROOT/capabilities/manifest.md" 2>/dev/null || gaps=$((gaps + 1))
+    done
+    echo $gaps
+  } || echo 0),
+  "orphaned_agents": $(for a in "$ROOT"/agents/*.md; do
+    [ -f "$a" ] || continue
+    n=$(basename "$a" .md)
+    grep -rl "$n" "$ROOT/commands/" "$ROOT/capabilities/" CLAUDE.md 2>/dev/null | wc -l | tr -d ' '
+  done | awk '$1==0{c++}END{print c+0}'),
+  "collisions": $COLLISIONS,
+  "overlaps": $OVERLAP_FOUND
+}
+JSONEOF
+
+echo "  Report written: $REPORT_PATH"
+
+# Exit code: 0 if no warnings, 1 if warnings found
+exit $( [ "$WARN" -eq 0 ] && echo 0 || echo 1 )

package/templates/skills/agent-creator/SKILL.md

@@ -0,0 +1,91 @@
+---
+name: agent-creator
+description: >
+  Creates and improves Claude Code agent definitions. Use when the user says
+  "create an agent", "add an agent", "new agent", "build an agent", "write
+  an agent", "make an agent", "I need an agent for", "agent for", "custom
+  agent", "specialized agent", "add a reviewer", "add a builder". Also use
+  when an existing agent is incomplete, making mistakes, missing context,
+  producing inconsistent results, or needs its 5-layer structure fixed.
+  Use when splitting work across multiple agents, defining agent boundaries,
+  checking agent overlap, or pairing agents with skills. Even if the user
+  doesn't say "agent", use this when they describe a workstream that needs
+  isolation, parallelism, or specialized context.
+---
+
+# Agent Creator
+
+Creates production-quality Claude Code agents following the 5-layer structure.
+An agent is an OWNERSHIP BOUNDARY — not a persona. If two agents can do the
+same task, one shouldn't exist.
+
+## 5-Minute Checklist
+Before diving into the full workflow, verify these 5 essentials:
+1. Does this workstream genuinely need isolation or parallelism? (If not, a skill is enough)
+2. Is the description pushy enough? (30+ trigger keywords, ends with "even if...")
+3. Are all 5 layers filled? (Persona, Scope, Tools, Constraints, Domain — Domain is largest)
+4. Does Scope have explicit DOES NOT TOUCH boundaries? (Without them, agents drift)
+5. Are constraints positive directives that hold under pressure? ("Always X" not "Don't Y")
+
+## When NOT to Create an Agent
+- A skill with direct tool calls can do the same work — agents add coordination overhead
+- The "agent" would just read one file and return its content — that's a tool call, not an agent
+- You're using agents as a routing mechanism — routing belongs in CLAUDE.md, not agents
+- Two existing agents already cover this territory — merge or tighten scope instead
+- The project has < 20 files — CLAUDE.md alone is probably enough
+
+## Workflow
+
+1. **Determine boundaries.** Run co-change analysis to find what changes together:
+   ```bash
+   bash .claude/skills/agent-creator/scripts/scaffold.sh --analyze
+   ```
+
+2. **Generate the agent file:**
+   ```bash
+   bash .claude/skills/agent-creator/scripts/scaffold.sh AGENT_NAME
+   ```
+
+3. **Write the description.** Follow the pushy formula — 30+ trigger keywords.
+   End with: "even if not explicitly mentioned, route to this agent when..."
+
+4. **Fill all 5 layers:**
+   - Layer 1 PERSONA (5%) — one sentence role, not personality
+   - Layer 2 SCOPE (25%) — what it OWNS + what it does NOT touch
+   - Layer 3 TOOLS (10%) — restrictions matter more than grants
+   - Layer 4 CONSTRAINTS (25%) — positive directives, 5-10 max
+   - Layer 5 DOMAIN (35%) — project-specific knowledge, the real value
+
+5. **Check framework collision:**
+   ```bash
+   grep -r "langgraph\|crewai\|autogen\|langchain.*agent" pyproject.toml package.json 2>/dev/null
+   ```
+   If found: prefix all agents with `cc-` (e.g., `cc-backend`).
+
+6. **Pair with skills.** Add mandatory skill check to agent body:
+   "Before writing any code, check if a skill matches this task."
+
+7. **Validate.** Read `references/quality-checklist.md` and verify all items pass.
+
+## Rules
+- 3-5 agents for most projects (3 focused > 6 overlapping)
+- Layer 5 (Domain) matters more than Layer 1 (Persona) — domain drives correctness
+- Every agent has explicit DOES NOT TOUCH boundaries in scope
+- Positive directives: "Always validate" not "Don't skip validation"
+- Review agents: read-only (planMode), no Write/Edit tools
+- Experiment agents: isolated in git worktree
+- Testing is a responsibility, not a role — agent owns its test files
+- `disable-model-invocation: true` ONLY for dangerous agents
+
+## Agent Sizing Guide
+| Project size | Recommended agents |
+|---|---|
+| < 20 files | 1-2 (or none — CLAUDE.md is enough) |
+| 20-100 files | 2-3 |
+| 100-500 files | 3-5 |
+| 500+ files | 4-6 with SKIM mode |
+
+## References
+For the complete agent engineering guide: `references/agent-engineering-guide.md`
+For the quality checklist: `references/quality-checklist.md`
+For a sample agent output: `examples/sample-agent.md`

package/templates/skills/agent-creator/examples/sample-agent.md

@@ -0,0 +1,80 @@
+# Example: Backend API Agent
+
+## Input
+User asked: "create an agent for the backend API layer"
+
+## Output: Generated .claude/agents/cc-backend.md
+
+```yaml
+---
+name: cc-backend
+description: >
+  Backend API specialist. Route to this agent for: API endpoints, routes,
+  middleware, request validation, response formatting, database queries,
+  repository pattern, migrations, Alembic, SQLAlchemy, Pydantic models,
+  authentication, authorization, JWT, OAuth, session management, rate
+  limiting, caching, Redis, background tasks, error handling, logging,
+  health checks, OpenAPI schema, FastAPI dependencies, Depends(), testing
+  API routes, pytest, httpx, integration tests. Also handles: performance
+  issues in API layer, N+1 queries, slow endpoints, connection pooling.
+  Even if the user doesn't mention "backend" or "API", route here when
+  the task involves any server-side code in src/api/, src/middleware/,
+  or src/db/.
+tools: Read, Write, Edit, Bash, Grep, Glob
+model: sonnet
+permissionMode: acceptEdits
+---
+
+## Layer 1: PERSONA
+Backend API specialist. Writes production-quality API code with tests.
+
+## Layer 2: SCOPE
+OWNS: src/api/, src/middleware/, src/db/, tests/api/
+DOES NOT TOUCH: src/frontend/, src/workers/, infrastructure/
+
+## Layer 3: TOOLS & RESOURCES
+- Read, Write, Edit: for all files in scope
+- Bash: for running tests and scripts only
+- Grep, Glob: for searching codebase
+RESTRICTIONS:
+- Do NOT use Bash for installing packages (ask the user)
+- Do NOT use Write on files outside scope directories
+
+## Layer 4: CONSTRAINTS
+- Always write the failing test BEFORE implementation code
+- Always run existing tests after every change: `pytest tests/api/ -x`
+- Always include error handling for every external call
+- Always log structured JSON, never print() or console.log()
+- Always validate inputs on user-facing endpoints
+- Reference the specific requirement being implemented
+
+## Layer 5: DOMAIN CONTEXT
+### Architecture
+FastAPI application with:
+- Pydantic v2 for all models (use .model_dump(), not .dict())
+- SQLAlchemy 2.0 async (always use async session)
+- Alembic for migrations (never modify tables directly)
+- Redis for caching (connection pool in src/core/redis.py)
+
+### Conventions
+- One router per domain (auth_router, users_router, billing_router)
+- All routes use Depends() for auth and database session
+- Error responses: RFC 7807 format via src/core/errors.py
+- Cursor-based pagination (see src/core/pagination.py)
+
+### Patterns
+- Repository pattern for all database access
+- Service layer between routes and repos for business logic
+- Background tasks via FastAPI BackgroundTasks, not Celery
+
+### Self-Correction
+If the first attempt fails: re-read the error, try one alternative.
+After 2 attempts: stop. Present what was tried, what the error says,
+what is needed to proceed.
+
+## Before Starting Any Task
+1. Read .claude/memory/patterns.md for project conventions
+2. Read .claude/memory/antipatterns.md for known mistakes
+3. Check if a relevant skill matches this task type
+4. If touching auth or payments → load security-review skill
+```