harness-experimental

Turn any software repo into an agent-ready workspace.

harness-experimental is a repository-level operating harness for Claude Code,
Codex, Cursor, and other coding agents. It gives agents the missing project
context they need before they change code: where to start, what the product
contract says, how risky the work is, what proof is required, and which
decisions future agents should inherit.

The app is what users touch. The harness is what agents touch.

Why Star This Repo

Star this repo if you want practical, reusable patterns for making AI-assisted
software development more reliable, inspectable, and easier for humans to steer.

This project is exploring a simple idea:

Coding agents do not only need better prompts. They need better repositories.

The Problem

Most repos are built for humans reading code in a familiar codebase. Coding
agents usually enter with only a chat prompt and a shallow snapshot of files.
That leads to common failure modes:

• The agent edits code before understanding product intent.
• Important constraints live only in chat history or in someone's head.
• Validation expectations are vague or discovered too late.
• Architecture tradeoffs are repeated instead of inherited.
• Large requests do not get broken into reviewable story-sized work.

The Harness Approach

A repository starts to have a harness when it helps an agent answer practical
engineering questions without relying only on chat history:

• What should I read first?
• What type of work is this?
• Which product contract does it affect?
• How risky is the change?
• What proof will show the work is done?
• What decision or lesson should future agents inherit?

In this repo, those answers live in:

• AGENTS.md — the agent entrypoint and operating rules.
• docs/HARNESS.md — the human-agent collaboration model.
• docs/FEATURE_INTAKE.md — tiny, normal, and high-risk work classification.
• docs/ARCHITECTURE.md — architecture discovery and boundary rules.
• docs/TEST_MATRIX.md — behavior-to-proof validation expectations.
• docs/stories/ — story packets and backlog items.
• docs/decisions/ — durable decisions and tradeoffs.
• docs/templates/ — reusable spec, story, decision, and validation templates.

OpenAI describes this shift as an agent-first world where humans steer and
agents execute:

https://openai.com/index/harness-engineering/

Install Harness Into A Project

From a target project directory, run:

curl -fsSL "https://raw.githubusercontent.com/hoangnb24/harness-experimental/main/scripts/install-harness.sh?$(date +%s)" | bash -s -- --yes

If the target already has AGENTS.md, docs/, or scripts/, choose one:

# Keep existing files and add only missing Harness files
curl -fsSL "https://raw.githubusercontent.com/hoangnb24/harness-experimental/main/scripts/install-harness.sh?$(date +%s)" | bash -s -- --merge --yes

# Back up and replace AGENTS.md, docs/, and scripts/
curl -fsSL "https://raw.githubusercontent.com/hoangnb24/harness-experimental/main/scripts/install-harness.sh?$(date +%s)" | bash -s -- --override --yes

Or install into a specific path:

curl -fsSL "https://raw.githubusercontent.com/hoangnb24/harness-experimental/main/scripts/install-harness.sh?$(date +%s)" | bash -s -- --directory /path/to/project --yes

Use --dry-run to preview changes before writing files.

Try The Flow

The fastest way to understand the harness is to inspect the tiny demo:

• docs/demo/README.md: shows how a simple product idea becomes product docs,
  stories, validation expectations, and decisions before implementation starts.

A typical flow looks like this:

human intent or product spec
  -> product contract
  -> feature intake
  -> story packet
  -> validation expectations
  -> implementation work
  -> decision or lesson captured for future agents

Implementation prompts do not go straight to code. They first pass through
feature intake, become story-sized work when needed, and then carry both product
validation and harness maintenance expectations.

Current State

This repository is in Harness v0.

There is no application implementation and no baked-in product specification
yet. The current work is the reusable project harness: the file structure,
agent operating model, feature intake process, story templates, and validation
expectations that help humans and agents turn a future user-provided spec into
implementation work.

Product Sources

No product contract is currently defined.

When a user provides a project specification, add or reference it as the input
spec for the first buildout, then derive smaller living artifacts from it:

• docs/product/: current product contract files, created from the spec.
• docs/stories/: story packets and backlog created from selected work.
• docs/TEST_MATRIX.md: behavior-to-proof control panel.
• docs/decisions/: durable decisions and tradeoffs.

Do not keep a project-specific spec or product breakdown in this harness until
a real project supplies one.

Repository Structure

project/
  AGENTS.md
  README.md
  docs/
    HARNESS.md
    FEATURE_INTAKE.md
    ARCHITECTURE.md
    TEST_MATRIX.md
    HARNESS_BACKLOG.md
    product/
    stories/
    decisions/
    demo/
    templates/
  scripts/
    README.md

Contributing

This project is early and benefits most from real-world agent failure cases,
example harness installs, docs improvements, and reusable workflow patterns.
See CONTRIBUTING.md for contribution ideas.

Useful contributions include:

• Show how the harness works in a real project.
• Add missing templates or improve existing ones.
• Propose validation patterns for different stacks.
• Share failures where an agent made the wrong change because the repo lacked
  context.
• Compare harness behavior across Claude Code, Codex, Cursor, and other tools.

Share

If this idea resonates, please star the repo and share it with someone building
with coding agents.

Short description:

An agent-ready repo harness for Claude Code, Codex, Cursor, and other coding
agents: AGENTS.md, product contracts, story packets, validation matrix, and
decision records.