Claude Code Harness

Plan. Work. Review. Ship.
A disciplined delivery loop for Claude Code, with bounded paths for Codex and OpenCode.

English | 日本語

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.

Path	Start
New user	Tool-first onboarding
Existing user	Migration check
Claude Code fast path	Install in 30 seconds
Trigger proof	Skill trigger gate

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.
4. Approve the generated contract or reply with the correction you want.
5. Run the smallest approved task, for example /harness-work 1.1.1.
6. 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.
3. 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.
4. Harness treats those files as the source of truth. Data the agent has not seen stays unknown instead of being silently invented.
5. /harness-work implements the approved slice with TDD and verification.
6. /harness-review separates review from implementation.
7. /harness-release packages only verified evidence.

Commands

Command	What happens inside
/harness-setup	Installs project guidance, command surfaces, hooks, and checks so the workflow starts from one known baseline.
/harness-plan	Turns intent into spec.md and Plans.md, including scope, acceptance criteria, dependencies, unknowns, stop conditions, and non-trivial planning validation.
/harness-work	Executes one approved task or range, adds tests when required, runs verification, and keeps work inside the plan.
/harness-work all	Runs the approved plan through implementation and review paths; use after the plan is clear and the repo baseline is known.
/harness-review	Reviews the result separately from implementation and treats major findings as blockers.
/harness-release	Checks release readiness, CHANGELOG/tag boundaries, and evidence packaging after implementation and review are complete.
bin/harness doctor --migration-report	Inventories old plugin caches, Codex skills, OpenCode files, symlinks, and memory state without deleting data.

Basic Workflow

Stage	Output	Gate
Investigate	Evidence and unknowns	Do not promote unobserved data into claims.
Plan	spec.md + Plans.md	User approves or corrects the generated contract.
Work	Code and tests	TDD required when the task says so.
Review	Independent verdict	Major findings block completion.
PR	Evidence pack	PR ready is not release ready.
Release	Tag/release artifacts	Release preflight must pass on the release path.

Install By Tool

Tool	Tier	Route
Claude Code	supported	Claude plugin marketplace, then /harness-setup.
Codex CLI	internal-compatible	scripts/setup-codex.sh --user; direct plugin smoke is tracked separately.
Codex app	candidate	Candidate smoke only; do not reuse Codex CLI proof.
OpenCode	internal-compatible	scripts/setup-opencode.sh; runtime parity is not claimed.
Cursor	internal-compatible	scripts/setup-cursor.sh real-directory local install; top support tier still gated on workflow smoke.
GitHub Copilot CLI	candidate	Manual profile research only.
Antigravity CLI	future/unsupported	No end-user install route in this phase.

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.

Capability	What it adds	Boundary
Breezing	Planner/Critic/Worker style team execution for larger task lists.	Still gated by plan quality and review.
Codex companion review	Schema-backed Codex second opinion through scripts/codex-companion.sh.	Raw codex exec is not the Harness companion path.
OpenCode bootstrap	Mirrors Harness guidance into OpenCode-compatible surfaces.	Real runtime parity is not claimed.
harness-mem	Project-scoped memory and recall across sessions.	Optional companion; purge remains explicit.

Documentation

Resource	Description
Tool-first onboarding	Where to start by host tool.
Install routes	Per-tool setup and support-tier boundaries.
Migration check	Existing-user impact, compatibility, and rollback path.
Skill trigger gate	How install success is verified.
Capability matrix	Supported, internal-compatible, candidate, and unsupported host claims.
Claude Code Compatibility	Current Claude Code requirements and compatibility notes.
Cursor Integration	Cursor handoff boundary and internal-compatible adapter notes.
Distribution Scope	Included vs compatibility vs development-only paths.
Hardening parity	Runtime safety differences between Claude hooks and Codex gates.
Work All Evidence Pack	Success/failure verification contract for full-plan execution.
Changelog	User-facing version history.

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.