autoharness 1.4.7

Globally-installed agent harness framework that generates AI coding assistant primitives into any target workspace

---

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

#	Primitive	Purpose
1	State, Context & Knowledge Retrieval	Durable memory, checkpoints, retrieval, compaction
2	Task Granularity & Horizon Scoping	Decompose work to prevent error compounding
3	Model Routing & Escalation	Match model capability to task complexity
4	Orchestration, Delegation & Lifecycle Handoffs	Sequence agents through a feature/chore lifecycle
5	Tool Execution, Safety Modes & Guardrails	Safe environment mutation with policy enforcement
6	Injection Points & Dynamic Reminders	Surface constraints exactly when needed
7	Observability & Evaluation	Track agent efficacy, output quality, and entropy
8	Workflow Policy	Cross-agent sequencing and gate enforcement
9	Repository Knowledge & Agent Legibility	Structure the repo as a navigable knowledge base
10	Operational Closure & Feedback	Verify runtime behavior and close the delivery loop

Presets & Capability Packs

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

Preset	Scope	Best For
starter	Core planning, execution, guardrails, repo knowledge	First adoption, smaller repos
standard	Full 10-primitive harness	Most application and service repositories
full	Full harness plus recommended capability packs	Teams wanting deeper verification

Pack	Purpose
agent-intercom	Operator visibility, heartbeat, approval routing
agent-engram	Indexed search, code graph lookup, workspace binding
backlogit	backlogit-native query, queue, dependencies, memory/checkpoints, and traceability
browser-verification	Browser-aware runtime verification for web UIs
continuous-learning	Observation capture, instinct formation, learned artifacts
strict-safety	Explicit ProposedAction / ActionRisk / ActionResult tracking
release-observability	Richer operational closure and monitoring
adversarial-review	Multi-model consensus review and escalation

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

Quick Start

# Option A: Copilot CLI plugin (recommended — no Python needed)
copilot plugin marketplace add softwaresalt/autoharness
copilot plugin install autoharness@autoharness

# Option B: Python CLI (for setup-vscode and verify-workspace)
python -m pip install autoharness
autoharness setup-vscode        # VS Code with GitHub Copilot

# Register with other AI environments (requires Python CLI)
autoharness setup-claude        # Claude Code
autoharness setup-codex         # Codex

# Install 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 .

If you previously installed the Python CLI from the Git URL or uv tool, switch once to the PyPI wheel before relying on upgrades:

python -m pip uninstall autoharness   # if installed from a pip Git URL
uv tool uninstall autoharness         # if installed with uv tool
python -m pip install autoharness

That ensures future python -m pip install --upgrade autoharness updates use the published wheel instead of leaving a Git-based install in place or recloning the repository.

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.

The marketplace-based plugin install path gives Copilot CLI users built-in versioning and update management with no Python dependency. The Python CLI is still needed for setup-vscode (writing VS Code user settings), verify-workspace (CI-friendly JSON Schema validation), and registering with Claude Code or Codex.

The PyPI package is the stable Python CLI distribution path. Use the Git URL only when you explicitly want an unreleased snapshot from the repository tip.

The setup-claude and setup-codex commands copy agent or skill files into each tool's standard global config directory, so rerun them after upgrading autoharness to refresh those files. setup-vscode writes user-settings pointers to autoharness home; rerun it only if that resolved install path changes.

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:

Prompt	Use When	What It Does
/feature-flow	You want the normal full lifecycle for the next feature or chore	Routes through the Orchestrator, which runs the standard sequential Stage -> Ship workflow
/feature-flow-parallel	You want the same lifecycle but prefer P-016-compliant planning overlap when safe	Routes through the Orchestrator, which lets Stage plan ahead only when doing so does not create parallel implementation branches/worktrees; otherwise it falls back to sequential mode
/feature-flow-dark	You want the same lifecycle in bounded P-017 dark factory mode	Routes through the Orchestrator using the exact Run pipeline in dark mode trigger, records DARK_MODE_ACTIVE, and keeps local review, merge, telemetry, and closure gates mandatory

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

Document	Description
Getting Started	Install autoharness, configure your workspace, compose a harness
Environment Setup	Per-environment registration (VS Code, Copilot CLI, Claude Code, Codex, Cursor)
Primitives	Deep reference for the 10 irreducible harness primitives
Capability Packs	Overlay pattern, pack catalog, and composition rules
Tuning Guide	Maintain and adapt your harness as the codebase evolves, including checksum drift and schema-contract upgrades
Backlog Integration	Backlog tool detection, registry abstraction, and manual registration
Credits	Sources of inspiration, research, and tools that shaped autoharness

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