moai-meta-harness

name	moai-meta-harness
description	Meta-harness skill that designs project-specific agent teams and generates the skills they use. Adapts the revfactory/harness 7-Phase workflow to MoAI's agent ecosystem. Triggered by /moai project Socratic interview and produces dynamic harness-* skills + .claude/agents/harness/* + .moai/harness/* artifacts.
license	Apache-2.0
compatibility	Designed for Claude Code (v2.1.111+)
allowed-tools	Read, Write, Edit, Grep, Glob, Bash
user-invocable	false
metadata	{"version":"0.1.0","category":"meta","status":"active","updated":"2026-04-27","modularized":"false","tags":"meta-skill, harness, project-init, agent-team-architect, apache-2-0-attribution","upstream_source":"revfactory/harness","generated_by":"moai-adk"}
progressive_disclosure	{"enabled":true,"level1_tokens":100,"level2_tokens":5000}
triggers	{"keywords":["harness","project-init","meta-skill","agent-team","harness-evolve"],"agents":["manager-spec","manager-strategy","evaluator-active"],"phases":["plan","run","sync"]}

moai-meta-harness

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

Meta-factory skill that architects and generates project-specific agent teams. Adapts the 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 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	evaluator-active	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, evaluator-active)
• Phase 6 (Evaluation): evaluator-active 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 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-strategy, plan-auditor), Implementation (expert-*, manager-develop, manager-quality), Builders (builder-harness with artifact_type=agent|skill|plugin), Workflow Managers (manager-develop, manager-quality, manager-docs, manager-git), Quality (evaluator-active).

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

Generated Harness Validation

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

4-Dimension Sprint Contract Assessment:

Dimension	What is Checked
Functionality	Agent definitions execute their stated purpose; skills have valid trigger conditions
Security	No credentials in generated files; tool permissions follow least-privilege
Craft	YAML frontmatter valid (CSV allowed-tools, quoted metadata); progressive disclosure configured
Consistency	Domain alignment with answers.yaml; naming follows moai-harness-* convention

Scoring:

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

For Phase 3b — HRN-003 Hierarchical Scoring (when harness.yaml sets evaluator_mode: hierarchical), see HRN-003 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. REQ-HARNESS-009 explicitly states this REQ does not require runtime measurement.

---

Namespace Separation

[HARD] Skills + Agents namespace는 "범용 배포" vs "사용자 생성" 으로 명확히 분리된다.

Distributed (template-managed)

moai-* namespace (모든 prefix 포함: moai-foundation-*, moai-workflow-*, moai-domain-*, moai-ref-*, moai-meta-*, moai-harness-*) is moai-adk distributed. moai update 가 sync (삭제 후 신규 설치). 사용자 직접 수정은 다음 update로 overwrite.

본 namespace의 하네스 자산:

• moai-meta-harness (this skill — 7-Phase generator)
• moai-harness-learner (lifecycle 관리 빌더, project-agnostic)

User-Generated (this meta-harness emits)

harness-* namespace and .claude/agents/harness/ directory are user-owned. Created by this meta-harness during /moai project Phase 5+ interview, tailored to the user's project domain.

User-generated artifacts:

• .claude/skills/harness-<domain>/SKILL.md — domain-specific skill (e.g., harness-trading, harness-llm-cascade)
• .claude/agents/harness/<role>.md — agent definition (e.g., .claude/agents/harness/trading-specialist.md)
• .moai/harness/main.md — harness entry point + extensions

Contract

• [HARD] This meta-harness MUST emit user-generated skills with harness-* prefix ONLY. Emitting a moai-* (including moai-harness-*) prefixed file during Phase 4 or 5 is a contract violation.
• [HARD] moai update MUST NOT delete, modify, or sync harness-* skills or .claude/agents/harness/* files. Backup before update is mandatory.
• [HARD] Template (internal/template/templates/) MUST NOT contain harness-* skills or .claude/agents/harness/*-specialist.md files. Leak detection triggers cleanup chore.
• [HARD] harness-* (user-owned) vs moai-harness-* (template builder) substring 구분: prefix 매칭은 정확한 startsWith 비교를 사용 (*harness-* substring 패턴은 false positive 위험으로 금지).
• [HARD] Doctrine-code drift (2026-05-26 ~ catch-up SPEC 완료 전): 본 namespace 정책은 harness-* declaration이지만 Go enforcement (update.go / prefix_conflict.go / test fixtures)는 my-harness-* 작동 유지. 새 harness-* prefix로 실제 generation 금지 — protection 없음. catch-up SPEC 완료 후 generator runtime behavior가 harness-*로 전환. SSOT 참조: the harness namespace separation policy (maintainer doctrine).

Storage Roots

Namespace / Path	Location	Source	moai update 동작
moai-* skills (incl. moai-harness-* builders)	.claude/skills/moai-*/	template	삭제 후 신규 설치 (overwrite)
harness-* skills	.claude/skills/harness-*/	user project (this meta-harness emits — intent declaration, actual emission deferred to catch-up SPEC)	절대 삭제/modify 금지 + 백업 보존
MoAI agents (retained 7, FLAT)	.claude/agents/moai/	template	삭제 후 신규 설치 (overwrite)
Generated harness agents	.claude/agents/harness/	user project (this meta-harness emits)	절대 삭제/modify 금지 + 백업 보존
Harness config	.moai/harness/	user project	절대 삭제 금지 + 백업 보존

Cross-References

• .claude/skills/moai-meta-harness/SKILL.md § Namespace Separation (this file — canonical generator-side namespace contract)
• .claude/rules/moai/development/skill-authoring.md § Skills Namespace Policy
• .claude/rules/moai/development/agent-authoring.md § Agent Directory Convention

---

Trigger Mechanics

Auto-load Conditions:

1. /moai project Phase 5+ runs and .moai/harness/main.md is absent
2. CLAUDE.md contains <!-- moai:harness-start --> markers. These markers are installed by SPEC-V3R3-PROJECT-HARNESS-001 during project initialization; this skill does not install them.

Frontmatter Triggers:

This skill loads when any of the following match:

• Keywords: harness, project-init, meta-skill, agent-team, harness-evolve
• Agents: manager-spec, manager-strategy, evaluator-active
• Phases: plan, run, sync

Deferred Execution Contract:

This skill provides the workflow recipe and agent cross-references. It does NOT execute /moai project Phase 5+ logic — that invocation is owned by SPEC-V3R3-PROJECT-HARNESS-001. The separation is intentional:

• This skill = capability (what to do and how)
• PROJECT-HARNESS-001 = invocation wiring (when to do it)

---

Out of Scope

The following capabilities are explicitly NOT implemented by this skill:

• 5-layer integration mechanism — owned by SPEC-V3R3-PROJECT-HARNESS-001. The integration with /moai project phases, hook installation, and CLAUDE.md marker management are all delegated to that SPEC.
• 16-question Socratic interview — owned by SPEC-V3R3-PROJECT-HARNESS-001. The manager-spec conducts the interview under that SPEC's control.
• Auto-evolution loop — owned by SPEC-V3R3-HARNESS-LEARNING-001. The learning feedback mechanism (Phase 7) and delta capture are separate work items outside Wave A.
• Modification of .claude/agents/{moai,harness}/ or static moai-* skills — this meta-harness generates only moai-harness-* prefixed artifacts and has no write access to MoAI's own agent/skill directories.

---

Works Well With

• moai-foundation-core — SPEC-First DDD and TRUST 5 quality gates
• moai-foundation-cc — Claude Code skill/agent authoring standards
• manager-spec — Conducts Discovery and Synthesis phases
• evaluator-active — Sprint Contract evaluation in Phase 6
• builder-harness (artifact_type=agent|skill|plugin) — Artifact generation helper

---

Upstream: revfactory/harness (Apache-2.0) | MoAI adaptation: SPEC-V3R3-HARNESS-001 See .claude/rules/moai/NOTICE.md for full Apache 2.0 attribution.