The Planning Repo Pattern

I often manage 20+ git repositories across work projects, side projects, infrastructure, and experiments. For years I tried different approaches — git submodules, monorepos, scattered directories. They all had friction.

Then I landed on something simple that changed how I work: a planning repo.

The Problem

If you work on multiple projects, you've felt this pain. Your repos are scattered across your filesystem. Context-switching means jumping between directories, losing mental state, forgetting where things live. Cross-project work — refactoring shared patterns, moving code, planning features that span repos — becomes a navigation nightmare.

Git submodules promise to help but deliver complexity instead. Version coupling, update headaches, merge conflicts. Monorepos solve the visibility problem but create tight coupling and tooling overhead that doesn't fit most workflows.

What I wanted was simpler: all my projects visible in one workspace, but each maintaining full git independence.

The Solution

A planning repo is a git repository that contains other git repositories — and intentionally ignores them.

That's it. One directory, organized by portfolio, with nested repos that the parent .gitignore treats as opaque. No submodule tracking. No version coupling. No synchronization headaches.

~/prj/                    # Planning repo (git-tracked)
├── .git/
├── .gitignore            # Lists all nested repos
├── CLAUDE.md             # Workspace-level context
│
├── jp/                   # Personal projects
│   ├── ai-gateway/
│   ├── mcp-exploration/
│   └── agents/
│
├── ps/                   # Company projects
│   ├── daax/
│   ├── hawkeye/
│   └── nanofuse/
│
└── ext/                  # Third-party exploration
    └── interesting-lib/

The .gitignore lists each nested directory:

jp/ai-gateway/
jp/mcp-exploration/
ps/daax/
ps/hawkeye/
ext/

Now git status in the planning repo shows only its own files. Each nested repo operates completely independently—separate history, branches, remotes. You get unified visibility without unified coupling.

Why This Works

Single workspace, instant navigation. Everything lives under one roof. Jump between projects without leaving your working directory. Your editor's file tree shows your entire ecosystem.

Cross-project visibility. Planning a feature that touches multiple repos? You can see all the pieces at once. Moving code between projects becomes a simple file copy instead of a multi-repo dance.

Clean exploration. Want to study a third-party library or reference implementation? Clone it into ext/, explore, learn, delete when done. It never pollutes your tracked work.

Scoped credentials. Different projects need different access. Structure .env files by portfolio—work credentials stay with work projects, personal keys stay personal. Easy to audit, easy to rotate.

AI context at scale. Modern AI coding assistants work best with context. A CLAUDE.md at the planning repo root can describe your entire ecosystem—how projects relate, shared patterns, conventions. The AI understands not just the repo you're in, but how it fits the bigger picture.

Setting It Up

Start simple:

mkdir -p ~/prj
cd ~/prj
git init
mkdir -p work personal infra ext

Move or clone your repos into the appropriate directories:

git clone git@github.com:myorg/api-service.git work/
mv ~/old-location/side-project personal/

Update .gitignore for each nested repo:

echo "work/api-service/" >> .gitignore
echo "personal/side-project/" >> .gitignore
echo "ext/" >> .gitignore
git add .gitignore && git commit -m "Ignore nested repos"

That's it. You now have a unified workspace where every project maintains full independence.

What Lives in the Planning Repo

The planning repo itself stays minimal — just the meta-layer:

• CLAUDE.md — Workspace-level AI context describing the ecosystem
• .gitignore — List of nested repos
• docs/ — Architecture decisions, roadmaps, cross-project planning
• scripts/ — Automation helpers that work across projects

The actual code lives in the nested repos where it belongs.

Portfolio Organization

Pick groupings that match how you think about your work. I use:

• jp/ — Personal projects (blog, practice, experiments)
• ps/ — Company projects (Peregrine Summit)
• ext/ — Third-party repos for exploration

Others might prefer domain-based groupings (frontend/, backend/, infra/) or lifecycle-based (active/, maintenance/, archived/). The pattern is flexible—organize by whatever boundaries make sense for your context.

Growing With the Pattern

The benefits compound as your ecosystem grows. With 5 repos, it's convenient. With 20+, it's essential. You stop thinking about where projects live and start thinking about what they do.

Cross-project refactoring becomes natural. Credential management becomes auditable. AI assistants get the context they need to actually help. And you always know where to find things.

It's not complicated. One repo that ignores its children. But sometimes the simple patterns are the ones that stick.

Originally published on Medium