An Agent Swarm That Builds Agent Swarms#

The Problem: Claude Code’s Best Features Are Its Least Used#

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.

The setup cost is the barrier. 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.

Figure 2 - The Infrastructure Gap: The most powerful Claude Code features have the lowest adoption. Agent definitions, hooks, and skills require significant upfront investment to configure correctly. The Bootstrap Framework exists to close this gap.

Migration is even harder. An existing codebase has established patterns, implicit conventions, domain knowledge buried in code, and toolchain assumptions. Extracting all of that into Claude Code infrastructure — while also improving the codebase during migration — is a task most teams never attempt.

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

The Insight: Use Claude Code to Generate Claude Code#

The Bootstrap & Migrator Framework is a meta-project: Claude Code agents that generate Claude Code agent infrastructure. You give it a project description (greenfield mode) or point it at an existing codebase (migration mode), and it produces a complete .claude/ configuration tailored to that specific project.

The framework contains no project-specific code. It contains knowledge about how to build Claude Code configurations:

• 8 reusable skills teaching agent design, hook engineering, skill authoring, migration strategy, project analysis, validation, harness design, and project-type patterns
• 6 slash commands guiding users through analyze, scaffold, generate-agents, generate-hooks, generate-skills, and validate workflows
• 10 templates for hook scripts, dev startup scripts, and project scaffolding
• 808 lines of methodology documenting a 7-step process refined through real use

KEY INSIGHT: The most effective way to drive adoption of advanced tooling features is to build tools that generate the configuration. Instead of teaching every developer how to write agent definitions, teach one framework how to generate them.

The Architecture: Three Folders, Strict Boundaries#

The framework enforces a three-folder architecture that prevents the most common migration mistakes:

1. Framework repo (claude-teams-project-framework/) — reusable knowledge, templates, methodology. Project-agnostic. Never contains project-specific code.
2. Source project (metabase-server/) — the existing codebase. READ-ONLY. Never modified. This is the reference implementation.
3. Target project (textToSql-metabase/) — built fresh with generated infrastructure. All new code lands here.

Figure 3 - The 7-Step Migration Methodology: Analysis and scaffolding are sequential, but agent, hook, and skill generation run in parallel since they target different directories. The entire infrastructure generation pipeline completes in 20-40 minutes.

The READ-ONLY invariant on the source project is not just a convention — it is the single most important architectural decision. It means:

• The old project keeps running in production throughout the migration
• Every comparison between old and new behavior has a stable reference point
• No accidental modifications can break the source while you’re building the target
• The psychological clarity is as valuable as the technical enforcement: agents that know they cannot write to a directory don’t waste tokens attempting it

What the Framework Actually Generated#

For the metabase-server migration, the framework analyzed the existing codebase and produced:

1
#!/usr/bin/env python3
2
"""PostToolUse hook: Run ruff on Python file writes, feed errors back to agent."""
3
import json, sys, subprocess
4

5
def main():
6
    event = json.loads(sys.stdin.read())
7
    file_path = event.get("tool_input", {}).get("file_path", "")
8
    if not file_path.endswith(".py"):
9
        sys.exit(0)
10

11
    result = subprocess.run(
12
        ["ruff", "check", "--fix", file_path],
13
        capture_output=True, text=True, timeout=10
14
    )
15
    if result.returncode != 0:
16
        print(json.dumps({
17
            "additionalContext": (
18
                f"ruff found issues in {file_path}:\n"
19
                f"{result.stdout}\nFix these before continuing."
20
            )
21
        }))
22

23
if __name__ == "__main__":
24
    main()

The Migration: 40 Features, 10 Sessions, One First-Try Success#

The framework generated a 40-item feature list ordered by dependency, which the agent team executed over 10 sessions:

The porting order followed the dependency graph: config first (zero dependencies), then LLM clients and Metabase client (depend on config), then SQL pipeline and dashboard pipeline (depend on everything above), then the FastAPI application (imports all modules), then frontend (independent, ported in parallel).

Figure 6 - Dependency-Order Porting: Every module was testable the moment it landed because its dependencies were already ported. The frontend ran in parallel with backend porting since it has no Python dependencies.

The Gaps: What We Got Wrong#

No framework survives first contact with reality unscathed. Five gaps emerged across two migrations:

1. .gitignore carryover. The scaffold step created a fresh .gitignore but didn’t carry over source-project-specific patterns. Data files that should have been ignored were committed. Fix: now an explicit migration step.

2. Dev startup scripts. The pipeline had no step for porting development orchestration — the npm run dev scripts that start backend, frontend, and Metabase simultaneously with concurrently. The migrated project couldn’t run in dev mode until we added this. Fix: new templates and migration step added.

3. .env files. The framework scaffolded .env.example with placeholders but never prompted the developer to copy actual credentials from the source project. All 223 unit tests pass (they mock external services), so this gap was invisible until the first live test. Fix: explicit manual step documented.

4. Processing pipeline completeness. Every module ported correctly. The route handler only called step 1 of a 4-step chain. In Migration 2, the YouTube processing pipeline chained transcript extraction, markdown generation, YAML frontmatter generation, and tag resolution into a final Obsidian note. The target project ported each module independently, but the route handler that orchestrated them only wired the first step. The result: markdown output with no YAML frontmatter and no tags. Three steps existed as dead code, never called. The root cause was that the project analysis identified modules and endpoints but not processing pipelines. Modules are nouns. Pipelines are verbs. Without an explicit pipeline inventory, the porting agent treated each module as independent. Fix: processing pipelines are now first-class entities in project_analysis.json, with mandatory detection during analysis and mandatory verification during cutover.

5. Dev startup scripts — missed twice. Despite being documented as Gap #2 above, the second migration hit the exact same failure. The documentation existed. The checklist mentioned it. But the verification step never tested whether the project could actually start. Documenting a lesson is not the same as enforcing it. Fix: dev orchestration is now a MANDATORY blocking check in the verification checklist, not an advisory recommendation. The gap had to recur before we learned to make it impossible rather than merely documented.

Figure 7 - Discovery Timeline: Every gap was discovered during active use and immediately fed back into the framework. This is the core feedback loop: the framework improves through every project it touches.

Migration 2: The Framework Proves Itself#

The metabase-server migration proved the concept. The second migration proved the framework compounds.

We pointed the framework at obsidian_notes — a YouTube-to-Obsidian AI pipeline built with FastAPI, React 19, PostgreSQL, Qdrant vector search, Anthropic Claude, and OpenAI embeddings. 67 Python source files, a 2,800-line monolithic API, 8 independent database connections, and an Anthropic Batch API processing system that took 4+ hours to handle a single set of videos.

The framework analyzed it and generated 5 specialized agents, 7 domain skills, 5 hooks, and a 167-line CLAUDE.md. Phase 1 — building the framework knowledge base — took zero sessions. The 3-session investment from Migration 1 paid for itself immediately.

The most dramatic change was not a port. It was a complete architectural replacement. The source project used Anthropic’s Batch API for processing YouTube videos into Obsidian notes. The Batch API was unreliable: 4+ hour waits with no per-item progress, no cancellation support, and opaque failures that required resubmitting entire batches. Rather than porting this broken architecture, we replaced it with asyncio.TaskGroup parallel processing. The result: seconds per video instead of hours per batch, per-item WebSocket progress updates, individual cancellation, and configurable concurrency.

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

The structural improvements went further than Migration 1. The 2,800-line monolithic main.py became 7 focused router modules and a 70-line entry point. 8 independent psycopg2.connect() calls became a centralized connection pool with get_connection() as a context manager. 7 accumulated SQL migration scripts consolidated into 1 idempotent initial schema. Python typing modernized throughout (X | None instead of Optional[X], list[X] instead of List[X]), enum patterns standardized (StrEnum instead of str, Enum), and deprecated stdlib APIs updated (datetime.now(tz=UTC) instead of datetime.utcnow()).

Figure 8 - The 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 dropped to zero on reuse. The framework gets faster with every project it touches.

The same visual treatment shows Migration 2’s transformation. Click to zoom:

BEFORE Migration: obsidian_notes — 67 Python files, 8 independent database connections, a 2,800-line monolithic API, and the Anthropic Batch API bottleneck that took 4+ hours per processing run.

AFTER Migration: obsidian-youtube-agent — The Batch API replaced with asyncio.TaskGroup parallel processing (seconds instead of hours), 8 database connections consolidated into a centralized pool, and full Claude Code infrastructure: 5 agents, 7 skills, 5 hooks.

The hook pattern from Migration 1 held up without changes. Simple command hooks — ruff after Python writes, tsc after TypeScript writes, pytest before session end — were sufficient again. No script-based hooks needed. Hook simplicity is now confirmed across two independent projects with different tech stacks.

Why This Matters: The Infrastructure Multiplier#

The Bootstrap Framework exists to solve a specific problem: Claude Code’s most powerful features have a high setup cost that prevents adoption. By encoding the knowledge of how to configure these features into reusable skills and automated workflows, the framework turns a full-day expert task into a 20-40 minute generation pipeline.

But the multiplier effect goes beyond setup time:

For the migrated project, every future session benefits from the generated infrastructure. Hooks catch bugs automatically. Skills give agents domain context without token-heavy re-reading. Agent ownership prevents file conflicts. The 157-line CLAUDE.md orients every new session in seconds.

For the framework, every migration makes it smarter. The metabase-server migration produced 3 new templates, updated 14+ framework files, and documented 6 lessons learned. The obsidian-notes migration discovered 2 more gaps and added processing pipeline detection and mandatory verification checks. Each migration makes the next one faster because these patterns are now encoded.

For Claude Code adoption broadly, the framework demonstrates that the answer to “these features are too complex to set up” is not “make the features simpler”, but rather “build tools that generate the configuration.” The features are powerful because they’re detailed. A hook that runs ruff check --fix on every Python file write is powerful precisely because it’s specific. The Bootstrap Framework makes that specificity achievable without the manual cost.

Figure 9 - Before and After: The quantitative improvement across every dimension. The most striking metric: 168 print() statements reduced to 0 while simultaneously adding 223 unit tests. Quality infrastructure compounds.

The Real Payoff: A System That Can Now Improve Itself#

The migration was not the destination. It was the foundation.

The old metabase-server project could not improve itself. When a SQL query failed, the error vanished into a print() statement. When a pattern didn’t work, there was no place to record what went wrong. When a developer, human or AI, started a new session, they had no orientation, no domain context, no safety rails. Every session started from zero.

The migrated project is fundamentally different. It has the infrastructure for continuous self-improvement through feedback loops that the old project could never support.

1
T-SQL dialect: All queries use SQL Server syntax. TOP N instead of LIMIT,
2
GETDATE() and DATEADD() for dates, ISNULL() instead of COALESCE().

What Comes Next#

The framework is battle-tested on two real projects — a text-to-SQL dashboard and a YouTube-to-Obsidian AI pipeline. The second migration was more complex but completed faster, validating the compound returns. Two paths remain:

Greenfield mode is completely untested. The framework can theoretically generate Claude Code infrastructure from a plain-English project description. The skills and methodology support it, but no one has tried it yet. This is the biggest blind spot.

Different archetypes would validate generality. Both migrations have been Python FastAPI + React. The framework includes patterns for Node.js Express, CLI tools, and pure frontends, but these are theoretical until proven on real projects. A third migration on a different stack would confirm the framework is truly general, not just well-tuned for one archetype.

The framework’s readiness assessment rates 6 of 8 core skills as production-ready, with project-type-patterns and validation-checklist gaining real-world validation through the second migration. The “redesign during migration” pattern is documented but needs testing on a different type of redesign (database swap, auth system replacement) to confirm it generalizes beyond the Batch API case.

KEY INSIGHT: Two successful migrations — the second faster on a harder project — prove the compound returns. But both were Python FastAPI + React. Three migrations across different archetypes (Node.js, CLI, pure frontend) would prove the framework is truly general, not just well-tuned for one technology stack.

The Series#

This is Part 1 of a 4-part series on Building the Bootstrap Framework:

1. An Agent Swarm That Builds Agent Swarms (this article) — Case study migrating two production apps with generated Claude Code infrastructure
2. From Prototype to Platform — How the framework learned from every migration and improved itself
3. Securing Agentic AI — Building security-conscious agent systems with Claude Code
4. WordPress to Astro — Migrating a production site with AI-assisted infrastructure

References#

Anthropic Engineering Blog:

[1] E. Schluntz and B. Zhang, “Building effective agents,” Anthropic Engineering Blog, Dec 2024. https://www.anthropic.com/engineering/building-effective-agents

[2] J. Young et al., “Effective harnesses for long-running agents,” Anthropic Engineering Blog, Nov 2025. https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents

[3] N. Carlini, “Building a C compiler with a team of parallel Claudes,” Anthropic Engineering Blog, Feb 2025. https://www.anthropic.com/engineering/building-c-compiler

Community implementations:

[4] Disler, “Claude Code Hooks Mastery,” GitHub Repository, 2025. https://github.com/disler/claude-code-hooks-mastery

[5] Disler, “Agentic Finance Review,” GitHub Repository, 2025. https://github.com/disler/agentic-finance-review

[6] Disler, “Claude Code Hooks Multi-Agent Observability,” GitHub Repository, 2025. https://github.com/disler/claude-code-hooks-multi-agent-observability

[7] A. Osmani, “Claude Code Swarms,” AddyOsmani.com, Feb 2026. https://addyosmani.com/blog/claude-code-agent-teams/

Claude Code Documentation:

[8] Anthropic, “Automate workflows with hooks,” Claude Code Documentation, 2025. https://code.claude.com/docs/en/hooks-guide

[9] Anthropic, “Orchestrate teams of Claude Code sessions,” Claude Code Documentation, 2025. https://code.claude.com/docs/en/agent-teams

[10] Anthropic, “Skill authoring best practices,” Claude Platform Documentation, 2025. https://platform.claude.com/docs/en/agents-and-tools/agent-skills/best-practices

Companion articles:

[11] G. Dotzlaw, K. Dotzlaw, and R. Dotzlaw, “Building Effective Claude Code Agents: From Definition to Production,” 2026. /insights/claude-agents/

[12] G. Dotzlaw, K. Dotzlaw and R. Dotzlaw, “Claude Code Skills: Building Reusable Knowledge Packages for AI Agents,” 2026. /insights/claude-skills/

[13] G. Dotzlaw, K. Dotzlaw and R. Dotzlaw, “Claude Code Hooks: The Deterministic Control Layer for AI Agents,” 2026. /insights/claude-hooks/

[14] G. Dotzlaw, K. Dotzlaw and R. Dotzlaw, “Claude Code Agent Teams: Building Coordinated Swarms of AI Developers,” 2026. /insights/claude-teams/