When I introduced the meta-repo to the team, the goal was a true agentic coding setup: a shared doc set, shared skills, shared rules, all loaded automatically no matter which platform repo you had open. Onboarding got easier and setup went from three commands to one as a side effect of that.
Several months later, that's still true — structuring a codebase for AI context turns out to be a different problem than structuring it for human developers.
This isn't a pattern we roll out on every project. It's what this specific project needed, given a constraint most codebases don't have: three mature repos that couldn't be merged into one.
The setup
The platform I work on has three repos: shared Kotlin Multiplatform code, an iOS presentation layer, an Android presentation layer. They were set up 4–5 years ago, well before AI assistants were part of anyone's toolchain. Three separate git histories, three separate CI pipelines, three sets of conventions. That's just how multi-platform mobile worked on this project — it's not a universal N5 setup, just how this particular client's codebase evolved.
When AI coding tools became serious, the obvious answer would have been a monorepo. One folder, full context, done. We raised it. The client team pushed back. Reasonable objections: independent release cycles, existing CI setup, git history. Migrating three mature repos into a monorepo isn't a weekend project, and it wasn't worth the disruption.
So the meta-repo is the answer to a constraint: how do you give AI assistants full cross-platform context without moving everyone to a monorepo?
It sits on top of the three platform repos. It contains no app code. What it contains is three things: a .ai/ directory with shared skills and agents, a docs/ folder with shared architecture knowledge, and a setup script. Via symlinks, every tool and every platform repo points back to .ai/:
meta-repo/
├── .ai/ ← single source of truth
│ └── skills/
├── docs/ ← shared architecture docs, ADRs, diagrams
├── .cursor/skills → ../.ai/skills
├── .claude/skills → ../.ai/skills
│
├── ios-app/
│ └── .claude/skills → ../../.ai/skills
├── android-app/
│ └── .claude/skills → ../../.ai/skills
└── shared-kmp/
└── .claude/skills → ../../.ai/skills
Skills
Skills are multi-step workflows encoded as files. Some are basic and used daily by everyone — commit, which writes a properly formatted commit message from the staged diff, branch, which creates a new branch following our naming convention, worktree, which sets up a git worktree for parallel work on a ticket. Others are heavier — multi-platform-search, which runs parallel agents against iOS, Android, and KMP simultaneously, or dependency-audit, which compares pinned versions against latest across all three codebases at once. They live in .ai/skills/ and get symlinked into every tool config and every platform repo.
Write a skill once, it goes through code review like any other change, and every teammate gets it on next pull.
The scoping matters too. Engineers don't have to work from the meta-repo root. Open ios-app/ directly and you get iOS-scoped context without Android or KMP noise, useful for a focused bug fix or a platform-specific feature. Either way, the full skill library is available. An Android developer who rarely touches iOS can work entirely out of android-app/ and get a clean, platform-focused experience, with access to cross-platform skills when a ticket touches the shared layer. The scoping is intentional, not a limitation.
Documentation
docs/ serves three purposes at once: documentation for future teammates who need to understand how the system works, a record of architectural decisions so the reasoning behind past choices doesn't get lost, and direct context for agents. When a skill or agent needs to answer a question about how something works, it reads from docs/ rather than scanning the codebase from scratch every time. The documentation isn't just for humans anymore — it's fuel.
Onboarding
Before the meta-repo, getting a new developer up and running meant cloning three separate repos, finding the scattered docs, figuring out which branch conventions applied where, and hoping someone remembered to mention the CI quirks. AI context was whatever they managed to assemble themselves.
Now it's one command:
git clone <meta-repo> meta
cd meta
./setup.sh
The setup script clones the three platform repos into the right folder structure, creates all the symlinks, and verifies each one resolves correctly. It's idempotent — safe to run again if something gets out of sync. When it finishes, the developer has the full workspace: all three platform repos, the shared docs/, the skills, and the AI configuration wired up and ready.
The practical consequence is that a new engineer gets the exact same AI-assisted environment as someone who's been on the project for a year. The rules, the skills, the documented context: it's all there from day one, not something you accumulate gradually. That matters more than it might seem: the AI context is only as useful as it is consistent across the team.
What it actually unlocks
When a developer opens android-app/, the AI already knows the module structure, the branch conventions, the testing approach, the CI pipeline, the documented pitfalls, how the Android layer relates to shared KMP code. None of that gets explained in the prompt — it's loaded automatically. You just ask the question.
Here's what that makes possible, broken into three tiers:
Low-key wins — living code docs, test generation, consistent branch and commit conventions across all three platforms. These work because the rules files exist and because every teammate's AI assistant loads the same rules. No one has to remember to explain the conventions.
Medium wins — cross-platform search, contextual implementation lookup, technical approach preparation. The multi-platform-search skill runs parallel agents against iOS, Android, and KMP simultaneously. That used to take 30–60 minutes of manual repo-hopping. It now takes 2–5 minutes. This skill only exists once, in .ai/skills/, and is available in every context via the symlink chain.
Big impact — parallel implementation across multiple tickets in flight simultaneously, POC speed, bridging expertise gaps. At one point I needed to improve build times in the Kotlin/Gradle setup — not my primary area. With full project context already loaded, the AI could apply optimization knowledge I didn't have. We landed a 25% build time improvement. I wouldn't have known where to start.
Some concrete numbers from running this way for several months:
- MR description writing: 15–20 min → under 2 min
- Dependency audit across three codebases: half a day → 15–20 min
- Jira ticket triage with written functional analysis and technical approach: 1–2 hours → 15–30 min
The compounding is real. On a typical working day I have several tickets in parallel flight: different stages, each in its own git worktree, one waiting on product clarification, one in implementation, one in review. The AI setup is consistent across all of them. Same rules, same skills, same memory of project conventions. Switching context between loops costs almost nothing because the AI doesn't need to be re-briefed.
(My colleague Mats wrote about the worktree approach in depth on the November Five engineering blog: How I stopped working in serial — Claude combined with worktrees.)
Closing thoughts
Codebases are structured for human readers: clear folder names, good naming conventions, inline comments. These help humans navigate.
AI assistants benefit from all of that, but they also need explicit, aggregated context that humans don't, because humans ask colleagues and remember from last time. A rule file that says "our testing approach for this module is X" or "don't do Y because of Z" is context a human would carry from experience. The AI needs it written down, in a place where it's loaded by default.
Treating .ai/ as a first-class directory in the codebase, something you maintain, review, and extend like any other part of the project, is the shift. Not a folder that accumulates random prompt snippets, but a structured layer you care about keeping accurate.
The meta-repo makes that layer possible across a multi-platform project without duplication. One edit to a rule propagates to every tool, every platform, every developer on next pull.
That's the multiplier. Not the prompts. The substrate.
Top comments (4)
The “substrate, not prompts” framing is exactly right. I would add one operational guardrail to the meta-repo: treat .ai/ changes like executable infrastructure, with an owner, review, and a small compatibility test that checks every symlinked tool sees the same rules. I also like the scoped-context approach: full cross-platform context when a ticket crosses boundaries, but a narrow repo by default to reduce noise and accidental edits. How do you detect stale docs or skills before they quietly become shared agent behavior?
That's good feedback, thank you! As with the entire codebase and team operations, the tech-lead should be final owner. But it wouldn't hurt to assign it to a team member to distribute the load. In my team, we reviewed each-other's skill PRs as we do with regular code reviews. A compatibility check is not something we worked with yet, I might include it in the future. Thanks for the suggestion!
Stale docs and skills are indeed something to be cautious about. At this point, I don't have a readily available solution to it. I think the stale docs are potentially the biggest issue here.
Some things that could work:
I like this pattern because it admits the repo boundary is political as much as technical. The piece I would make boring is drift detection. A tiny CI check that hashes the shared .ai files from each platform checkout and fails when one view diverges catches a surprising amount before an assistant turns stale context into policy. For docs, I’d treat last validated against repo state as metadata, not prose.
Great feedback, totally agree! Still something we need to fully solve.