The Meta-Workspace Pattern

The Problem: Fragmented Context

Your company has a frontend repo, a backend repo, infrastructure-as-code, shared libraries, maybe a data pipeline or two. When you open Claude Code or Cursor in one repo, the AI has zero knowledge of the others. It cannot reason about how a backend API change affects the frontend. It cannot plan a feature that spans three repos.

This is the fundamental bottleneck. AI tools are powerful within a single repo, but most real work crosses repo boundaries. A feature ticket often means: add an API endpoint (backend), build a UI (frontend), update the deployment (infra), and maybe add a migration job (data). Without unified context, the AI becomes a tool that only sees one piece of the puzzle.

The Solution: A Meta-Workspace

A meta-workspace is a Git repository that contains all your other repositories as subdirectories. The child repos keep their own Git histories — the meta-workspace simply aggregates them via .gitignore. Think of it as a 'repo of repos' with a shared brain.

company-workspace/
  AGENTS.md                    # Single source of truth for AI agents
  .claude/                     # Claude Code configuration
    agents/                    # Agent definitions
    skills/                    # Skill definitions (pipelines)
  repos/                       # All child repos (gitignored)
    backend/                   # Django/Rails/Express repo
    frontend/                  # Next.js/React/Vue repo
    infra/                     # Terraform + k8s manifests
    shared-libs/               # Shared packages
    data-pipeline/             # ETL jobs
  projects/                    # Project tracking
    ACTIVE                     # Current active project
    TICKET-123/
      README.md                # Project plan and status
  docs/                        # Cross-repo documentation
  setup.sh                     # One-command workspace setup

The key insight: the meta-workspace itself is a Git repo, but all child repos under repos/ are gitignored. Each child repo maintains its own branches, PRs, and CI. The meta-workspace only tracks the shared configuration — agent definitions, skills, project plans, and workspace-level docs.

AGENTS.md: The Single Source of Truth

AGENTS.md (or CLAUDE.md for Claude Code, GEMINI.md for Gemini CLI) is the most important file in your workspace. Every AI agent reads it first. It tells the AI: what repos exist, what each one does, what conventions to follow, and which agents/skills are available.

# Company Workspace

Meta-workspace for managing all company repositories with AI agents.

## Repository Map

| Repo | Path | Stack | Description |
|------|------|-------|-------------|
| Backend API | repos/backend/ | Django + Ninja | REST API, auth, payments |
| Frontend | repos/frontend/ | Next.js 15 | Customer-facing web app |
| Admin | repos/admin/ | Next.js 15 | Internal admin dashboard |
| Infra | repos/infra/ | Terraform + k8s | Cloud infrastructure |
| Shared Types | repos/shared-types/ | TypeScript | Shared API types |

## Conventions

- All repos use trunk-based development (short-lived feature branches)
- Backend: Django apps under apps/, tests mirror app structure
- Frontend: App Router, server components by default
- Infra: Terraform modules in modules/, environments in envs/

## Agents

| Agent | File | Model | Role |
|-------|------|-------|------|
| Solution Architect | .claude/agents/solution-architect.md | opus | Cross-repo planning |
| Backend Developer | .claude/agents/backend-dev.md | sonnet | Django implementation |
| Frontend Developer | .claude/agents/frontend-dev.md | sonnet | Next.js implementation |
| Infra Engineer | .claude/agents/infra-eng.md | sonnet | Terraform + k8s |
| Reviewer | .claude/agents/reviewer.md | opus | Code review |

## Skills

| Skill | File | Description |
|-------|------|-------------|
| /feature | .claude/skills/feature-pipeline.md | Full feature implementation |
| /deploy | .claude/skills/deploy.md | Deploy to staging/production |
| /review | .claude/skills/review.md | Cross-repo code review |

Symlinks for Tool Compatibility

Different AI tools look for different filenames. Claude Code reads CLAUDE.md, Cursor reads .cursorrules or .cursor/rules, Gemini CLI reads GEMINI.md. Instead of maintaining multiple copies, use symlinks.

# Create the canonical source
vi AGENTS.md

# Symlink for each tool
ln -s AGENTS.md CLAUDE.md
ln -s AGENTS.md GEMINI.md
mkdir -p .cursor && ln -s ../AGENTS.md .cursor/rules

# Verify
ls -la CLAUDE.md
# lrwxr-xr-x  CLAUDE.md -> AGENTS.md

Now when you update AGENTS.md, every tool automatically picks up the changes. This is critical for teams — one person updates the conventions and every developer's AI tools reflect it immediately.

The .gitignore Strategy

The meta-workspace .gitignore is the glue that holds everything together. It ignores all child repos (they have their own Git) while tracking everything else.

# .gitignore for the meta-workspace

# Child repos — each has its own git history
repos/

# OS files
.DS_Store

# IDE files (optional — some teams track these)
.idea/
.vscode/

This means the meta-workspace commits only contain: AGENTS.md, agent definitions, skill definitions, project plans, and documentation. The actual code lives in child repos with their own branches and CI.

What Goes Where

• Meta-workspace repo: AGENTS.md, agent/skill definitions, project tracking, cross-repo docs, setup.sh
• Child repos: All source code, tests, CI/CD configs, repo-specific AGENTS.md files
• Never in meta-workspace: source code, dependencies, build artifacts, secrets

Real Example: Opening the Workspace

Here is what it looks like in practice. You open a terminal in the workspace root and start Claude Code. The AI immediately reads AGENTS.md and knows about every repo, every agent, every skill. You say 'implement TICKET-456' and it knows which repos to touch.

$ cd ~/company-workspace
$ claude

> Implement TICKET-456: Add user preferences API endpoint
  with a settings page in the frontend.

# Claude reads AGENTS.md, sees:
# - Backend repo at repos/backend/ (Django + Ninja)
# - Frontend repo at repos/frontend/ (Next.js)
# - Solution Architect agent for planning
# - Backend Developer agent for implementation
# - Frontend Developer agent for UI

# It plans the work across both repos,
# creates branches in each, and implements the feature.

Why Not a Monorepo?

Monorepos solve the same context problem — everything in one place. But they come with heavy tooling requirements (Nx, Turborepo, Bazel), force all repos into one CI system, and are hard to adopt incrementally. The meta-workspace pattern works with any existing repo setup. You do not need to change your CI, your branching strategy, or your deployment pipeline. You just add a thin layer on top.

If you already have a monorepo, the meta-workspace still adds value: it provides the agent definitions, skills, and project tracking that monorepo tools do not handle.