--- name: modu-ai/moai-meta-harness source: https://app.decimal.ai/s/modu-ai-moai-meta-harness@2/SKILL.md source_sha256: 08d0317451f8 --- # moai-meta-harness (DEPRECATED — redirect to v4) > **DEPRECATION NOTICE** — This legacy 7-Phase meta-harness is > **superseded by the v4 harness Builder** (`/moai:harness 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--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 ` > (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 > ``, 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](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 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 ` 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 `` 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 `. **Harness execution**: `/harness:` (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 ` (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](https://github.com/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` - CLAUDE.md contains `` 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](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 | `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](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 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](references/agent-cross-references.md) 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](references/hierarchical-scoring.md). **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-/SKILL.md` — domain-specific skill (e.g., `hns-trading`, `hns-llm-cascade`) - `.claude/agents/harness/.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/.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--*` 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/moai/` | 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. CLAUDE.md contains `` 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 CLAUDE.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.*