An opinionated project initialization system for Claude Code. Agent teams by default, strict TDD pipeline, multi-engine code review, security-first.
The bottleneck has moved from code generation to code comprehension. AI can generate infinite code, but humans still need to review, understand, and maintain it. Claude Bootstrap provides guardrails that keep AI-generated code simple, secure, and verifiable.
New in v3.3.1: Mnemos two-layer post-compaction task restoration — guaranteed context recovery when Claude Code's compaction fires, crashes, or doesn't run. Typed memory graph (goals never evicted), 4-dimension fatigue monitoring, checkpoint/resume across sessions. iCPG intent-augmented code property graph — track why code exists, detect drift, prevent duplicate work.
┌────────────────────────────────────────────────────────────────┐
│ TDD LOOPS VIA STOP HOOKS │
│ ─────────────────────────────────────────────────────────────│
│ Stop hooks run tests after each Claude response. │
│ Failures feed back automatically. Claude iterates until green.│
│ Real Claude Code infrastructure — no plugins needed. │
├────────────────────────────────────────────────────────────────┤
│ TESTS FIRST, ALWAYS │
│ ─────────────────────────────────────────────────────────────│
│ Features: Write tests → Watch them fail → Implement → Pass │
│ Bugs: Find test gap → Write failing test → Fix → Pass │
│ No code ships without a test that failed first. │
├────────────────────────────────────────────────────────────────┤
│ SIMPLICITY IS THE GOAL │
│ ─────────────────────────────────────────────────────────────│
│ 20 lines per function │ 200 lines per file │ 3 params max │
│ Enforced via .claude/rules/ with paths: frontmatter. │
├────────────────────────────────────────────────────────────────┤
│ SECURITY BY DEFAULT │
│ ─────────────────────────────────────────────────────────────│
│ No secrets in code │ Permission deny rules for .env files │
│ Dependency scanning │ Pre-commit hooks │ CI enforcement │
├────────────────────────────────────────────────────────────────┤
│ AGENT TEAMS BY DEFAULT │
│ ─────────────────────────────────────────────────────────────│
│ Every project runs as a coordinated team of AI agents. │
│ Agent definitions use proper frontmatter: tools, model, │
│ maxTurns, effort, disallowedTools. │
├────────────────────────────────────────────────────────────────┤
│ CONDITIONAL RULES │
│ ─────────────────────────────────────────────────────────────│
│ Rules in .claude/rules/ activate based on file paths. │
│ React rules only load when editing .tsx files. │
│ Python rules only load when editing .py files. │
│ Saves tokens. Reduces noise. More targeted guidance. │
└────────────────────────────────────────────────────────────────┘
# 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-projectClaude will:
- Validate tools - Check gh, vercel, supabase CLIs
- Ask questions - Language, framework, AI-first?, database, graph analysis level
- Set up repository - Create or connect GitHub repo
- Create structure - Skills, rules, settings, security, CI/CD, specs, todos
- Copy settings.json - Pre-configured permissions and Stop hooks
- Generate CLAUDE.md - With
@includedirectives for modular skills - Generate CLAUDE.local.md - Template for private developer overrides
- Spawn agent team - Deploy Team Lead + Quality + Security + Review + Merger + Feature agents
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).
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.mdThese 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.
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 |
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.
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 │
└─────────────────────────────────────────────────────────────┘
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 content with typed eviction priorities.
Layer 2 (guaranteed): Post-compaction injection via PreToolUse re-injects the full checkpoint on the first tool call after compaction. Doesn't depend on the summarizer. Fast path ~5ms when no compaction occurred.
You could — but you'd immediately face: what format? When to update? How to distinguish "this is critical" from "this is nice to have"? The MnemoGraph's typed nodes solve this:
| Node Type | Eviction Policy | Example |
|---|---|---|
| GoalNode | NEVER evict | "Implement auth module" |
| ConstraintNode | NEVER evict | "API backward compatibility" |
| ResultNode | Compress first | "JWT middleware tested" → summary kept |
| WorkingNode | Compress first | Current reasoning / in-progress analysis |
| ContextNode | Evictable | File contents → re-read from disk |
Without typed priorities, a checkpoint is just a blob. With them, the system knows goals > constraints > working memory > context, and makes intelligent decisions about what to restore within token budgets.
The real value isn't the happy path — it's when things go wrong:
| Failure Mode | CC Built-in | Mnemos |
|---|---|---|
| Session crash/collapse | Context gone | Checkpoint on disk survives |
/compact doesn't fire |
Truncation at limit | Fatigue hooks wrote checkpoints earlier |
| Multi-agent child dies | No recovery | Child's .mnemos/ has structured state |
| Forced restart | Generic summary | SessionStart reloads full checkpoint |
/clear fails in multi-agent |
Stuck in weird state | MnemoGraph is independent of CC's state |
4 dimensions passively observed from hooks — no agent cooperation needed:
| Dimension | Weight | Signal Source | Detects |
|---|---|---|---|
| Token utilization | 0.40 | Statusline JSON | How full the context window is |
| Scope scatter | 0.25 | PreToolUse file paths | Agent bouncing between directories |
| Re-read ratio | 0.20 | PreToolUse Read calls | Agent re-reading files (context loss) |
| Error density | 0.15 | PostToolUse outcomes | Agent struggling (high error rate) |
Fatigue states: FLOW (0-0.4) → COMPRESS (0.4-0.6) → PRE-SLEEP (0.6-0.75) → REM (0.75-0.9) → EMERGENCY (0.9+). The fatigue model ensures checkpoints are written before things go wrong — so when a crash happens at 0.85, you have a recent checkpoint from 0.6.
mnemos init # Initialize .mnemos/
mnemos status # Node counts + fatigue
mnemos fatigue # Detailed 4-dimension breakdown
mnemos checkpoint --force # Write checkpoint now
mnemos resume # Output checkpoint for session inject
mnemos add goal "Build auth" # Create a GoalNode
mnemos bridge-icpg # Import iCPG ReasonNodesOverhead: ~5ms per tool call (fast path), 84KB on disk. Token signal auto-feeds via statusline.
iCPG tracks why code exists, not just what it does. Every code change is linked to a ReasonNode that captures the intent, postconditions, and invariants.
icpg create "Implement auth" --scope src/auth/ # Create intent
icpg record src/auth/middleware.ts # Link symbols
icpg query constraints src/auth/middleware.ts # Get invariants
icpg drift # Check for drift
icpg bootstrap # Infer from git historyPre-Task Queries (injected automatically via PreToolUse hook):
icpg query context <file>— What intents touch this file?icpg query constraints <file>— What invariants must hold?icpg drift file <file>— Has this file drifted from its intent?
6-Dimension Drift Detection: spec drift, decision drift, ownership drift, test drift, usage drift, dependency drift.
.claude/settings.json includes permission rules so users don't get pestered for routine operations:
{
"permissions": {
"allow": [
"Bash(npm test *)",
"Bash(npm run lint *)",
"Bash(pytest *)",
"Bash(git status *)",
"Bash(gh pr *)"
],
"deny": [
"Bash(rm -rf *)",
"Bash(git push --force *)",
"Write(.env)",
"Write(.env.*)"
]
}
}Each developer gets a .gitignore'd CLAUDE.local.md for personal preferences:
# My Preferences
- I prefer verbose explanations
- My local DB runs on port 5433
- Use pnpm instead of npmThis loads at higher priority than project CLAUDE.md — personal preferences override team config without polluting the repo.
Every project runs as a coordinated team of AI agents with proper frontmatter definitions:
# .claude/agents/team-lead.md
---
name: team-lead
description: Orchestrates the agent team
model: sonnet
tools: [Read, Glob, Grep, TaskCreate, TaskUpdate, TaskList, TaskGet, SendMessage]
disallowedTools: [Write, Edit, Bash]
maxTurns: 50
effort: high
---Default Team:
| Agent | Role | Can Edit Code? |
|---|---|---|
| Team Lead | Orchestrates, assigns tasks (never writes code) | No |
| Quality Agent | Verifies RED/GREEN TDD phases, coverage >= 80% | No |
| Security Agent | OWASP scanning, secrets detection, dependency audit | No |
| Code Review Agent | Multi-engine reviews | No |
| Merger Agent | Creates feature branches and PRs via gh CLI |
No |
| Feature Agent (x N) | One per feature, follows strict TDD pipeline | Yes |
Pipeline (enforced by task dependencies):
Spec > Spec Review > Tests > RED Verify > Implement >
GREEN Verify > Validate > Code Review > Security > Branch+PR
# Auto-spawned by /initialize-project, or manually:
/spawn-teamyour-project/
├── .claude/
│ ├── agents/ # Agent definitions with frontmatter
│ │ ├── team-lead.md # name, model, tools, disallowedTools, maxTurns
│ │ ├── quality.md
│ │ ├── security.md
│ │ ├── code-review.md
│ │ ├── merger.md
│ │ └── feature.md
│ ├── rules/ # Conditional rules (paths: frontmatter)
│ │ ├── quality-gates.md # Always active
│ │ ├── tdd-workflow.md # Always active
│ │ ├── security.md # Always active
│ │ ├── react.md # Active on .tsx/.jsx files
│ │ ├── typescript.md # Active on .ts/.tsx files
│ │ ├── python.md # Active on .py files
│ │ └── nodejs-backend.md # Active on api/routes/server files
│ ├── skills/ # Skills loaded via @include
│ │ ├── base/SKILL.md
│ │ ├── iterative-development/SKILL.md
│ │ ├── security/SKILL.md
│ │ ├── mnemos/SKILL.md
│ │ └── [framework]/SKILL.md
│ └── settings.json # Permissions + hooks + statusline
├── scripts/
│ ├── tdd-loop-check.sh # Stop hook script for TDD loops
│ ├── icpg/ # Intent-Augmented Code Property Graph
│ └── mnemos/ # Task-Scoped Memory Lifecycle
├── .mnemos/ # Mnemos state (auto-created, gitignored)
│ ├── mnemo.db # SQLite MnemoGraph
│ ├── fatigue.json # Live fatigue signal
│ ├── signals.jsonl # Behavioral signal log
│ └── checkpoint-latest.json # Most recent checkpoint
├── .github/workflows/
│ ├── quality.yml
│ └── security.yml
├── _project_specs/
│ ├── features/
│ └── todos/
├── CLAUDE.md # @include directives, project context
└── CLAUDE.local.md # Private developer overrides (gitignored)
┌─────────────────────────────────────────────────────────────┐
│ COMMIT SIZE THRESHOLDS │
├─────────────────────────────────────────────────────────────┤
│ OK: ≤ 5 files, ≤ 200 lines │
│ WARN: 6-10 files, 201-400 lines → "Commit soon" │
│ STOP: > 10 files, > 400 lines → "Commit NOW" │
└─────────────────────────────────────────────────────────────┘
| Skill | Purpose |
|---|---|
base.md |
Universal patterns, constraints, TDD workflow, atomic todos |
iterative-development.md |
TDD loops via Stop hooks (replaces Ralph Wiggum) |
mnemos.md |
Task-scoped memory lifecycle — fatigue monitoring, checkpoints, typed compaction |
icpg.md |
Intent-augmented code property graph — track why code exists, detect drift |
code-review.md |
Mandatory code reviews - Claude, Codex, Gemini, or multi-engine |
codex-review.md |
OpenAI Codex CLI code review |
gemini-review.md |
Google Gemini CLI code review, 1M token context |
workspace.md |
Multi-repo workspace awareness, contract tracking |
commit-hygiene.md |
Atomic commits, PR size limits |
code-deduplication.md |
Prevent semantic duplication with capability index |
agent-teams.md |
Agent team workflow with proper frontmatter definitions |
ticket-craft.md |
AI-native ticket writing optimized for Claude Code |
team-coordination.md |
Multi-person projects, shared state, handoffs |
code-graph.md |
Persistent code graph via MCP |
cpg-analysis.md |
Deep CPG analysis - Joern + CodeQL |
security.md |
OWASP patterns, secrets management |
credentials.md |
Centralized API key management |
session-management.md |
Context preservation, resumability |
project-tooling.md |
gh, vercel, supabase CLI + deployment |
existing-repo.md |
Analyze existing repos, setup guardrails |
| Skill | Purpose |
|---|---|
python.md |
Python + ruff + mypy + pytest |
typescript.md |
TypeScript strict + eslint + jest |
nodejs-backend.md |
Express/Fastify patterns, repositories |
react-web.md |
React + hooks + React Query + Zustand |
react-native.md |
Mobile patterns, platform-specific code |
android-java.md |
Android Java with MVVM, ViewBinding, Espresso |
android-kotlin.md |
Android Kotlin with Coroutines, Jetpack Compose, Hilt |
flutter.md |
Flutter with Riverpod, Freezed, go_router |
| Skill | Purpose |
|---|---|
ui-web.md |
Web UI - Tailwind, dark mode, accessibility |
ui-mobile.md |
Mobile UI - React Native, iOS/Android patterns |
ui-testing.md |
Visual testing |
playwright-testing.md |
E2E testing - Playwright, Page Objects |
user-journeys.md |
User experience flows |
pwa-development.md |
Progressive Web Apps - service workers, offline |
| Skill | Purpose |
|---|---|
database-schema.md |
Schema awareness |
supabase.md |
Core Supabase CLI, migrations, RLS |
supabase-nextjs.md |
Next.js + Supabase + Drizzle ORM |
supabase-python.md |
FastAPI + Supabase |
supabase-node.md |
Express/Hono + Supabase |
firebase.md |
Firebase Firestore, Auth, Storage |
cloudflare-d1.md |
Cloudflare D1 SQLite with Workers |
aws-dynamodb.md |
AWS DynamoDB single-table design |
aws-aurora.md |
AWS Aurora Serverless v2 |
azure-cosmosdb.md |
Azure Cosmos DB |
| Skill | Purpose |
|---|---|
agentic-development.md |
Build AI agents |
llm-patterns.md |
AI-first apps, LLM testing |
ai-models.md |
Latest models reference |
| Skill | Purpose |
|---|---|
aeo-optimization.md |
AI Engine Optimization |
web-content.md |
SEO + AI discovery |
site-architecture.md |
Technical SEO |
web-payments.md |
Stripe Checkout, subscriptions |
reddit-api.md |
Reddit API |
reddit-ads.md |
Reddit Ads API + agentic optimization |
ms-teams-apps.md |
Microsoft Teams bots |
posthog-analytics.md |
PostHog analytics |
shopify-apps.md |
Shopify app development |
woocommerce.md |
WooCommerce REST API |
medusa.md |
Medusa headless commerce |
klaviyo.md |
Klaviyo email/SMS marketing |
mkdir my-new-app && cd my-new-app
claude
> /initialize-projectcd my-existing-app
claude
> /initialize-project
# Auto-detects existing code → runs analysis firstcd "$(cat ~/.claude/.bootstrap-dir)"
git pull
./install.sh# GitHub CLI
brew install gh && gh auth login
# Vercel CLI (optional)
npm i -g vercel && vercel login
# Supabase CLI (optional)
brew install supabase/tap/supabase && supabase login| Feature | v2.x (Old) | v3.0.0 (New) |
|---|---|---|
| TDD Loops | Ralph Wiggum plugin (doesn't exist) | Stop hooks (real Claude Code infrastructure) |
| CLAUDE.md | Lists skills as text | @include directives (actually load at parse time) |
| Quality Rules | In CLAUDE.md as prose | .claude/rules/ with paths: frontmatter |
| Agent Teams | Required CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 |
Works natively via .claude/agents/ |
| Agent Definitions | Plain markdown | Proper frontmatter: tools, model, maxTurns, effort |
| Permissions | Manual approval for everything | Pre-configured allow/deny in settings.json |
| Developer Overrides | None | CLAUDE.local.md (gitignored, higher priority) |
| Framework Rules | Always loaded (57 skills = token waste) | Conditional rules activate by file path |
| Compaction | Generic summarization | PreCompact hook + Mnemos typed preservation |
| Memory | Lost on compaction/new session | Mnemos checkpoint/resume across sessions |
| Intent Tracking | None | iCPG links code to reasons, detects drift |
| Enforcement | "STRICTLY ENFORCED" prose | Real hooks that run code |
See CONTRIBUTING.md for guidelines.
See CHANGELOG.md for version history.
MIT - See LICENSE
Built on learnings from 100+ projects across customer experience management, agentic AI platforms, mobile apps, and full-stack web applications.
Need help scaling AI in your org? Claude Code & MCP experts