New: 98,000+ skills indexed from GitHub repos with 100+ stars · every skill safety-checkedBrowse top skillsTop skills
Esc to closeBrowse all skills
Submit a skillBrowse skills
Submit a skillBrowse skills

Agent skill

Moai

by modu-ai in modu-ai/moai-adk

MoAI unified orchestrator for autonomous development. An agent skill from modu-ai/moai-adk.

Apache-2.0Auto-check: notesTesting & QA

Install Moai

skills CLI
$ npx skills add modu-ai/moai-adk --skill moai -a claude-code

Project install by default; add -g for ~/.claude/skills/.

GitHub CLI
$ gh skill install modu-ai/moai-adk moai --agent claude-code

Project scope by default; add --scope user for a personal install. Needs GitHub CLI 2.90.0 or later (public preview).

Manual copy
$ git clone --depth 1 https://github.com/modu-ai/moai-adk.git skills-src && mkdir -p .claude/skills && cp -r skills-src/.claude/skills/moai .claude/skills/moai && rm -rf skills-src

Use ~/.claude/skills/ instead of .claude/skills for a personal install. The folder must contain SKILL.md.

Claude Code skills documentation · loads skills from .claude/skills/

Facts

Skill name
moai
GitHub stars
1.2k
Token cost
~8.3k tokens
SKILL.md length
3,882 words
Files
52 (incl. references)
Skills in repo
48
Repo updated
First seen
Licence
Apache-2.0

At a glance

MoAI unified orchestrator for autonomous development. An agent skill from modu-ai/moai-adk.

  • Works in 4 steps: Requirement summary (1-3 sentences):… → Completion condition: the end state that… → Pipeline contract: full-pipeline… → …
  • Tasks that involve End-to-end testing
  • SKILL.md covers Pre-execution Context, Essential Files, Authority References and Routing Observation Ledger, plus 3 more sections
  • Calls git

What it does

Moai is an agent skill from modu-ai/moai-adk. 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.

Its SKILL.md is about 8.3k tokens, which your agent loads only when the skill is triggered. The skill folder holds 53 other files, including reference files (for example `references/anti-patterns.md`, `references/file-reading-optimization.md` and `references/mx-tag.md`).

It sits in Testing & QA, covering End-to-end testing. The repository describes itself as: Agentic development harness for Claude Code — SPEC-driven plan/run/sync, TRUST 5 quality gates, model+effort routing, and Claude×GLM multi-LLM cost control. Single Go binary, 16… The licence is Apache-2.0.

When your agent uses it

  • Tasks that involve End-to-end testing

Example prompts

  • “/moai”

Requirements

  • Pre-approved tools (allowed-tools): Agent, AskUserQuestion, Skill, TaskCreate, TaskUpdate, TaskList, TaskGet, Bash, Read, Write, Edit, Glob, Grep

Workflow steps

4 steps, taken from the first numbered list in SKILL.md.

  1. Requirement summary (1-3 sentences): what the user asked for, restated in the orchestrator's own words.
  2. Completion condition: the end state that means "done". Where the condition is machine-verifiable (test exit code, lint-clean state, grep…
  3. Pipeline contract: full-pipeline (default natural-language route — run-phase completion auto-chains into sync) or single-phase (explicit…
  4. Orchestration-shape pre-signal: an early input to the Phase 4 4-mode selection (orchestration-mode-selection.md §A) — noted here, decided…

What it can do on your machine

Read from SKILL.md and the folder at commit a2a184a. It shows what the files ask for, not the result of running them.

  • Tool permissions

    Pre-approves these tools, so the agent can use them without asking each time:

    • Agent
    • AskUserQuestion
    • Skill
    • TaskCreate
    • TaskUpdate
    • TaskList
    • TaskGet
    • Bash
    • Read
    • Write

    …and 3 more on the same allowed-tools line.

    From allowed-tools in the SKILL.md frontmatter.

  • Runs code

    Shell commands in SKILL.md call:

    • git

    From the folder's file list and the shell code blocks in SKILL.md.

  • Network

    No URLs in SKILL.md. Its commands use git, which can reach the network depending on how they are called.

    From URLs in SKILL.md, links to its own repository left out.

  • Credentials

    Names no API keys, tokens, secrets or passwords.

    From names ending in _API_KEY, _TOKEN, _SECRET, _KEY or _PASSWORD in SKILL.md.

Context cost

Moai loads about 8.3k tokens when it runs, and up to ~15k if it reads all its reference files. Until then it costs about 59 tokens; SKILL.md has 3,882 words of instructions outside code blocks.

Always · name and description, kept in context so the agent knows when to use it
~59
When it runs · the whole SKILL.md, loaded when a task matches
~8.3k
With references · SKILL.md plus every file in references/, read only if the agent opens them
~15k

Estimates: characters ÷ 4, the usual rule of thumb; real counts depend on the model's tokenizer. Scripts and assets cost tokens only if the agent reads them.

Safety

Auto-check: notes

The automated check noted patterns worth knowing about, such as sudo or a known installer.

  • NotePre-approves every shell command (allowed-tools: Bash)SKILL.md
    allowed-tools: Agent, AskUserQuestion, Skill, TaskCreate, TaskUpdate, TaskList, TaskGet, Bash, Read, Write, Edit, G

Automated static check — not a guarantee. Review scripts before installing. It scans the text of SKILL.md for risky patterns (piping downloads into a shell, reading credential files, hidden Unicode, destructive commands); files beside SKILL.md are not scanned.

SKILL.md

The full file from modu-ai/moai-adk at commit a2a184a, republished under its Apache-2.0 licence (© modu-ai). 3,882 words, ~8,272 tokens.

Download SKILL.mdSave it as .claude/skills/moai/SKILL.md (or your agent's skills folder). This skill also uses 51 other files; get the full folder from GitHub.
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>") with approve, run, status, revoke, and resume lifecycle verbs
  • todo (aliases: backlog): Canonical queue workflow — the operator's backlog queue (GTD task management)
  • gtd: Compatibility alias — route to the canonical todo workflow while preserving the supplied arguments
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 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 (experimental — Agent Teams re-allowed; see Execution Mode Flags) For detailed orchestration: Read workflows/run.md

sync - Documentation Sync and PR

Purpose: Synchronize documentation with code changes and prepare pull requests. Agents: manager-docs (primary), sync-auditor (quality gate), manager-git Skills: moai-workflow-project (per delegation.yaml) Modes: auto, force, status, project. Flags: --auto-merge, --merge (deprecated alias of --auto-merge), --skip-mx For detailed orchestration: Read workflows/sync.md

gate - Pre-Commit Quality Gate

Purpose: Lightweight pre-commit quality check running lint, format, type-check, and tests in parallel. Also integrated into run (Phase 15) and sync (Phase 1) workflows as automatic pre-checks. Agents: Direct execution (no agent delegation) Flags: --fix, --staged, --file PATH Integration: Automatically invoked by run workflow (Phase 15) and sync workflow (Phase 1) with --fix behavior. For detailed orchestration: Read workflows/gate.md

e2e - Multi-Platform End-to-End Testing

Purpose: Create and run E2E tests across web, mobile, and desktop applications with project-type auto-detection, CLI-first toolchain selection (Playwright, Maestro, Playwright-Electron, WebdriverIO + tauri-service), and token-minimized execution. Agents: e2e-tester (primary — detection, journey mapping, script creation, execution, recording) Skills: moai-foundation-quality, moai-ref-testing-pyramid (per delegation.yaml) Flags: --tool, --platform, --record, --url, --journey, --headless, --browser, --timeout, --retry For detailed orchestration: Read workflows/e2e.md

goal - Condition Goal and Approved Auto Mission

Purpose: Preserve condition-declared goal loops while exposing a distinct approved autonomous-mission lifecycle. Condition goal: /moai goal "<condition>" (register + arm), status [--all], clear, render. Auto mission: /moai goal --auto "<mission>", followed by approve, run, status, revoke, or resume. Flags: --auto selects mission_mode=auto; it does not mean progression_mode=autonomous. Shared metadata flags include --session and --json. Progression mode: autonomous (default) vs. semi-autonomous — chosen at Implementation Kickoff Approval; the gate stays mandatory in both modes. For detailed orchestration: Read workflows/goal.md

<!-- moai:contract-mode-start id="contract-signing-router" -->

Where workflow.autonomy.mode: contract — the Kickoff approval named here is the contract signature checked by moai contract kickoff-check; the progression mode is chosen when a goal is armed after that check passes. See .claude/rules/moai/workflow/contract-autonomy.md § The signing gate.

<!-- moai:contract-mode-end -->
todo - Queue Workflow and Backlog Queue

Purpose: Carry captured work through Capture, Clarify, Organize, Reflect, and Engage, and hold what the operator wants to work on next. backlog has no owning session, so admission to the board is always an operator act — this is that surface. Verbs — slash surface: /moai todo "<description>" (append), bare /moai todo (list). CLI only: moai todo next (print queued cards; moai todo next <n> [--spec <SPEC-ID>] marks one picked — the pick itself is presented through AskUserQuestion), moai todo done <n> (remove). GTD stages: capture, clarify, organize, reflect, engage, plus answer for a gate-blocked card. Captured items stay separate from the established development queue until an explicitly approved Engage publishes one. Compatibility: /moai gtd and moai gtd are the compat alias of the canonical /moai todo and moai todo — same database, same card identities, same ordering, archive, and restore path. State: ~/.moai/db/<project-key>/todo/backlog.db — home-scoped, project-keyed, not committed, a SQLite database every mutation takes a cross-process lock over. A backlog.json beside an existing database is an export or a legacy leftover; the read verbs report that distinction. Before migration, a legacy JSON-only queue remains readable. The pick is the operator's: never preselect, never reorder by inferred priority (the --auto cycle's own candidate ranking is the one auto-scoped ranking exception — selection order only), never auto-populate from TODO comments or issues. Enablement: when workflow.todo.enabled is false in .moai/config/sections/workflow.yaml, do NOT route to this workflow by inference — a backlog-shaped phrase the operator did not name a subcommand for is answered directly instead of being queued. The gate binds AUTOMATIC routing only: an explicit /moai todo or /moai todo "<description>" still runs normally, exactly as it does when the key is absent or true. The flag suppresses guidance, not the feature — the queue verbs stay registered and every one of them keeps working, so refusing or silently ignoring a named invocation is a defect, not the intended behavior. For detailed orchestration: Read workflows/gtd.md

fix - Auto-Fix Errors

Purpose: Autonomously detect and fix LSP errors, linting issues, and type errors. Agents: manager-develop (cycle_type=autofix), Agent(general-purpose) with domain whitelist (fixes) Skills: moai-workflow-ddd (per delegation.yaml) + domain moai-ref-* injected per mission Flags: --dry, --sequential, --level N, --resume, --team (experimental — Agent Teams re-allowed; see Execution Mode Flags) For detailed orchestration: Read workflows/fix.md

loop - Iterative Auto-Fix

Purpose: Repeatedly fix issues until completion conditions are satisfied or max iterations reached. Agents: manager-develop (cycle_type=autofix), Agent(general-purpose) with domain whitelist Skills: moai-workflow-loop (per delegation.yaml) + domain moai-ref-* injected per mission Flags: --max N, --auto-fix, --seq For detailed orchestration: Read workflows/loop.md

mx - MX Tag Scan and Annotation

Purpose: Scan codebase and add @MX code-level annotations for AI agent context. Agents: Explore (scan), Agent(general-purpose) with backend scope (annotation) Flags: --all, --dry, --priority P1-P4, --force, --team (experimental — Agent Teams re-allowed; see Execution Mode Flags) For detailed orchestration: Read workflows/mx.md

review - Code Review

Purpose: Multi-perspective code review with security, performance, quality, and UX analysis. Agents: sync-auditor (review), Agent(general-purpose) with security scope Skills: moai-foundation-quality, moai-ref-owasp-checklist (per delegation.yaml; per-perspective ref skills injected per lens) Flags: --staged, --branch, --security, --team (experimental — Agent Teams re-allowed; see Execution Mode Flags) For detailed orchestration: Read workflows/review.md

clean - Dead Code Removal

Purpose: Identify and safely remove unused code with test verification. Agents: manager-develop, Agent(general-purpose) with refactoring scope Skills: moai-workflow-ddd (per delegation.yaml) Flags: --dry, --safe-only, --file PATH For detailed orchestration: Read workflows/clean.md

codemaps - Architecture Documentation

Purpose: Scan codebase and generate architecture documentation. Agents: Explore, manager-docs Flags: --force, --area AREA For detailed orchestration: Read workflows/codemaps.md

(default) - MoAI Autonomous Workflow

Purpose: Full autonomous research -> plan -> annotate -> run -> sync pipeline. Phases: Parallel Exploration (research.md) -> SPEC Generation -> Annotation Cycle -> Implementation -> Sync Agents: Explore, manager-spec, plan-auditor (quality gate), manager-develop, manager-docs, manager-git, sync-auditor (quality gate) Skills: moai-workflow-spec, moai-workflow-tdd (per delegation.yaml) + domain moai-ref-* injected per mission Flags: --loop, --max N, --branch, --pr, --resume SPEC-XXX, --team (experimental — Agent Teams re-allowed; see Execution Mode Flags), --solo, --issue (opt-in; default skips GitHub Issue creation per the late-branch opt-in policy) For detailed orchestration: Read workflows/moai.md

project - Project Documentation

Purpose: Generate project documentation by analyzing the existing codebase. Agents: Explore, manager-docs, Agent(general-purpose) with devops scope (optional) Skills: moai-workflow-project (per delegation.yaml) Output: product.md, structure.md, tech.md in .moai/project/ For detailed orchestration: Read workflows/project.md

feedback - GitHub Issue Creation

Purpose: Collect user feedback and create GitHub issues. Agents: orchestrator-direct (records feedback via gh CLI) For detailed orchestration: Read workflows/feedback.md

harness - Harness Lifecycle + Natural-Language Build (argument-branching)

This single harness subcommand dispatches to ONE of two workflows based on the FIRST token of $ARGUMENTS (argument-based routing — no second command is introduced). Apply the routing rule before any workflow-specific logic:

  • Reserved verb (status / apply / rollback / disable) → route to the existing harness learning lifecycle workflow (Branch A below). This path is unchanged.
  • Reserved verb (list / edit / remove / doctor) → route to the harness-v4 lifecycle handler (Branch A.1 below). These enumerate / edit / atomically-remove harness-v4 entries and run the reference-integrity smoke gate (doctor) via the moai harness <verb> Go binary subcommand.
  • Anything else (a natural-language harness-creation request, e.g. "build a harness for CLI template development") → route to the harness build entry workflow (Branch B below).
Show full SKILL.md (1,521 more words)Show less
Branch A — harness learning lifecycle (reserved verbs: status / apply / rollback / disable)

Purpose: Surface the harness learning subsystem (observer, 4-tier proposal ladder, 5-layer safety pipeline) to the user via the slash command path. The lifecycle verbs (status / apply / rollback / disable) dispatch through the unified moai harness Go-binary Cobra subcommand tree, which performs the file-system operations. Tier-4 application is gated by orchestrator-issued AskUserQuestion. Skills: moai-harness-learner (Tier-4 surfacing companion). Project-specific harness generation is handled by the v4 Builder (builder-harness agent, Branch B). Verbs: status (tier distribution + telemetry) | apply (next Tier-4 proposal → AskUserQuestion → 5-layer pipeline → snapshot + write) | rollback <YYYY-MM-DD> (restore snapshot) | disable (set learning.enabled: false) Artifacts: .moai/harness/usage-log.jsonl, .moai/harness/proposals/, .moai/harness/learning-history/snapshots/, .moai/harness/learning-history/applied/, .moai/harness/learning-history/frozen-guard-violations.jsonl Authoritative SPEC: the harness foundation policy (supersedes V3R3-HARNESS-001, V3R3-HARNESS-LEARNING-001, V3R3-PROJECT-HARNESS-001) For detailed orchestration: Read workflows/harness.md

Branch A.1 — harness-v4 lifecycle (reserved verbs: list / edit / remove / doctor)

Purpose: Manage harness-v4 entries — enumerate built harnesses, locate their manifest + specialist files for editing, atomically remove a harness with all its artifacts, or run the reference-integrity smoke gate. The four verbs dispatch to the moai harness <verb> Go binary subcommand which performs the filesystem work (scan .claude/commands/harness/*.md joined with manifest.json; atomic remove with fail-closed orphan prevention; doctor cross-references manifest/specialist/skill file existence). Verbs: list (enumerate all harnesses: name + domain + entry command, plus the declared schedule — interval + mechanism — when the manifest declares one; schedule-less harnesses render identically to the pre-schedule baseline) | edit <name> (show manifest + specialist + skill paths for editing — manifest is the SSOT) | remove <name> (atomic removal of command + workflow + specialists + skills + manifest; fail-closed if any artifact is missing; when the manifest declared a schedule, prints an unregister notice naming the declared mechanism — CronDelete for cron, session-scoped loop cancellation for loop — computed from the manifest before deletion) | doctor (reference-integrity smoke gate: verifies every built harness's manifest/specialist/skill files exist and cross-reference correctly; a schema-invalid schedule declaration is an ERROR-severity finding) CLI: moai harness list [--json], moai harness edit <name> [--json], moai harness remove <name>, moai harness doctor (all support --project-root) Artifacts: .claude/commands/harness/<name>.md (thin-wrapper command), .claude/commands/harness/<name>/manifest.json (SSOT), .claude/workflows/hns-<name>-run.js (Runner), .claude/agents/harness/hns-<name>*-specialist.md (specialists), .claude/skills/hns-<name>*/ (companion skills) Namespace: .claude/commands/harness/, .claude/workflows/hns-*.js, .claude/agents/harness/, and .claude/skills/hns-*/ are USER-OWNED — moai update preserves them (backup if needed, never overwrites). Legacy generations with the harness- or my-harness- prefix are equally preserved (recognition-based backward compatibility); the Builder emits hns- names only.

Branch B — harness build entry (natural-language request)

Purpose: Turn a natural-language harness-creation request into a concrete harness via Context-First Discovery (extract domain / goal / constraints / scope), harness <name> derivation (the name is derived from the request — NOT statically supplied by the user), explicit orchestrator-issued approval, then transition into the orchestrator-direct Builder (4 signal-driven phases: ANALYZE / PLAN / GENERATE / ACTIVATE). The orchestrator MUST conduct AskUserQuestion Socratic rounds (max 4 questions per round) when intent clarity is below 100%. Agent: builder-harness (v4 Builder — project-specific harness generation) Builder: orchestrator-direct processing (NOT a dynamic-workflow script) — the entry's Phases 0-3 hand off to workflows/harness-builder.md for the 4-phase creation logic. The orchestrator holds the PLAN→GENERATE AskUserQuestion approval gate directly; that gate round also carries the recurrence question (optional manifest schedule, discovery-only scheduled runs), and ACTIVATE registers a declared schedule after the smoke gate. A request referencing an EXISTING harness together with scheduling intent routes to the entry workflow's Schedule Retrofit branch (evaluated before name-collision handling) instead of the creation pipeline. For detailed orchestration: Read workflows/harness-build-entry.md

Execution Directive

When this skill is activated, execute the following steps in order:

Step 1 - Parse Arguments: Extract subcommand keywords and flags from the Raw User Input. Recognized global flags: --resume [ID], --seq, --team, --solo. Also detect ultrathink keyword in the input text.

CRITICAL: Deep analysis mode:

  • ultrathink keyword detected → Activate Claude's native extended reasoning (xhigh effort mode). This is native Claude behavior with no MCP dependency.

Step 1.5 - Flag-Subcommand Compatibility Validation: [HARD] After parsing the subcommand and flags (Step 1), validate flag-subcommand compatibility BEFORE routing. If a forbidden combination is detected, STOP all further processing and output an error in the user's conversation_language. Do NOT proceed to Step 2.

Forbidden flag-subcommand combinations:

FlagAllowed subcommandsForbidden subcommands
--branchplan, default (autonomous)run, sync

Rationale: --branch creates the feature branch at SPEC initialization, so /moai run and /moai sync MUST operate on the branch plan already established — re-creating it mid-lifecycle corrupts the SPEC lifecycle and is rejected at the router level.

The retired --worktree flag is handled separately: a request carrying it is not a forbidden-combination error but a retired flag. Tell the user that plan no longer creates a workspace, and that entering one first is the replacement.

Error message template (Korean conversation_language; substitute the actual flag and subcommand):

에러: --branch 플래그는 /moai plan 전용입니다.
/moai run 과 /moai sync 는 plan 단계에서 만든 브랜치를 그대로 씁니다.

올바른 사용법:
  /moai plan SPEC-XXX --branch    (브랜치 생성)
  /moai run SPEC-XXX              (기존 브랜치 재사용)
  /moai sync SPEC-XXX             (기존 브랜치 재사용)

--branch 플래그를 뺀 형태로 다시 실행하세요.

Retired-flag message (--worktree):

안내: --worktree 플래그는 폐기됐습니다. plan 은 더 이상 작업 공간을 만들지 않습니다.

격리된 공간에서 작업하려면 먼저 들어간 뒤 plan 을 실행하세요:
  moai cc -w <이름>              (그 자리에서 진입)
  moai cc -w <이름> --spawn      (새 Claude 세션을 tmux 창으로 열고 현재 세션 유지)
  /moai plan "<설명>"

For English (en conversation_language), translate the message; the structure remains identical.

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.2 - Record Routing Decision: Immediately after routing resolves (Step 2), record the routing decision to the append-only routing-ledger (.moai/state/routing-ledger.jsonl) so that auto-invocation is observable. Run:

echo "<raw request text>" | moai harness ledger record --subcommand <matched> --mode <phase-4-mode> --tier <tier> --level <harness-level> --session <session-id>

The request text is piped via stdin and only a privacy-preserving digest is stored, never verbatim user text (policy source: § Routing Observation Ledger above). This step is opt-in and fail-open: if the moai CLI is absent from PATH or the command exits non-zero, log nothing and continue — it NEVER blocks routing, never gates the workflow, and never triggers a retry loop. An un-recorded dispatch is an observation gap, not an error.

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:

  • Create project documentation (Recommended): Generates product.md, structure.md, tech.md through a guided interview. This helps MoAI understand your project context for better results in all subsequent workflows.
  • Skip and continue: Proceed without project documentation. MoAI will have less context about your project.

This check does NOT apply to: project, feedback subcommands.

[HARD] Beginner-Friendly Option Design: All AskUserQuestion calls throughout MoAI workflows MUST follow these rules:

  • The first option MUST always be the recommended choice, clearly marked with "(Recommended)" suffix — this is the push-mode branch; while interview.recommendation_mode is pull the suffix is withheld from every option and no option carries a preference claim (.claude/rules/moai/core/askuser-protocol.md § Recommendation Placement Principles)
  • Every option MUST include a detailed description explaining what it does and its implications

Step 2.8 - Requirement Analysis & Completion Condition: Before loading the workflow body (Step 3), produce a requirement-analysis record for the routed request:

  1. Requirement summary (1-3 sentences): what the user asked for, restated in the orchestrator's own words.
  2. Completion condition: the end state that means "done". Where the condition is machine-verifiable (test exit code, lint-clean state, grep count, bounded turn count), express it in /moai goal-compatible form per .claude/rules/moai/workflow/goal-directive.md (one measurable end state + a stated check + a bound clause). Do NOT invent a parallel evaluator: arm the condition via /moai goal when the goal engine is available (hooks enabled — the evaluator is the stop-goal Stop hook); otherwise the orchestrator evaluates the identical condition text per-turn (graceful degradation — no new machinery).
  3. Pipeline contract: full-pipeline (default natural-language route — run-phase completion auto-chains into sync) or single-phase (explicit run/sync subcommand — chaining is offered as the "(Recommended)" next-step option, never fired silently).
  4. Orchestration-shape pre-signal: an early input to the Phase 4 4-mode selection (orchestration-mode-selection.md §A) — noted here, decided at Phase 4.

Trivial-scope exemption: skip this step entirely for feedback, gate, codemaps, sync status mode, and any Stage-1-Clarify exception per askuser-protocol.md § Ambiguity Triggers and Exceptions. Socratic-first ordering: while intent clarity is below 100%, run the Socratic interview (per askuser-protocol.md) BEFORE deriving the completion condition — the condition encodes drained intent, never a guess. A derived completion condition NEVER authorizes autonomous run-phase entry — Implementation Kickoff Approval remains mandatory at the plan→run boundary.

Step 3 - Load Workflow Details: Read workflows/<name>.md for the target subcommand. (Agent Teams is experimental and re-allowed: a --team flag selects the Agent Teams layer, subject to the constraints in .claude/rules/moai/workflow/orchestration-mode-selection.md §C.1. Only the static layer stays retired, so there is no separate team/<name>.md workflow file — the same workflows/<name>.md is read either way. Historical: the retired era emitted MODE_TEAM_UNAVAILABLE and fell back to sub-agent mode; the sentinel is retained as documented history.)

Step 4 - Read Configuration: Load relevant configuration from the .moai/config/sections/*.yaml section files as needed.

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. Delegate all implementation to appropriate agents via Agent(). Collect user approvals at designated checkpoints via AskUserQuestion. Before each implementation/review Agent() spawn, apply .claude/rules/moai/workflow/skill-routing.md §1: inject 0-3 At start, invoke Skill("<name>") for <reason> lines per the delegation map (.moai/config/sections/delegation.yaml).

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.

Step 9 - Declare Completion: When all workflow phases complete successfully, state that the workflow is complete in the Completion Report (banner / prose) so the result is unambiguous.

Step 10 - Guide Next Steps: Use AskUserQuestion to present the user with logical next actions based on the completed workflow.

Version: 2.8.0

© modu-ai, Apache-2.0. Rendered from Markdown: HTML in the file is shown as text, images as links, and headings moved down two levels. Raw file

Files

SKILL.md and 51 other files (references) in .claude/skills/moai of modu-ai/moai-adk.

  • SKILL.md
  • references/anti-patterns.md
  • references/file-reading-optimization.md
  • references/mx-tag.md
  • references/reference.md
  • workflows/clean.md
  • workflows/codemaps.md
  • workflows/design.md
  • workflows/e2e.md
  • workflows/factory.md
  • workflows/feedback.md
  • workflows/fix.md
  • workflows/gate.md
  • workflows/goal.md
  • workflows/gtd.md
  • workflows/harness-build-entry.md
  • workflows/harness-builder.md
  • workflows/harness.md
  • workflows/loop.md
  • … and 33 more

Open the folder on GitHubat commit a2a184a

Compare with similar skills

Moai next to the 5 skills that share the most tags, products or categories with it. Stars are the repository's; “used in” counts other GitHub owners with a copy.

Moai compared with similar skills
SkillStarsUsed inTokensAuto-checkLicenceRepo updated
Moai this skillmodu-ai/moai-adk1.2k—~8.3kAutomated safety check: NotesApache-2.0
Web Application Testinganthropics/skills180k51 repos~966Automated safety check: PassApache-2.0
TDD WorkflowhellangleZ/burn-in-cceverywhere-ralph11211 repos~2.4kAutomated safety check: PassNone
Uloop Replay Inputkurotu/VRCQuestTools3733 repos~615Automated safety check: PassMIT
Ui4 Convert Testspayloadcms/payload45k—~3.5kAutomated safety check: PassMIT
E2Estackia/rtp2httpd2.2k—~517Automated safety check: PassGPL-2.0

Similar skills

  • Web Application Testing

    anthropics/skills

    Official

    Tests local web applications with Python Playwright scripts, checking frontend behavior, capturing screenshots and reading browser console logs.

    180k GitHub starsUsed in 51 repos~966 tokens
    Testing & QAAuto-check passed

  • TDD Workflow

    hellangleZ/burn-in-cceverywhere-ralph

    A skill your agent uses when writing new features, fixing bugs, or refactoring code.

    112 GitHub starsUsed in 11 repos~2.4k tokens
    Testing & QAAuto-check passed

  • Uloop Replay Input

    kurotu/VRCQuestTools

    Replay recorded PlayMode keyboard and mouse input. An agent skill from kurotu/VRCQuestTools.

    373 GitHub starsUsed in 3 repos~615 tokens
    Testing & QAAuto-check passed

  • Ui4 Convert Tests

    payloadcms/payload

    A skill your agent uses when UI changes are complete and e2e tests need updating.

    45k GitHub stars~3.5k tokensUpdated yesterday
    Testing & QAAuto-check passed

  • E2E

    stackia/rtp2httpd

    Write, run, review, or debug rtp2httpd E2E tests and their harness in e2e/ and scripts/run-e2e.sh.

    2.2k GitHub stars~517 tokensUpdated 6 days ago
    Testing & QAAuto-check passed

  • Moav E2E

    MotherofallVPNs/MoaV

    Run and debug MoaV's end-to-end tests — real protocol connectivity (client-test.sh) and the moav CLI smoke test — against a LIVE server, via the self-hosted e2e workflow or a local test VPS.

    448 GitHub stars~1.9k tokensUpdated yesterday
    Testing & QAAuto-check: notes

More from modu-ai/moai-adk

All 48 skills in this repo

  • SVG Technical Infographic Author

    modu-ai/moai-adk

    Builds hand-editable SVG diagrams from computed layout coordinates, lints the source and renders a 2x PNG, with rules for when mermaid is the better choice.

    1.2k GitHub stars~5.2k tokensUpdated today
    Auto-check: notes

  • MoAI Foundation Core

    modu-ai/moai-adk

    Reference for MoAI-ADK's core development principles: TRUST 5 quality gates, SPEC-first domain-driven workflow, agent delegation and token budgeting.

    1.2k GitHub stars~5k tokensUpdated today
    Auto-check passed

  • MoAI SPEC Workflow

    modu-ai/moai-adk

    Manages SPEC documents for MoAI-ADK development, with GEARS or EARS requirement notation, acceptance criteria and a link into the Plan-Run-Sync workflow.

    1.2k GitHub stars~5.1k tokensUpdated today
    Auto-check passed

  • MoAI TDD Workflow

    modu-ai/moai-adk

    Drives test-first development through the RED, GREEN, REFACTOR cycle, with a config switch that selects between TDD and a DDD workflow for existing code.

    1.2k GitHub stars~3.1k tokensUpdated today
    Auto-check passed

  • MoAI Worktree Management

    modu-ai/moai-adk

    Gives each SPEC its own Git worktree with a registry of active workspaces, base-branch sync and cleanup of merged ones, inside the MoAI-ADK workflow.

    1.2k GitHub stars~3.9k tokensUpdated today
    Auto-check passed

  • CI Watch and Auto-Fix Loop

    modu-ai/moai-adk

    Watches a pull request's CI checks after creation, separates required from auxiliary failures, applies limited safe fixes and escalates anything semantic to you.

    1.2k GitHub stars~2.4k tokensUpdated today
    Auto-check: notes

Categories

Questions about Moai

What does Moai do?

MoAI unified orchestrator for autonomous development. An agent skill from modu-ai/moai-adk. Moai is an agent skill from modu-ai/moai-adk. MoAI unified orchestrator for autonomous development.

When should I use Moai?

Moai fits situations like: tasks that involve End-to-end testing.

How do I install Moai in Claude Code?

Run `npx skills add modu-ai/moai-adk --skill moai -a claude-code`. Or copy the skill folder (.claude/skills/moai in modu-ai/moai-adk) into .claude/skills/moai in your project. Claude Code loads it when a task matches its description.

How do I install Moai in Codex?

Run `npx skills add modu-ai/moai-adk --skill moai -a codex`. Or copy the skill folder (.claude/skills/moai in modu-ai/moai-adk) into .agents/skills/moai in your project. Codex loads it when a task matches its description.

Can I use Moai in Cursor, Gemini CLI or GitHub Copilot?

Cursor, Gemini CLI, GitHub Copilot and OpenCode also load SKILL.md folders. With the skills CLI, run `npx skills add modu-ai/moai-adk --skill moai -a cursor` (or -a gemini-cli, github-copilot or opencode for the others). To copy it by hand, put the folder in .cursor/skills/moai, .gemini/skills/moai, .github/skills/moai and .opencode/skills/moai in your project.

What does Moai need to run?

Going by SKILL.md and its folder, Moai needs the command-line tools its instructions call (git). Its frontmatter pre-approves these tools: Agent, AskUserQuestion, Skill, TaskCreate, TaskUpdate, TaskList, TaskGet, Bash, Read, Write, Edit, Glob, Grep.

Does Moai access the network?

SKILL.md contains no URLs. Its commands use git, which can reach the network depending on how they are called. This is read from the text; nothing was executed.

Is Moai safe to install?

Our automated static check of SKILL.md found notes only (pre-approves every shell command (allowed-tools: bash)), nothing it rates as a warning. It is not a guarantee. Review the folder before installing.

What licence does Moai use?

Moai is published under the Apache-2.0 licence (the repository's licence). It allows redistribution, so the full SKILL.md is shown on this page.

How many tokens does Moai use?

About 8.3k tokens (SKILL.md is roughly 33k characters). Agents keep only the skill's name and description in context until a task matches; then they load SKILL.md in full. Its references folder adds about 6.5k tokens, read only when the agent opens those files.

What are the alternatives to Moai?

Skills that share tags, products or a category with Moai: Web Application Testing (anthropics/skills, 180k stars), TDD Workflow (hellangleZ/burn-in-cceverywhere-ralph, 112 stars), Uloop Replay Input (kurotu/VRCQuestTools, 373 stars) and Ui4 Convert Tests (payloadcms/payload, 45k stars). The comparison table on this page puts their stars, adoption, token cost, safety result and licence side by side.

Who maintains Moai?

modu-ai (a GitHub organization) maintains it in modu-ai/moai-adk, which has 1,230 GitHub stars. The repository holds 48 skills in this directory. The repository was last updated on October 8, 2026.

Source: modu-ai/moai-adk on GitHub. Facts on this page come from the repository at the commit we read; the author's words are quoted as theirs.