Harness v2: A Factory for Designing Claude Code Agent Teams

What Harness Is and Who It Is For

Harness is a Claude Code plugin that functions as a team-architecture factory. The core interaction is simple: a developer describes their domain in a sentence or two, and Harness produces a set of agent definition files (.claude/agents/), skill files (.claude/skills/), and an orchestrator that specifies when each agent and skill runs. The README summarizes this as: one sentence triggers a design process that turns a domain description into an agent team and the skills they use.

The intended users are developers who work on multi-agent workflows in Claude Code and find themselves repeatedly making the same architecture decisions: how many agents, which one orchestrates, how they communicate, and what skills they need. Harness encodes those decisions into a structured process so developers can focus on domain-specific requirements rather than plumbing.

Harness v2 was rebuilt from scratch. Version 1 relied on the TeamCreate API, which no longer exists in the current Claude Code runtime. V2 targets the three execution modes that actually ship: Workflow orchestration, persistent agent collaboration with SendMessage, and one-shot sub-agent delegation.

The Three Execution Modes

The factory assigns execution modes based on the shape of the control flow, not on team size. The README documents the decision logic as a table.

Workflow orchestration uses Workflow scripts with pipeline() and parallel() primitives. It is appropriate when control flow is deterministic: enumerable fan-outs, verification loops, large-scale runs, and structured outputs. This mode produces the most reproducible and auditable execution paths.

Persistent agent collaboration uses named Agent calls with SendMessage and shared task lists. It suits long-lived specialists that need to retain context across turns, or iterative workflows involving feedback and negotiation between agents. The agents keep their context window populated with the conversation history.

Sub-agent delegation is the lightest mode: one-shot Agent calls that fire and return results without persistence. This is appropriate for parallel work that is fully independent and where only the final output is needed.

The factory can mix modes within a single harness when different phases of a workflow have different control-flow shapes. A harness for a code review pipeline might use Workflow orchestration for the parallel review phase and persistent agents for the iterative feedback phase.

Installing Harness and Running the Factory

Harness can be installed through the Claude Code marketplace:

/plugin marketplace add revfactory/harness
/plugin install harness@harness-marketplace

Alternatively, the skill files can be copied directly into the global Claude skills directory:

cp -r skills/harness ~/.claude/skills/harness
cp -r skills/evolve ~/.claude/skills/harness-evolve

No environment variables or experimental flags are required. Once installed, running the factory requires only a natural language description:

build a harness for this project

or in Korean:

하네스 구성해줘

After a harness has been used and improved, the evolution command updates it based on feedback:

evolve the harness with this feedback

The README also documents the domain-specific trigger: `design an agent team for <domain>`.

The Seven-Phase Design Workflow

Harness runs through a seven-phase process when generating a harness. Phase 0 audits any existing harness, detecting v1 artifacts such as TeamCreate calls or experimental flags and offering a migration path. Phase 1 analyzes the domain, including the control-flow shape of the work. Phase 2 selects an execution mode and team architecture pattern from the six available patterns.

The six architecture patterns are Pipeline, Fan-out/Fan-in, Expert Pool, Producer-Reviewer, Supervisor, and Hierarchical Delegation. Each is mapped to its best execution mode in the factory's decision logic.

Phase 3 generates agent definitions in .claude/agents/. Phase 4 generates skill files in .claude/skills/. Phase 5 handles orchestration: data-passing protocols, error handling, and resume support. Phase 6 is verification: trigger evals, dry runs, and A/B testing with and without the skill. Phase 7 is maintenance, handled through the /harness:evolve command.

The generated CLAUDE.md file contains a minimal pointer with a trigger rule and change history rather than a full specification, which keeps it from growing into a context-window burden.

Evolution and Feedback Loops with harness:evolve

The /harness:evolve command captures the difference between the initial harness design and the current state after actual use. It generalizes the feedback into changes for the agents, skills, and orchestrators, and feeds the improvements back into the harness. The README describes this as capturing the delta, generalizing feedback, and applying measurable next-generation improvements.

This mechanism addresses a common problem with generated configurations: they are designed for the expected workflow but the actual workflow reveals gaps once real tasks are run. Most code generation tools do not have a built-in feedback loop. Harness treats the initial design as a first draft and /harness:evolve as the iteration mechanism.

The v1 documentation mentioned an evolution mechanism but did not implement it. The README explicitly distinguishes this as a feature that v1 only documented while v2 actually ships it.

Limitations and When Harness Is Not the Right Tool

Harness is most valuable for workflows that have genuine multi-agent complexity: fan-outs, verification loops, iterative feedback between specialists, or large-scale parallel work. For a workflow that amounts to running one agent to complete one task, the seven-phase design process adds overhead without corresponding benefit.

The v1 A/B test cited in the README (mean quality 49.5 to 79.3, 15/15 win rate, minus 32% variance, n=15) was author-measured and based on v1 rather than v2. The README itself recommends running a pilot for adoption decisions. These numbers should be treated as directional evidence rather than a validated benchmark.

V1 harnesses require migration before they work with v2. The factory automates that migration when it detects v1 artifacts in Phase 0, but teams with large existing v1 harnesses should plan for a review step to verify that the automated migration produced the intended behavior.

Harness v2 vs. Writing Agent Definitions by Hand

Writing agent definitions manually requires understanding the Claude Code agent file format, knowing which execution mode fits the workflow, and making all architecture decisions without a structured decision framework. The output is the same artifact type: .claude/agents/ and .claude/skills/ files.

Harness produces the same artifacts faster, with a decision process that is consistent across domains. The trade-off is that the factory makes design choices that a domain expert might override. For unusual workflows or workflows with specific performance requirements, manual design may produce a more tailored result.

The sane model policy introduced in v2 is one concrete improvement over manual work. V1 pinned every agent to the Opus model regardless of task complexity. V2 selects a tier per agent (fable, opus, or sonnet) based on complexity, duration, autonomy, and latency requirements. Doing this correctly by hand requires that same analysis; Harness encodes the criteria so it is done consistently.

License and Maintenance

Harness is released under the Apache-2.0 license, which permits commercial use without source-disclosure requirements. The repository is at revfactory/harness on GitHub with a live demo site at revfactory.github.io/harness/.

The last push was on 2026-09-26. The project is under active development. There are no GitHub releases tagged for the repository, so version tracking is done through the CHANGELOG.md file in the repository.

The .claude-plugin/ directory at the repository root contains the Claude Code plugin manifest. The skills directory holds the harness and evolve skill implementations. An interactive walkthrough demo in Korean is linked in the README at revfactory.github.io/harness-animation/.

Editorial conclusion

Harness is appropriate for Claude Code users who work with multi-agent workflows regularly and want a structured, repeatable process for designing team architectures rather than writing agent definitions from scratch each time. It is not a general-purpose tool for all Claude Code users: its value increases with the complexity of the workflow being designed. For simple one-agent tasks, the overhead of running the seven-phase design process is not justified. Verify that your Claude Code installation supports the execution modes Harness uses (Workflow scripts, named Agent calls with SendMessage, and one-shot Agent delegation) before committing to a harness design.

Frequently asked questions

Official sources

1. Issues
2. License: Apache-2.0
3. Project website
4. README
5. revfactory/harness on GitHub