/moai

name: moai
description: >
  MoAI unified orchestrator for autonomous development. Routes natural
  language or subcommands (plan, run, sync, project, fix, loop, mx,
  feedback, review, clean, codemaps, gate, e2e, harness, goal, gtd, todo) to
  specialized agents.
allowed-tools: Agent, AskUserQuestion, Skill, TaskCreate, TaskUpdate, TaskList, TaskGet, Bash, Read, Write, Edit, Glob, Grep
argument-hint: "[subcommand] [args] | \"natural language task\""

Pre-execution Context

!`git status --porcelain 2>/dev/null || true` !`git branch --show-current 2>/dev/null || true`

Essential Files

.moai/config/sections/*.yaml

---

Authority References

Rules and constraints governing all workflows are always loaded from these sources. Do NOT duplicate their content here:

• Core identity, orchestration principles, agent catalog: AGENTS.md + `.moai/config/sections/delegation.yaml`
• Quality gates, security boundaries: .claude/rules/moai/core/moai-constitution.md
• SPEC workflow phases, token budgets: .claude/rules/moai/workflow/spec-workflow.md
• Development methodologies (DDD/TDD): .claude/rules/moai/workflow/spec-workflow.md (Run Phase section)
• Agent definitions: See `.moai/config/sections/delegation.yaml`. For agent creation, use builder-harness subagent (artifact_type=agent).
• @MX tag rules and protocol: .claude/rules/moai/workflow/mx-tag-protocol.md

---

Routing Observation Ledger

When dispatching a subcommand or workflow, the orchestrator records the routing decision to the append-only routing-ledger (`.moai/state/routing-ledger.jsonl`) via `moai harness ledger record` at dispatch time — the request text is piped via stdin and only a privacy-preserving digest is stored, never verbatim user text. As the routed pipeline reaches gate points, machine evidence is appended via `moai harness ledger evidence` (gate exits, audit verdicts, verify-log paths). Outcome is never supplied as an input; it is finalized from machine evidence only. This observation is opt-in and fail-open — it never blocks routing. NOTE: recording depends on the orchestrator actually invoking `moai harness ledger record` at dispatch; when the observability opt-in is ON but that record call is not emitted, the ledger stays empty — an un-recorded dispatch, NOT an opt-in-off no-op. Do not read an empty routing-ledger as 'opt-in disabled'.

---

Intent Router

Raw User Input

$ARGUMENTS

Routing Instructions

[HARD] Route the Raw User Input above using the strict priority order below. Extract the FIRST WORD of the input for subcommand matching. All text after the subcommand keyword is CONTEXT to be passed to the matched workflow — it is NOT a routing signal and MUST NOT influence which workflow is selected.

Execution Mode Flags (mutually exclusive)

• `--team`: Force agent-team of the Phase 4 4-mode catalog (`.claude/rules/moai/workflow/orchestration-mode-selection.md` §A), subject to its capability gate
• `--solo`: Force serial (sub-agent — single sequential agent per phase)
• No flag: The orchestrator auto-selects from the full 4-mode catalog at Phase 4; the complexity auto-select thresholds are stated once in `orchestration-mode-selection.md` §B.1 (machine source: `workflow.yaml` `auto_selection`) and are not restated here

The `--team` / `--solo` flags are forced overrides onto the catalog; the flag-free default resolves through the catalog decision tree (§B) and its capability gates. The `--mode` dispatch axis is a separate axis — see the crosswalk in `orchestration-mode-selection.md` §G.1 (correspondence, not merge).

Priority 1: Explicit Subcommand Matching

[HARD] Extract the FIRST WORD from the Raw User Input section above. If it matches any subcommand below (or its alias), route to that workflow IMMEDIATELY. Do NOT analyze the remaining text for routing — it is context for the matched workflow:

[HARD] Mixed-language guard: FIRST-WORD subcommand matching applies only when (a) the input is pure ASCII/Latin, OR (b) the message is prefixed with a literal `/moai ` slash form. When the message contains non-Latin script (Korean/Japanese/Chinese/etc.) beyond the first token, do NOT route immediately on the leading English word — treat it as a possible embedded loanword and fall through to Priority 3 semantic classification of the ENTIRE message. Rationale: CJK technical writing embeds English loanwords such as 'goal', 'run', 'fix', 'plan' at sentence start; immediate first-word routing misfires on them.

• **plan** (aliases: spec): SPEC document creation workflow
• **run** (aliases: impl): DDD/TDD implementation workflow (per quality.yaml constitution.development_mode)
• **sync** (aliases: docs, pr): Documentation synchronization and PR creation
• **project** (aliases: init): Project documentation generation
• **feedback** (aliases: fb): GitHub issue creation
• **fix**: Auto-fix errors in a single pass
• **loop**: Iterative auto-fix until completion conditions are satisfied
• **mx**: MX tag scan and annotation for codebase
• **review** (aliases: code-review): Code review with security and MX tag compliance
• **clean** (aliases: dead-code): Identify and safely remove dead code
• **codemaps**: Generate architecture documentation in `.moai/project/codemaps/`
• **gate** (aliases: check, pre-commit): Lightweight pre-commit quality gate (lint+format+type-check+test)
• **e2e** (aliases: e2e-test, end-to-end): Multi-platform end-to-end testing (web/mobile/desktop) with project-type auto-detection and CLI-first toolchain selection
• **harness** (aliases: hrn): harness lifecycle management — learning-lifecycle verbs (status / apply / rollback <date> / disable) + v4-lifecycle verbs (list / edit / remove / doctor), all dispatching through the unified `moai harness` Go-binary Cobra subcommand tree; the slash command is the documented user-facing entry point
• **goal**: Two compatible modes — a condition goal (`/moai goal "<condition>"`) or an approved auto mission (`/moai goal --auto "<mission>"