Athlentic maintains separate Git repositories for iOS, Android, and Web. That separation makes releases and history clear, but creates a problem for AI agents: an agent opened inside the iOS repository cannot see a policy already implemented on Android, product copy from the website, or the plan for the next release.
Our solution is deliberately simple. Instead of merging repositories, we place a product-level workspace above them.
Start one level above the repositories
Create an Athlentic directory at the root and place both shared documents and platform repositories inside it.
Each platform directory still owns its own .git. The parent workspace tracks product-level documents and rules, while code is committed and released independently within each platform repository.
Keep platform code out of the parent Git repository
We also initialize Git in the parent Athlentic directory, then ignore the platform folders. This preserves the history of plans without accidentally tracking nested repositories.
If the parent repository must pin exact platform commits, submodules are a better fit. Our goal is simply to expose local context while keeping repositories independent, so ignored sibling repositories are enough.
Open only the root folder for the AI agent
Set the AI agent's workspace to the Athlentic root instead of an individual repository. The agent can then inspect the shared plan and all three implementations before it starts.
- It can translate a feature already implemented on Android into native iOS patterns.
- It can find inconsistencies between website copy and in-app language.
- It can assess how a shared model change affects every platform.
- It can break down a product-level plan into repository-specific work.
A request such as “plan workout export and implement iOS first” can now lead the agent to write a plan under docs/plans, inspect Android's existing model and the website's privacy copy, then make scoped changes in the iOS repository.
Plans become the agent's long-term memory
Co-location alone is not enough. Product context needs to be written down so the agent does not repeat the same reasoning in every session.
AGENTS.md,CLAUDE.mddefines build commands, conventions, and repository boundaries.docs/plansrecords goals, scope, and completion criteria.docs/architectureexplains shared concepts and data flows.docs/decisionscaptures why a decision was made, not only what was chosen.
These files survive a new conversation. Context that once lived only in chat becomes a reviewable asset: onboarding material for people and long-term memory for AI.
When to Split Repositories vs. Fold Them Together
"Monorepo, or split?" is a decision almost everyone hits before adopting this structure. The right answer depends on team size and release cadence, but the table below cuts down on mistakes.
When iOS (Swift), Android (Kotlin), and Web (static HTML/Eleventy) each have different languages and different release cadences, keeping the repositories separate still wins. But if you also scatter plans and decision records across them, the AI can't see the product as a whole. That's why the parent workspace is less about merging and more about overlaying.
Where a Document Lives Becomes the Rule
The same information stored in two places drifts apart. Deciding upfront what belongs in the parent workspace and what stays inside each repository cuts maintenance cost sharply.
- In the parent workspace: product definition, feature plans, cross-platform decisions, shared data models and API contracts, brand copy, and legal policy. Everything that doesn't change when a platform does.
- Inside each repository: build and release instructions, platform-specific coding rules, that repo's folder conventions, its CI workflows. Everything that has to travel with the code.
- Never in both: the same spec document. Keep the source in the parent, and let each repo's CLAUDE.md link to it. Moving the source only requires updating the link.
Split this way, a new teammate opening only the iOS repo can still see every rule that repo enforces — and the product context is one link away in the parent.
When Rule Files Get Ignored — and What to Do
No matter how careful your AGENTS.md or CLAUDE.md is, the agent sometimes just won't follow it. The cause is usually one of three things.
The one most often missed is the second. Piling every platform's rules into the parent CLAUDE.md means Android rules eat context while iOS work is running. Parent file holds shared rules only; each repository owns its own CLAUDE.md — this gets followed far more reliably.
Migrating Existing Repositories Into This Structure
If plans and decisions are already scattered across your platform repos, the move itself is the risk. The following order preserves history.
Skipping step 5 is where you lose time: broken references don't fail any build, so you find them days later. After the first move, walking each repo's outbound links to parent docs once is worth the ten minutes.
The benefit—and the boundary
The biggest benefit is that the agent starts thinking in terms of the product, not a single file. It checks other platforms before duplicating an implementation and reads the plan before changing code.
A broad workspace still needs a narrow change boundary. Seeing every repository does not mean the agent should edit every repository. State the target repository and completion criteria, and require separate Git status checks for each repository.
“Read context from the whole product; make changes only in the requested repository.” It preserves the advantage of a broad workspace while reducing surprises.
Frequently Asked Questions
Can the platform repositories live in different GitHub organizations?
Yes. The parent workspace is only a local folder; each repo's remote URL stays put. But different orgs mean CI secrets and access are managed separately, so decide upfront which documents may exist in which org. If the parent workspace is a personal repo and the platforms live in a company org, company-only information doesn't belong in the parent.
Wouldn't a monorepo be better?
If shared code is large (say, web and apps share the same TypeScript) and release cadences roughly align, a monorepo is better. When languages and cadences all differ, monorepos usually make CI matrices and IDE indexing painful. If three or more items in the left column of the table above apply, keeping repositories separate is still the safer call.
Why not submodules or git worktree?
Submodules matter when the parent repo must pin an exact commit of each platform. We wanted the opposite — each platform releasing on its own schedule — so the pinning gets in the way. git worktree is for opening multiple branches of the same repository in parallel; it solves a different problem.
How much detail should a plan document carry?
The test is whether your future self, six months from now, could reproduce the decision from it. Goal, decision, rationale is enough. Pasting the whole chat log usually hurts — it buries the conclusion. Execution details belong in the PR descriptions of each repository.
Closing thought
Working effectively with AI agents turned out to be less about writing longer prompts and more about designing a workspace where the right information is discoverable. Persisting plans and decisions as files made an even larger difference.
If one product spans several platforms, try creating a lightweight product workspace above the repositories before merging them. It gives both people and AI a map of the whole product.