Skip to content

ADR-006

Title

Project staffing rule: one lead agent and one coding agent per project

Status

Proposed (draft by Claude Code from Atul's decision of 2026-10-03; to be reviewed through the MMDEP merge request workflow)

Context

Several AI agents can write to the programme's repositories: Claude Code, ChatGPT with forge connectors, Codex, Copilot and others. When two agents change the same project in parallel, they conflict, duplicate work and lose context. Nobody is then accountable for the result.

The Cross-Project Knowledge Governance standard already says AI assistants must treat other repositories as context, not as permission to change them.

Decision

  1. Per project, at any one time:
  2. one lead agent: architecture, design and project management;
  3. one coding agent: the only agent that writes the project's code. It may be the same agent as the lead.
  4. A second agent joins only:
  5. for a read-only review, on request or by a risk rule; or
  6. for a full takeover: a written handover (this repo's AI Session Handoff Template), confirmed by the new owner, with the role map changed by an approved item.
  7. Every move is a handover, never parallel coding.
  8. The project owner (Atul) sets each project's priority and stage. The MMDEP orchestrator proposes reallocations; a person decides.
  9. Read access for dependencies: other agents may read a project they depend on (for example, Portfolio Engine reads api and mm-crons), never write it.
  10. Enforcement, strongest first:
  11. forge permissions where the plan allows (GitLab Reporter, GitHub organisation Read, read-only tokens);
  12. the MMDEP orchestrator's role map and dispatcher (coding tasks only to the project's coder; worktree access by role);
  13. AGENTS.md and the agent's context;
  14. detection: a commit by a non-coder agent is recorded as an external change and raises an item.

Alternatives

  • Several coding agents per project, coordinated by locks or leases. Rejected for now: more conflict and less accountability, for throughput the programme doesn't need yet.
  • Rely on instructions alone (AGENTS.md). Rejected as the only control: conventions are the second line, after permissions.

Consequences

  • Each project's role map names its lead and its coder. The Portfolio Register or the project's PROJECT.md shows them.
  • The orchestrator stops falling back to a different agent for coding tasks: a coding task parks for a person instead.
  • Changing a project's coder takes a handover record and an approved item, which costs time; that is intended.