Quick Start

# Clone and install (clone anywhere you like)
git clone https://github.com/alinaqi/claude-bootstrap.git
cd claude-bootstrap && ./install.sh

# In any project directory
claude
> /initialize-project

Claude will:

1. Validate tools - Check gh, vercel, supabase CLIs
2. Ask questions - Language, framework, AI-first?, database, graph analysis level
3. Set up repository - Create or connect GitHub repo
4. Create structure - Skills, rules, settings, security, CI/CD, specs, todos
5. Copy settings.json - Pre-configured permissions and Stop hooks
6. Generate CLAUDE.md - With @include directives for modular skills
7. Generate CLAUDE.local.md - Template for private developer overrides
8. Spawn agent team - Deploy Team Lead + Quality + Security + Review + Merger + Feature agents

How TDD Loops Work (Stop Hooks)

No plugins. No fake commands. Claude Code's Stop hook runs a script when Claude finishes a response. Exit code 2 feeds stderr back to Claude and continues the conversation.

┌─────────────────────────────────────────────────────────────┐
│  1. You say: "Add email validation to signup"               │
│  2. Claude writes tests + implementation                    │
│  3. Claude finishes response                                │
│  4. Stop hook runs: npm test && npm run lint                │
│  5a. All pass (exit 0) → Done!                              │
│  5b. Failures (exit 2) → stderr fed back to Claude          │
│  6. Claude sees failures, fixes, finishes again             │
│  7. Stop hook runs again → repeat until green               │
└─────────────────────────────────────────────────────────────┘

Configuration in .claude/settings.json:

{
  "hooks": {
    "Stop": [{
      "hooks": [{
        "type": "command",
        "command": "scripts/tdd-loop-check.sh",
        "timeout": 60,
        "statusMessage": "Running tests..."
      }]
    }]
  }
}

The tdd-loop-check.sh script runs tests, lint, and typecheck. It tracks iteration count (max 25) and distinguishes code errors (loop) from environment errors (stop).

@include Directives

CLAUDE.md uses @include to modularly load skills:

# CLAUDE.md
@.claude/skills/base/SKILL.md
@.claude/skills/iterative-development/SKILL.md
@.claude/skills/security/SKILL.md

These are resolved at load time by Claude Code — the content is recursively inlined (max depth 5, cycle detection built in). This means skills actually become part of the prompt instead of just being listed as text.

Conditional Rules

Rules in .claude/rules/ use YAML frontmatter with paths: to activate only when relevant files are being edited:

# .claude/rules/react.md
---
paths: ["src/components/**", "**/*.tsx"]
---
Prefer functional components with hooks...

# .claude/rules/python.md
---
paths: ["**/*.py"]
---
Use type hints, pytest, ruff...

Included rules:

| Rule | Activates When | |------|----------------| | quality-gates.md | Always (no paths: filter) | | tdd-workflow.md | Always | | security.md | Always | | react.md | Editing .tsx/.jsx files | | typescript.md | Editing .ts/.tsx files | | python.md | Editing .py files | | nodejs-backend.md | Editing api/routes/server files |

Smarter Compaction (PreCompact Hook)

Claude Code's built-in compaction fires at ~83% context and summarizes everything into 20K tokens using a generic 9-section template. It doesn't know what YOUR project cares about.

The PreCompact hook fixes this by injecting project-specific preservation priorities into the summarizer:

┌─────────────────────────────────────────────────────────────┐
│  Built-in compaction:                                       │
│  "Summarize this conversation" → generic summary            │
├─────────────────────────────────────────────────────────────┤
│  With PreCompact hook:                                      │
│  "Summarize, but preserve ALL schema decisions verbatim,    │
│   keep exact error messages, keep API contract details,     │
│   reference these Key Decisions by name, and here's the     │
│   current git state to include" → project-aware summary     │
└─────────────────────────────────────────────────────────────┘

The hook auto-detects:

• Project type (TypeScript/Next.js, Python/FastAPI, Flutter, etc.)
• Schema files (Drizzle, Prisma, SQLAlchemy) → tells summarizer to preserve schema discussion
• API directories → tells summarizer to preserve endpoint paths and contracts
• Key Decisions from CLAUDE.md → tells summarizer to reference them by name
• Git state → injects branch, uncommitted changes, staged files

Zero overhead during normal usage. Only runs when compaction actually fires.

Mnemos — Task-Scoped Memory Lifecycle

Claude Code's built-in compaction is lossy and unreliable. It sometimes doesn't fire, /compact and /clear can fail (especially in multi-agent executions), and crashes/restarts lose all context. Mnemos provides disk-persistent structured state that survives all of these failure modes.

┌─────────────────────────────────────────────────────────────┐
│  DEFAULT CLAUDE CODE          vs  WITH MNEMOS               │
├─────────────────────────────────────────────────────────────┤
│  Blind until 83.5%               Continuous 4-dim monitoring│
│  Sudden hard compaction           Graduated: 40→60→75→83%   │
│  Uniform summarization            Typed: goals never evict  │
│  No cross-session memory          Auto checkpoint/resume    │
│  Crash = total context loss       Crash = resume from disk  │
│  Multi-agent: no shared state     Per-agent structured state│
│  No behavioral awareness          Detects re-reads, scatter │
└─────────────────────────────────────────────────────────────┘

Post-Compaction Task Restoration (Two-Layer Defense)

When compaction fires, the built-in summarizer often drops task-specific state. Mnemos uses two independent layers to guarantee restoration:

BEFORE COMPACTION                    AFTER COMPACTION

PreCompact hook fires                First tool call → PreToolUse fires
├── Write emergency checkpoint       ├── Detect ".mnemos/just-compacted" marker
├── Build task narrative from        ├── Read checkpoint-latest.json
│   signals.jsonl (files, tools)     ├── Output full checkpoint into context
├── Output STRONG preservation       ├── Delete marker (one-shot)
│   instructions to summarizer       └── Claude now has: summary + checkpoint
└── Write ".mnemos/just-compacted"
    marker file                      = Task fully restored

Layer 1 (best-effort): PreCompact tells the summarizer what to keep, including inline checkpoint conte