Claude Bootstrap

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 v2.5.0: Every project now runs as a coordinated team of AI agents. A Team Lead orchestrates, a Quality Agent enforces TDD, a Security Agent scans for vulnerabilities, a Code Review Agent runs multi-engine reviews, a Merger Agent creates PRs, and dedicated Feature Agents implement each feature in parallel - all following an immutable pipeline: Spec > Tests > Fail > Implement > Pass > Review > Security > PR.

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.     │
├────────────────────────────────────────────────────────────────┤
│  AGENT TEAMS BY DEFAULT                                        │
│  ─────────────────────────────────────────────────────────────│
│  Every project runs as a coordinated team of AI agents.        │
│  Team Lead + Quality + Security + Review + Merger + Features   │
│  Strict pipeline: Spec > Test > Fail > Build > Pass > PR       │
│  Task dependencies make it impossible to skip steps.           │
└────────────────────────────────────────────────────────────────┘

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 (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
3. Set up repository - Create or connect GitHub repo
4. Create structure - Skills, security, CI/CD, specs, todos
5. Ask for features - List your key features
6. Spawn agent team - Deploy Team Lead + Quality + Security + Review + Merger + Feature agents
7. Work begins - Each feature runs the strict TDD pipeline in parallel

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 400 lines: 40%+ defect rate (rubber-stamped, not reviewed)

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

Agent Teams (Default Workflow)

Every project runs as a coordinated team of AI agents. Features are implemented in parallel by dedicated agents following a strict TDD pipeline.

┌─────────────────────────────────────────────────────────────┐
│  STRICT FEATURE PIPELINE (IMMUTABLE)                        │
├─────────────────────────────────────────────────────────────┤
│  1. Spec           Feature Agent writes specification       │
│  2. Spec Review    Quality Agent reviews completeness       │
│  3. Tests          Feature Agent writes failing tests       │
│  4. RED Verify     Quality Agent confirms tests FAIL        │
│  5. Implement      Feature Agent writes minimum code        │
│  6. GREEN Verify   Quality Agent confirms tests PASS        │
│  7. Validate       Feature Agent runs lint + typecheck      │
│  8. Code Review    Review Agent runs /code-review           │
│  9. Security Scan  Security Agent runs OWASP checks         │
│  10. Branch + PR   Merger Agent creates branch and PR       │
└─────────────────────────────────────────────────────────────┘

Default Team Roster:

Agent	Role
Team Lead	Orchestrates, assigns tasks, monitors progress (never writes code)
Quality Agent	Verifies RED/GREEN TDD phases, enforces coverage >= 80%
Security Agent	OWASP scanning, secrets detection, dependency audit
Code Review Agent	Multi-engine reviews (Claude/Codex/Gemini)
Merger Agent	Creates feature branches and PRs via gh CLI
Feature Agent (x N)	One per feature, follows strict TDD pipeline

How it works:

1. /initialize-project asks for your features
2. Spawns 5 permanent agents + 1 feature agent per feature
3. Creates 10-task dependency chain per feature (enforces pipeline order)
4. All features run in parallel - shared agents handle verification as tasks unblock
5. Each feature results in a separate PR with full pipeline results

Task dependencies make it structurally impossible to skip steps. A feature agent cannot implement until the quality agent verifies tests fail. The merger cannot create a PR until security scan passes.

10-task dependency chain per feature:

┌─────────────────────────────────────────────────────────────┐
│  Feature: "auth"                                             │
│                                                              │
│  auth-spec ──> auth-spec-review ──> auth-tests               │
│  (Feature)     (Quality)            (Feature)                │
│                                         │                    │
│  auth-fail-verify ──> auth-implement ──> auth-pass-verify    │
│  (Quality)            (Feature)          (Quality)           │
│                                              │               │
│  auth-validate ──> auth-code-review ──> auth-security        │
│  (Feature)         (Review Agent)       (Security)           │
│                                              │               │
│  auth-branch-pr                                              │
│  (Merger)                                                    │
│                                                              │
│  Each arrow = addBlockedBy dependency                        │
│  Cannot start until predecessor completes                    │
└─────────────────────────────────────────────────────────────┘

Cross-agent verification (trust but verify):

• Quality Agent independently runs tests (doesn't trust feature agent's report)
• Security Agent independently scans (doesn't trust review agent)
• Merger Agent verifies all predecessors before branching
• Every PR includes full pipeline results: test output, coverage, review, security

Multiple features run in parallel. If your project has auth, dashboard, and payments - that's 3 feature agents working simultaneously, with shared Quality/Review/Security/Merger agents processing tasks as they unblock.

# Auto-spawned by /initialize-project
# Or spawn manually on existing project:
/spawn-team

Environment required:

export CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1

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 1%, CPA /initialize-project

Answer questions, get full setup

### Existing Project
```bash
cd my-existing-app
claude
> /initialize-project
# Skills updated, existing config preserved

Existing Codebase (Auto-Analysis!)

cd unfamiliar-codebase
claude
> /initialize-project
# Auto-detects existing code → runs analysis first
# Shows: structure, tech stack, guardrails status, conventions
# Asks: "What would you like me to do?"
#   1. Add Claude skills only
#   2. Add skills + missing guardrails
#   3. Full setup
#   4. Just show analysis

Standalone Analysis

cd any-repo
claude
> /analyze-repo
# Run analysis anytime without making changes

Update Skills Globally

cd "$(cat ~/.claude/.bootstrap-dir)"
git pull
./install.sh

# Then in any project:
claude
> /initialize-project
# Gets latest skills

Prerequisites

Install and authenticate these CLIs:

# GitHub CLI
brew install gh
gh auth login

# Vercel CLI
npm i -g vercel
vercel login

# Supabase CLI
brew install supabase/tap/supabase
supabase login

Quality Gates

Every project gets automated enforcement:

Pre-Commit (Local)

• Linting with auto-fix
• Type checking
• Security checks (no secrets, no .env)
• Unit tests on changed files

CI (GitHub Actions)

• Full lint + type check
• All tests with 80% coverage
• Secret scanning (trufflehog)
• Dependency audit (npm audit / safety)

Atomic Todos

All work is tracked with validation, test cases, and TDD execution logs:

## [TODO-042] Add email validation to signup form

**Status:** in-progress
**Priority:** high
**Estimate:** S

### Acceptance Criteria
- [ ] Email field shows error for invalid format
- [ ] Form cannot submit with invalid email

### Test Cases
| Input | Expected |
|-------|----------|
| user@example.com | Valid |
| notanemail | Error |

### TDD Execution Log
| Phase | Command | Result |
|-------|---------|--------|
| RED | `npm test -- --grep "email validation"` | 2 tests failed ✓ |
| GREEN | `npm test -- --grep "email validation"` | 2 tests passed ✓ |
| VALIDATE | `npm run lint && npm run typecheck && npm test -- --coverage` | Pass, 84% ✓ |

Bug reports include test gap analysis:

## [BUG-007] Email validation accepts "user@"

### Test Gap Analysis
- Existing tests: `signup.test.ts` - only tested valid emails
- Gap: Missing test for email without domain
- New test: Add case for partial emails

### TDD Execution Log
| Phase | Command | Result |
|-------|---------|--------|
| DIAGNOSE | `npm test` | All pass (test gap!) |
| RED | `npm test -- --grep "partial email"` | 1 test failed ✓ |
| GREEN | `npm test -- --grep "partial email"` | 1 test passed ✓ |
| VALIDATE | `npm run lint && npm test -- --coverage` | Pass ✓ |

Error Handling in Loops

Not all failures are equal. Claude classifies errors before iterating:

Error Type	Examples	Claude Fixes?	Action
Code Error	Logic bug, wrong assertion	✅ Yes	Continue loop
Access Error	Missing API key, DB refused	❌ No	Stop + report
Environment Error	Missing package, wrong version	❌ No	Stop + report

When Claude hits an access/environment error:

🛑 LOOP BLOCKED - Human Action Required

Error: ECONNREFUSED 127.0.0.1:5432

Required Actions:
1. Start PostgreSQL: brew services start postgresql
2. Verify connection: psql -U postgres -c "SELECT 1"
3. Check DATABASE_URL in .env

After fixing, run /ralph-loop again.

Common blockers and fixes:

Error	Cause	Fix
ECONNREFUSED :5432	PostgreSQL not running	brew services start postgresql
ECONNREFUSED :6379	Redis not running	brew services start redis
401 Unauthorized	Bad API key	Check .env file
MODULE_NOT_FOUND	Missing package	npm install

---

FAQ

How is this different from just using Claude Code?

Claude Code is powerful but unpredictable without guardrails. Claude Bootstrap adds:

• TDD enforcement - Tests must fail before implementation
• Automatic iteration - Loops until tests pass, not one-shot
• Error classification - Knows when to stop and ask for help
• Complexity limits - Hard caps prevent unmaintainable code

Do I need to manually run /ralph-loop every time?

No. With Claude Bootstrap skills loaded, Claude automatically transforms your requests into iterative TDD loops. Just say "add email validation" and it loops until tests pass.

What if I don't want a loop for something?

Use opt-out phrases:

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

What if the loop runs forever?

Three safety mechanisms:

1. --max-iterations - Hard limit (default 20-30)
2. Error classification - Stops on access/environment errors
3. Blocker detection - Reports when stuck and needs human help

Does this work with existing projects?

Yes. Run /initialize-project in any directory. It adds skills without breaking existing config.

What about test coverage?

Minimum 80% coverage enforced. CI blocks PRs below threshold.

How do I update skills?

cd "$(cat ~/.claude/.bootstrap-dir)"
git pull
./install.sh

Then run /initialize-project in your project to get latest skills.

Can I customize the skills?

Yes. Skills are markdown files in .claude/skills/. Edit or add your own.

What languages/frameworks are supported?

Category	Supported
Languages	TypeScript, Python, Kotlin, Dart, Java
Frontend	React, Next.js, React Native, Flutter, PWA
Mobile	React Native, Flutter, Android (Java/Kotlin)
Backend	Node.js, Express, FastAPI
Database	Supabase, Firebase, Cloudflare D1, AWS DynamoDB, Aurora, Azure Cosmos DB
Web Tech	PWA (Service Workers, Workbox, Offline-First)
E-commerce	Shopify, WooCommerce, Medusa
Advertising	Reddit Ads API (campaigns, targeting, conversions)
Collaboration	Microsoft Teams (bots, AI agents, Adaptive Cards)
Marketing	Klaviyo, PostHog

---

Comparison

Feature	Other Tools	Claude Bootstrap
Testing	Optional, often skipped	TDD mandatory - tests fail first
Iteration	One-shot	Loops until tests pass
Bug Fixes	Jump to fix	Test gap analysis → failing test → fix
Error Handling	Loop forever	Classifies errors, stops on blockers
Security	Rarely covered	First-class with CI enforcement
Complexity	Vague guidance	Hard limits (20 lines/function, 200/file)

Contributing

See CONTRIBUTING.md for guidelines.

Key principles:

• Measurable constraints over vague guidance
• Working code examples
• Maintain idempotency
• Test locally before submitting

Changelog

See CHANGELOG.md for version history and updates.

Latest: v2.6.0 - 55 skills with AI-native ticket writing, INVEST+C criteria, and Claude Code Ready checklist

License

MIT - See LICENSE

Credits

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