Harness Coding Protocol

A harness-first protocol that lets AI coding agents bootstrap any repo with one IDE command.

Open your project in an AI IDE, run /harness-init, and the agent will:

1. Detect your stack, frameworks, repo shape, and any existing AI tool traces (deterministic; runs once via scripts/harness-detect.mjs).
2. Read the existing root-truth files, top README, and package manifests within a bounded read budget.
3. Judge & write Drafts for each root-truth file (AGENTS.md, CLAUDE.md, steering/harness-recommendations.md, plus the Cursor pair when Cursor is detected) — the agent itself authors the bytes.
4. Show & confirm: a one-line-per-file summary; one yes/no. On yes, a Hash-Recorded Plan (HRP) records the intended bytes and their SHA-256.
5. Apply writes the recorded bytes verbatim — no re-detect, no re-plan — with backup/rollback handled for you.

This is IDE + AI agent only — there is no terminal CLI and no npm package. Any agent that can read/write files and run shell commands can execute the flow (Claude Code, Cursor, Codex, Antigravity, opencode, Hermes, etc.). .claude-plugin/ is just the Claude Code discovery layer.

Prerequisites

• Node.js (v18+) with npm/npx — the Phase 1 detector runs via npx tsx
• An AI agent that can read/write files and execute shell commands

Compatibility

Agent	Status	How to run
Claude Code	Supported	Install as plugin; run /harness-init
Cursor	Supported	Point agent at SKILL.md; run shell commands
Codex	Supported	Same as Cursor
Antigravity	Supported	Same as Cursor
opencode	Supported	Same as Cursor
Hermes	Supported	Same as Cursor

The core flow (detect → read → judge → record → apply) is platform-agnostic. .claude-plugin/ and .claude/skills/ are the Claude Code discovery layer only.

Quick Start

1. Get the plugin

   git clone https://github.com/manhua-man/harness-coding-protocol.git
   

   Then point your IDE plugin/marketplace at this repo (e.g. Claude Code: source: ./ in .claude-plugin/marketplace.json).

2. Open a target repository in the IDE. The target does not need a package.json of its own.

3. Run /harness-init. The agent narrates detection, drafts the plan, and asks for one yes/no confirmation.

Don't use npm install, terminal harness commands, or npm run smart for onboarding — those paths were removed.

Usage in Any Agent

Claude Code discovers /harness-init automatically via the plugin. For other agents (Cursor, Codex, Antigravity, opencode, Hermes, etc.), point the agent at SKILL.md and run the three scripts in order:

Step 1 — Detect

npx tsx /path/to/harness-coding-protocol/scripts/harness-detect.mjs <target-repo>

Prints Detect run: <run-id>. The agent reads .harness/runs/<run-id>/detection.json to understand the project.

Step 2 — Agent reads, judges, drafts (Phase 2-4)

The agent reads the target repo's existing files, judges what each Root_Truth_File should say, drafts content, and presents a summary. This is reasoning, not scripting — the agent does it.

Step 3 — Record Plan

The agent writes a JSON file with the plan and pipes it in:

npx tsx /path/to/harness-coding-protocol/scripts/harness-record-plan.mjs --file plan-input.json

Step 4 — Apply

npx tsx /path/to/harness-coding-protocol/scripts/harness-apply.mjs <target-repo> <plan-run-id>

Writes each entry verbatim, verifies SHA-256 round-trip.

The full workflow spec is in .claude/skills/harness-init/SKILL.md — any agent can read it as a prompt.

See It on a Fixture First

If you want to see what /harness-init would propose without writing anything, run the detect-only script against a fixture:

npx tsx scripts/harness-detect.mjs templates/auto-detect/fixtures/node-monorepo

Sample output:

Detect run: 20260522-032145-64a32d

Phase 1 produces .harness/runs/<detect-run-id>/{detection.json, manifest.json} and stops there. The rest of the flow (read, judge, draft, confirm, apply) runs inside the agent during /harness-init; there is no separate dry-run script for Drafts because the agent itself writes them.

The same script accepts any path, so you can point it at your own repo:

npx tsx scripts/harness-detect.mjs ../my-app

Available fixtures:

Fixture	Shape & signals
minimal-repo	Empty target with prior AGENTS.md / CLAUDE.md so the agent must reuse existing heading sections
cursor-heavy	React + Vite monorepo with existing .cursor/ configuration
claude-mcp	Claude Code + MCP traces (.claude/, mcp.json)
node-monorepo	pnpm + turborepo + react + express + vite, no AI traces
python-fastapi	Poetry + FastAPI + ruff + black + pytest, layered repo
meta-claude-plugin	Claude Code plugin with .claude-plugin/ metadata

What Gets Created

Output	Purpose
AGENTS.md	Facts — directory shape, commands, modules
CLAUDE.md	Protocol — decisions, workflow
steering/	Scoped overrides (per area, per ecosystem)
.cursor/rules/, .cursor/commands/	Cursor mirror, only when Cursor is detected
.harness/runs/<run-id>/	Detection / plan / apply artifacts the agent inspects

Existing user content outside the target ## heading section is preserved when the agent uses a patch-section action; overwrite is only allowed on files that already carry harness-managed sections.

Architecture (Capabilities)

Capability	Role
C1 Detection	Tech stacks, frameworks, AI tool traces, repo shape (deterministic)
C2 Agent Authoring	The IDE_Agent reads, judges, and writes Root_Truth_File Drafts directly
C3 Apply	Verbatim writes from a Hash-Recorded Plan, with backup and rollback
Run Contract	Every run is an immutable artifact set under .harness/runs/

Implementation entry: runInitDetect (Phase 1) and runInitApplyFromPlan(targetPath, planRunId) (Phase 5) in templates/auto-detect/init-pipeline.ts. Phases 2–4 are agent-driven per .claude/skills/harness-init/SKILL.md.

Internal Documentation

docs/ and internal/ are maintainer-only — they describe the protocol, capabilities, and review history. Casual users do not need to read them. Start here:

• docs/architecture.md — system shape
• docs/run-contract.md — behavior contract + Operational Rules appendix
• docs/tool-adaptation.md — how harnesses map to the contract
• docs/agent-triggering.md — entry points and rule precedence

Contributing

There is no package.json and no vitest/jest test runner. Change TypeScript under templates/auto-detect/ or .claude/commands/, then verify in the IDE with /harness-init against a fixture (see CONTRIBUTING.md). Headless smoke suite (6 fixture detect + property/example tests + golden HRP apply round-trips):

npx tsx scripts/smoke-suite.mjs               # full suite (Parts 1–3)
npx tsx scripts/smoke-suite.mjs --filter python-fastapi  # one fixture (Part 1 only)

Minimal end-to-end smoke (detect → recordPlan → apply): npx tsx scripts/smoke-init.mjs.

Roadmap: ROADMAP.md · Conventions: CONTRIBUTING.md · License: MIT.

Example Outcomes

See docs/dogfood/ for real-repo case studies documenting what /harness-init proposes, how the agent judges, and what lands on disk after yes.

Documentation Authority

If two documents conflict, prefer the higher item and fix the lower one.

1. docs/architecture.md, docs/run-contract.md
2. docs/tool-adaptation.md, docs/bundles/