Repository structure for projects¶
1. Principles¶
- Code and work are separate (Atul, 10–11 Oct):
- Code repo on GitLab: protected
main; the coder and the reviewer; CI on our runner. - Work repo on GitHub: issues (Work Requests), specs, decisions, evidence, handovers, labels; the lead/PM, other agents, Claude and MCL.
- The company owns the spaces: a GitHub organisation and GitLab groups, all owned by Atul. People and agents are members; nothing important lives in a personal namespace.
- One governance home: cross-project standards, ADRs and the estate (TEA) stay in the GitLab governance repo (DR-001).
- Group by vertical, not by project, where projects are tightly coupled. One work repo per vertical keeps the count down. For example, API and MM-Cron share one agent, one data contract and one review queue.
- No duplication: content lives in one repo; others link to it with repository-qualified references (governance standard §2).
- Claude sees code through read-only mirrors on GitHub, refreshed by our own scheduled job (A-09 changed).
2. Use cases and what each needs¶
| Use case | Example | Code repo (GitLab) | Work repo (GitHub) |
|---|---|---|---|
| Product with code | Portfolio Engine, API, MM-Cron, website | Yes | Yes (per project or per vertical) |
| Design or documentation phase, no code yet | MCRM today | Not yet | Yes; a code repo is created when coding starts |
| Estate and governance | TEA, standards, ADRs | — | The GitLab governance repo stays the home (DR-001); its issues are the TEA tasks |
| Shared testing | Selenium suite, MMCLONE sandbox | Yes, one shared testing group | Issues go to the work repo of the project being tested |
| Tooling and automation | MCL (mmdep-control), collectors, setup scripts |
GitHub (MCL runs on Actions) | Same repo |
| The orchestrator itself | MMDEP | GitHub MMDEP (exception: ADR-005 draft) |
Same repo for now |
3. Proposed layout¶
GitLab: code, one top-level group per vertical¶
Each group gets its own CI minutes and member list (Free: 5 users per top-level group), and our runner is registered per group.
| Group (proposed name) | Projects (code) | Members |
|---|---|---|
mm-platform |
api, mm-crons |
Atul (Owner), Ajay (Maintainer), platform agent account (Developer) |
mm-web |
webapp-sakai (production website, branch dashboard, with the customer dashboard), website (WPDev, the next generation; today money-marche/money-marche-website), wordpress-plugins, website-staging (old implementation); webapp is old and a retirement candidate |
Atul, Ajay, web agent account (Developer) |
mm-products |
portfolio-engine (code, when moved), mcrm (code, when it starts) |
Atul, product agent account (Developer) |
mm-testing |
website-tests (Selenium; put under git), sandbox (MMCLONE engineering) |
Atul, operations head, testing agent account |
money-marche-group (existing) |
Governance repo (stays) | As today |
Production and development rules differ, so production deploy jobs run only on protected branches with a protected runner (estate proposal §8b).
GitHub: work, one organisation¶
| Repo (proposed) | Covers | Today |
|---|---|---|
platform-work |
API and MM-Cron: specs, contracts, evidence, review packs, Work Requests | Spread across the API and MM-Cron repos as documentation MRs |
website-work |
Production site, WPDev, plugins, staging | MCRM issue #96 (WPDev compatibility); website issues on GitLab |
portfolio-engine |
Portfolio Engine work (and code until it moves) | moneymarche-dev/portfolio-engine |
mcrm |
MCRM design, gates G1–G4, decisions | moneymarche-dev/MCRM (already a work repo) |
MMDEP |
The orchestrator | moneymarche-dev/MMDEP |
mmdep-control |
MCL configuration, state, workflows | New |
mirror-<code-repo> |
Read-only copies of GitLab code for Claude | New, written by the mirror job only |
Organisation: create a free GitHub organisation owned by Atul and transfer the three existing repos into it. A transfer keeps issues, PRs and history, and GitHub redirects the old URLs. Actions minutes then belong to the organisation (2,000 a month on Free).
4. Standard contents¶
Work repo:
README.md what the project is; links to its code repo(s) and governance records
PROJECT.md roles table (lead, coder, reviewer, seat) and working agreement
AGENTS.md generated from MMDEP's AG-1 template (roles, labels rule, Work Result format, trailers)
docs/spec/ requirements and design
docs/decisions/ project decisions and their assumptions
docs/evidence/ test, audit and review evidence (no client data)
docs/handovers/ current-state record and handovers
.github/ISSUE_TEMPLATE/ Work Request, Work Result, Role Transfer (HO-1)
labels state:*, role:*, type:*, flags
Code repo:
README.md run, test, deploy; link back to the work repo
AGENTS.md coder and reviewer rules; act only on issues labelled for your role
src/ tests/ deploy/
.gitlab-ci.yml jobs tagged for our runner; rules: MRs and protected branches only
CHANGELOG.md
Implementation notes stay next to the code. Everything else goes to the work repo.
Linking:
- Each code MR names its work-repo issue.
- Each Work Result names the MR and commit.
- Commits carry the trailers (Work-Item: points to the issue).
5. Moving from today's layout (gradually, nothing breaks)¶
| Step | What | When | Risk and mitigation |
|---|---|---|---|
| 1 | Create the GitHub organisation; transfer MMDEP, Portfolio Engine and MCRM | After the vacation | URLs redirect; update local remotes, the Actions secrets for PE's deploy and connector permissions |
| 2 | Create mm-testing on GitLab; put website-tests under git there |
With the tools box test | Low |
| 3 | Create platform-work. New API and MM-Cron documentation goes there; the open documentation MRs are merged or closed where they are (Ajay's review) |
After the Ajay meeting | Avoid moving history; link instead |
| 4 | Reorganise GitLab groups (mm-platform, mm-web) by transferring projects (no data loss, A-31) |
When the runner and agent accounts exist | Group CI variables, runners and labels don't move with a project; deploy keys and remotes need updating; one project at a time |
| 5 | Portfolio Engine code to mm-products (protected main) |
Decide after the tools box test | PE's GitHub Actions deploy moves to GitLab CI; largest change, so last |
| 6 | Mirror job for Claude | With MCL | — |
6. Questions for Atul¶
- Verticals: Platform (API, MM-Cron), Web (website, WPDev, plugins, staging, webapp), Products (Portfolio Engine, MCRM), Testing, Governance. Is that the right split? It's to settle in the projects discussion.
- One work repo per vertical for Platform and Web, but per project for Portfolio Engine and MCRM (different leads). Agreed?
- A GitHub organisation name, and whether to transfer the existing repos after the vacation.
- Does Portfolio Engine's code move to GitLab (protection), or stay on GitHub until budgets allow GitHub Pro or Team?