Compositions

# CLAUDE.md
 
## Memory Routing
When working on authentication: load memory/project_auth_migration.md
When debugging API issues: load memory/reference_external_apis.md
When writing tests: load memory/feedback_testing.md
When deploying: load memory/reference_deploy_urls.md

---
description: Analyzes test failures and records patterns
memory: project
allowed-tools:
  - Read
  - Write
  - Edit
  - Bash
---
 
# Test Failure Analyst
 
When invoked:
1. Read the test output from stdin
2. Check memory/feedback_testing.md for known patterns
3. If this is a new pattern, append it to the memory file
4. Suggest fix based on accumulated knowledge

---
description: Reviews pull requests using accumulated codebase knowledge
memory: project
allowed-tools:
  - Read
  - Grep
  - Bash
---
 
# Code Reviewer
 
1. Read your MEMORY.md for known patterns and past review findings
2. Review the diff against accumulated knowledge
3. Flag patterns that violated conventions in past reviews
4. After review, write any new patterns to memory/feedback_review.md

First invocation:
  Agent reads empty MEMORY.md -> does work -> writes patterns found
 
Fifth invocation:
  Agent reads MEMORY.md with 4 sessions of patterns -> does work ->
  writes new patterns, merges with existing
 
Twentieth invocation:
  Agent has deep codebase knowledge -> catches subtle issues ->
  barely needs to explore code it's seen before

.claude/agent-memory/
  test-analyst/     # Only test-analyst reads/writes here
  code-reviewer/    # Only code-reviewer reads/writes here
  deploy-checker/   # Only deploy-checker reads/writes here

{
  "hooks": {
    "Stop": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "python3 ~/.claude/scripts/capture_session_knowledge.py",
            "timeout": 30000
          }
        ]
      }
    ]
  }
}

#!/usr/bin/env python3
# ~/.claude/scripts/capture_session_knowledge.py
import sys, json, os, re
from datetime import datetime
from pathlib import Path
 
input_data = json.loads(sys.stdin.read())
 
# Critical: check for recursive call
if input_data.get("stop_hook_active"):
    sys.exit(0)
 
session_id = input_data.get("session_id", "unknown")
project_path = input_data.get("cwd", os.getcwd())
 
# Derive memory directory from project path
encoded = project_path.replace("/", "-").lstrip("-")
memory_dir = Path.home() / ".claude" / "projects" / encoded / "memory"
memory_dir.mkdir(parents=True, exist_ok=True)
 
daily_file = memory_dir / f"daily/{datetime.now().strftime('%Y-%m-%d')}.md"
daily_file.parent.mkdir(parents=True, exist_ok=True)
 
# Append session marker
with open(daily_file, "a") as f:
    f.write(f"\n## Session {session_id} — {datetime.now().isoformat()}\n")
    f.write(f"- Working directory: {project_path}\n")
 
    # Extract transcript path if available
    transcript = input_data.get("transcript_path")
    if transcript and os.path.exists(transcript):
        with open(transcript) as t:
            for line in t:
                try:
                    entry = json.loads(line)
                    # Capture user corrections (messages starting with "no," "actually," "instead")
                    if entry.get("role") == "user":
                        text = entry.get("content", "")
                        if re.match(r"^(no[,.]|actually|instead|wrong|fix)", text, re.I):
                            f.write(f"- Correction: {text[:200]}\n")
                except json.JSONDecodeError:
                    continue
 
print("Session knowledge captured", file=sys.stderr)
sys.exit(0)

{
  "hooks": {
    "UserPromptSubmit": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "bash ~/.claude/scripts/preload-memory.sh"
          }
        ]
      }
    ]
  }
}

#!/bin/bash
# ~/.claude/scripts/preload-memory.sh
INPUT=$(cat)
QUERY=$(echo "$INPUT" | jq -r '.prompt')
CWD=$(echo "$INPUT" | jq -r '.cwd')
 
# Derive memory directory from project path
ENCODED=$(echo "$CWD" | tr '/' '-' | sed 's/^-//')
MEMORY_DIR="$HOME/.claude/projects/$ENCODED/memory"
 
[ -d "$MEMORY_DIR" ] || exit 0
 
# Extract keywords (3+ char words, skip stop words)
KEYWORDS=$(echo "$QUERY" | tr ' ' '\n' | grep -E '^.{3,}$' | \
  grep -viE '^(the|and|for|that|this|with|from|have|are|was)$' | head -5)
 
# Match index entries against query keywords
for kw in $KEYWORDS; do
  grep -il "$kw" "$MEMORY_DIR"/*.md 2>/dev/null
done | sort -u | head -3 | while read -r file; do
  echo "Relevant memory: $(basename "$file")" >&2
done
 
exit 0

Session -> Stop hook -> flush.py extracts knowledge ->
daily/YYYY-MM-DD.md -> compile.py ->
knowledge/concepts/, connections/, qa/ ->
SessionStart hook injects index -> next session

1. MCP query reveals API has new rate limit (discovered via monitoring MCP)
2. Claude updates memory/reference_external_apis.md with the new limit
3. Future sessions know about the rate limit without querying MCP again
4. MCP still used for current status; memory stores the stable finding

---
name: external-apis
description: Third-party API rate limits, quirks, retry configs, breaking change log
type: reference
---
 
## Stripe
- Rate limit: 100 requests/sec in live mode, 25/sec in test mode
- Webhook delivery: retries at 1h, 6h, 24h, 48h intervals
- Idempotency keys expire after 24 hours (discovered 2026-04-08)
- API version pinned to 2026-02-15 in dashboard
 
## Twilio
- Rate limit: 100 messages/sec per account (upgraded from default 1/sec)
- Webhook retry: 5s, 30s, 300s — then gives up
- Status callback URLs must be HTTPS in production (HTTP fails silently)
 
## SendGrid
- v3 API: 600 requests/min for free tier
- Template rendering timeout: 10s — complex Handlebars templates fail silently
- Event webhook delivers batched every 30s, not real-time

---
name: architecture-decisions
description: Key technical decisions, rationale, and alternatives considered
type: project
---
 
## 2026-04-10: Switched from gray-matter to next-mdx-remote
- Reason: gray-matter couldn't handle nested frontmatter in MDX 3.0
- Alternative considered: mdx-bundler (rejected: too heavy for SSG)
- Impact: Changed content pipeline in lib/posts.ts