Metadata-Version: 2.4
Name: autoharness
Version: 1.5.0
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 |
| **graphtor-docs** | Indexed local documentation search and semantic retrieval |

See [Capability Packs](docs/capability-packs.md) 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](docs/installation.md)**
guide.

```bash
# 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](docs/installation.md) 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](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 |
| [Installation](docs/installation.md) | Authoritative install path: scripted one-command deploy and manual pip/clone/plugin |
| [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
