Harness

Harness turns a blank repository into a self-reviewing workspace for coding agents.

Harness is a TypeScript CLI for teams that want agents to work in a closed loop instead of improvising against an empty repo. It bootstraps the planning structure, evidence flow, and review rules first, then uses Codex to tailor the repository to the actual project.

The result is a repository where agents can plan, implement, validate, and review with much less hidden context.

Why Harness

Start from a documentation-first scaffold instead of ad hoc agent instructions.
Personalize the repository interactively through Codex instead of guessing every project choice up front.
Enforce a separate validation-subagent pass so implementation and review do not collapse into one step.
Preserve evidence, plans, and workflow rules inside the repository itself.

What You Get

Harness sets up a repository to support this loop from day one:

Define intent through PRODUCT_SPECS.md and repository product specs.
Record architecture and tradeoffs in design docs.
Execute non-trivial work through ExecPlans.
Run validations and archive evidence.
Run a separate validation subagent with an explicit review prompt that follows REVIEW.md before considering the task complete.
Review changes against explicit expectations.

Commands

harness init: create the baseline scaffold in the current directory.
harness configure: launch an interactive Codex session that personalizes the scaffold for the real project.

Quick Installation

Prerequisites:

Node.js 20 or newer.
harness init works without Codex.
harness configure currently supports only Codex, so the local codex executable must be installed and available on PATH.

Global install:

npm install -g @antubattle/harness

One-off use with npx:

npx @antubattle/harness init --project-name "My Project"

Quick Usage

Create or enter a project directory:

mkdir my-project
cd my-project

Initialize the baseline Harness scaffold:

harness init --project-name "My Project"

This creates the generic repository structure for product-spec standards, review guidance, design docs, ExecPlans, generated evidence, and agent workflow guidance.

Personalize that scaffold for the actual project:

harness configure

harness configure defaults to Codex, and --provider codex is the only supported explicit provider value right now.

Result:

After init, you have a deterministic, language-agnostic baseline scaffold.
After configure, Codex interviews you about the project direction, language, architecture, validation setup, observability, and tooling, then personalizes the repository guidance into a more complete, self-sufficient workspace for future agent work.

The npm package name is @antubattle/harness, and the installed executable is harness.

What Makes It Different

The scaffold is intentionally generic first and project-specific second.
configure is interactive, so the repository setup can reflect real constraints instead of hard-coded presets.
The workflow explicitly separates implementation from validation by requiring a distinct validation subagent.
The repository keeps specs, plans, design rationale, and generated evidence close to the code.

Current State

Harness is implemented as a Node-based TypeScript CLI.
The command surface is intentionally small and validated through typed objects.
Generated repositories stay language agnostic until configure applies project-specific guidance.
Codex is the only supported interactive configuration runtime right now.

Documentation

Repository Map

AGENTS.md: agent workflow and execution policy for this repository.
CHANGELOG.md: root release history for notable changes.
REVIEW.md: validation and review standard for reviewer agents.
ARCHITECTURE.md: system boundaries and implementation direction for Harness.
PLANS.md: ExecPlan authoring standard.
PRODUCT_SPECS.md: product-spec authoring standard.
features/: versioned product specs, design docs, ExecPlans, generated artifacts, and tech debt tracking.

License

MIT. See LICENSE.

This site is open source. Improve this page.