moai

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: CLAUDE.md
• 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 CLAUDE.md Section 4. 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 Mode 3 (agent-team) of the Phase 4 6-mode catalog (.claude/rules/moai/workflow/orchestration-mode-selection.md §A), subject to its capability gate
• --solo: Force Mode 5 (sub-agent — single sequential agent per phase)
• No flag: The orchestrator auto-selects from the full 6-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: Condition-declared universal agentic loop — arm a completion condition (/moai goal "<condition>"), check status, clear, or resume; evaluated each turn-end by the stop-goal Stop hook
• todo (aliases: backlog): Backlog queue — add an item (/moai todo "<description>"), list the queue, pick the next card (next), or remove one (done <n>); the operator's entry point into the kanban board

Priority 2: SPEC-ID Detection

Only if Priority 1 did not match: Check if the Raw User Input contains a pattern matching SPEC-XXX (such as SPEC-AUTH-001). If found, route to the run workflow automatically. The SPEC-ID becomes the target for DDD/TDD implementation.

Priority 3: Natural Language Classification

Only if BOTH Priority 1 AND Priority 2 did not match: Classify the intent of the ENTIRE Raw User Input as natural language. This priority is NEVER reached when the first word matches a known subcommand.

[HARD] The cue words listed below are English exemplars, NOT literal-match requirements. Classify intent semantically for any conversation_language — a Korean, Japanese, Chinese, or other-language request expressing the same intent routes identically. Do not require the literal English tokens to appear.

• Planning and design language (design, architect, plan, spec, requirements, feature request) routes to plan
• Quality gate language (format, check, pre-commit, quality gate) routes to gate
• E2E and user-journey testing language (e2e, end-to-end test, browser test, mobile app test, desktop app test, user journey) routes to e2e — semantic exemplars; any conversation_language expressing e2e-testing intent routes identically
• Security language (security, audit, owasp, vulnerability, injection, xss, csrf) routes to review (with --security scope)
• Code-review language (review my code, code review, check my PR, look at my changes, take a look at my changes) routes to review
• Error and fix language (fix, error, bug, broken, failing, lint) routes to fix
• Iterative and repeat language (keep fixing, until done, repeat, iterate, all errors) routes to loop
• Dead-code and cleanup language (dead code, unused code, safely remove, cleanup, orphaned code) routes to clean
• Documentation language (document, sync, docs, readme, changelog, PR) routes to sync or project
• Architecture-map language (architecture map, code maps, dependency graph, structure documentation) routes to codemaps
• Feedback and bug report language (report, feedback, suggestion, issue) routes to feedback
• MX tag language (mx tag, annotation, code context, legacy annotate) routes to mx
• Backlog language (add to the backlog, note this for later, what should I work on next, remind me to) routes to todo — semantic exemplars; a request in any conversation_language expressing "queue this, do not start it now" routes identically
• Implementation language (implement, build, create, add, develop) with clear scope routes to moai (default autonomous)

Priority 4: Default Behavior

If the intent remains ambiguous after all priority checks, use AskUserQuestion to present the top 2-3 matching workflows and let the user choose.

If the intent is clearly a development task with no specific routing signal, default to the moai workflow (plan -> run -> sync pipeline) for full autonomous execution.

Workflow Quick Reference

plan - SPEC Document Creation

Purpose: Create comprehensive specification documents using GEARS format with Research-Plan-Annotate cycle. Phases: Deep Research (research.md) -> SPEC Planning -> Annotation Cycle (1-6 iterations) -> SPEC Creation -> Independent Review (plan-auditor) Agents: manager-spec (primary), Explore (research), plan-auditor (quality gate), manager-git (conditional) Skills: moai-workflow-spec, moai-foundation-thinking (per delegation.yaml) Flags: --branch, --resume SPEC-XXX, --issue (opt-in; default skips GitHub Issue creation per the late-branch opt-in policy) For detailed orchestration: Read ${CLAUDE_SKILL_DIR}/workflows/plan.md

run - DDD/TDD Implementation

Purpose: Implement SPEC requirements through configured development methodology. Agents: manager-develop (cycle_type=ddd|tdd per quality.yaml, primary), manager-git Skills: moai-workflow-tdd, moai-workflow-ddd (per delegation.yaml; cycle_type-selected) + domain moai-ref-* injected per mission Flags: --resume SPEC-XXX, --team (RETIRED — see Execution Mode Flags) For detailed orchestration: Read ${CLAUDE_SKILL_DIR}/workflows/run.md

sync - Documentation Sync and PR

Purpose: Synchronize documentation with code changes

Content truncated.