Agent Guide

A detailed guide to the catalog of 12 core agents in MoAI-ADK v3.0.

Info

One-line summary: Agents are a team of specialists, one for each field. MoAI, as team leader, distributes work to the right specialist — and the agent that authors a plan is always separated from the agent that audits it.

Platform basics

Background on the platform layer is in Subagents. This page is the MoAI-ADK account of it.

An agent is an AI task performer specialized in a particular field.

Built on Claude Code’s Sub-agent system, each agent has an independent context window, a custom system prompt, specific tool access, and independent permissions.

In a company analogy, MoAI is the CEO, Manager agents are department heads, Evaluator agents are quality inspectors, the Builder agent is the new-team creation officer, and the Advisor agent is an external consultant.

The agent count was refined over the v3 period from 22 → 17 → 8 → 10 → 11. More agents is not better — every delegation carries a context cost, so shrinking the catalog is itself part of tokenomics.

MoAI is the top-level coordinator of MoAI-ADK. It analyzes user requests and delegates work to the appropriate agents.

MoAI-ADK uses 12 core agents (11 MoAI custom + 1 Anthropic built-in).

The key point is that planning and auditing are separated — the one who built it does not inspect their own work. Audit agents approach with a skeptical (fresh-judgment) stance — doubting every claim until evidence appears, and accepting only reproducible results rather than “it seems to pass.” Scores are computed as the harmonic mean rather than the simple average, so if one dimension collapses, the overall score falls with it. This design upholds the reliability of the TRUST 5 quality framework.

Info

4-tier token-cost tiers ( max · high · medium · low): model: inherit inherits the parent session model, and effort determines the reasoning-token budget.

The values above are the shipped frontmatter, which is pinned to the medium column of the profile matrix so a fresh deployment matches the default profile. Switching the profile rewrites these values — under high, manager-develop and super-advisor move to max (the only two cells that use it), and under low the agentic rows drop to low while manager-docs and e2e-tester fall back to Sonnet. Inspect the resolved values for the active profile with moai model profile.

Rather than keeping one agent per domain, a single manager-develop is invoked with domain-specific context injected.

• Backend work: manager-develop + backend domain context + the moai-domain-backend skill
• Frontend work: manager-develop + frontend domain context + the moai-domain-frontend skill
• Other domains: per-language skills + expertise prompts

The process by which MoAI analyzes a user request and selects the appropriate agent.

flowchart TD
    START[User request] --> Q1{Read-only
code exploration?}

    Q1 -->|Yes| EXPLORE["Explore sub-agent
Understand code structure"]
    Q1 -->|No| Q2{External docs/API
research needed?}

    Q2 -->|Yes| WEB["WebSearch / WebFetch"]
    Q2 -->|No| Q3{Workflow
coordination needed?}

    Q3 -->|Yes| MANAGER["Manager-* agents
Process management"]
    Q3 -->|No| Q4{Quality verification
needed?}

    Q4 -->|Yes| EVAL["plan-auditor or
sync-auditor"]
    Q4 -->|No| Q5{High-reasoning
consultation needed?}

    Q5 -->|Yes| ADVISOR["super-advisor
E1-E4 escalation"]
    Q5 -->|No| DIRECT["MoAI handles directly
Simple tasks"]

manager-lead is a dedicated agent for coordinating Tier L run phases. It writes no code itself. Instead, it splits the work into milestones, hands each one to a leaf worker, then folds context and runs cross-verification at every milestone boundary. Leaf workers are created on demand via Agent(general-purpose) and run on worktree-isolated branches so their write surfaces never overlap.

This delegation path is a variant of serial (sequential sub-agents), not a new execution mode. It is also unrelated to the Agent Teams layer — now an experimental explicit-request surface; the MODE_TEAM_UNAVAILABLE sentinel remains documented history.

The orchestrator spawns manager-lead only when all three conditions below hold. If any one falls short, the orchestrator processes the milestones sequentially itself in serial. Attaching manager-lead to work that does not meet the bar only adds coordination cost that is never recovered.

The three conditions are AND, not OR. The thresholds are deliberately narrow so that work touching only one axis — a single-milestone 10-file refactor, for instance — is not pulled in. The orchestrator records its finding that all three conditions are satisfied in progress.md § Mode Selection before spawning.

flowchart TD
    START["Run-phase delegation request"] --> Q1{"3 or more milestones?"}
    Q1 -->|"No"| MODE5["Orchestrator handles serial directly
manager-develop sequentially"]
    Q1 -->|"Yes"| Q2{"10 or more write-target files?"}
    Q2 -->|"No"| MODE5
    Q2 -->|"Yes"| Q3{"3 or more domains?"}
    Q3 -->|"No"| MODE5
    Q3 -->|"Yes"| LEAD["Spawn manager-lead
Coordinate leaf-worker fan-out"]

manager-lead is the only catalog agent that carries Agent in its tools: list. Every other agent omits Agent, which is how the flat hierarchy is maintained — and this is the single place where that exception is opened, one layer deep. So orchestrator → manager-lead is depth 1, manager-lead → leaf worker is depth 2, and no depth 3 is ever created.

Leaf workers receive their tools: list at spawn time, and Agent is always excluded from it. Should leaf workers later be defined as files, declaring themselves via the frontmatter field leaf_of: manager-lead or the body marker <!-- manager-lead leaf-worker --> makes the CI guard in internal/template/manager_lead_depth_test.go check that file’s tools: for Agent and fail the build if it is present.

Warning

This seal is a MoAI policy invariant, not a runtime invariant. The Claude Code runtime itself permits deeper recursion — nested spawning is enabled by default as of v2.1.219, with a default depth ceiling of 3. Since the runtime will not stop it, the only two things actually holding the depth are the practice of omitting Agent from tools: and the CI guard above.

flowchart TD
    ORCH["Orchestrator"] -->|"depth 1"| LEAD["manager-lead
Agent in tools (only one)"]
    LEAD -->|"depth 2"| W1["Leaf worker A
no Agent in tools"]
    LEAD -->|"depth 2"| W2["Leaf worker B
no Agent in tools"]
    W1 -.->|"blocked"| X["depth 3 recursion"]
    W2 -.->|"blocked"| X
    GUARD["manager_lead_depth_test.go
CI guard"] -.->|"caught by build failure"| X

Once every AC row for milestone Mn is PASS and the cross-verification of those rows also comes back PASS, manager-lead takes three steps before moving to the next milestone. The procedure composes only existing tooling — it introduces no new Go code, no new hooks, and no new CLI subcommands.

1. Persist evidence — redirect each AC’s verification command output to .moai/state/verify/<session>/M<n>.<AC-id>.{log,out}. /tmp is not used because the OS clears it. The cited evidence is valid only if that path actually opens at audit time. An AC whose evidence could not be captured is marked GAP, not PASS.
2. Append a fold row — add one line to progress.md §E.2 in the existing row format: M<n>: <AC-id-1>=PASS, ... | evidence: .moai/state/verify/<session>/M<n>.* | fold-at: <ISO-8601>. The M<n>: prefix was chosen so it does not collide with the §E heading matcher in internal/spec/era.go, letting the two coexist without touching the matcher.
3. Run /compact — compact with explicit retain instructions: retain-current-milestone (the milestone just finished and its fold row), retain-fold-rows (every earlier fold row in §E.2), and retain-armed-goal (the condition armed via /moai goal, if any).

Two invariants hold after the fold: post-compaction token usage must be lower than it was before compaction, and it must simultaneously sit below the model-specific handoff threshold (50% for the 1M class, 90% for the 200K/256K class). If it did not drop, treat the fold as failed and re-plan. When /compact is unavailable in a sub-agent context, return a blocker report so the orchestrator can compact on its behalf or route around it via /clear plus a resume message.

flowchart TD
    MN["Milestone Mn complete
all ACs PASS + cross-verification PASS"] --> S1["Step 1: Persist evidence
.moai/state/verify/session/"]
    S1 --> S2["Step 2: Append fold row
progress.md §E.2"]
    S2 --> S3["Step 3: Run /compact
3 retain instructions"]
    S3 --> CHECK{"Usage dropped and
below threshold?"}
    CHECK -->|"Yes"| NEXT["Enter milestone M(n+1)"]
    CHECK -->|"No"| REPLAN["Treat as failed fold
re-plan"]

When a leaf worker marks an AC as PASS, manager-lead spawns a second read-only Agent(general-purpose) that did not do that work. Read-only is enforced by omitting Write/Edit/NotebookEdit from its tools:. That worker re-runs the Given-When-Then commands from acceptance.md §D verbatim and returns one of PASS / PARTIAL / FAIL.

The second worker has no stake in the author’s claim. That is what exposes self-report failures such as miscounting a grep result, citing a stale baseline, or skipping one verification command.

On FAIL or PARTIAL, manager-lead does not advance to the next milestone. It returns a blocker report to the orchestrator carrying the AC ID, the evidence the author offered, the cross-verifying worker’s evidence, and the point where the two diverged. Asking the user is the orchestrator’s job — sub-agents do not use the user channel. Tier S skips cross-verification (the scope is small enough that verification costs more than it returns).

The role differs from sync-auditor in the sync phase. sync-auditor is a final skeptical read that scores four dimensions after implementation is done; peer cross-verification is a binary verdict attached to each individual AC during implementation. Neither substitutes for the other.

flowchart TD
    AUTHOR["Leaf worker reports AC-X as PASS"] --> TIER{"Tier S?"}
    TIER -->|"Yes"| SKIP["Skip cross-verification"]
    TIER -->|"No"| PEER["Spawn read-only second worker
no Write/Edit tools"]
    PEER --> RERUN["Re-run acceptance.md §D GWT commands"]
    RERUN --> VERDICT{"Verdict"}
    VERDICT -->|"PASS"| NEXT["Fold, then next milestone"]
    VERDICT -->|"PARTIAL or FAIL"| BLOCK["Return blocker report
halt milestone progression"]
    BLOCK --> ORCH["Orchestrator queries the user"]

The 10 MoAI custom agents are defined as markdown files in the .claude/agents/moai/ directory.

.claude/agents/moai/
├── manager-spec.md
├── manager-develop.md
├── manager-docs.md
├── manager-git.md
├── manager-design.md
├── plan-auditor.md
├── sync-auditor.md
├── builder-harness.md
├── super-advisor.md
├── e2e-tester.md
└── (Explore: Anthropic built-in, no file)

---
name: my-specialist
description: >
  A specialist for this project. Describe the specific domain expertise.
tools: Read, Write, Edit, Grep, Glob, Bash
model: inherit
---

You are this project's [domain] specialist.

## Role

- Responsibility 1
- Responsibility 2
- Responsibility 3

## Skills Used

- moai-domain-[domain]
- Language-specific skills

The most fundamental collaboration flow. An independent audit is inserted between each phase.

# 1. manager-spec creates the SPEC
/moai plan "feature description"

# 2. plan-auditor validates SPEC quality
# (runs automatically)

# 3. manager-develop implements with DDD/TDD
/moai run SPEC-XXX

# 4. sync-auditor scores quality across 4 dimensions
# (runs automatically)

# 5. manager-docs synchronizes documentation
/moai sync SPEC-XXX

Claude Code’s official Sub-agent system is the foundation of the MoAI-ADK agent architecture.

Which tools a sub-agent can use is not decided by a single setting but by a two-stage filter: a static allowlist applied at spawn time is stage 1, and runtime deferred loading is stage 2.

Stage 1 — the spawn-time static filter. Every agent definition carries a tools: allowlist in its frontmatter (a CSV string, e.g. tools: Read, Write, Edit), and tools outside the list cannot be invoked. Read-only roles earn their restriction by shrinking this very list — auditors and cross-verification workers drop the write tools (Write, Edit) from the list, cutting off the very path by which they could accidentally modify a file.

Stage 2 — runtime deferred loading. Some tools do not have their schema loaded at spawn time. AskUserQuestion (the tool that presents options to the user) and the Task* family (task-list management) are like this. These deferred tools can be invoked only after their schema is explicitly loaded at the moment of need via a ToolSearch select: query, which makes this a second gate that narrows the field once more even among the tools that passed stage 1.

Two rules emerge from these two stages combined:

The rule from the previous section — that sub-agents cannot interact with the user directly — is upheld at runtime by exactly this two-stage filter.

The Agent Teams static orchestration layer from earlier versions (the workflow.team.* settings and the --team force flag) was retired in v3.0.0, then re-allowed later as an experimental explicit-request surface (selectable only via an explicit --team request; never auto-selected).

• Historical: during the retirement era, forcing --team announced MODE_TEAM_UNAVAILABLE and fell back to sub-agent mode; the sentinel string survives as documented history.
• Research and review work that needs parallelism is handled with parallel sub-agent fan-out; sequential coding work is handled with a sub-agent chain.
• The native Claude Code teammate runtime (the GLM panes of moai cg, moai worktree --team) continues to operate independently of this — from a tokenomics standpoint, CG mode’s Claude-leader + GLM-worker division of labor takes over this role.

• Builder Agents and Harness v4 - dynamic agent team creation
• Skill Guide - the skill system agents draw on
• SPEC-Based Development - SPEC workflow details

Info

Tip: You do not need to specify agents directly. Ask MoAI in natural language and Analyze-First routing will analyze your intent and automatically select the optimal agent.