Claude Bootstrap

An opinionated project initialization system for Claude Code. TDD-first, iterative loops, security-first, AI-native.

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.

Core Philosophy

┌────────────────────────────────────────────────────────────────┐
│  ITERATIVE LOOPS BY DEFAULT                                    │
│  ─────────────────────────────────────────────────────────────│
│  Every task runs in a self-referential loop until tests pass.  │
│  Claude iterates autonomously. You describe what, not how.     │
│  Powered by Ralph Wiggum - iteration > perfection.             │
├────────────────────────────────────────────────────────────────┤
│  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 NON-NEGOTIABLE                                  │
│  ─────────────────────────────────────────────────────────────│
│  20 lines per function │ 200 lines per file │ 3 params max     │
│  If you can't understand the whole system in one session,      │
│  it's too complex.                                             │
├────────────────────────────────────────────────────────────────┤
│  SECURITY BY DEFAULT                                           │
│  ─────────────────────────────────────────────────────────────│
│  No secrets in code │ No secrets in client env vars            │
│  Dependency scanning │ Pre-commit hooks │ CI enforcement       │
├────────────────────────────────────────────────────────────────┤
│  CODE REVIEWS ARE MANDATORY                                    │
│  ─────────────────────────────────────────────────────────────│
│  Every commit requires /code-review before push.               │
│  🔴 Critical + 🟠 High = blocked │ 🟡 Medium + 🟢 Low = can ship │
│  AI catches what humans miss. Humans catch what AI misses.     │
└────────────────────────────────────────────────────────────────┘

Why This Exists

After hundreds of AI-assisted projects across Node, React, Python, and React Native, patterns emerged:

1. Engineers struggle with Claude Code not because of the tool, but because of how they instruct it - The delta is in the guardrails
2. Complexity has a ceiling - There's a point where AI loses coherent understanding of the system. That's a signal, not a failure
3. Restart is a feature, not failure - When fixing something increases complexity, restart with learnings. Each iteration is faster

This toolkit encodes those learnings into reusable skills.

Quick Start

# Clone and install
git clone https://github.com/alinaqi/claude-bootstrap.git ~/.claude-bootstrap
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
3. Set up repository - Create or connect GitHub repo
4. Create structure - Skills, security, CI/CD, specs, todos
5. Prompt for specs - Transition to defining first feature

Automatic Iterative Loops (Ralph Wiggum)

You talk naturally. Claude automatically runs iterative TDD loops.

┌─────────────────────────────────────────────────────────────┐
│  You say: "Add email validation to signup"                  │
├─────────────────────────────────────────────────────────────┤
│  Claude automatically:                                       │
│  1. Extracts requirements from your request                 │
│  2. Structures as TDD loop with completion criteria         │
│  3. Runs /ralph-loop with tests as exit condition           │
│  4. Iterates until all tests pass + lint clean              │
└─────────────────────────────────────────────────────────────┘

No need to manually invoke /ralph-loop. Just describe what you want:

| You Say | Claude Does | |---------|-------------| | "Add user authentication" | Loops until auth tests pass | | "Fix the login bug" | Finds test gap → writes test → loops until fixed | | "Build a REST API for todos" | Loops until all endpoint tests pass | | "Refactor the auth module" | Loops with tests as safety net |

Opt-out phrases (for when you don't want loops):

• "Just explain..." → explanation only
• "Quick fix..." → one-liner, no loop
• "Don't loop..." → explicit opt-out

Setup Ralph Wiggum Plugin

# Install from official marketplace (in Claude Code)
/plugin install ralph-loop@claude-plugins-official

Troubleshooting: "Source path does not exist: .../ralph-wiggum"

The plugin was renamed from ralph-wiggum to ralph-loop in the marketplace. If you see this error, the cache references the old name but the plugin folder uses the new name. Fix with a symlink:

ln -s ~/.claude/plugins/marketplaces/claude-plugins-official/plugins/ralph-loop \
      ~/.claude/plugins/marketplaces/claude-plugins-official/plugins/ralph-wiggum

Then retry /plugin install ralph-loop@claude-plugins-official.

Commit Hygiene (Automatic PR Size Management)

Claude monitors your changes and advises when to commit before PRs become too large.

┌─────────────────────────────────────────────────────────────┐
│  COMMIT SIZE THRESHOLDS                                     │
├─────────────────────────────────────────────────────────────┤
│  🟢 OK:     ≤ 5 files,  ≤ 200 lines                         │
│  🟡 WARN:   6-10 files, 201-400 lines  → "Commit soon"      │
│  🔴 STOP:   > 10 files, > 400 lines    → "Commit NOW"       │
└─────────────────────────────────────────────────────────────┘

Claude automatically checks and advises:

| Status | Claude Says | |--------|-------------| | 3 files, 95 lines | ✅ Tests passing. Good time to commit! | | 7 files, 225 lines | 💡 Approaching threshold. Consider committing. | | 12 files, 400 lines | ⚠️ Changes too large! Commit now. |

Why this matters:

• PRs < 200 lines: 15% defect rate
• PRs 200-400 lines: 23% defect rate
• PRs > 400 lines: 40%+ defect rate (rubber-stamped, not reviewed)

Atomic commit principle: If you need "and" to describe your commit, split it.

Agentic Ad Optimization (Reddit Ads)

Run automated Reddit ad campaigns with AI-powered optimization.

┌─────────────────────────────────────────────────────────────┐
│  BACKGROUND SERVICE (runs every 4-6 hours)                  │
├─────────────────────────────────────────────────────────────┤
│  1. Fetch performance data (CTR, CPA, ROAS)                 │
│  2. Claude analyzes and recommends actions                  │
│  3. Auto-execute: pause, scale, adjust bids, rotate ads     │
└─────────────────────────────────────────────────────────────┘

AI-driven actions:

| Action | Trigger | Result | |--------|---------|--------| | PAUSE | CTR < 0.3%, no conversions | Stop wasting budget | | SCALE | CTR > 1%, CPA < target | Increase budget 1.5x | | ADJUST_BID | Moderate performance | Tweak bids ±10-20% | | ROTATE_CREATIVE | Declining CTR 3+ days | Flag for new creative |

Deploy as Docker service:

docker-compose up -d reddit-ads-optimizer

Multi-Repo Workspace Awareness

Claude Code now understands your entire workspace - monorepo or multi-repo.

┌─────────────────────────────────────────────────────────────┐
│  /analyze-workspace                                          │
├─────────────────────────────────────────────────────────────┤
│  Discovers: Modules, dependencies, contracts                 │
│  Generates: TOPOLOGY.md, CONTRACTS.md, KEY_FILES.md         │
│  Tracks: API contracts, shared types, cross-repo changes    │
└─────────────────────────────────────────────────────────────┘

Generated context artifacts:

| Artifact | Purpose | |----------|---------| | TOPOLOGY.md | What modules exist, their roles, tech stacks | | CONTRACTS.md | API endpoints, shared types, validation status | | DEPENDENCY_GRAPH.md | Who calls whom, change order | | KEY_FILES.md | What to load for each context | | CROSS_REPO_INDEX.md | Search capabilities before reimplementing |

Contract freshness (automatic):

| Trigger | Action | Time | |---------|--------|------| | Session start | Staleness check | ~5s | | Post-commit | Auto-sync if contracts changed | ~15s | | Pre-push | Validation gate | ~10s |

Cross-repo change detection:

⚠️  CROSS-REPO CHANGE DETECTED
This change affects: apps/api
Recommended order: shared-types → backend → frontend

Code Reviews (Mandatory Guardrail)

Every push requires code review. No exceptions.

┌─────────────────────────────────────────────────────────────┐
│  WORKFLOW: Code → Test → Commit → Push → Review blocks     │
├─────────────────────────────────────────────────────────────┤
│  Run manually: /code-review                                 │
│  Enforced: Pre-push hook blocks on Critical/High            │
└─────────────────────────────────────────────────────────────┘

Enable pre-push hook in any project:

~/.claude/install-hooks.sh

Severity levels:

| Level | Action | Can Push? | |-------|--------|-----------| | 🔴 Critical | Must fix now | ❌ BLOCKED | | 🟠 High | Must fix now | ❌ BLOCKED | | 🟡 Medium | Fix soon | ✅ Advisory | | 🟢 Low | Nice to have | ✅ Advisory |

What it catches:

• Security vulnerabilities (SQL injection, XSS, secrets)
• Performance issues (N+1 queries, memory leaks)
• Architecture problems (coupling, SOLID violations)
• Code quality (complexity, dupli