Orchestrator

A self-configuring infrastructure for shared Claude Code resources across all projects in your organization.

What Is This?

The Orchestrator is a shared AI infrastructure for organizations using Claude Code (and is designed to be expandable to other AI tools) across multiple repositories. Instead of duplicating agents, skills, prompts, and guidelines in every repo, you maintain them in one place, and each project auto-propagates them via symlinks.

Key Features:

• 📚 Centralized Shared Resources - One source of truth for agents, skills, hooks, commands, and guidelines (documentation) - they all live in Orchestrator. All repos can have access or just a subset by symlinking selected directories/resources into the repo
• 🤖 Specialized Agents - comes with several preconfigured specialized agents for wide-range of tasks. You can edit them as needed or add any number of agents
• 🤖 Self-configuring - Setup wizard that walks you through your entire configuration. You do not have to do it all by yourself
• 🔄 Cross Repo Documentation Synchronization Agent - This agent lives inside the orchestrator and its job is to keep documentation in sync across all repos.
  • How It Works: From the orchestrator repo, you simply ask claude to activate the agent and ask it to update the documentation based on the last n commits. It is recommended to do this daily (if in active development) or after key codebase changes.
  • NOTE: This agent is not automated because documentation updates may require human review.
• 🛠️ Customizable - Each repo can have its own agents, guidelines or skills. There is no one right way to use this orchestrator

Why This Exists

Any organization (including us!) using AI coding assistants faces challenges like:

• duplicated agents (if you even use any) across the board
• inconsistent/outdated documentation
• large multi-repo codebases with no shared context

This creates hallucinations, unpredictable responses, and agents that get lost in long and complex tasks.

The Orchestrator solves all these problems by:

• keeping up-to-date documentation
• centralizing best practices and patterns for your codebase
• reducing duplicated efforts across multiple repositories

This makes AI assistance context-aware, more predictable and accurate, and consistent across your entire engineering organization.

Quick Start

Go to QUICKSTART.md for the complete setup guide.

Below is a brief overview:

1. Clone This Repository

git clone <this-repo-url> orchestrator
cd orchestrator

2. Run Setup Wizard

‼️IMPORTANT ‼️ This assumes you have Claude Code installed and running in terminal. Check installation here.

Open in Claude Code and run:

/setup-orchestrator

The wizard will:

• Collect your organization information
• Scan your repositories to detect tech stacks
• Generate customized configuration files
• Create repository-specific skills and guidelines

Time: Depends on complexity of your repos. For mid-sized 2 repo structure it should take ~30 minutes.

3. Create Symlinks

Symlinks connect each repository to the shared resources in the orchestrator.

./setup/scripts/create-symlinks.sh

4. Delete Setup Directory

Delete the setup directory to keep your orchestrator clean.

rm -rf setup/

Done! Your orchestrator is ready to use.

Architecture

How it works:

1. All shared resources live in orchestrator/shared/

2. Repositories use symlinks to connect the shared resources from orchestrator/shared/ to their own .claude/ directory.

3. You ONLY need to update the orchestrator to update all repositories instantly.

4. Each repo can have its own agents and MUST HAVE CLAUDE.md.

IMPORTANT! Below is how the orchestrator and each repo are structured: If after setup your structure looks different(i.e. missing files), then it is not setup properly. You can ask Claude Code to help you fix it.

YourOrganization/
├── orchestrator/
│   └── shared/
│       ├── agents/
│       │   └── global/               # Global agents for all repos
│       │   └── orchestrator/         # Orchestrator-only agents
│       │   └── <repo-name>/          # (OPTIONAL) Repo-specific agents (directory for each repo)
│       ├── copilot-agents/           # GitHub Copilot custom agents (.agent.md files)
│       ├── commands/                 # Wrappers around agents/skills
│       ├── guidelines/               # Long-form documentation
│       │   └── global/               # Global guidelines (for all repos)
│       │   └── <repo-name>/          #  (OPTIONAL) Repo-specific guidelines (directory for each repo)
│       ├── settings/                 # Repository-specific settings files
│       │   └── <repo-name>/          # Directory per repository
│       │       └── settings.json     # Settings file for that repo
│       ├── hooks/                    # Event-driven scripts
│       ├── skills/                   # Small, focused behavior
│             └── global/             # Skill-developer, logging conventions, security-guardrails, testing-convention
│             └── <repo-name>/        #  (OPTIONAL) Repo-specific skills (directory per repo)
│      
│
├── repo-a/
│   ├── .claude/
│   │   ├── agents/
│   │   │   └── global/               # symlink to orchestrator/shared/agents/global
│   │   │   └── <repo-a>/             # symlink to orchestrator/shared/agents/<repo-a>
│   │   ├── commands/                 # symlink to orchestrator/shared/commands
│   │   ├── guidelines/
│   │   │   └── global/               # symlink to orchestrator/shared/guidelines/global
│   │   │   └── <repo-a>/             # symlink to orchestrator/shared/guidelines/<repo-a>
│   │   ├── hooks/                    # symlink to orchestrator/shared/hooks
│   │   ├── skills/
│   │         └── global/             # symlink to orchestrator/shared/skills/global
│   │         └── <repo-a>/           # symlink to orchestrator/shared/skills/<repo-a>
│   │   └── settings.json             # symlink to orchestrator/shared/settings/<repo-a>/settings.json
│   ├── .github/                      # (optional - if copilotAgents enabled)
│   │   └── agents/                   # symlink to orchestrator/shared/copilot-agents
│   └── CLAUDE.md                     # Repo Specific Entry Point; MUST exist
│...

(you can have any number of repositories)

Resources Overview

For in depth details on all the resources in the orchestrator, see: docs/orchestrator-resources.md

Pre-Configured (Ready to Use)

During setup, symlinks are created to connect each repository to the shared resources in the orchestrator.

Global Agents (shared/agents/global/) 7 specialized agents for code review, refactoring, planning, documentation, error fixing, and web research. Available to all repos via symlinks.

Orchestrator Agents (shared/agents/orchestrator/) Agents that run ONLY from the orchestrator repository (NOT symlinked to application repos):

• cross-repo-doc-sync - Keeps orchestrator docs aligned with your evolving codebase

Copilot Agents (shared/copilot-agents/) GitHub Copilot custom agent configurations for specialized AI personas (code review, refactoring, documentation, etc.). Optionally symlinked to each repo's .github/agents/ for VS Code/Copilot integration (enabled via setup wizard).

Hooks (shared/hooks/) Event-driven scripts that auto-suggest skills and track file changes.

Commands (shared/commands/) Slash commands like /dev-docs for creating planning docs and /setup-orchestrator for initial configuration.

Global Skills (shared/skills/global/) Meta-skill for creating new skills. Auto-triggers when working on the skill system.

Global Guidelines (shared/guidelines/global/) Documentation standards that all agents and skills follow. Language-agnostic best practices.

Generated During Setup

Repo-Specific Resources (one set per repository) The wizard generates custom skills, guidelines, and optionally agents tailored to each repo's tech stack. Skills auto-trigger when sending a message in Claude Code in that repo, guidelines provide tech-specific patterns, and agents offer specialized assistance.

How It Works

Day-to-Day Usage

1. Skills Auto-Trigger After a Message To Claude

• Edit a file in your repo → Orchestrator detects the file path and tech stack
• Relevant skill activates automatically on your next prompt
• Example: Edit backend/app/main.py → Python/FastAPI skill provides error handling patterns and best practices

2. Ask Claude Code for Help (Agents Invoke Automatically)

• Just describe what you need in natural language
• Claude Code automatically launches the right agent (or specifically ask Claude to use an agent's name)
• Examples:
  • "Review my authentication code" → code-architecture-reviewer agent runs
  • "Use code-architecture-reviewer agent to review my authentication code" → explicitly invokes that agent
  • "Help me plan a refactor" → refactor-planner agent creates a plan
  • "Fix these TypeScript errors" → auto-error-resolver agent fixes them

3. Use Slash Commands for Complex Tasks

• /dev-docs feature-name and description → Creates planning docs (plan.md, context.md, tasks.md)
• /dev-docs-update → Updates dev docs before context reset
• /setup-orchestrator → Runs first-time setup wizard

4. Guidelines Reference (When Needed)

• Skills and agents reference guidelines automatically
• You can read them directly for detailed patterns:
  • shared/guidelines/<repo-name>/error-handling.md - Error patterns for your stack
  • shared/guidelines/<repo-name>/testing-standards.md - Testing strategies
  • shared/guidelines/<repo-name>/architectural-principles.md - System architecture

5. Cross Repo Documentation Sync (Orchestrator Only)

• IMPORTANT: This agent is ONLY available when working in the orchestrator repository
• From the orchestrator repo, ask Claude to use cross-repo-doc-sync agent to update documentation
• Examples:
  • "Use cross-repo-doc-sync agent to update documentation based on the last 5 commits from all repos"
  • "Use cross-repo-doc-sync agent to update documentation based on the last 3 commits in repo-a"
  • "Update the documentation using cross-repo-doc-sync agent based on all commits from today"

6. Everything Stays in Sync

• Update an agent in orchestrator → All repos get the update via symlinks
• No manual copying, no version drift
• One source of truth for all AI resources

Setup Process Details

The wizard:

1. Collects org name, repo count, and repo details (name, path, type)
2. Scans repos to detect tech stacks
3. Generates SETUP_CONFIG.json, customizes CLAUDE.md, and updates README.md in orchestrator.
4. Creates CLAUDE.md for each repo.
5. Creates repo-specific skills (auto-trigger for each repo's tech stack)
6. Generates repo-specific guidelines (error handling, testing, architecture)
7. Creates settings.json for each repo (links skills/hooks)
8. Validates all generated files

Compatibility

Operating Systems

• ✅ macOS - Native symlink support
• ✅ Linux - Native symlink support
• ⚠️ Windows - Requires Developer Mode or administrator privileges for symlinks

AI Coding Tools

• ✅ Claude Code (primary target)
• ✅ GitHub Copilot (simplified compatibility):
  • Uses basic agent markdown files in shared/copilot-agents/
  • Less comprehensive than Claude Code agents but functional
  • Can be used alongside Claude Code infrastructure
  • Custom agents work as chat references rather than full skill integration
  • Cost-effective for routine tasks - Leverage Copilot for simpler queries and code completion
  • Smart token allocation - Use Copilot for basic tasks, preserve Claude Code tokens for complex reasoning and architecture work
  • Budget optimization - Allocate easier development tasks to Copilot while reserving Claude's full capabilities for critical problem-solving
• ✅ Any tool respecting .claude/ directory structure

Documentation

• QUICKSTART.md - Detailed setup guide (start here!)
• CLAUDE.md - Complete resource discovery for AI agents
• shared/agents/README.md - Agent capabilities guide
• dev/README.md - Dev docs pattern explanation

Additional reference docs:

• docs/reconfiguration.md - Reconfiguration
• docs/troubleshooting.md - Troubleshooting
• docs/supported-tech-stacks.md - Supported tech stacks
• docs/new-shared-resources.md - Adding new shared resources
• docs/skills_vs_guidelines.md - Skills vs Guidelines
• docs/repo-specific-agents.md - Repo-specific agents
• docs/repo-specific-skills.md - Repo-specific skills
• docs/orchestrator-resources.md - Orchestrator resources

Extensions

This orchestrator is designed to be customized and extended for your organization's needs. Feel free to:

• Add any useful organization-specific agents
• Create custom skills
• Extend guidelines with your patterns

🧠 Credits & Inspiration

Created by: mvoutov
Built while working on BoardKit — an AI-powered whiteboard.

This project grew out of the need to manage shared AI resources across BoardKit’s multi-repo architecture.

Inspired by the Reddit post “Claude Code is a Beast – Tips from 6 Months of Hardcore Use”,
I expanded the idea into a full orchestrator system for syncing documentation and AI resources across repositories.

Its key feature — a cross-repo documentation synchronization agent — keeps docs aligned with your evolving codebase, ensuring AI agents always have up-to-date context.

I hope this project is useful to you! If you find any issues or have suggestions for improvements, I'd love to hear your feedback.

---

Ready to get started? See QUICKSTART.md for the full setup guide!