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

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

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

Generated Output

your-project/
├── .claude/
│   ├── agents/          # agent definitions (analyst.md, builder.md, qa.md …)
│   └── skills/          # skills (each SKILL.md + references/)
├── 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// and .codex/agents/.toml are emitted alongside the .claude/ output (same source of truth). 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:

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/              # factory-map · agent-design-patterns · orchestrator-template ·
│   │                            #   external-review-loop · tdd-doctrine · dev-rules ·
│   │                            #   runtime-adapters · harness-update · loop-self-eval, etc.
│   └── scripts/                 # check-review-tools · build-scorecard · harness-update
├── 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.

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. 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 UI-launched runs only; 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.

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

⚠️ 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

License

Apache 2.0