by hoangnb24
Turn any repo into an agent-ready workspace for Claude Code, Codex, Cursor, and other coding agents.
# Add to your Claude Code skills
git clone https://github.com/hoangnb24/harness-experimentalGuides for using ai agents skills like 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.
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.
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:
A repository starts to have a harness when it helps an agent answer practical engineering questions without relying only on chat history:
No comments yet. Be the first to share your thoughts!
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/
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.
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.
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.
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.
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
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:
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.