// 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.
UI/UX design systems specialist covering accessibility, icons, theming, design tokens, and user experience patterns. Use when user asks about design systems, WCAG accessibility compliance, ARIA patterns, icon libraries, dark mode theming, design tokens, or user experience research. Do NOT use for React component coding or frontend implementation (use moai-domain-frontend instead) or shadcn/ui specifics (use moai-library-shadcn instead).
Canonical Claude Code authoring kit covering Skills, sub-agents, plugins, slash commands, hooks, memory, settings, sandboxing, headless mode, and advanced agent patterns. Use when creating Claude Code extensions or configuring Claude Code features.
Provides MoAI-ADK foundational principles including TRUST 5 quality framework, SPEC-First DDD methodology, delegation patterns, progressive disclosure, and agent catalog reference. Use when referencing TRUST 5 gates, SPEC workflow, EARS format, DDD methodology, agent delegation patterns, or MoAI orchestration rules. Do NOT use for context and token management (use moai-foundation-context instead) or strategic analysis (use moai-foundation-philosopher instead).
Structured thinking toolkit combining Critical Evaluation, Diverge-Converge Brainstorming, and Deep Questioning frameworks for creative problem-solving and rigorous analysis. Use when generating ideas, evaluating proposals, questioning assumptions, or exploring solution spaces systematically. Do NOT use for architecture decisions (use moai-foundation-philosopher instead) or code quality validation (use moai-foundation-quality instead).
Ralph Engine - Automated feedback loop with LSP diagnostics and AST-grep integration for continuous code quality improvement. Use when implementing error-driven development, automated fixing, or continuous quality validation workflows.
Template management system for code boilerplates, feedback templates, scaffolding, and project optimization workflows. Use when creating code templates, generating boilerplate files, managing project scaffolding, optimizing template performance, or preparing GitHub issue templates. Do NOT use for SPEC document creation (use moai-workflow-spec instead) or documentation generation (use moai-workflow-project instead).
| name | moai |
| description | 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. |
| license | Apache-2.0 |
| compatibility | Designed for Claude Code |
| allowed-tools | Task AskUserQuestion TaskCreate TaskUpdate TaskList TaskGet Bash Read Write Edit Glob Grep |
| user-invocable | true |
| metadata | {"argument-hint":"[subcommand] [args] | \"natural language task\""} |
!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--solo: Force sub-agent mode (single agent per phase)When 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/.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