Moai Meta Harness

moai-meta-harness (DEPRECATED — redirect to v4)

DEPRECATION NOTICE — This legacy 7-Phase meta-harness is superseded by the v4 harness Builder (/moai:harness <natural-language request>). The v4 design replaces the static 7-Phase workflow with:

• An orchestrator-direct 4-phase Builder (ANALYZE -> PLAN -> GENERATE -> ACTIVATE) that holds the plan in Claude's session context and can call AskUserQuestion at the PLAN->GENERATE approval gate (first-class boundary).
• A manifest-driven dynamic-workflow Runner (hns-<name>-run.js) that reads manifest.json and dispatches specialists per their declared primitive (sub-agent / dynamic-workflow / worktree / /moai goal / adversarial-fan-out) — no heuristic re-derivation.
• Conditional sub-agent-granular worktree isolation (no mandatory top-level worktree; worktree only for conflict-prone parallel generation).
• Signal-driven phase synthesis (not a fixed pipeline); the evaluator is conditional (skipped for tasks within the model's solo reliable range).

To create a new harness: issue /moai:harness <natural-language request> (e.g., /moai:harness build a harness for my-project's API development). The orchestrator runs Context-First Discovery on the request, derives a harness <name>, and enters the Builder. Do NOT use the 7-Phase workflow below for new harness creation.

What is preserved here: the 7-Phase body below is retained as the redirect source for backward-compat — so existing invocation paths that reference the legacy workflow land on a deprecation notice + redirect rather than a dead link. The 7-Phase content is historical reference material, NOT active workflow. The revfactory 7-Phase residual grep excludes this body precisely because it IS the redirect source.

<!-- @MX:NOTE: [AUTO] prior contract SUPERSEDED — the original contract preserved this skill body unchanged per the harness foundation policy §10 exclusion #10 (text annotation only, no behavioral change). That contract is hereby EXPLICITLY SUPERSEDED by the v4 harness redesign: the body is converted to a v4 redirect. Rationale for supersession: (1) the prior contract protected against behavioral change, but v4 IS a deliberate behavioral change — the 7-Phase workflow is retired in favor of the orchestrator-direct Builder + manifest-driven Runner; (2) preserving the body unchanged would leave a dead-path 7-Phase workflow that contradicts the v4 design; (3) the AskUserQuestion-only contract is itself preserved verbatim under v4 — any generated subagent under .claude/agents/harness/ still MUST NOT invoke AskUserQuestion (this is reaffirmed, not weakened). The supersession is narrow: the 7-Phase workflow is retired; the AskUserQuestion boundary + namespace separation + Apache-2.0 attribution are all preserved. Cross-reference: the v4 design's Migration Path (revfactory 7-Phase -> v4 mapping) in the companion harness-builder.md workflow. -->

<!-- ATTRIBUTION
Original work: revfactory/harness (https://github.com/revfactory/harness)
License: Apache License 2.0
Adaptations: 7-Phase workflow integrated with MoAI agent ecosystem (manager-*, expert-*, sync-auditor)
NOTICE: This file contains modifications. See the harness policy for derivation history. The 7-Phase workflow below is superseded by the v4 Builder; it is retained as the redirect source for backward-compat.
-->

Apache 2.0 Attribution: Adapted from revfactory/harness (Apache License 2.0). The 7-Phase workflow below is a MoAI adaptation of the upstream 6-Phase + Evolution Mechanism. See .claude/rules/moai/NOTICE.md for the full third-party notices and the harness policy for derivation history. The v4 Builder (the replacement) is documented in ~/.claude/skills/moai/workflows/harness-builder.md.

---

v4 Redirect (the active path)

New harness creation: /moai:harness <natural-language request>

This routes to the v4 Builder (orchestrator-direct). The Builder:

1. Context-First Discovery on the request (extract domain / goal / constraints / scope).
2. AskUserQuestion Socratic rounds if clarity <100%; derives harness <name> from confirmed intent.
3. Explicit approval gate (AskUserQuestion, PLAN->GENERATE boundary).
4. ANALYZE / PLAN / GENERATE / ACTIVATE as orchestrator-direct phases.
5. Emits 5 artifact types: entry command, Runner Workflow, specialists, companion skills, manifest.json.

Harness lifecycle (list / edit / remove): /moai:harness list|edit|remove <name>.

Harness execution: /harness:<name> (auto-generated thin-wrapper command -> the harness's Runner Workflow).

See harness-builder.md (companion workflow under moai/workflows/) for the full Builder contract and .claude/rules/moai/workflow/dynamic-workflows.md for the Runner's dynamic-workflow primitive.

---

Legacy 7-Phase Body (HISTORICAL REFERENCE — redirect source, NOT active)

The content below this separator is the original 7-Phase workflow, preserved verbatim as the redirect source. It is NOT the active harness-creation path. New harness creation MUST use /moai:harness <NL request> (v4) above. The revfactory 7-Phase residual grep excludes this body because it IS the legacy source being redirected away from.

Meta-factory skill that architects and generates project-specific agent teams. Adapts the revfactory/harness 7-Phase workflow to MoAI's agent ecosystem. Produces hns-* skills and agent definitions tailored to each project's domain.

Upstream: revfactory/harness (Apache-2.0) — "A meta-skill that designs domain-specific agent teams, defines specialized agents, and generates the skills they use." (2905 stars, 420 forks, created 2026-03-26)

Effectiveness data (design target): +60% avg quality score (49.5 → 79.3), 15/15 win rate, −32% variance (n=15, author-measured A/B, third-party replications pending). Source: Hwang, M. (2026). "Harness: Structured Pre-Configuration for Enhancing LLM Code Agent Output Quality." revfactory/claude-code-harness.

---

Quick Reference

When to Use

• /moai project Phase 5+ runs and detects an absent .moai/harness/main.md
• AGENTS.md contains <!-- moai:harness-start --> markers (installed by the project-harness generation policy, not this skill)
• User explicitly requests harness generation for their project domain

Key Outputs

All generated artifacts use the hns- prefix — never moai-* (which is template-managed). The moai-harness-* prefix specifically denotes template-managed harness builders (moai-meta-harness, moai-harness-learner) and is NOT used by this generator's emissions.

6 Architectural Patterns (upstream)

Pipeline, Fan-out/Fan-in, Expert Pool, Producer-Reviewer, Supervisor, Hierarchical Delegation.

See phase walkthrough detail for pattern semantics and selection guidance.

---

Implementation Guide

7-Phase Workflow — Source Mapping

Each MoAI phase maps to upstream revfactory/harness phases (ref: https://github.com/revfactory/harness#workflow):

Phase Summaries

• Phase 1 (Discovery): manager-spec conducts 16-question Socratic interview (owned by the project-harness generation policy). Output: .moai/harness/answers.yaml
• Phase 2 (Analysis): manager-spec scans repo (file structure, existing agents/skills, dependency files, test coverage) — strategic analysis is absorbed into manager-spec
• Phase 3 (Synthesis): manager-spec produces SPEC with EARS requirements selecting one of 6 architectural patterns, defining agent roles, skill categories, acceptance criteria
• Phase 4 (Skeleton): This skill generates harness skeleton — main.md, agents.md, skills.md extensions, agent definition stubs
• Phase 5 (Customization): This skill fills the skeleton with domain-specific content referencing the retained MoAI agents (manager-*, builder-harness, sync-auditor) plus per-spawn Agent(general-purpose) domain delegations for domain-specific work
• Phase 6 (Evaluation): sync-auditor runs Sprint Contract protocol (design constitution §11.5) — 4 dimensions, pass threshold 0.75 (FROZEN floor 0.60)
• Phase 7 (Iteration): Owned by the harness-learning policy (out of scope for this skill)

See Phase 1-7 detailed walkthrough + agent involvement for full per-phase activity, inputs, outputs, and cross-reference notes.

MoAI Agent Cross-References

This skill orchestrates but does NOT replace existing agents. All named agents are retained MoAI agents — no new agents are introduced; domain-specific work is delegated via per-spawn Agent(general-purpose) with domain instructions. Categories: Planning & Strategy (manager-spec, plan-auditor), Implementation (manager-develop, plus per-spawn Agent(general-purpose) domain delegations), Builders (builder-harness with artifact_type=agent|skill|plugin), Workflow Managers (manager-develop, manager-docs, manager-git; quality gate via /moai gate or the sync-phase-quality-gate.sh Stop hook), Quality (sync-auditor).

See agent cross-references full inventory for per-agent role and phase mapping.

Generated Harness Validation

After Phase 5 (Customization) emits new hns-* skills, this meta-harness automatically hands off to sync-auditor using the Sprint Contract protocol (design constitution §11.5).

4-Dimension Sprint Contract Assessment:

Scoring:

• Pass threshold: 0.75 default (configurable via design.yaml pass_threshold)
• FROZEN floor: 0.60 (design constitution §2, immutable)
• Scoring rubric: sync-auditor rubric anchoring (design constitution §12, Mechanism 1)

For Phase 3b — Hierarchical Scoring (when harness.yaml sets evaluator_mode: hierarchical), see hierarchical scoring detail.

Design Target Reference: The +60% effectiveness figure from Hwang (2026) — 49.5 → 79.3 in a 15-run A/B study (author-measured, third-party replications pending) — is the design intent for this validation hook. The governing requirement explicitly states this does not require runtime measurement.

---