Claude Code Bootstrap Framework

The Problem#

Claude Code ships with powerful infrastructure: agent definitions that create specialized AI teammates, hooks that enforce quality automatically, skills that package domain knowledge for 140x token efficiency, and slash commands that encode complex workflows into single invocations.

Most developers use none of it.

Configuring a proper Claude Code project — with CLAUDE.md, agent teams, hooks, skills, slash commands, init scripts, and settings.json — takes a full day for an expert. Most people write a basic CLAUDE.md and stop. They get maybe 20% of Claude Code’s potential. Migration is even harder: an existing codebase has established patterns, implicit conventions, and domain knowledge buried in code that needs to be extracted into Claude Code infrastructure.

We asked: what if Claude Code agents could do this work themselves?

What We Built#

A meta-framework: Claude Code agents that generate Claude Code agent infrastructure. Point it at an existing codebase (migration mode) or give it a plain-English project description (greenfield mode), and it produces a complete .claude/ configuration tailored to that specific project in 30-55 minutes.

The framework contains no project-specific code. It contains knowledge about how to build Claude Code configurations: 17 reusable skills, 12 slash commands, 17 hook templates, and over 1,000 lines of methodology refined through real production use.

Figure 1 - The Three-Folder Architecture: The framework reads the source project but never modifies it. All generated infrastructure lands in a fresh target project. This READ-ONLY invariant held across 18 sessions and was never violated.

Key Results#

The 12-Step Pipeline#

The pipeline analyzes, generates, validates, and documents — with parallel execution paths that keep wall-clock time under an hour.

Figure 2 - The 12-Step Pipeline: Gold steps are required (core generation). Teal steps are optional (documentation and security). Steps 1.5a/1.5b run in parallel after analysis. Steps 3/4/5 run in parallel since they write to different directories. Three new documentation steps added only 10-15 minutes total thanks to concurrency.

Three Migrations: The Compound Returns#

The framework’s core thesis: each migration makes the next one faster, even when the next project is more complex.

Migration 1: textToSql-metabase — A text-to-SQL dashboard (FastAPI, React, Metabase, Qdrant, MS SQL Server). 45 Python files ported across 10 sessions. 168 print() statements eliminated. 223 unit tests created from zero. 7 anti-pattern categories fixed during migration. The framework itself was built during this migration — 3 sessions just for framework knowledge base construction.

Migration 2: obsidian-youtube-agent — A YouTube-to-Obsidian AI pipeline (FastAPI, React, PostgreSQL, Qdrant, Anthropic Claude). 67 Python files — more complex than Migration 1. Completed in 8 sessions, not 10. The framework build phase (3 sessions in Migration 1) dropped to zero on reuse. The most dramatic change: the Anthropic Batch API (4+ hour waits, opaque failures) was replaced entirely with asyncio.TaskGroup parallel processing — seconds per video instead of hours per batch.

Migration 3: dotzlaw.com — A WordPress-to-Astro migration. 41 articles extracted from a SQL backup file (no live admin access), 187 images redistributed from WordPress’s flat /wp-content/uploads/YYYY/MM/ structure to per-article co-located folders, a design-matched dark theme rebuilt from scratch. The framework contributed methodology and skills (CMS Content Migration, Visual State Capture, SSG/Astro archetype) but the bulk of the work was content transformation and visual design — domains the framework guides rather than automates.

Figure 3 - Compound Returns: Migration 2 was more complex (67 files vs 45, AI/ML integration, full architectural redesign) but completed in fewer sessions. The 3-session framework investment from Migration 1 paid for itself immediately and continues paying on every subsequent project.

KEY INSIGHT: Migration is not just an opportunity to fix code. It is an opportunity to fix architecture. When a component is demonstrably failing, redesign it during migration rather than porting the failure and planning a future rewrite that never happens.

Security: Defense in Depth for Agent Systems#

After two production migrations, a security audit against the OWASP Top 10 for Agentic Applications found 11 concrete gaps in the framework. Not theoretical risks — specific vulnerabilities with concrete attack paths. We closed all 11 across 14 tasks in 4 phases.

Figure 4 - Defense in Depth: Four concentric rings protect the pipeline. Ring 1 (per-call): input sanitization, security scan, rate limiting, audit logging. Ring 2 (trajectory): heartbeat monitoring, watchdog timers, trajectory analysis. Ring 3 (structural): file ownership, tool restrictions, 72 blocked commands. Ring 4 (session): secrets pre-commit scan, hygiene checks, stop hooks.

The security architecture operates across 4 timescales:

Per-archetype security patterns cover all 7 project types: Python FastAPI, React Vite, SSG/Astro, Node.js Express, AI/ML, Fullstack, and CLI tools. Each archetype gets security hooks and CLAUDE.md constraints tailored to its specific threat surface.

The Self-Improvement Loop#

The framework’s most distinctive property: it improves itself using its own methodology. After two migrations, a systematic gap analysis identified 8 missing capabilities. Round 1 added source documentation, improvement analysis, and project documentation — expanding the pipeline from 7 to 10 steps. An independent review graded the output A-, with 5/5 spot-checked claims confirmed accurate against actual source code.

Round 2 added security review, bootstrapper agent definitions, and the pipeline orchestrator. Round 3 added comprehensive security hardening — 6 new hooks, 2 JSON schemas, a 3-tier trajectory monitoring system. Each round builds on the last.

Figure 5 - Before and After: The quantitative improvement across every dimension from Migration 1. 168 print() statements reduced to 0 while simultaneously adding 223 unit tests. Quality infrastructure compounds.

KEY INSIGHT: The highest-leverage improvement to a generation framework is improving the framework itself. Every capability added to the pipeline benefits every future project. The cost is paid once; the return compounds indefinitely.

Architecture#

6 core bootstrapper agents:

1. Project Analyst — reads the source codebase, produces project_analysis.json with security profile
2. Harness Engineer — scaffolds directory structure, CLAUDE.md, root configuration
3. Agent Designer — designs agent team composition with file ownership and tool restrictions
4. Hooks Engineer — generates hook configurations and enforcement scripts per archetype
5. Skills Architect — extracts domain knowledge into SKILL.md files with progressive disclosure
6. Validator Agent — runs 50+ structural, coherence, and security checks

3 documentation agents (optional):

• Source Documentation Agent — 7 architecture documents from any codebase
• Improvement Analyst — 25 improvements across 5 categories with file/line references
• Project Documentation Agent — 5 documents for the completed project

Key architectural decisions:

• Three-folder separation: framework (reusable), source (READ-ONLY), target (built fresh)
• Per-agent file ownership prevents conflicts across parallel sessions
• Progressive disclosure on skills: 15 lines always loaded, 2,100+ available on demand (140x efficiency)
• Simple command hooks proved sufficient across all 3 migrations — no script-based hooks needed
• Hooks enforce quality deterministically (100% compliance vs 90% from prompt instructions)

Technologies#

The Article Series#

This project is documented in a 4-part series covering the framework’s origin, evolution, security hardening, and real-world validation:

Part 1: An Agent Swarm That Builds Agent Swarms — The origin story. Two production migrations prove the concept: a text-to-SQL dashboard and a YouTube-to-Obsidian AI pipeline. The second was harder but faster. 67 Python files, 8 sessions, zero framework build time.

Part 2: From Prototype to Platform — The framework turns its own methodology on itself. A gap analysis identifies 8 missing capabilities. Round 1 adds 3, expanding the pipeline from 7 to 10 steps. An independent review grades the output A-.

Part 3: Securing Agentic AI — A security audit finds 11 gaps. All 11 closed with 6 new hooks, 2 JSON schemas, a 3-tier trajectory monitoring system, and per-archetype security patterns across 7 project types. Full OWASP Top 10 for Agentic Applications coverage.

Part 4: WordPress to Astro — The third migration. 41 WordPress articles extracted from a SQL backup, 187 images redistributed, a design-matched dark theme rebuilt. An honest assessment of what the framework contributed — and what still required manual craft.

Companion deep-dives:

• The Anatomy of a Domain Skill — Progressive disclosure, skill extraction, and 140x token efficiency
• Hooks, Agents, and the Deterministic Control Layer — How hooks enforce what prompts cannot, and why agent file ownership prevents chaos

The throughline: The answer to “these features are too complex to set up” is not “make the features simpler” — it is “build tools that generate the configuration.” The features are powerful because they are detailed. A hook that runs ruff check --fix on every Python file write is powerful precisely because it is specific. The Bootstrap Framework makes that specificity achievable without the manual cost.