Skip to content

Maia builds Maia

Status: planned (SH0–SH3, owner direction 22 October 2026). The roadmap owns order and entry conditions.

Maia's own development is its first production deployment. Agents build the roadmap in parallel through Maia, people decide and confirm, and every friction found becomes a task with evidence. It runs the same path production setups take (production migration), one step earlier and on this repository, so their cutover meets problems already fixed.

The ladder

  • SH0, now, on shipped source candidates, with no pending decision.
    • A coordinator (Claude Code or Codex through maia mcp, S1 and S4c) plans units as a run ledger graph (S19), using a versioned maia-roadmap Skill in .maia that reads the lanes and critical path.
    • Codex and Claude Code worker Sessions (S3, S5, S6) each edit one unit in their own worktree, with the worker Skill (S22) and leased ports (S16). This repository is a Maia Project without a setup command: a Node refuses Project setup commands today, and worker sandboxes lack the repository's toolchain (D-075).
      • Workers hold no GitHub credential. The coordinator, acting for the person, never checks out or runs worker-authored code on the host: it pushes each archived branch by ref, from a trusted checkout with Git hooks off, to a fork of this repository and opens the pull request from there. GitHub runs a fork's pull request with a read-only token and no secrets whatever its workflow files say, given the repository settings that keep write tokens and secrets from fork pull requests (the owner's settings, D-124). A branch that changes .github/ is published only after a person reviews it. A person reviews and merges.
    • Workers run the gates themselves once S47b's sandbox image carries the toolchain, or once S47b runs Project setup commands inside the sandbox (D-174).
  • SH1, Maia runs its own roadmap (after S49, S50, S53, S65 and R8a). Maia's own Agents and Routines take over planning, building and review: the loop below, with the planner on a schedule and on demand (S50). Until S61a, pushes and pull requests still go through SH0's coordinator path, and reviewers read session diff; the coordinator stays the fallback.
  • SH2, this repository as the first production deployment (after S61a, S47b, S57a and S74). GitHub through S61a with this repository's App, so agents stop using a person's tools; S47b containment; S57a's required gateway; S74 alerts on the Maia Workspace. Merging follows the owner's Workspace configuration (D-116). Production setups run their read-only shadow without waiting for SH2, and their cutover no longer waits for it (D-150).
  • SH3, continuous delivery to itself (after RL6). The dogfood Node takes each canary that passes its gates and updates itself without losing a run.

The loop

From SH1, one Workspace for this repository holds the loop:

  1. Plan. A planner Routine, on a schedule and on demand (after each merge once S51 ships), reads the lanes, the critical path and the open tasks. It creates one task per ready unit of work, where every dependency is done and no listed decision is pending, and assigns its lane's builder Agent within the lane's cap.

  2. Build. A builder Agent works in its own worktree under the rules below, runs the gates, and opens a pull request with its evidence.

  3. Review. A review Routine runs two reviewers on different models, one for correctness and security, one for contracts and simplicity. Findings return to the builder; a pull request still failing after three rounds goes to the attention inbox (R8).

  4. Merge. A person merges, except where this Workspace's policy grants the merge tool to exact Agents for exact paths (D-116, D-124). Maia hardcodes no protected path. The owner's suggested starting policy for this repository keeps these merged only by a person:

    • authentication, authorization, confirmation, containment and credentials;
    • the protocol's risk and exposure policy, and release signing;
    • the gates themselves: .github/ with the code-owners file, scripts/quality and scripts/metrics, every AGENTS.md, and the .maia Agents, Routines, Skills, rules and grants that run this loop.

    Under that policy a Metrics-Accepted trailer, which waives a measured regression, also needs a person. A code-owners file, if the owner turns one on, binds from SH2, when pull requests come from this repository's GitHub App rather than a person's account.

  5. Release. Every merge reaches the next canary once RL1 ships.

  6. Measure and improve. From SH2, S74 watches the Workspace. A weekly optimizer Routine reads the measures below and proposes changes to caps, Skills, models and schedules as previews.

People do four things: make the decisions in the decision table, confirm consequential operations, merge what no grant covers, and sign off qualification.

Working in parallel

  • Unit of work. One operation end to end per pull request: protocol entry, SDK method, Node handler, CLI command, contract test and docs. Aim for under about 600 changed lines, generated files excluded. A slice is split into such units before work starts; its acceptance closes it.

  • Lanes. A lane runs at most one unit per feature folder at once, and the critical-path lanes get capacity first. A unit touches its own feature folders (source organization) and the shared files below.

  • Shared files. Before PD0, nearly every operation edits the same files (PD0 lists them):

    • the method list and exposure map, the contract unions, the feature registry's pinned counts, and the protocol and SDK export barrels with their public-export snapshot;

    • the CLI grammar digest and the CLI bundle test, which pins exact bytes and a hash;

      • the receipt list and reviewed coordinator tool counts, and the Desktop method allowlist;

    • the single lint baseline.

      PD0 moves each to the per-feature registry, derived checks or a budget. After it:

    • A unit rebases and regenerates derived files, never merging them by hand.

    • Lint baselines only shrink. A conflict is resolved by pruning the baseline again on the rebased branch.

    • The roadmap and decision log: a unit edits only its own slice's lines. A status change lands with the code that earns it.

    • A file-moving source-organization phase runs one package at a time and is announced, so no other unit edits that package while it runs.

  • Gates. Each unit runs pnpm check:changed locally and its scoped CI jobs from the shared build cache. A merge queue, if the owner turns one on, reruns the gates on the combined change, so two green pull requests cannot break the main branch together.

  • Capacity. A developer machine runs eight worktrees at once (qualified for the production migration); Execution Nodes add more (S14). The S65 governor keeps each Connection under its quota, and the review step, not machines, sets the pace.

Measures

Recorded per day and per lane, from the run ledger, then T1–T3, S56 and S61a's merge feed:

  • units merged, and time from ready to merged
  • runs per merge, and review rounds per pull request
  • failures by typed cause, and rebases forced by shared files
  • reverts within seven days of a merge

SH0's first week sets the baseline. Each later step must keep or improve it.

Acceptance

  • PD0: two units that each add an operation, opened from the same base, merge one after the other with no hand-resolved conflict.
  • SH0: a batch of at least eight units runs from one run ledger graph through parallel worker Sessions to merged pull requests, with no worker code run on the host; a hostile unit that reads the environment, home directory and Node files finds no credential and no dogfood state in CI, and one that edits a workflow to ask for write permissions or secrets waits for a person before publication and still runs with a read-only token.
  • SH1: a ready unit becomes a task without a person, and a pull request failing review three times reaches the attention inbox once.
  • SH2: no worker launch carries a person's GitHub credentials, and the FR cutover gates other than update survival (SH3's) hold on this repository for seven consecutive days.
  • SH3: a canary update while units run loses no run.
  • At every step, merges follow this Workspace's policy: a change it protects is merged only by a person.

Imported from Maia OS docs at 3dc3e07