MIP-0070: split marola into single-purpose repos under an umbrella

[brunogbv]

Proposal: MIP-0070 · Draft PR: #521

We want to break the monorepo into single-purpose repos without losing what makes it good for agentic work, which is one place where an agent can see everything. The idea is a two-layer setup: an umbrella repo holds the team layer, and every code repo is a git submodule inside it.

The shape

Three layers

• Umbrella (marola-dev/marola, this repo): ways of working, MIPs, issues, the phase list, a workspace AGENTS.md, and the aggregated docs site at docs.marola.dev. No code, no build.
• marola-devkit: the shared harness (stack/uprd/cost-split/issues, hooks, generic skills and agents, reusable CI). Each repo consumes it as a pinned flake input, a Claude Code plugin and reusable workflows.
• Each repo: its own AGENTS.md, docs, gates and specialised tooling. It can override devkit defaults, but never the org invariants (cost safety, agent-ready, commit trailers, no secrets, phase discipline).

Repos, split where the stack or release cadence changes

Repo	What it is
marola-app	The Scala product (core/local/cli stay together) plus the OODS ingest code
marola-site	The map at marola.dev
marola-corpus	Sourced ocean knowledge
marola-ml	DSPy, fine-tuning, marola-sea, the model benchmark gate
marola-oods	The water-quality dataset only

Contracts: every place where one directory reads another's files today becomes a versioned artifact that the producer publishes and the consumer pins. For example, the site builds its boards by running a pinned app image and never compiles Scala. No repo reads another repo's tree, in CI or in tests.

Docs: each repo keeps README.md + docs/ and pings the umbrella when they change. The umbrella rebuilds and deploys the aggregated site, so a docs change in the app redeploys the docs without touching the map.

Migration order:

1. Prep inside the monorepo, so every contract works before anything moves.
2. The devkit.
3. The site, together with the docs host swap. One Pages site per repo forces this.
4. Corpus and ml.
5. App and oods.

What we'd like input on

1. Granularity. Is marola-corpus worth its own repo (7 files, but different contributors and two consumers)? Should dspy and finetune stay together?
2. Cross-repo cost. A board-schema change becomes two PRs plus an image bump. Is that acceptable for the build-time and parallel-work gains?
3. Cross-repo credential: a GitHub App or a fine-grained PAT?
4. Repo names: marola-app or something else?
5. Issues: do they all stay in the umbrella for good, or do repo-specific issues move out eventually?
6. Anything missed. A coupling between directories that §5.4's contracts table doesn't cover is the biggest risk. If you know one, please point it out.

Comments on specific lines are best on the draft PR; direction and trade-offs are best here.

[h0ffmann]

LGTM. All new 6 new submodules. I think this will make things more organized for everyone

[h0ffmann]

We may add more ML specific partitions in the future ... 'marola-llm, marola-nlp, marola-ml' ... the initial 6 looks a good split (app, site, corpus, ml, data & utils/devkit)

[h0ffmann]

Maybe another discussion but after umbrella is finished we could move root repo to IBRAMAR or IBAMAR

[brunogbv]

On "Cross-repo credential: a GitHub App or a fine-grained PAT?" IMHO both works fine, I'd go with the simplest approach which I consider to be the fine-grained PAT

[brunogbv]

On "Repo names: marola-app or something else?" I like the current proposed schema, I'd go with marola-backend or marola-core instead of marola-app and marola-frontend instead of marola-site. Not strongly opinionated though.

[brunogbv]

On Issues: each repo should have it's own issues IMHO. The project is org wide and can be used to coordinate cross repo issue tracking. We should respect as much as possible one issue per PR and when that's not possible, we have one sub-issue per PR.

[brunogbv]

Outcome: MIP-0070 is Accepted (PR #521). Thanks, everyone.

Decided

• Repos: the six as proposed, marola-app, marola-site, marola-corpus, marola-ml, marola-oods (data only) and marola-devkit, under this repo as the umbrella.
• ML: one marola-ml for now. marola-llm/marola-nlp/marola-ml is the next cut, once one of them grows its own cadence. Pinned-artifact contracts keep that split cheap.
• Cross-repo credential: a fine-grained PAT, the simpler option. Its owner (a person or a machine user) and its expiry are still to be set.
• Issues: each repo has its own, coordinated on the org Project "Marola". One issue per PR; cross-repo work gets a parent issue with one sub-issue per PR. Labels and forms sync from the devkit, so agent-ready means the same thing everywhere. Milestones are per repo on GitHub, so a cross-repo deliverable becomes a parent issue plus a Project field.
• Moving to IBRAMAR/IBAMAR: its own discussion, after the migration finishes. Pages isn't redirected on a transfer, so the devkit reads the umbrella's slug from one setting.

Next: the migration steps become task issues (mip-tasks), starting with the freeze on in-flight stacks and the prep inside the monorepo.