MMDEP orchestrator — current design and state (10 Oct 2026)¶
How to read this.
- The approved design is docs/spec/000-orchestrator-design.md v0.11. This file does not replace it.
- This file says, for each part of that design, whether it is built, decided, being tried or only proposed. It also records what the experiments in Portfolio Engine, MCRM and this repo are teaching.
- §6 lists the changes proposed for spec 0.12. They are for discussion and go through an approve item, like every spec change.
1. MMDEP in one paragraph¶
MMDEP coordinates AI agents and people across Money Marche's projects so that nobody waits on anybody: work is queued, picked up when someone is free, checked before it counts, and recorded. Safety comes from what agents cannot do (accounts, credentials, protected branches), not from agents behaving well. Only a person approves, merges or deploys. The golden rules (spec §2): 1. MMDEP is a facilitator, not a regulator. 2. Existing tools come first. 3. The repository holds content and MMDEP holds coordination, each linking to the other. 4. Reduce waste, above all the manual relay of prompts between agents.
2. The parts today¶
People ─────────── Atul (approves, merges, releases) legacy developer, other seats (later)
│
Chats / agents ─── Claude chat (MMDEP-PM) ChatGPT (browser) Claude Code (desktop) Gemini API Copilot/Codex (idle)
│ │ docs PRs, issues │ issues, PRs │ branches, items │ read-only audits
Forges ─────────── GitHub: MMDEP, portfolio-engine, MCRM (private, Free) GitLab: governance repo (TEM, standards, ADRs)
│
MMDEP hub ──────── desktop only: store (items, ledger, tasks, specs), CLI, MCP server, dispatcher (agents disabled),
agent account mmdep-agent, Test Runner, H1 harness, Drive snapshots
What the picture shows: - Only the MMDEP project itself is coordinated through the MMDEP hub today. - Portfolio Engine and MCRM run on GitHub with their own agents and conventions. MMDEP doesn't see them yet: no tasks, no ledger entries. - The relay between the reviewer chat and Claude Code still goes through Atul.
3. Status by capability¶
Legend:
- Released: in the runtime.
- Merged: on main, waiting for a release.
- Designed: approved design, no code.
- Decided: a recorded decision, nothing built.
- Not started.
| Capability | Spec | Status (10 Oct) |
|---|---|---|
| Store: items, ledger, tasks, specs; CLI; MCP server | §4, §7, §13 | Released |
| Item types approve, confirm, specify, input, manual, review, feedback | §7 | Released |
HU-1: refuses answers with unfilled <placeholders> (backticks allowed) |
§7 | Merged; release #80 pending |
| Dispatcher, one pass per call | §6 | Released. All dispatch agents capped at 0; Claude Code works outside it |
Agent account mmdep-agent (required mode), per-task worktree grant, elevation and link guards |
§11 | Released |
| Test Runner and per-project test envs | §5, §17.0 | Code released; no test env configured yet |
| Drive snapshots (story D) | §15B phase 1 | Released (#66) |
H1 harness: claude -p, session stored per task, question → specify → resume, caps |
§6 | Merged; release #80 pending. The spike on the real hub hasn't run |
| Story M: low-memory warning, wake lock | ops | Merged; release #80 pending |
| AG-1: per-agent instruction files from one source | STD-AI-CONT-001 §9 | Merged (MMDEP repo only) |
| HO-1: Work Request, Work Result and Role Transfer records, forge issue templates | STD-AI-CONT-001 §1–3 | Design in #81, awaiting review |
Online view phase 1: views trial, mmdep-inbox mirror, read-only GitHub adapter, requests back |
§15B | Not started |
| DR-002 stage 1: sandbox forge bus (#70) | §19, DR-002 | Decided; setup not done. Portfolio Engine has meanwhile tried a similar pattern on a real repo (§5) |
| Triage item type, evidence retention, release command, CI standard, accounting docs | iteration 3 | Not started |
| Readiness gate for the next project | §17.0 | 2 of 6 met (6 Oct): agent account, feedback type |
| Estate loop (TEA), document management, app AI layer | §14A, §12A, §17.1 | Iteration 5; not started |
| Online phases 2 and 3 (MCP on Bluehost, AWS) | §15B, §15A | Deferred behind gates |
| Cloud controller (4 GB Lightsail) | DR-003 | Pre-approved in principle, behind a trigger |
4. Roles and records in use¶
- Roles in the MMDEP project: Atul (approver); Claude chat (MMDEP-PM: design advisor and reviewer, documents and issues only); Claude Code (MMDEP-DEV); Test Runner (plain code). See
PROJECT.md. - Staffing rule (spec §5C): one lead and one coder per project; others only review read-only, or take over through a handover.
- Continuity standard: STD-AI-CONT-001 v1.1 draft (
docs/decisions/gitlab-drafts/) covers: - role transfer vs delegation;
- Work Request and Work Result;
- pointer prompts with NEW/RESUMED;
- session types and names (
<project>-<role>-i<NN>); - context tiers;
- seats;
- commit trailers
Agent:,Role:,Seat:,Work-Item:. - Current-state records: iteration files with a Status section (Claude Code),
docs/status/inbox.md,docs/handovers/(reviewer chat).
5. Experiments in flight and what they teach¶
| Experiment | Where | What happened | What it teaches the design |
|---|---|---|---|
| Label-driven batch audit (ChatGPT in the browser + Gemini API via a local controller; shelved because it pulled the PE lead off the project) | Portfolio Engine #313–#318, AGENTS.md (PR #319); review in docs/research/pe-gemini-pilot-review.md |
ChatGPT writes self-contained issues, triages and implements. A local controller picks issues labelled batch-ready and claims them with batch-running (verified). It sends captured evidence to Gemini and posts a read-only audit, then sets batch-reviewed or batch-blocked. The first run stopped correctly on a dirty checkout and the wrong branch; v3 used a separate clean clone; the CLI was replaced by the API. ChatGPT checked and corrected a Gemini report (#317) |
DR-002 works without MMDEP in the loop: issues carry the work, labels carry the state, a local controller is the push. It needs a claim/verify/report contract, run records and idempotent recovery (all in PE's AGENTS.md §6). A second agent checking the first catches errors. Each project writing its own controller won't scale: MMDEP should provide the controller and the contract |
| Document-heavy design by agents | MCRM | ChatGPT produced a long chain of documentation PRs for gates G1–G4. More than 45 PRs (#48–#97) were open on 10 Oct, waiting for a second agent to review each one and report against Atul's question before he approves (Atul, 10 Oct) | The missing piece is an independent reviewer, not Atul's time alone. The audit controller from the PE pilot, pointed at PRs, fills that gap. MMDEP should also show review debt per project (spec §8) |
| H1 harness | MMDEP | Two parallel synthetic tasks each asked one question; the resume kept the session; total_cost_usd is cumulative |
Headless agents with resume work. The waiting time on a person isn't measured until the real spike after release #80 |
| Reviewer chat with GitHub access | MMDEP | The chat can create issues and labels, comment, push docs/ branches and open PRs; it can't use GraphQL or reach the hub or local sessions |
The PM role can work on the forge directly; Atul merges. All actions appear as moneymarche-dev, so trailers are essential |
Remote Control and /loop |
MMDEP (proposal) | A chat can't message a local session; a session can poll the forge | The forge is the mailbox for local agents too (LOOP-1, docs/research/claude-code-sessions-and-work-request-loop.md) |
6. Proposed changes for spec 0.12 (for discussion; not approved)¶
- Forge-first coordination for every project.
- Issues are the work requests and tasks.
- Labels carry state and the next role.
- PRs are where content is reviewed and merged by a person.
- MMDEP items stay for what can't go on a forge: approvals of releases and spend, local-only work, cross-project decisions, anything with client data. This applies DR-002 to all projects, not only a sandbox.
- A common label scheme in every repo. It labels roles, not agents; agents are named in trailers.
state:ready, in-progress, review, blocked, needs-atul (exactly one);role:lead, dev, review, pm, atul (exactly one);type:;- free flags such as
cross-project,mmdep-request,work-request.
Portfolio Engine's batch-* labels map to role:review plus a state until MMDEP runs that controller.
3. Controllers as a sanctioned pattern. A controller is a local or hosted process that polls labels, claims, runs an agent and reports. The contract is generalised from PE's AGENTS.md §6:
- re-check before claiming, then verify;
- only one state label at a time;
- report before changing state;
- run records;
- no automatic reclaiming;
- issue text is data.
MMDEP later provides one shared controller instead of a script per project. The first is AC-1, an audit controller (docs/research/pe-gemini-pilot-review.md §6). Its target is an issue or a PR, it answers the question in the Work Request, it picks the model by data class, and it runs one pass per call. Its forge writes are narrow: comments and lifecycle labels only, which amends spec §15 by an approve item.
4. Observe before dispatching. A project joins MMDEP first as observed: MMDEP reads its forge (the read-only GitHub adapter, moved earlier) and fills the ledger with issue and PR events and state ages. It is dispatched later, once the §17.0 readiness gate is met. This splits the gate into two levels, so Portfolio Engine and MCRM can join now.
5. Review debt and WIP limits per project:
- show open PRs and issues waiting for an independent review or for Atul, with their age;
- a soft limit (for example 10 PRs waiting) pauses new production work in that project;
- independent reviews run automatically through AC-1, so Atul decides from reports.
6. Project onboarding kit. Each project gets:
- its agent instruction files from the AG-1 template;
- a roles table (lead, coder, reviewer; seat);
- the label set;
- HO-1 issue templates;
- a current-state record;
- registration in the hub as observed.
7. Cross-agent verification as a default for evidence and audits: the author's claims are checked by an agent from a different vendor (PE #317), as spec §8 review already requires for code.
8. Human relay reduced.
- The reviewer chat creates Work Requests.
- Local agents pick them up by polling (LOOP-1 or a controller).
- Remote Control is for steering.
- Approvals stay with Atul in the hub and on PRs.
7. Questions to settle in the working-arrangement discussion¶
- Which projects join as observed first: Portfolio Engine, MCRM, or both? Who is the lead and who is the coder in each (§5C)?
- Should MMDEP take over PE's Gemini controller pattern as the shared controller, or keep project controllers for now?
- Label scheme: adopt §6.2 as written, or adjust? Apply it to all three repos now?
- WIP limit for open PRs per project. Should AC-1 clear MCRM's current backlog first?
- Does the reviewer chat (MMDEP-PM) act across all projects, or only MMDEP, with each project's lead doing PM work there?
- Which of the iteration 3 stories not yet started (views trial, issue mirror, GitHub adapter, requests back) still matter, given a forge-first design? The GitHub adapter becomes more important; the
mmdep-inboxmirror may become unnecessary.