My Setup: Multi-Repo LLM Agent Organization

High-level overview of how I organize my development environment for LLM-driven workflows.

The Big Picture

graph TD
    A[~/repository] -->|bootstraps| B[System Setup]
    A -->|clones| C[Domain Repos]
    A -->|provides| D[Project Templates]

    C --> E[~/tester]
    C --> F[~/career-orchestrator]
    C --> G[~/developer]
    C --> H[~/operations]
    C --> I[~/design]
    C --> J[~/research]

    K[~/ai_agents] -->|syncs commands to| L[~/.claude/commands/]
    K -->|references| C

Core Concept: Separation by Domain

Each repository handles one concern:

• repository - Bootstrap new machines, create projects, set standards
• tester - Testing workflows and knowledge
• career-orchestrator - Goal and career management
• developer - Development tooling and practices
• operations - Deployment and infrastructure
• design - Architecture patterns
• research - Experiments and learning
• ai_agents - Orchestration and command sync

The Bootstrap Layer

graph LR
    A[New Machine] --> B[Clone repository]
    B --> C[Run setup scripts]
    C --> D[WSL Configuration]
    C --> E[Clone all repos]
    C --> F[Install UV tooling]
    D --> G[Ready to work]
    E --> G
    F --> G

repository is the foundation. One repo that makes all others possible.

Key Structure

repository/
├── configs/                    # Source of truth configs
│   ├── git/aliases.gitconfig
│   └── wsl/essential_packages.txt
├── scripts/
│   ├── repos/setup.sh         # Clone all domain repos
│   ├── setup/wsl_configuration.sh
│   └── uv/setup.sh
└── packages/setup/            # Project templates
    └── templates/

The Command Indirection Pattern

Commands aren’t implemented in the agent repo - they’re referenced.

graph TD
    A[~/tester/agents/commands/coverage_check.md] -->|actual implementation| B[Testing Logic]
    C[~/ai_agents/docs/commands/coverage_check.md] -->|pointer: read ~/tester/...| A
    D[~/ai_agents sync script] -->|copies to| E[~/.claude/commands/coverage_check.md]
    E -->|Claude reads| C
    C -->|follows pointer| A

The Flow:

1. Actual command lives in domain repo (tester)
2. ai_agents has a reference that points to it
3. Sync script copies reference to ~/.claude/commands/
4. Claude reads reference, follows pointer to actual implementation

Why: Single source of truth, shareable across agents, domain expertise stays with domain

ai_agents Structure

ai_agents/
├── docs/
│   ├── commands/              # Reference pointers only
│   │   ├── coverage_check.md  # Points to ~/tester/agents/commands/
│   │   ├── goal_creator.md    # Points to ~/career-orchestrator/agents/commands/
│   │   └── test_planner.md    # Points to ~/tester/agents/commands/
│   └── agents/
│       └── deep-research-analyst.md
└── src/                       # Python sync script
    └── ai_agents_claude/
        └── main.py            # Syncs commands to ~/.claude/

Command Organization by Domain

graph TD
    A[Commands] --> B[Testing Suite]
    A --> C[Goal Management]
    A --> D[Utilities]

    B --> B1[test_planner]
    B --> B2[test_builder]
    B --> B3[test_reviewer]
    B --> B4[coverage_check]

    C --> C1[goal_creator]
    C --> C2[goal_updater]
    C --> C3[goal_synthesizer]
    C --> C4[meta_goal_management]

    D --> D1[summarizer]
    D --> D2[add_frontmatter]

The Meta Layers

graph BT
    A[Projects - Build things] --> B[Domain Repos - Domain knowledge]
    B --> C[ai_agents - Orchestrate commands]
    C --> D[repository - Bootstrap everything]

Each layer enables the one below it:

• repository sets up the environment
• ai_agents orchestrates the commands
• Domain repos provide the expertise
• Projects get the work done

New Machine Setup

# Day 1 with new machine
git clone https://github.com/you/repository ~/repository
cd ~/repository

# Bootstrap everything
./scripts/setup/wsl_configuration.sh    # Configure environment
./scripts/repos/setup.sh                # Clone all repos
./scripts/uv/setup.sh                   # Install tooling

# Done - entire dev environment ready

New Project Creation

# Need new testing utility
cd ~/tester
python -m repository_setup.main create-package test-utils

# Generated with consistent structure:
# - pyproject.toml (with UV config)
# - README.md (with template)
# - src/ layout
# - tests/

Why This Works

Agent-Agnostic: Change sync target from ~/.claude to ~/.cursor - same pattern works

Single Source of Truth: Command logic lives once, referenced everywhere

Composable: Mix commands from different repos for different agents

Shareable: Share individual repos independently

Testable: Each domain repo has its own tests

Evolvable: LLMs maintain both specialized repos and orchestration layer

The Evolution Pattern

graph LR
    A[Experiment in domain repo] --> B[Refine command]
    B --> C[Update reference in ai_agents]
    C --> D[Sync to agent location]
    D --> E[Agent uses updated command]
    E --> F[Learn from usage]
    F --> A

Commands that manage commands. The organization system organizes itself.