claude-code-monorepo-structure

A refined structure for organizing LLM agent customizations through indirection and multi-repo architecture. Currently implemented for Claude Code, but designed to work with any agent system.

Source

From the ai_agents repository - a meta-orchestration layer that syncs command references to agent-specific locations.

The Structure

.
├── packages
│   └── claude
│       ├── README.md
│       ├── _local_settings -> /home/rolan/.claude
│       ├── docs
│       │   ├── agents
│       │   │   └── deep-research-analyst.md
│       │   └── commands
│       │       ├── add_frontmatter.md
│       │       ├── coverage_check.md
│       │       ├── goal_creator.md
│       │       ├── goal_synthesizer.md
│       │       ├── goal_updater.md
│       │       ├── meta_goal_management.md
│       │       ├── summarizer.md
│       │       ├── test_builder.md
│       │       ├── test_meta_setup.md
│       │       ├── test_planner.md
│       │       └── test_reviewer.md
│       ├── pyproject.toml
│       ├── src
│       │   └── ai_agents_claude
│       │       ├── __init__.py
│       │       └── main.py
│       └── tests
│           └── test_main.py
├── pyproject.toml

Key Patterns

Multi-Repo Architecture

Commands are split across domain-specific repositories in your home directory:

• ~/tester/ - Testing workflow commands and knowledge
• ~/career-orchestrator/ - Goal/career management workflows
• ~/developer/ - Developer tooling and practices
• ~/operations/ - Deployment and infrastructure workflows
• ~/design/ - Architecture patterns and decisions
• ~/research/ - Experiments and learning
• ~/ai_agents/ - Orchestration and sync layer

Each domain repo owns its concern. The ai_agents repo just coordinates them.

See: home-directory-as-knowledge-base.md for the full pattern.

Command Indirection

Commands in docs/commands/ are references, not implementations:

# Coverage Check

Read and execute the instructions in:

`~/tester/agents/commands/coverage_check.md`

This means:

• Actual logic lives in specialized repos
• Agent-specific repo just points to them
• Easy to share commands across different agents
• Single source of truth per command

Python Sync Script

The Python code doesn’t implement commands - it syncs them to the agent’s expected location:

ai_agents/docs/commands/*.md  →  ~/.claude/commands/*.md

This makes the setup agent-agnostic. Swap ~/.claude for ~/.cursor or whatever, same structure works.

Documentation Structure

agents/ - Agent-specific customizations

• Currently: deep-research-analyst for Claude

commands/ - Command reference pointers

• Point to actual implementations in other repos
• Organized by workflow area

Command Naming Patterns

The commands follow logical groupings:

Goal Management Suite

• goal_creator - Initialize new goals
• goal_synthesizer - Combine/refine goals
• goal_updater - Modify existing goals
• meta_goal_management - Meta-level orchestration

Testing Workflow

• test_planner - Design test strategy
• test_builder - Generate tests
• test_meta_setup - Configure test environment
• test_reviewer - Review/validate tests

Utilities

• add_frontmatter - Document metadata
• coverage_check - Test coverage analysis
• summarizer - Content summarization

Python Package Structure

Standard src-layout with tests:

• src/ai_agents_claude/ - Main package code
• tests/ - Test suite
• pyproject.toml - Dependencies and config

Why This Works

Separation of Concerns: Each repo handles one domain (testing, career, orchestration)

Agent-Agnostic: The pattern works with any agent system - just change the sync target

Single Source of Truth: Command logic lives in one place, referenced everywhere it’s needed

Composable: Mix and match commands from different repos for different agents

Testable: Each specialized repo can have its own test suite

Shareable: Share individual repos (tester, career-orchestrator) independently

Usage Pattern

1. Create specialized repos for different domains (tester, career-orchestrator, etc.)
2. Implement actual commands in those repos: ~/tester/agents/commands/coverage_check.md
3. Create reference pointers in ai_agents: docs/commands/coverage_check.md points to the real file
4. Run sync script to copy references to agent location: ~/.claude/commands/
5. Agent reads reference and follows the pointer to the actual implementation
6. Let LLMs maintain both the specialized repos and the orchestration layer

The Meta Layer

This structure enables commands that manage commands:

• meta_goal_management orchestrates goal commands across repos
• test_meta_setup configures the entire test workflow
• Commands can generate new commands in specialized repos
• The sync script propagates changes automatically
• The structure organizes itself across multiple repos

Perfect example of script-kiddies philosophy: the organization system is organized enough to organize itself, and it does so across repository boundaries.

Architecture Flow

┌─────────────────┐
│  Specialized    │
│  Repos          │
│                 │
│  ~/tester/      │◄─┐
│  ~/career-      │  │
│  orchestrator/  │  │  LLMs write/update
│                 │  │  actual commands here
└─────────────────┘  │
         │           │
         │ referenced by
         ▼           │
┌─────────────────┐  │
│  ai_agents/     │  │
│  docs/commands/ │──┘
│                 │
│  (pointers)     │
└─────────────────┘
         │
         │ synced by python script
         ▼
┌─────────────────┐
│  ~/.claude/     │
│  commands/      │
│                 │
│  Agent reads    │
│  and follows    │
│  references     │
└─────────────────┘

The agent (Claude, Cursor, etc.) reads the pointer, follows it to the specialized repo, executes the actual command. Change the sync target, same structure works with any agent.