Metadata-Version: 2.4
Name: autoharness
Version: 1.4.10
Summary: Globally-installed agent harness framework that generates AI coding assistant primitives into any target workspace
Project-URL: Repository, https://github.com/softwaresalt/autoharness
Author: softwaresalt
License-Expression: MIT
License-File: LICENSE
Keywords: agent,ai,coding-assistant,copilot,harness
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Software Development :: Quality Assurance
Requires-Python: >=3.10
Requires-Dist: jsonschema>=4.23.0
Requires-Dist: pyyaml>=6.0.2
Description-Content-Type: text/markdown

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

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

```text
┌──────────────────────────┐       ┌──────────────────────────┐
│  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](docs/primitives.md)):

| # | 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](docs/capability-packs.md) for the full overlay contract and pack details.

## Quick Start

```bash
# 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:

```bash
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](docs/getting-started.md) 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](docs/getting-started.md) | Install autoharness, configure your workspace, compose a harness |
| [Environment Setup](docs/environment-setup.md) | Per-environment registration (VS Code, Copilot CLI, Claude Code, Codex, Cursor) |
| [Primitives](docs/primitives.md) | Deep reference for the 10 irreducible harness primitives |
| [Capability Packs](docs/capability-packs.md) | Overlay pattern, pack catalog, and composition rules |
| [Tuning Guide](docs/tuning-guide.md) | Maintain and adapt your harness as the codebase evolves, including checksum drift and schema-contract upgrades |
| [Backlog Integration](docs/backlog-integration.md) | Backlog tool detection, registry abstraction, and manual registration |
| [Credits](docs/credits.md) | Sources of inspiration, research, and tools that shaped autoharness |

## Acknowledgements

autoharness builds on [METR Time Horizons research](docs/credits.md), [OpenAI harness engineering](docs/credits.md), [Anthropic Constitutional AI](docs/credits.md), [atv-starterkit](https://github.com/microsoft/atv-starterkit), [backlogit](https://github.com/softwaresalt/backlogit), and established software engineering practice. See [Credits](docs/credits.md) for the full breakdown.

## License

MIT
