MoAI super agent - unified orchestrator for autonomous development. Routes natural language or explicit subcommands (plan, run, sync, fix, loop, project, feedback) to specialized agents. Use for any development task from planning to deployment.
npxskills add modu-ai/moai-rank--skill moaiLoading…
!git status --porcelain 2>/dev/null || true
!git branch --show-current 2>/dev/null || true
@.moai/config/config.yaml
MoAI is the Strategic Orchestrator for Claude Code. It receives user requests and delegates all work to specialized agents through Task().
Fundamental Principles:
Parse $ARGUMENTS to determine which workflow to execute.
--team: Force Agent Teams mode for parallel execution--soloWhen no flag is provided, the system evaluates task complexity and automatically selects between team mode (for complex, multi-domain tasks) and sub-agent mode (for focused, single-domain tasks).
Match the first word of $ARGUMENTS against known subcommands:
If $ARGUMENTS contains a pattern matching SPEC-XXX (such as SPEC-AUTH-001), route to the run workflow automatically. The SPEC-ID becomes the target for DDD implementation.
When no explicit subcommand or SPEC-ID is detected, classify the intent:
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.
Purpose: Create comprehensive specification documents using EARS format. Agents: manager-spec (primary), Explore (optional codebase analysis), manager-git (conditional branch/worktree) Phases: Explore codebase, analyze requirements, create SPEC candidates, user approval, generate spec.md/plan.md/acceptance.md, optional branch or worktree creation. Flags: --worktree (isolated environment), --branch (feature branch), --resume SPEC-XXX, --team (parallel exploration) For detailed orchestration: Read workflows/plan.md
Purpose: Implement SPEC requirements through Domain-Driven Development methodology. Agents: manager-strategy (planning), manager-ddd (ANALYZE-PRESERVE-IMPROVE), manager-quality (TRUST 5 validation), manager-git (commits) Phases: SPEC analysis and execution plan, task decomposition, DDD implementation cycle, quality validation, git operations, completion guidance. Flags: --resume SPEC-XXX, --team (parallel implementation) For detailed orchestration: Read workflows/run.md
Purpose: Synchronize documentation with code changes and prepare pull requests. Agents: manager-docs (primary), manager-quality (verification), manager-git (PR creation) Phases: Phase 0.5 quality verification, documentation generation, README/CHANGELOG update, PR creation. Modes: auto (default), force, status, project. Flag: --merge (auto-merge PR) For detailed orchestration: Read workflows/sync.md
Purpose: Autonomously detect and fix LSP errors, linting issues, and type errors. Agents: expert-debug (diagnosis), expert-backend/expert-frontend (fixes) Phases: Parallel scan (LSP + AST-grep + linters), auto classification (Level 1-4), auto fix (Level 1-2), verification. Flags: --dry (preview only), --sequential, --level N (fix depth), --resume, --team (competing hypothesis) For detailed orchestration: Read workflows/fix.md
Purpose: Repeatedly fix issues until completion marker detected or max iterations reached. Agents: expert-debug, expert-backend, expert-frontend, expert-testing Phases: Parallel diagnostics, TODO generation, autonomous fixing, iterative verification, completion detection. Flags: --max N (iteration limit, default 100), --auto-fix, --seq For detailed orchestration: Read workflows/loop.md
Purpose: Full autonomous plan -> run -> sync pipeline. Default when no subcommand matches. Agents: Explore, manager-spec, manager-ddd, manager-quality, manager-docs, manager-git Phases: Parallel exploration, SPEC generation (user approval), DDD implementation with optional auto-fix loop, documentation sync, completion marker. Flags: --loop (iterative fixing), --max N, --branch, --pr, --resume SPEC-XXX, --team (force team mode), --solo (force sub-agent mode)
Note: When no execution mode flag is provided, the system automatically selects based on complexity:
For detailed orchestration: Read workflows/moai.md
Purpose: Generate project documentation by analyzing the existing codebase. Agents: Explore (codebase analysis), manager-docs (documentation generation), expert-devops (optional LSP setup) Output: product.md, structure.md, tech.md in .moai/project/ For detailed orchestration: Read workflows/project.md
Purpose: Collect user feedback, bug reports, or feature suggestions and create GitHub issues. Agents: manager-quality (feedback collection and issue creation) Phases: Analyze feedback type, collect details, create GitHub issue. For detailed orchestration: Read workflows/feedback.md
These rules apply to ALL workflows and must never be violated.
[HARD] ALL implementation MUST be delegated to specialized agents via Task().
MoAI NEVER implements directly. Agent selection follows these mappings:
[HARD] AskUserQuestion is used ONLY at the MoAI orchestrator level.
Subagents invoked via Task() operate in isolated, stateless contexts and cannot interact with users directly. The correct pattern is:
Constraints for AskUserQuestion:
[HARD] Track all discovered issues and work items using task management tools.
AI must add a marker when work is complete:
<moai>DONE</moai> signals task completion<moai>COMPLETE</moai> signals full workflow completionThese markers enable automation detection of workflow state.
[HARD] All user-facing responses MUST be in the user's conversation_language (from .moai/config/sections/language.yaml).
Team agents for Agent Teams mode (--team flag, requires CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1):
| Agent | Model | Phase | Purpose |
|---|---|---|---|
| team-researcher | haiku | plan | Read-only codebase exploration |
| team-analyst | sonnet | plan | Requirements and domain analysis |
| team-architect | sonnet | plan | System design and architecture |
| team-designer | sonnet | run | UI/UX design with Pencil/Figma MCP |
| team-backend-dev | sonnet | run | Server-side implementation |
| team-frontend-dev | sonnet | run | Client-side implementation |
| team-tester | sonnet | run | Test creation (exclusive test ownership) |
| team-quality | sonnet | run | TRUST 5 validation (read-only) |
When multiple operations are independent, invoke them in a single response. Claude Code automatically runs multiple Task() calls in parallel (up to 10 concurrent). Use this during exploration phases to launch codebase analysis, documentation research, and quality assessment simultaneously.
When operations have dependencies, chain them sequentially. Each Task() call receives context from the previous phase results. Use this for DDD workflows where Phase 1 (planning) feeds Phase 2 (implementation) which feeds Phase 2.5 (quality validation).
When a workflow is interrupted or needs to continue, use the --resume flag with a SPEC-ID. The workflow reads existing SPEC documents and resumes from the last completed phase checkpoint.
Each phase must pass its results forward to the next phase. Include previous phase outputs in the Task() prompt so the receiving agent has full context without re-analyzing. This ensures semantic continuity across planning, implementation, quality validation, and git operations.
For detailed workflow orchestration steps, read the corresponding workflow file:
For SPEC workflow overview: See .claude/rules/moai/workflow/spec-workflow.md For quality standards: See .claude/rules/moai/core/moai-constitution.md
When this skill is activated, execute the following steps in order:
Step 1 - Parse Arguments: Extract subcommand keywords and flags from $ARGUMENTS. Recognized global flags: --resume [ID], --seq, --ultrathink, --team, --solo. Workflow-specific flags: --loop, --max N, --worktree, --branch, --pr, --merge, --dry, --level N, --auto-fix, --security. When --ultrathink is detected, activate Sequential Thinking MCP (mcp__sequential-thinking__sequentialthinking) for deep analysis before execution.
Step 2 - Route to Workflow: Apply the Intent Router (Priority 1 through Priority 4) to determine the target workflow. If ambiguous, use AskUserQuestion to clarify with the user.
Step 2.5 - Project Documentation Check:
Before executing plan, run, sync, fix, loop, or default workflows, verify project documentation exists by checking for .moai/project/product.md. If product.md does NOT exist, use AskUserQuestion to ask the user (in their conversation_language):
Question: Project documentation not found. Would you like to create it first? Options:
This check does NOT apply to: project, feedback subcommands (project creates the docs, feedback is independent).
When the user selects "Create project documentation", execute the full project workflow (Phase 0 through Phase 4) to collect requirements and generate product.md, structure.md, and tech.md. After completion, resume the originally requested workflow.
[HARD] Beginner-Friendly Option Design: All AskUserQuestion calls throughout MoAI workflows MUST follow these rules:
Step 3 - Load Workflow Details: Read the corresponding workflows/<name>.md file for detailed orchestration instructions specific to the matched workflow.
Step 4 - Read Configuration: Load relevant configuration from .moai/config/config.yaml and section files as needed by the workflow.
Step 5 - Initialize Task Tracking: Use TaskCreate to register discovered work items with pending status.
Step 6 - Execute Workflow Phases: Follow the workflow-specific phase instructions from the loaded workflow file. Delegate all implementation to appropriate agents via Task(). Collect user approvals at designated checkpoints via AskUserQuestion.
Step 7 - Track Progress: Update task status using TaskUpdate as work progresses (pending to in_progress to completed).
Step 8 - Present Results: Display results to the user in their conversation_language using Markdown format. Include summary statistics, artifacts created, and next step options.
Step 9 - Add Completion Marker:
When all workflow phases complete successfully, add the appropriate completion marker (<moai>DONE</moai> or <moai>COMPLETE</moai>).
Step 10 - Guide Next Steps: Use AskUserQuestion to present the user with logical next actions based on the completed workflow.
Version: 2.0.0 Last Updated: 2026-02-07
Create or update AgentSkills. Use when designing, structuring, or packaging skills with scripts, references, and assets.
Create or update AgentSkills. Use when designing, structuring, or packaging skills with scripts, references, and assets.
Set up and use 1Password CLI (op). Use when installing the CLI, enabling desktop app integration, signing in (single or multi-account), or reading/injecting/running secrets via op.
CLI to manage emails via IMAP/SMTP. Use `himalaya` to list, read, write, reply, forward, search, and organize emails from the terminal. Supports multiple accounts and message composition with MML (MIME Meta Language).
Create or update AgentSkills. Use when designing, structuring, or packaging skills with scripts, references, and assets.
Create or update AgentSkills. Use when designing, structuring, or packaging skills with scripts, references, and assets.
Set up and use 1Password CLI (op). Use when installing the CLI, enabling desktop app integration, signing in (single or multi-account), or reading/injecting/running secrets via op.
CLI to manage emails via IMAP/SMTP. Use `himalaya` to list, read, write, reply, forward, search, and organize emails from the terminal. Supports multiple accounts and message composition with MML (MIME Meta Language).