Meta Repos

A meta repo is a special repository that contains shared skills, architecture documentation, team conventions, and onboarding materials for a project. In progressive polyrepo setups, the meta repo is the single source of truth for agent configuration and team onboarding.

What a Meta Repo Contains

team-meta/
├── .agent-template/              # Copied into every workspace
│   └── .claude/
│       ├── CLAUDE.md             # Project conventions for agents
│       └── skills/               # Team-specific skills
│           └── workspace-add-repo/
├── overdeck/                   # Overdeck-specific config
│   └── repo-groups.yaml          # Repo group definitions
├── docs/                         # Architecture and reference docs
│   ├── repo-map.md               # What each repo does
│   ├── architecture.md           # System architecture overview
│   └── onboarding/               # Team onboarding materials
│       ├── checklist.md          # Prerequisites checklist
│       ├── machine-setup.sh      # Automated setup script
│       └── README.md
└── README.md

Directory Structure

`.agent-template/`

This directory is copied into every workspace created for the project. It contains:

Path	Purpose
`.claude/CLAUDE.md`	Project-specific AI instructions
`.claude/skills/`	Team-specific skills available to agents
`.claude/commands/`	Team-specific commands
`.claude/agents/`	Custom agent definitions

`overdeck/repo-groups.yaml`

Defines named groups of repositories for progressive workspace creation:

groups:
  simphony:
    - int-micros-simphony
    - int-micros-simphony-api
    - micros-symphony-canonical-transform

  aloha:
    - int-aloha
    - int-aloha-hrbridge
    - aloha-agent-canonical-transfer

  shared-lib:
    - int-aws-hs-service
    - int-aws-store-config-labels

`docs/`

Architecture and reference documentation:

File	Purpose
`repo-map.md`	What each repo does, dependencies, common change patterns
`architecture.md`	System architecture overview
`onboarding/checklist.md`	Prerequisites checklist for new team members
`onboarding/machine-setup.sh`	Automated setup script
`onboarding/README.md`	Getting started guide

Creating a Meta Repo

Via Setup Wizard

The setup wizard (pan setup) creates a meta repo as part of progressive polyrepo project setup:

Step 6: Meta Repo
  Progressive polyrepo projects use a meta repo for shared skills,
  architecture docs, and team conventions.

  Create a new meta repo? [Y/n]: _
  Meta repo name [team-meta]: _

Via Setup Agent

The Setup Agent generates meta repo contents automatically:

Explores all repositories in the project
Detects conventions, patterns, and dependencies
Generates CLAUDE.md with only non-obvious project-specific rules
Generates repo-map.md documenting each repo’s purpose
Generates repo-groups.yaml with logical groupings
Generates onboarding checklist with prerequisites

Manual Creation

Create the directory structure manually:

mkdir -p team-meta/{.agent-template/.claude,overdeck,docs/onboarding}

Onboarding Flow

When a new team member joins:

Clone the meta repo

git clone git@github.com:yourorg/team-meta.git

Run the machine setup script
cd team-meta/docs/onboarding ./machine-setup.sh
This installs prerequisites, authenticates CLI tools, and clones repositories.
Run pan setup
pan setup
The wizard detects existing repos and applies your team’s template with pre-configured settings.
Ready to work
pan workspace create INT-123

Updating the Meta Repo

When team conventions change:

Update the meta repo (normal git workflow)
Changes propagate when agents sync skills:
pan sync

Agents pull the latest .agent-template/ contents when:

A new workspace is created
pan sync is run
The Setup Agent runs and regenerates files

Meta Repo Best Practices

What to Include in CLAUDE.md

Focus on non-obvious conventions only. Don’t document:

How to run npm install, git commit, etc. (LLMs know these)
Standard industry practices

Do document:

Deviations from defaults — “PRs target qa not main”
Per-repo quirks — “Each Lambda has its own package.json, no root one”
Breaking behaviors — “Never run terraform apply without approval”
Architecture patterns — “API gateway handles auth, microservices don’t”

What to Include in Repo Map

For each repo, document:

Purpose — What the repo does
Dependencies — What it depends on, what depends on it
Common change patterns — “Changes here usually need corresponding changes in api-service”
Key files — Where to start looking

Machine Setup Script

Generated by the Setup Agent based on detected prerequisites:

#!/bin/bash
# Auto-generated by Overdeck Setup Agent

echo "=== Team Onboarding Setup ==="

# Check prerequisites
command -v git >/dev/null || { echo "Install git first"; exit 1; }
command -v gh >/dev/null || { echo "Install GitHub CLI"; exit 1; }
command -v node >/dev/null || { echo "Install Node.js 20+"; exit 1; }

# Authenticate GitHub CLI
gh auth status || gh auth login

# Clone repos
REPOS=(
  "yourorg/int-micros-simphony"
  "yourorg/int-toast"
)

for repo in "${REPOS[@]}"; do
  name=$(basename "$repo")
  if [ ! -d "$name" ]; then
    gh repo clone "$repo" "$name"
  fi
done

echo "Done! Run 'pan status' to verify setup."

Progressive Polyrepo — Progressive workspace configuration
Setup Wizard — Interactive project setup
Projects — Project registry and configuration

​Meta Repos

​What a Meta Repo Contains

​Directory Structure

​.agent-template/

​overdeck/repo-groups.yaml

​docs/

​Creating a Meta Repo

​Via Setup Wizard

​Via Setup Agent

​Manual Creation

​Onboarding Flow

​Updating the Meta Repo

​Meta Repo Best Practices

​What to Include in CLAUDE.md

​What to Include in Repo Map

​Machine Setup Script

​Related Guides