/moai harness

Creates a project-specific specialist set (harness) and manages the harness learning lifecycle.

Info

Slash command: Type /moai:harness <natural-language request> in Claude Code to run this command directly.

/moai:harness runs MoAI-ADK’s Harness v4 Builder to auto-generate a specialist set tailored to the project’s requirements. The Builder is driven directly by the orchestrator (not the Agent Teams static layer), and the generated harness has its manifest-based Runner dispatch specialists via the sub-agent or dynamic-workflow primitive.

It is the command that lets you feel v3’s third pillar, the agentic harness, directly — a recursive structure where a harness builds a harness. When there is a project-specific area the general-purpose agent catalog cannot cover (e.g., a particular DB migration procedure, an in-house API convention), you can scaffold a specialist team for that area with a single sentence of natural language. The generated harness connects to the recursive self-learning subsystem — as usage observations accumulate, the harness produces improvement proposals on its own, and guidance evolves through a user-approval gate.

The Harness v4 Builder composes a specialist set through a Socratic-interview-based 4-phase workflow (ANALYZE → PLAN → GENERATE → ACTIVATE). The orchestrator drives the 4 phases directly; it is not a dynamic-workflow script.

moai harness is a single Cobra subcommand tree that branches into one of three paths based on the first argument (the first token of $ARGUMENTS) — argument-branching routing that introduces no separate command.

flowchart TD
    A["moai harness <first token>"] --> B{"Reserved verb?"}
    B -->|status / apply / rollback / disable| C["Branch A
learning lifecycle"]
    B -->|list / edit / remove / doctor| D["Branch A.1
v4 lifecycle"]
    B -->|natural-language request| E["Branch B
harness build entry"]
    E --> F["ANALYZE → PLAN → GENERATE → ACTIVATE"]
    C --> G["Filesystem operations
(Go binary Cobra subcommands)"]
    D --> G

All verbs dispatch the same way through the moai harness <verb> Go binary Cobra subcommand tree — the learning verbs and the v4 verbs are not split into different Go binaries.

> /moai:harness <natural-language request>

Example:

Create a specialist team for our Go backend project.
I need teams that handle DB migrations, REST API endpoints, and unit tests respectively.

The Builder runs the 4 phases automatically:

1. ANALYZE: detect the Go, PostgreSQL, REST API tech stack
2. PLAN: decide on 3 specialist roles — DB Engineer, API Developer, Test Engineer
3. GENERATE:
   • .claude/agents/harness/hns-backend-team-db-specialist.md
   • .claude/agents/harness/hns-backend-team-api-specialist.md
   • .claude/agents/harness/hns-backend-team-test-specialist.md
   • .claude/commands/harness/backend-team/manifest.json (SSOT)
   • .claude/workflows/hns-backend-team-run.js (Runner)
4. ACTIVATE: register the /harness:backend-team command (smoke gate)

After creation, the team is used automatically in all work:

/moai run SPEC-BACKEND-001

MoAI analyzes the SPEC complexity and auto-delegates to the teammates in the manifest’s phase order.

The generated harnesses are managed with the moai harness subcommand. Four v4 lifecycle verbs dispatch as Go binary Cobra subcommands.

Lists all generated harnesses:

moai harness list

Output info: harness name, domain, entry command, and the schedule declared in the manifest (shown only when declared).

Displays the manifest.json and agent-definition file paths to guide editing — the manifest is the SSOT:

moai harness edit backend-team

Edit targets:

• .claude/commands/harness/<name>/manifest.json (SSOT)
• .claude/agents/harness/hns-<name>*-specialist.md (specialist definitions)
• .claude/skills/hns-<name>*/ (companion skills)

Atomically deletes the harness and all associated files:

moai harness remove backend-team

Deleted items:

• .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)

Warning

remove operates fail-closed — if any single artifact is missing, it aborts the deletion and reports the missing file. This guarantees no orphan artifacts are left behind.

A smoke gate that verifies the reference integrity of all harnesses:

moai harness doctor

Checks:

• Whether every harness’s manifest / specialist / skill files exist
• Cross-reference consistency between the manifest and its artifacts
• Schema validity of the schedule declaration (ERROR severity if invalid)

A harness is not a static artifact you create and forget. You manage the lifecycle of the learning subsystem with the moai harness subcommand. The learning verbs (status / apply / rollback / disable) route to Branch A.

The 4-tier learning ladder — the more observations accumulate, the higher the learning stage climbs:

Artifacts: the .moai/harness/ directory (usage-log.jsonl, learned-rules.yaml, proposals/, learning-history/snapshots/)

Tier-4 (TierAutoUpdate) proposals must pass through an orchestrator-issued AskUserQuestion round before any file is modified. The workflow body runs in the orchestrator’s main context, and sub-agents cannot call AskUserQuestion directly — if a sub-agent needs user input, it returns a structured blocker report and the orchestrator re-runs the gate.

On approval, a 5-layer safety pipeline runs:

1. FrozenGuard — path-prefix check (blocks modification of protected paths)
2. Schema validation — schema validation of the proposal fields
3. Diff inspection — inspection of the changes
4. Rate-limit window — max 3 per week, 24-hour cooldown (harness.yaml rate_limit SSOT)
5. Snapshot creation — save a pre-modification snapshot to .moai/harness/learning-history/snapshots/<ISO-DATE>/

Warning

The moai harness apply --execute --id <proposal-id> CLI path is a separate ungated trust boundary — it applies directly via the Go execute pipeline without the AskUserQuestion approval gate. Because a CLI process cannot prompt the user, --execute is an explicit opt-in for callers who have obtained approval by other means before invocation. The default apply (no --execute) is payload-only, emitting JSON only and modifying no files.

Auto-evolution is always applied only under the user-approval gate. You can restore at any time with moai harness rollback <YYYY-MM-DD>.

Harness v4 defines the specialist-set configuration with manifest.json (.claude/commands/harness/<name>/manifest.json, SSOT). The Runner reads this manifest and dispatches each phase’s specialists via the orchestrator-direct sub-agent or dynamic-workflow primitive — not by registering with the Agent Teams static layer.

{
  "spec_id": "HARNESS-BACKEND-001",
  "name": "Backend Development Team",
  "version": "1.0.0",
  "created_at": "2026-07-01T10:00:00Z",
  "worktree_isolation": "L1_optional",
  
  "phases": [
    {
      "name": "plan",
      "teammates": [
        {
          "name": "architect",
          "role": "API architecture specialist",
          "model": "inherit",
          "skills": ["moai-foundation-core"]
        }
      ]
    },
    {
      "name": "run",
      "teammates": [
        {
          "name": "db-engineer",
          "role": "DB design and migration",
          "model": "inherit"
        },
        {
          "name": "api-developer",
          "role": "REST API endpoints",
          "model": "inherit"
        },
        {
          "name": "test-engineer",
          "role": "unit tests",
          "model": "inherit"
        }
      ]
    }
  ]
}

Being able to specify a different model per teammate (the model field) is an extension of the Tokenomics design — there is no reason to use the same model for a reasoning-heavy role like architecture decisions and a lightweight role like repetitive test writing.

Harness v4 supports optional worktree isolation.

"worktree_isolation": "L1_optional"

Claude Code automatically creates an L1 worktree when it detects a conflict between parallel teammates.

• Optional: isolation applied only on conflict
• Automatic: the runtime creates it automatically after detecting a conflict
• Cost: worktree isolation increases memory

"worktree_isolation": "none"

All teammates work at the project root (minimal memory usage).

Once a harness is activated, the manifest-based Runner uses that specialist set automatically.

> /moai run SPEC-BACKEND-001

Orchestrator-direct decisions:

1. Estimate SPEC complexity (file count, lines of code)
2. Select the appropriate harness
3. Dispatch specialists in the manifest phase order via the sub-agent or dynamic-workflow primitive

PLAN Phase:
  → the architect specialist handles the architecture design

RUN Phase:
  → db-specialist, api-specialist dispatched as sequential sub-agents
  → test-specialist dispatched as a sub-agent (tests)

SYNC Phase:
  → documentation generation and PR writing (default manager-docs)

The Harness v4 Builder understands requirements through a Socratic interview.

Our team is developing a Python FastAPI backend.
We need a team that is good at API endpoints, data validation, and error handling.

The Builder automatically:

• Detects the Python, FastAPI, asyncio tech stack
• Decides on a 3-5 person team size
• Sets each teammate’s specialization area
• Preloads the needed skills

I need a team.

→ Builder: What is the project's main technology? (language, framework)
→ Builder: What area should the team focus on? (backend, frontend, full)
→ Builder: Any specialized expertise you specifically need?

• Harness v4 Builder Guide - Builder 4-phase details
• Agent Guide - understanding the 11-agent catalog
• SPEC-Based Development - SPEC workflow overview

Info

Tip: Once you create a harness, that team is used automatically in all subsequent work. You can reuse it any time with the /harness:team-name command.