Agent Skills: moai-meta-harness (DEPRECATED — redirect to v4)

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.

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

| 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/hns-*/SKILL.md | this skill |

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):

| 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 | 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/hns-*/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 | the harness-learning policy (separate SPEC) | Scoring deltas | Factory feedback (out of scope) |

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:

| 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 the hns-* convention |

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.

Namespace Separation

[HARD] The Skills and Agents namespace splits cleanly into distributed and user-generated halves.

Distributed (template-managed)

The moai-* namespace — every prefix under it (moai-foundation-*, moai-workflow-*, moai-domain-*, moai-ref-*, moai-meta-*, moai-harness-*) — ships with moai-adk. moai update syncs it by removing and reinstalling, so any direct user edit is overwritten on the next update.

Harness assets in this namespace:

• moai-meta-harness (this skill — 7-Phase generator)
• moai-harness-learner (project-agnostic lifecycle-management builder)

User-Generated (this meta-harness emits)

The hns-* namespace and the .claude/agents/harness/ directory are user-owned. This meta-harness creates them during the /moai project Phase 5+ interview, tailored to the user's project domain. harness-* and my-harness-* are earlier generations of the same namespace; tooling still recognizes them as user-owned, but new artifacts use hns-*.

User-generated artifacts:

• .claude/skills/hns-<domain>/SKILL.md — domain-specific skill (e.g., hns-trading, hns-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 the hns- 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 user-owned skills or .claude/agents/harness/* files. Backup before update is mandatory.
• [HARD] The template tree MUST NOT contain user-owned skills or .claude/agents/harness/*-specialist.md files. Leak detection triggers a cleanup chore.
• [HARD] Distinguishing user-owned hns-* / harness-* from the template builder moai-harness-* requires an exact startsWith comparison. A *harness-* substring pattern is prohibited — it matches moai-harness-* too and produces false positives.
• [HARD] New artifacts carry hns-. Tooling also recognizes the earlier harness- and my-harness- prefixes as user-owned, so harnesses generated before the rename keep working; they are not rewritten automatically.

Generated-Agent Self-Activation Contract

[HARD] Each generated .claude/agents/harness/<role>.md agent MUST be emitted with both of the following frontmatter fields so the generated harness self-activates when the agent is delegated:

• A skills: frontmatter entry preloading the agent's companion harness-<domain>-* skill. This makes the domain skill load deterministically when the agent runs, rather than relying on auto-discovery which fails silently when the companion skill is absent from the agent's context.
• A non-empty, trigger-shaped description frontmatter field naming the domain + the observable task-shape, so the orchestrator's .moai/harness/main.md Task-Shape Routing table can dispatch to it.

Both fields are enforced at runtime by the Phase-6 post-generation smoke gate (moai doctor harness, see the project/meta-harness.md workflow Phase 7): a generated agent with an empty description, a dangling skills: reference (pointing at a non-existent hns-* dir), or NO skills: key at all causes the gate to FAIL. A skills:-less agent must not pass silently — that is the auto-discovery failure mode this contract closes. Full emission template + example: project/meta-harness.md § 6.4.1.

Storage Roots

| Namespace / Path | Location | Source | moai update behavior | |------------------|----------|--------|------------------------| | moai-* skills (incl. moai-harness-* builders) | ~/.claude/skills/moai-*/ | template | Removed and reinstalled (overwrite) | | hns-* skills (legacy: harness-*, my-harness-*) | .claude/skills/hns-*/ | user project (this meta-harness emits — intent declaration) | Never deleted or modified; backed up | | MoAI agents (retained catalog, FLAT) | ~/.claude/agents/ | template | Removed and reinstalled (overwrite) | | Generated harness agents | .claude/agents/harness/ | user project (this meta-harness emits) | Never deleted or modified; backed up | | Harness config | .moai/harness/ | user project | Never deleted; backed up |

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. AGENTS.md contains <!-- moai:harness-start --> markers. These markers are installed by the project-harness generation policy 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, sync-auditor
• 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 the project-harness generation policy. The separation is intentional:

• This skill = capability (what to do and how)
• the project-harness generation policy = 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 the project-harness generation policy. The integration with /moai project phases, hook installation, and AGENTS.md marker management are all delegated to that SPEC.
• 16-question Socratic interview — owned by the project-harness generation policy. The manager-spec conducts the interview under that SPEC's control.
• Auto-evolution loop — owned by the harness-learning policy. 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 hns-* 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
• sync-auditor — Sprint Contract evaluation in Phase 6
• builder-harness (artifact_type=agent|skill|plugin) — Artifact generation helper

Upstream: revfactory/harness (Apache-2.0) | MoAI adaptation: the harness policy | v4 supersession: the v4 harness Builder redesign See .claude/rules/moai/NOTICE.md for full Apache 2.0 attribution.