claude-code-harness

<p align="center"> <img src="docs/images/claude-harness-logo-with-text.png" alt="Claude Harness" width="400"> </p>

<p align="center"> <strong>Plan. Work. Review. Ship.</strong><br> <em>A disciplined delivery loop for Claude Code, with bounded paths for Codex and OpenCode.</em> </p>

<p align="center"> <a href="https://github.com/Chachamaru127/claude-code-harness/releases/latest"><img src="https://img.shields.io/github/v/release/Chachamaru127/claude-code-harness?display_name=tag&sort=semver" alt="Latest Release"></a> <a href="LICENSE.md"><img src="https://img.shields.io/badge/License-MIT-green.svg" alt="License"></a> <a href="docs/CLAUDE_CODE_COMPATIBILITY.md"><img src="https://img.shields.io/badge/Claude_Code-v2.1+-purple.svg" alt="Claude Code"></a> <img src="https://img.shields.io/badge/Skills-5_Verbs-orange.svg" alt="Skills"> <img src="https://img.shields.io/badge/Core-Go_Native-00ADD8.svg" alt="Go Core"> </p>

<p align="center">

</p>

<p align="center"> <img src="docs/images/readme/hero-operating-loop-en.png" alt="Claude Code Harness operating loop: Spec, Plan, Work, Review, Release" width="900"> </p>

Claude Code is powerful, but raw agent work drifts: plans live in chat, tests become optional, review happens too late, and release evidence gets rebuilt by memory. Harness turns that into one repeatable operating path.

After install, the default changes from "ask the agent to code" to:

1. write the spec and plan,
2. implement only the approved slice,
3. verify the result,
4. review independently,
5. package evidence for PR or release.

Quickstart

New users should start from the tool they already use. Existing users should run the migration report before cleanup or reinstall.

Install in 30 Seconds

claude
/plugin marketplace add Chachamaru127/claude-code-harness
/plugin install claude-code-harness@claude-code-harness-marketplace
/harness-setup

Next command: run /harness-plan with one small request.

/harness-plan Improve the README onboarding flow

First 15 Minutes

1. Install through your tool route.
2. Run /harness-setup or the equivalent setup script.
3. Run /harness-plan with a small request; Harness writes the spec.md and

Plans.md drafts for you to check. Small typo, docs, and status updates stay lightweight.

1. Approve the generated contract or reply with the correction you want.
2. Run the smallest approved task, for example /harness-work 1.1.1.
3. Run /harness-review and keep the verification output.

Your job is not to hand-write the plan. It is to approve or correct the generated contract before execution continues.

How It Works

Harness adds a source-of-truth loop around agent work. The 5 verb skills keep that surface small: plan, work, review, sync, release.

1. You describe the outcome in normal language.
2. /harness-plan drafts or updates spec.md and Plans.md with scope,

acceptance criteria, unknowns, and stop conditions.

1. Non-trivial planning records team_validation_mode and validates the plan

through team/sub-agent or manual-pass perspectives for spec/Plans alignment, memory reuse, product fit, security fit, and works-in-practice.

1. Harness treats those files as the source of truth. Data the agent has not

seen stays unknown instead of being silently invented.

1. /harness-work implements the approved slice with TDD and verification.
2. /harness-review separates review from implementation.
3. /harness-release packages only verified evidence.

Commands

Basic Workflow

Install By Tool

Existing User Migration

Run bin/harness doctor --migration-report before changing an existing setup. The report inventories stale Claude plugin caches, duplicate Codex skills, old symlinks, OpenCode backup paths, and harness-mem state without deleting anything.

Support Boundary

Harness can describe candidate paths, but it does not inherit support claims from Superpowers, Hermes Agent, or any other project. A host only moves up when Harness has its own bootstrap, trigger, runtime, and release evidence.

not_observed != absent: missing local proof means "not proven here", not "impossible" and not "supported".

Requirements

• •Claude Code v2.1+ for the supported Claude path.
• •A project repository with write access for local setup.
• •No Node.js is required for the Go-native guardrail engine.
• •Optional harness-mem for

cross-session memory when configured and healthy.

Advanced

Use these after the basic trigger path is visible.

Documentation

Contributing

Issues and PRs welcome. See CONTRIBUTING.md.

Acknowledgments

• •AI Masao - Hierarchical skill design
• •Beagle - Test tampering prevention patterns

License

MIT License. See LICENSE.md.