moai-meta-harness

# moai-meta-harness

<!-- @MX:NOTE: [AUTO] V3R4 contract — this skill body is preserved unchanged per SPEC-V3R4-HARNESS-001 §10 exclusion #10 (text annotation only, no behavioral change). The meta-harness 7-Phase workflow that generates project-specific moai-harness-* skills and .claude/agents/harness/* definitions is governed by REQ-HRN-FND-015 (orchestrator-only AskUserQuestion contract) — any subagent generated under .claude/agents/harness/ MUST NOT invoke AskUserQuestion; if user input is required, the subagent returns a structured blocker report and the orchestrator runs the AskUser round. Cross-reference: .claude/rules/moai/core/agent-common-protocol.md § User Interaction Boundary. -->

<!-- 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 SPEC-V3R3-HARNESS-001 for derivation history.
-->

> **Apache 2.0 Attribution**: Adapted from [revfactory/harness](https://github.com/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 SPEC-V3R3-HARNESS-001 for derivation history.

Meta-factory skill that architects and generates project-specific agent teams. Adapts the [revfactory/harness](https://github.com/revfactory/harness) 7-Phase workflow to MoAI's agent ecosystem. Produces `moai-harness-*` 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`
- CLAUDE.md contains `<!-- moai:harness-start -->` markers (installed by SPEC-V3R3-PROJECT-HARNESS-001, not this skill)
- User explicitly requests harness generation for their project domain

### Key Outputs

| Artifact | Location | Owner |
|----------|----------|-------|
| Harness config | `.moai/harness/main.md` + extension files | this skill |
| Agent definitions | `.claude/agents/harness/*.md` | this skill |
| Domain skills | `.claude/skills/harness-*/SKILL.md` | this skill |

All generated artifacts use the `harness-*` 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](references/seven-phase-workflow.md) 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):

| MoAI Phase | Upstream Harness Phase | Owning Agent | Inputs | Outputs |
|------------|------------------------|--------------|--------|---------|
| 1. Discovery | Phase 0 (audit) + Phase 1 domain analysis (Socratic) | manager-spec | User request | `answers.yaml` |
| 2. Analysis | Phase 1 domain analysis (codebase scan) | manager-spec + manager-strategy | `answers.yaml` + repo state | Analysis report |
| 3. Synthesis | Phase 2 team architecture design | manager-spec | Analysis report | SPEC doc with EARS |
| 4. Skeleton | Phase 3 agent definition generation | meta-harness (this skill) | SPEC doc | `.moai/harness/main.md` + extensions |
| 5. Customization | Phase 4 skill generation | meta-harness (this skill) | Skeleton | `.claude/agents/harness/*.md` + `.claude/skills/harness-*/SKILL.md` |
| 6. Evaluation | Phase 5 integration + Phase 6 validation | sync-auditor | Generated artifacts | Sprint Contract score |
| 7. Iteration | Harness Evolution Mechanism + Phase 7-5 ops | LEARNING-001 (separate SPEC) | Scoring deltas | Factory feedback (out of scope) |

### Phase Summaries

- Phase 1 (Discovery): `manager-spec` conducts 16-question Socratic interview (owned by SPEC-V3R3-PROJECT-HARNESS-001). Output: `.moai/harness/answers.yaml`
- Phase 2 (Analysis): `manager-spec` + `manager-strategy` scan repo (file structure, existing agents/skills, dependency files, test coverage)
- 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 existing MoAI agents (manager-*, expert-*, builder-harness, sync-auditor)
- 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 SPEC-V3R3-HARNESS-LEARNING-001 (out of scope for this skill)

See [Phase 1-7 detailed walkthrough + agent involvement](references/seven-phase-workflow.md) 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 agents referenced are static MoAI agents — no new agents are introduced. Categories: Planning & Strategy (manager-spec, manager-str