Every piece of MoAI work follows the three-phase lifecycle plan → run → sync. This page covers how that lifecycle flows — what goes in and comes out of each phase, what the three gates between phases protect, and how the size of the work decides its tier and route.

Info

Division of labor: SPEC-Based Development covers what a SPEC document is (the GEARS requirement format, the 3-file composition, Era classification and drift checks). This page covers how the lifecycle flows — the two pages link to each other rather than repeating each other.

Each phase is owned by a different agent. manager-spec authors the SPEC, manager-develop implements it, and manager-docs tidies the result into docs and closes it — the owner changes per phase so that no agent audits its own output.

flowchart TD
    Req["Natural-language request"] --> Plan["plan
manager-spec · SPEC authoring"]
    Plan --> PA{"Plan audit
(plan-auditor)"}
    PA -->|"PASS"| Kickoff{"Implementation Kickoff Approval
(human gate)"}
    PA -->|"FAIL"| Fix["Amend the SPEC, then re-audit"]
    Fix --> Plan
    Kickoff -->|"approved"| Run["run
manager-develop · implementation → AC convergence"]
    Kickoff -->|"declined"| Stop["Stop"]
    Run --> Sync["sync
manager-docs · docs + closure"]
    Sync --> SA{"Sync audit
(sync-auditor
4-dimension scoring)"}
    SA --> Done["completed"]

For the file composition and format of the SPEC document, see SPEC-Based Development; for run’s methodology cycle, see Development Methodology (DDD/TDD).

Three gates sit between the phases. Each protects something different.

The human gate at the plan → run boundary. It is the last human check standing between an unreviewed plan and implementation; the orchestrator requests approval through AskUserQuestion.

• Mandatory and score-independent. Even when the plan audit PASSes, even with a high score, this gate is never skipped automatically.
• Passing the gate lets you pick the autonomous vs semi-autonomous progression mode in the same place — that choice decides only what happens after approval; it never relaxes or substitutes for the gate itself.

At the start of every /moai run — before implementation begins — the plan-auditor sub-agent independently reviews the full SPEC plan artifacts. It cannot be turned off at any harness level (including minimal).

The PASS bar is the tier-specific passing score — Tier S 0.75 · Tier M 0.80 · Tier L 0.85 (tier table below). If the previous verdict was PASS, the score clears the tier bar, and the artifact hash is unchanged, re-running the audit can be skipped — but this skip covers only the audit re-run. It never passes the Implementation Kickoff Approval human gate on your behalf.

The independent review of sync quality. The sync-auditor scores it in a fresh context with no attachment to the code just written, across four dimensions — Functionality / Security / Craft / Consistency. Each dimension is scored separately and the overall verdict follows the harmonic mean of the dimension scores, so a collapsed dimension cannot be escaped by making up the average.

Every SPEC is classified into one of three tiers during the plan phase. The tier decides the artifact set and the plan-audit passing score — over-formalization that forces big ceremonies on small work is why this classification exists.

The tier also sets the budget for requirements and acceptance criteria — up to 8 for S, 16 for M, and 25 for L. The two caps apply independently to the requirement count and the acceptance-criteria count (not a combined total). Exceeding either cap is a signal to raise the tier or split the SPEC, not to grow the budget.

Which event triggers the transition between phases is decided by the route the SPEC takes. Route A — hybrid trunk (direct to main) is the default (Tier S/M): each phase commits and pushes directly to main, and the transition fires on the commit·push event plus green CI. Route B — the PR route applies to Tier L or an explicit --pr: manager-git creates a branch and opens a PR per phase, and the transition fires on the PR merge. Neither route changes the phase order (plan → run → sync) or the artifact set — only the vocabulary of the event that drives the transition differs.

The principle is to clear the session context as each phase ends:

• Right after /moai plan completes — mandatory. Do not carry the tokens spent on plan authoring into implementation. This one /clear frees 45–50K more tokens for implementation.
• When context exceeds 150K.
• Just before a major phase transition.

Even when the session is cut, the SPEC stays in its files — that is the starting point of SPEC-based development — so the next session picks the work up with a single line (/moai run SPEC-XXX). For the full procedure of cutting and resuming sessions safely, see Token Budget Management and Graceful Stop.

• SPEC-Based Development — what the SPEC document is: the GEARS format, the 3-file composition, Era classification and drift checks
• /moai plan · /moai run · /moai sync — execution detail of each phase command
• Development Methodology (DDD/TDD) — the two methodology cycles the run phase follows
• TRUST 5 Quality Framework — the quality frame run artifacts must pass
• Kanban Mode — the shape that runs this lifecycle on a multi-session board