myharness — The Agent-Team Architecture Factory

English | 한국어 | 日本語

myharness is a Claude Code · Codex dual-runtime factory that turns a single sentence about your domain into an agent team and skills. Just say "Build a harness for this project" — it analyzes your domain and stamps out specialized agent definitions (.claude/agents/) and skills (.claude/skills/), picking whichever of the 6 team architecture patterns fits.

---

What is myharness?

When you tackle a complex job with one giant prompt, context gets polluted, the same blind spots repeat, and nothing is reusable. myharness decomposes that job and generates it as a team of specialized agents with separated roles + skills that carry the procedures + an orchestrator that weaves them together.

• Input: a single sentence about your domain (e.g., "deep research", "full-stack web development", "code review")
• Output: agent definitions + skills + an orchestrator skill + entry pointers (CLAUDE.md/AGENTS.md)
• Characteristics: Korean-first · slim by default (gates tighten only as risk rises) · outputs for both Claude Code and Codex

myharness itself is a meta skill (plugin), and it treats itself as a system that evolves — it feeds execution feedback back into the appropriate layer (skill/agent/orchestrator) and leaves a change history.

Quick Start

1. Install (pick one)

Marketplace (recommended)

/plugin marketplace add cookyman74/my_harness
/plugin install myharness@myharness-marketplace

Copy directly as a global skill

cp -r skills/myharness ~/.claude/skills/myharness

Codex CLI (dual runtime) — from the repo root:

bash install.sh
# → ~/.codex/skills/myharness  (symlink to the source of truth, always up to date)
# → .agents/skills/myharness   (for trusted projects)
# → AGENTS.md                  (auto-loaded by Codex)

2. Turn on agent teams + start the CLI (Claude Code)

export CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1
claude   # start the Claude Code CLI (for Codex, use the codex command)

3. Triggers

• Claude Code: Build a harness for this project · /myharness · Design an agent team for this domain
• Codex: $myharness · the /skills menu · Build a harness (description matching). A session restart after install is recommended. (Codex doesn't support custom slash commands — /myharness is unavailable.)

Copy-paste examples by domain → Example Prompts

Core Features

Feature	Details
6 team architectures	Pipeline · Fan-out/Fan-in · Specialist pool · Generate-and-verify · Supervisor · Hierarchical delegation. Picks the pattern that fits the domain
Configuration interview	Phase 0.5 asks for the harness premises up front — completion criteria · irreversibility · failure cost · approval points · existing assets — and records them in a profile. scripts/harness-intake.mjs (scan·questions·answer·render·verify) renders the answers into 5 wiring blocks (completion·tier·approval·assets in the orchestrator skill, premise in CLAUDE.md/AGENTS.md), and verify fails Phase 6 when any block is missing, stale, or hand-edited. Non-interactive runs fall back to safe defaults and report every ASSUMED: item. Contract: references/harness-interview.md
Agent teams by default	Spawn teammates with the Agent tool, communicate directly via SendMessage, and self-coordinate through a shared task list (TaskCreate). Quality rises through shared findings and debating disagreements
Automatic skill generation	Progressive Disclosure (staged loading: metadata → body → references) for context efficiency. Trigger descriptions are written aggressively
Two-layer quality gate	Internal generate-and-verify QA + an external independent review loop. The launcher is a script file, scripts/run-review.sh (stage lock · REVIEWERS_OVERRIDE · REVIEW_TIMEOUT), never inline shell. Any shrinking of the reviewer set is recorded as degraded and the stage closes with an explicit label — degraded-accepted / degraded-override / degraded-blocked by risk tier — so a reduced review fails closed instead of passing quietly. Details below
Doctrine injection	Injects TDD (tdd-doctrine.md) and dev rules (dev-rules.md) into the working principles of coding/editing agents via real paths. Includes (RED verified before GREEN; only contract/schema/security tests go to external cross-review) and a (destructive dropped). Risk tiers (light/standard/critical) tune gate strength

Two-Layer Quality Gate (code/design domains)

Internal QA runs in the same session and the same context, so it shares the same blind spots. That's why an external independent AI review is placed on a separate axis.

• Engine diversity — reviewers are chosen by excluding the runner engine (same engine = same blind spots). When running on Claude Code, codex+agy; when running on Codex, claude+agy. (agy = a Gemini model)
• Direct verdict on every item — external reviewers don't know the design decisions, frozen contracts, or actual measurements, so the orchestrator judges every reported issue against the real code as confirmed/partial/deferred/rejected. Consensus is not the answer; verdict authority stays with the orchestrator (no delegation).
• Convergence loop — loop-until-dry (zero new issues for K consecutive rounds) + a round cap, a verdict ledger (verdicts.json, prevents reappearance), and re-review of the fix. Only confirmed items are fixed via TDD.
• Skip when tools are absent — check-review-tools.sh produces a runner-excluded REVIEWERS: list; if no external reviewer exists, the gate shrinks to internal QA (avoids a non-functional skill).
• SHADOWED: — installed but off PATH — the same script emits a four-line contract (AVAILABLE: · RUNNER: · REVIEWERS: · SHADOWED:), reporting a reviewer that is installed but sits outside PATH as name=path instead of silently calling it missing. It does not inject the path for you — that stays your decision.
• Reduced review is recorded, not hidden — when the reviewer set shrinks (one reviewer only · a missing axis · an off-PATH install · a runtime failure · a failed self-verification), the reason is written into _review_status.json under degraded and carried through to the result document. A reviewer that exits 0 without the required verdict marker is counted as suspect — a failure, not a pass. The stage then closes with one of degraded-accepted / degraded-override / degraded-blocked according to risk tier.

This README is verified through that gate too — committed after an external audit by codex (consistency) + agy (performance & stability).

How It Works — Skills ↔ Agents

A generated harness separates who from how:

• Agent = who — an expert persona + working principles. Defined as a .claude/agents/{name}.md file (no inlining → reusable across sessions). 1 agent = 1 role.
• Skill = how — procedures + bundled tools. skills/{name}/SKILL.md. One agent uses 1–N skills (shareable).
• Orchestrator = who, when, in what order — weaves individual agents/skills into a single workflow.
• Data passing — messages (real-time coordination) + a shared task list (progress tracking) + files (_workspace/, large payloads & audit trail). Result documents keep judgment continuous across stages via a ## Next-step reference block.
• Why-first · DRY pointers — instead of forcing "ALWAYS/NEVER", explain the why (sharpens judgment on edge cases) and reference a single source (no duplication).

In short: the orchestrator decides who/when/order, the agents are the who, the skills are the how, and the two-layer gate protects quality.

7-Phase Workflow

Phase 0  Status audit (check existing harness for drift · branch into new/extend/maintain/update)
Phase 0.5  Configuration interview (completion criteria · risk tier · approval gates · existing assets → profile)
Phase 1  Domain analysis (task type · conflicts with existing assets · detect user skill level)
Phase 2  Team architecture design (execution mode + choice among the 6 patterns)
Phase 3  Generate agent definitions (.claude/agents/ · doctrine injection)
Phase 4  Generate skills (.claude/skills/ · Progressive Disclosure)
Phase 5  Integration & orchestration (+ two-layer quality gate · dual-runtime output · CLAUDE.md pointers)
Phase 6  Validation & testing (trigger verification · dry run · with/without comparison)
Phase 7  Harness evolution (feedback loopback · runtime synchronization · built-harness update)

Read first: skills/myharness/references/factory-map.md — a map of minimal paths by domain/risk. Slim by default — external review, TDD, and evaluation are turned on only as risk rises (avoids overburdening a simple harness).

Execution Modes & Architecture Patterns

Execution mode	Tools	Best for
Agent team (default)	Agent (spawn teammates) + SendMessage + TaskCreate	2+ collaborators, real-time coordination & feedback
Sub-agents	Direct Agent tool calls (run_in_background for parallelism)	One-off work, no inter-agent communication needed
Hybrid	Mix team/sub per phase	When phases have different characteristics

Architecture pattern	Description
Pipeline	Sequentially dependent tasks
Fan-out/Fan-in	Parallel independent tasks, then merge
Specialist pool	Selective invocation by situation
Generate-and-verify	Generate, then quality-check (retry loop)
Supervisor	A central agent distributes work dynamically
Hierarchical delegation	Recursive top → bottom delegation

Generated Output

your-project/
├── .claude/
│   ├── agents/          # agent definitions (analyst.md, builder.md, qa.md …)
│   └── skills/          # skills (each SKILL.md + references/)
│       └── <orchestrator>/harness-profile.json   # Phase 0.5 interview profile
├── .agents/behaviors/   # <name>/BEHAVIOR.md (optional behavior specs)
├── .harness-manifest.json   # file hashes used by /myharness update
├── CLAUDE.md            # Claude Code entry pointer
└── AGENTS.md            # Codex entry pointer (when dual runtime)

Dual-runtime output: If Codex is also a target, .agents/skills/<name>/ and .codex/agents/<name>.toml are emitted alongside the .claude/ output (same source of truth). The interview profile stays at .claude/skills/<orchestrator>/harness-profile.json only — it is not duplicated into the .agents/ copy. Details: skills/myharness/references/runtime-adapters.md.

Dual Runtime (Claude Code + Codex)

The source of truth (skill body · references · scripts) is runtime-agnostic Markdown. Only the adapter branching differs:

Concern	Claude Code	Codex CLI
Entry point	.claude-plugin/plugin.json + CLAUDE.md	AGENTS.md (auto-loaded)
Skills	.claude/skills/	.agents/skills/ (same format)
Agents	.claude/agents/*.md	.codex/agents/*.toml ⚠️ + built-in worker/explorer
Orchestration	Agent teammate spawn + SendMessage + TaskCreate	native subagents / codex exec subprocess
External reviewers	codex + agy (runner claude excluded)	claude + agy (runner codex excluded)

agy (antigravity, a Gemini model) is not a host runtime — it's dedicated to external review only. Details: skills/myharness/references/runtime-adapters.md.

⚠️ Codex custom agents load in interactive sessions only. .codex/agents/*.toml is not name-invocable from tool-backed sessions such as codex exec (upstream openai/codex#15250, still open). Skills and AGENTS.md do load. So a harness driven through codex exec runs the orchestrator skill alone, without the agent-team layer.

Example Prompts

After install, paste these straight into Claude Code (or Codex):

Deep research

Build a harness for deep research. I need an agent team that investigates a topic from
multiple angles — web search, academic sources, community sentiment — then cross-verifies
and produces a comprehensive report.

Full-stack web development

Build a harness for full-stack web development. I'd like a team where design · frontend
(React/Next.js) · backend (API) · QA collaborate as a pipeline from wireframe to deployment.

Webtoon production

A harness for producing webtoon episodes. I need agents for story · character prompts ·
panel layout · dialogue editing, and have them review each other's output for style consistency.

Code review & refactoring

A harness for comprehensive code review. I want a team that checks architecture · security
vulnerabilities · performance bottlenecks · code style in parallel, then merges every finding
into a single report.

Data pipeline design

A harness for data pipeline design. I need an agent team that hierarchically delegates
schema design · ETL logic · validation rules · monitoring setup.

AIOps — PaaS operations (Kubernetes) — one example showing model routing · slim path · a safety gate

Build a harness for PaaS operations management.
- Domain: stable Kubernetes cluster ops (collect → diagnose → remediate → report)
- Environment: single-node kind, kubectl context=docker-desktop, no metrics-server
- Agents: state-collector (read-only), root-cause-diagnoser, remediation-applier, health-reporter
- Risk: ops / non-code → slim path (skip external review · TDD · evaluation)
- Runtime: Claude Code only
- Models: high-reasoning (diagnose/remediate)=opus, collect=haiku, report=sonnet
- Safety gate (kept as a version-controlled procedure in the k8s-remediate skill body):
  evaluate 5 checks before applying any change; apply only if ALL pass. If ANY
  fails, stop and hand off to a human.
    1) Blast radius  2) Rollback  3) Approval  4) Timing  5) Tenant scope
  Put thresholds in references/thresholds.md (do not hard-code numbers in the body).

Plugin Structure

my_harness/
├── .claude-plugin/plugin.json   # manifest (name: myharness)
├── skills/myharness/
│   ├── SKILL.md                 # main skill (7-phase workflow)
│   ├── references/              # 17 docs — factory-map · agent-design-patterns · orchestrator-template ·
│   │                            #   external-review-loop · tdd-doctrine · dev-rules · behavior-specs ·
│   │                            #   runtime-adapters · harness-update · harness-interview · loop-self-eval ·
│   │                            #   self-improvement-loop · harness-scorecard · skill-writing-guide, etc.
│   └── scripts/                 # 13 scripts — harness-intake.mjs · selftest-harness-intake.mjs ·
│                                #   check-review-tools · selftest-review-tools · run-review ·
│                                #   run-policy-audit · check-behaviors · check-artifacts ·
│                                #   run-benchmark · grade-trajectory · build-scorecard ·
│                                #   emit-loop-scorecard · harness-update
├── tests/                       # contract & regression tests
├── .github/workflows/factory-ci.yml   # policy audit + tests on Linux and Windows
├── AGENTS.md                    # Codex entry point
├── install.sh                   # dual-runtime install
└── README.md / README_KO.md / README_JA.md

Where It Sits in the Ecosystem

myharness lives at the meta-factory layer of the Claude Code agent ecosystem — the side that generates other harnesses. Its role differs from adjacent layers, so you can pick one or combine them.

Neighbor	Their role	Relationship to myharness
coleam00/Archon	A factory for deterministic, reproducible runtime configuration	Same meta layer, different sub-area. Archon = runtime determinism, myharness = team architecture. Combinable (design with myharness → deploy with Archon)
LangGraph	State-graph orchestration, LLM-agnostic	A different track. LangGraph = long-running & state recovery, myharness = fast, Claude Code-native team design
wshobson/agents	A catalog of subagents/skills	Parts supply ↔ factory. Pick parts from the catalog and absorb them into the team myharness designs

Companion: My Harness Web

A local web app that observes and controls a built harness. It reads the file state under _workspace/runs/** and surfaces inventory, executions, history, documents, drift, evaluation, and harness composition on one screen — the things the CLI can't show at a glance. It also auto-builds a whole harness from a single domain sentence (draft → human review → create).

• Run: cd harness-ui && npm install && npm start — builds, serves a single origin on 127.0.0.1:5174, and opens the browser with a one-time (fragment) token. Dev mode: npm run dev.
• Features (by wave, all implemented & live · harness-web 0.9.0):
  • v0.5 core — supervisor · OS adapters · security · launcher (certified).
  • v0.6 — F2 prefill New Run · F3 projectRoot edit · F4 history · F5 doc/artifact viewer · F6 observability · F7 definition editor · F8 Eval dashboard · F9 Docs sources · F10 harness context.
  • v0.7–v0.8 multi-runtime — F11 factory maintenance · F12 runtime-adapter registry · F13 multi-runtime read · F14 Gemini md edit · F15 Codex TOML edit (strict parse · injection-safe) · F16 tri-runtime skill sync · F17 install matrix (agy 4-state auth). Manage claude/codex/gemini harnesses from one tool.
  • v0.9 — Eval v1 (4-axis artifact scoring, see below) + batch remediation (M-y): turn #/eval findings into AI drafts across many definitions → review queue → bulk apply, capped by a global run governor. Adds BEHAVIOR diagnostics — a broken behaviors: reference surfaces as a dead_link, an unreferenced spec as an orphan with subject_kind: "behavior" (reusing the existing finding types, no new one) — and a deletion-guard adapter that blocks auto-applied deletions unless every layer agrees: required-section/constraint wording, the four preserved BEHAVIOR dimensions (Evidence · Decision · Recovery · Failure modes), a semantic judge that positively confirms "no correspondence", and a dynamic test gate. Missing any of them means uncertain → suggest only, never auto-apply. Each critical milestone converged under external audit (codex + agy, no-high twice).
  • Plus config-centric self-evaluation (harness_scorecard, adoption-stage gate) and whole-harness auto-build.
• Screens (11, grouped sidebar): Overview · Harness / Agents / Skills / Context / History · Docs · Runs / Drift / Ops / Eval · Settings. Flow: domain → Harness auto-build (draft → create) or New Run → run created → observe (fire-and-observe).
• Security & scope: local 127.0.0.1 only · token bootstrap → session · read-first (the only mutating paths are definition editing, projectRoot, eval config, and harness build — whitelisted, atomic, gated off by default; auto-build runs no-tools isolated exec with no auto-apply). History/stats reflect ; terminal CLI runs are out of scope until v0.7 (CLI session-log observability).

Eval — how each agent/skill is scored (#/eval)

The Eval screen grades every agent and skill on four axes plus relationship health. Each axis is 0.0–1.0; the grade is a weighted average — A ≥ 0.90 · B ≥ 0.75 · C ≥ 0.60 · D < 0.60 — with a min-gate: a structural failure (e.g. a 500-line body with zero references/) caps the grade at D so a good prose score can't launder a broken structure.

Axis	What & why it measures	Weight (machine + judgment)
Trigger	description ROI — does the description justify its always-on context cost? States (a) what it does, (b) concrete trigger situations, (c) near-miss cases where it must not fire.	0.4 machine + 0.6 judgment
Structure	two-layer architecture — body keeps only the procedure (≤ 500 lines); conditional/bulky material moved to references/.	0.7 machine + 0.3 judgment
Induction	next-action steering — imperative voice, "why" rationale, and leading words that clearly steer the agent's next move (vs vague description).	0.3 machine + 0.7 judgment
Pruning	deletion test [core] — "if this sentence were deleted, would behavior change?" No = filler. Score = 1 − deletion-candidates / total. A completeness guard protects required sections (trigger conditions · error handling · core constraints) from over-pruning.	machine + conservative judgment

Relationship health (graph signals the four axes can't see): orphans (unwired definitions) · dead links · coverage gaps · drift (skill-copy mismatch) — folded into the score as penalties.

Current limitation — read it as advisory. Only the static layer (machine · deterministic · regex/density) is active; confidence is deliberately low (0.45–0.5). The semantic-judgment layer (LLM) and cross-verification are follow-ups. Nothing is auto-applied — findings feed the definition editor where a human reviews the diff before saving (or the batch review queue for many at once).

Full rubric, weights, and rationale → docs/harness-eval/design/eval-v1-design.md.

Detailed docs

• App package & dev guide → harness-ui/README.md
• Docs hub (design · PRD · acceptance criteria · audit history) → docs/harness-ui/
• v0.6 design (implemented) → docs/harness-ui/v0.6/design/design-v0.6.md · PRD → docs/harness-ui/v0.6/prd/
• v0.7 plan (CLI session-log observability) → docs/harness-ui/v0.7/

A distinct sub-project from the factory: the factory generates harnesses; My Harness Web operates one (and can auto-build one). Its own version line (v0.5/0.6) is separate from the factory version above.

Requirements

• Claude Code: enable agent teams — CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1
• Node.js 20+ (required): the policy audit's node --check and the intake self-test FAIL (they are not downgraded to warnings) when node is absent, and the factory CI pins node 20
• External review (optional): at least one of the codex/claude/agy CLIs excluding the runner (if agy is missing it falls back to the legacy gemini; if none are present the gate is auto-skipped). An installed CLI that sits outside PATH is reported as SHADOWED: rather than counted as missing

⚠️ Cost warning: In an agent team each teammate is an independent Claude instance, so by the nature of its parallel/shared-context structure the API token cost can climb quickly compared to a single prompt. In cost-sensitive environments, use sub-agent mode (returning only the run_in_background result) or turn agent teams off. myharness mitigates this with model routing, a concurrency cap, and an external-review budget.

Known limitations (experimental): Agent teams are an experimental Claude Code feature. There are limitations such as no --resume restoration, task status lag, and zombie processes in tmux mode — so myharness is designed to checkpoint intermediate output into _workspace/, require completion reports via SendMessage, and request an explicit shutdown on exit. Details: skills/myharness/references/agent-design-patterns.md.

FAQ

A. Both Claude Code and Codex (dual runtime). A single source of truth (skills/myharness/) + a thin per-runtime adapter. Claude Code is the most automated primary runtime (Agent teammate spawn); Codex is supported via AGENTS.md + .agents/skills/ + native subagents / codex exec ($myharness or /skills). Gemini is not a host — it's used only as an external reviewer (via agy). Details: skills/myharness/references/runtime-adapters.md.

A. No. Slim by default. Simple/non-code/reversible work uses internal QA only; standard code/design gets one external review pass; only contract changes and irreversible critical work get external review at every stage plus an approval ladder. Risk tiers tune the strength (skills/myharness/references/factory-map.md).

A. No. /myharness update classifies files by .harness-manifest.json hashes and holds USER-MODIFIED ones (replaced only with explicit approval, no partial merge). If you separate your own policy into *.local.* files, updates stay safe. Details: skills/myharness/references/harness-update.md.

License

Apache 2.0