Builder Agents and Harness v4

The last piece of the agentic harness is recursion — the harness builds the harness. The Harness v4 Builder is the entrance to that recursive structure, generating a project-specific specialist team from a single natural-language request.

Info

One-line summary: The Harness v4 Builder dynamically generates a project-specific specialist team from a natural-language request. It consists of a 4-phase workflow (ANALYZE → PLAN → GENERATE → ACTIVATE) and a manifest-based Runner.

The Harness v4 Builder dynamically generates a project-specific specialist team via /moai:harness <natural-language request>.

MoAI-ADK ships with a general-purpose agent catalog (11 agents) common to all projects, while the harness the Builder creates is a custom team that exists only in your project.

Analyzes the current project and identifies the expertise needed.

• Source code structure analysis
• Language and framework detection
• Inventory of existing agents/skills
• Project-scale estimation

Defines the composition and roles of the required specialist team.

• Team size decision (3-5 teammates)
• Role profile definition for each teammate
• Worktree-isolation necessity judgment
• Manifest schema design

Generates the actual agent definitions and configuration.

• Agent files created under .claude/agents/harness/
• .moai/harness/manifest.json created (Runner configuration)
• Per-role system prompts authored
• Skill preload lists defined

Activates the generated harness for immediate use.

• Agent registration and validation
• Manifest Runner initialization
• Optional worktree creation and isolation setup
• Teammate auto-delegation rules activated

Harness v4 uses a manifest-based Runner to operate the generated specialist team. Which specialist is deployed in which domain, with which execution primitive, isolation, effort, and model, is declared in a single manifest file — the tokenomics principle of managing model assignment declaratively applies here too. The number of specialists is held to a HARD cap of 3-7.

{
  "name": "oss-docs",
  "domain": "OSS project public docs — README 4-locale + Hugo docs-site",
  "patterns": ["Pipeline", "Fan-out/Fan-in", "Producer-Reviewer"],
  "specialists": [
    {
      "role": "content-author",
      "description": "canonical-locale source authoring (docs-site ko, README en)",
      "agent_file": ".claude/agents/harness/hns-oss-docs-content-author-specialist.md",
      "primitive": "sub-agent",
      "isolation": "none",
      "effort": "high",
      "model": "opus"
    },
    {
      "role": "locale-translator",
      "description": "derive the 3 derived locales within the same PR (parallel fan-out)",
      "agent_file": ".claude/agents/harness/hns-oss-docs-locale-translator-specialist.md",
      "primitive": "adversarial-fan-out",
      "isolation": "none",
      "effort": "medium",
      "model": "sonnet"
    }
  ],
  "sprint_contract": {
    "dimensions": ["locale-parity", "build-clean", "style-compliance", "content-fidelity"],
    "thresholds": { "locale-parity": 1.0, "build-clean": 1.0 },
    "must_pass": ["locale-parity", "build-clean"]
  },
  "companion_skills": ["hns-oss-docs-i18n-rules", "hns-oss-docs-verify"],
  "entry_command": "/harness:oss-docs",
  "runner_workflow": "hns-oss-docs-run.js"
}

• primitive: execution primitive (sub-agent, adversarial-fan-out, etc.)
• isolation / effort / model: assign each specialist’s isolation level, reasoning intensity, and model tier to fit its purpose
• sprint_contract: the Sprint Contract — quality dimensions and must_pass gates
• schedule (optional): a harness needing recurring execution can carry a mode: discovery-only schedule object

1. Specialist delegation: proceeds through the manifest’s specialist sequence according to the patterns
2. Fan-out spawn: parallel primitives (adversarial-fan-out, etc.) spawn concurrently
3. Isolation applied: applies each specialist’s isolation setting
4. Result aggregation: verifies and consolidates each specialist’s results against the Sprint Contract

A harness generated by the Harness v4 Builder is managed with the moai harness CLI.

# List generated v4 harnesses (name + domain + entry command)
moai harness list

# Check a harness's manifest/specialist edit path
moai harness edit <name>

# Atomically remove a harness (command + workflow + specialists + skills + manifest)
moai harness remove <name>

# Reference-integrity smoke gate
moai harness doctor

# Create a new harness with the Harness v4 Builder
/moai:harness <natural-language request>

The learning-subsystem management verbs also live under moai harness: moai harness status (observation/tier/evolution summary), moai harness apply (apply pending proposals), moai harness rollback <date> (revert an applied evolution), and moai harness disable (disable learning).

> Build a specialist team that fits our backend project.
> I need a team responsible for API design, DB schema, and testing.

1. ANALYZE: analyzes the project structure (Go, PostgreSQL, REST API)
2. PLAN: decides on a 3-person team (API Designer, DB Specialist, Test Engineer)
3. GENERATE: creates each agent definition and manifest.json
4. ACTIVATE: activates the team and registers the /harness:backend-team command

• Agent definitions: .claude/agents/harness/api-designer.md, db-specialist.md, …
• Manifest: .moai/harness/manifest.json
• Optional worktrees: ~/.moai/worktrees/<project>/ (on user opt-in)

Harness v4 supports conditional worktree isolation.

The Claude Code runtime creates an L1 worktree per agent.

• When used: when parallel teammates edit the same files
• Isolation scope: each teammate’s file writes occur in an independent worktree
• Cost: extra memory + offsets some of the parallelism benefit

Setting "worktree_isolation": "none" in the manifest skips L1 isolation.

• Harness v4 Builder Advanced Guide - Builder 4-phase details and the manifest schema
• Agent Guide - the 11-agent core catalog
• Dynamic Workflows - /effort ultracode parallel execution

Info

Tip: Generate a custom team just once per project with the Harness v4 Builder, and it will be delegated automatically for all subsequent work. After the initial creation you can reuse it anytime via /harness:team-name.