title: autoharness description: Globally-installed agent harness framework that generates AI coding assistant primitives into any target workspace doc_type: guide source: README.md

autoharness

A globally-installed agent harness framework that composes AI coding assistant primitives into any repository workspace. Discover your workspace's technology stack, then generate a customized set of agents, instructions, skills, prompts, policies, and constitutional foundations — all tailored to your codebase.

Install once globally. Invoke against any workspace. The target receives only finished harness artifacts, never engine files.

The Problem

Modern AI coding assistants (GitHub Copilot, Claude Code, Cursor, Codex) work dramatically better with structured guidance: agent definitions, skill workflows, coding instructions, review personas, and workflow policies. Building these from scratch for every repo is tedious. Maintaining them as the codebase evolves is worse.

How It Works

 Discover              Install               Tune
 ───────── ──────▶ ─────────── ──────▶ ─────────
 Scan workspace        Compose tailored       Adapt harness as
 profile: languages,   harness from the       the codebase,
 frameworks, build     10 universal           docs, and team
 tools, CI/CD          primitive templates    conventions evolve

┌──────────────────────────┐       ┌──────────────────────────┐
│  autoharness (global)    │       │  target workspace        │
│                          │       │                          │
│  templates/              │──────▶│  AGENTS.md               │
│  schemas/                │ reads │  .github/agents/         │
│  agents/                 │ tmpl, │  .github/skills/         │
│  skills/                 │ writes│  .github/instructions/   │
│  docs/                   │ output│  .github/policies/       │
│                          │       │  .backlog/               │
│                          │       │  .autoharness/           │
└──────────────────────────┘       └──────────────────────────┘

The 10 Primitives

Every effective agent harness implements these irreducible primitives (deep reference):

Presets & Capability Packs

Start light and grow. Presets control the installation shape; capability packs overlay deeper behavior on top.

See Capability Packs for the full overlay contract and pack details.

Quick Start

Install autoharness globally, then compose a harness into your workspace. Full install instructions — the scripted one-command deploy and the manual pip/clone/plugin paths — live in the Installation guide.

# Fastest manual install (pick one)
python -m pip install autoharness                         # Python CLI
copilot plugin marketplace add softwaresalt/autoharness   # Copilot CLI: add marketplace
copilot plugin install autoharness@autoharness            # Copilot CLI: install plugin

# Upgrade an existing Python CLI install
python -m pip install --upgrade autoharness

# Or use the scripted one-command deploy (bootstraps + registers + scaffolds)
./scripts/deploy-harness.sh --bootstrap --preset full     # bash
./scripts/deploy-harness.ps1 -Bootstrap -Preset full      # PowerShell

# Compose a harness (from the target workspace)
/install-harness preset=standard

# Run the full Stage -> Ship lifecycle through the Orchestrator
/feature-flow

# Prefer P-016 planning overlap when it will not create parallel implementation branches/worktrees
/feature-flow-parallel

# Run bounded P-017 dark factory mode through the Orchestrator
/feature-flow-dark

# Run deterministic verification against an installed workspace
autoharness verify-workspace --workspace .

MCP runtime prerequisites

Workspaces that enable JavaScript-based MCP tools need Bun and bunx installed on PATH. Native-binary MCP tools such as backlogit, Engram, and graphtor-docs still need their own executables on PATH. If an MCP launcher must remain bare bunx instead of verified bunx --bun, keep Node available too because package shebangs may still delegate to Node.

See Installation for environment registration, install methods, upgrade/migration steps, and the autoharness_home resolution order.

If the target workspace is Git-backed, treat install and tune output as feature-branch work. autoharness may still generate local uncommitted changes while you are on the default branch, but the intended review path is feature branch plus pull request, not a direct commit or push to the default branch.

See Getting Started for the full walkthrough, including workspace configuration, install layers, selective installation, and post-install verification.

Workflow Entry Points

After a harness is installed, the primary user-facing lifecycle entrypoints are:

These are workflow aliases, not separate pipelines, over the existing Orchestrator workflow. They do not bypass Stage, Ship, the backlog model, or shipment policies. feature-flow-parallel does not authorize parallel implementation branches/worktrees; the only extra worktree exception is explicit Stage spike/research investigation with no implementation, template/source/config mutation, shipment claim, PR preparation, or Ship execution. feature-flow-dark is not a safety bypass: P-001, P-009, P-014, P-016, P-017, required checks, telemetry, and closure still apply.

Documentation

Acknowledgements

autoharness builds on METR Time Horizons research, OpenAI harness engineering, Anthropic Constitutional AI, atv-starterkit, backlogit, and established software engineering practice. See Credits for the full breakdown.

License

MIT