Portable agent workflow design
Turn a project goal into reusable skills and inspectable handoffs.

Documentation · Source · Apache 2.0

Meta Harness

Meta Harness is a runtime-neutral meta-skill for designing domain-specific workflows, reusable specialist skills, and deterministic handoff artifacts. It is adapted from the original Harness project and distributed under the Apache 2.0 license.

Current project version: 0.8.4. Meta Harness actively supports Pi, Codex, Antigravity, and Cursor CLI/Agent through one portable workflow model and runtime adapters. Generic Agent Skills use is best effort; legacy client layouts are unverified and deprecated. See the changelog for the checkpoint-based project history.

Start here

The Meta Harness documentation portal is the recommended entry point. It covers installation, the Phase 0 inventory and drift audit, the six execution phases, architecture patterns, prompt design, compatibility, and durable output specs.

For a quick project install, use the installed meta-harness CLI:

meta-harness install \
  --scope project \
  --target /path/to/repo \
  --agent generic \
  --non-interactive

When running directly from a source checkout without the CLI on PATH, use ./meta-harness (macOS/Linux), .\meta-harness (Windows), or python scripts/install_harness.py with the same subcommand and options. This is the current planner entry point, not the deprecated --layout interface.

Then ask for a goal-shaped workflow, for example:

Design a reusable research harness for this repository.
Keep the handoffs deterministic and validate one normal and one failure flow.

What the repository contains

• a Phase 0 inventory and drift audit followed by six execution phases from domain analysis through validation;
• six coordination patterns: Pipeline, Fan-out/Fan-in, Expert Pool, Producer-Reviewer, Supervisor, and Hierarchical Delegation;
• portable skills under .agents/skills/;
• durable team specs and role contracts under docs/harness/;
• deterministic _workspace/ handoffs when inspection or resumption matters;
• a shared CLI/TUI installer planner with portable layout and optional native profiles;
• audit, doctor, compile, and validation commands over inspectable plans;
• removable runtime adapters for Pi, Codex, Antigravity, and Cursor CLI/Agent without forking the canonical skill;
• explicit capability degradation and rippability rules for runtime profiles.

Phase 0 audit plus six-phase workflow

Phase	Question it answers
Inventory and drift audit	What already exists, what is stale, and what operation is safe?
Domain analysis	What is this project, task, and quality bar?
Team architecture	What coordination shape earns its complexity?
Role and artifact definition	Who owns each output and handoff?
Skill generation	What reusable behavior belongs in a skill?
Integration and orchestration	How does information move between phases?
Validation and testing	Does the workflow work, fail clearly, and stay maintainable?

Read the workflow guide and pattern guide for the operational details.

Installation

Installing the meta-harness CLI

Install the meta-harness executable onto your system:

macOS / Linux:

curl -fsSL https://raw.githubusercontent.com/SaehwanPark/meta-harness/main/install.sh | bash

Windows (PowerShell):

irm https://raw.githubusercontent.com/SaehwanPark/meta-harness/main/install.ps1 | iex

The installer verifies Python 3.8+, installs the executable launcher, and ensures it is available on your PATH.

From a cloned repository:

git clone https://github.com/SaehwanPark/meta-harness.git
cd meta-harness

# Install to user PATH (~/.local/bin on Unix, user PATH on Windows):
./install.sh        # macOS / Linux
.\install.ps1       # Windows PowerShell

# Or run directly from the repo root:
./meta-harness      # macOS / Linux
.\meta-harness      # Windows

Installing Harness into target projects

Install into a project:

meta-harness install \
  --scope project \
  --target /path/to/repo \
  --agent pi \
  --agent cursor \
  --non-interactive

Install as a user-level shared skill:

meta-harness install \
  --scope user \
  --agent generic \
  --non-interactive

--agent is repeatable. Runtime-specific installation and capability guidance for the actively supported Pi, Codex, Antigravity, and Cursor CLI/Agent targets is in the compatibility matrix. Generic clients are best-effort only; ForgeCode, Droid, OpenHands, and Aider are retained as unverified, deprecated migration notes. Use audit, doctor, compile, and validate for inspectable lifecycle operations.

The installer owns only explicitly planned skill/profile destinations. The target repository keeps ownership of its AGENTS.md, README.md, and documentation. Legacy --layout flags remain compatibility aliases and are unverified/deprecated; use --agent for new automation.

Runtime support and architecture

The portable contract is authoritative: .agents/skills/ contains reusable behavior, docs/harness/ contains role and team contracts, and _workspace/ contains durable handoffs. Runtime-native profiles are removable adapters, not sources of truth. Read the architecture guide and compatibility matrix before adding a runtime-specific integration.

Repository contract

The canonical source is .agents/skills/harness/SKILL.md. Generated skills must begin with YAML frontmatter containing at least name and description. Use docs/harness/ for durable team specs and role briefs, and _workspace/ for deterministic intermediate artifacts that need inspection, resumption, or cross-agent synthesis.

Keep AGENTS.md short and repo-wide. Put conditional detail in skills, references, or project documentation. Prefer direct work for small tasks and add workers only when boundaries, ownership, synthesis, and partial-failure behavior are explicit.

Authoring guidance

Read the AGENTS Authoring Guide (.agents/skills/harness/references/agents-md-guide.md) when a target repository needs durable repo-wide rules. Keep temporary model-specific recovery logic in a rippable harness layer. Every generated skill starts with YAML frontmatter and declares its name and description.

Validation

Run the repository checks from the project root:

python3 scripts/validate_pages.py
python3 scripts/validate_skills.py
python3 scripts/validate_adapters.py
python3 scripts/test_install_harness.py
python3 scripts/test_install_planner.py
python3 scripts/test_installer_tui.py
python3 scripts/test_profile_compilation.py
python3 scripts/test_audit_harness.py
python3 scripts/validate_codex_port.py

The Pages check protects rendered source and navigation. Portable-skill and adapter validators protect frontmatter, links, capability guidance, and fixtures. The installer tests cover project/user scopes, multi-runtime plans, legacy aliases, dry runs, idempotent updates, conflicts, profiles, and symlink mode. The Codex-port validator protects canonical paths, synchronized docs, and legacy-path exclusions.

License

Apache 2.0. See LICENSE.