# Persona Harness
**A gate-first workflow CLI for AI coding agents building Java/Spring backends.**
[](https://www.npmjs.com/package/persona-harness)
[](https://www.npmjs.com/package/persona-harness)
[](https://nodejs.org)
[](./LICENSE)
[English](README.md) | [한국어](README.ko.md) | [日本語](README.ja.md) | [简体中文](README.zh-cn.md)
**[Start Here](docs/START-HERE.md) · [Quick Demo](docs/QUICK-DEMO.md) · [Measured Claims](docs/MEASURED-CLAIMS.md)**
> AI agents love to say "Done!" — Persona Harness makes them show their work. It is a local workflow gate that records and checks reports, evidence, and verification results for explicitly defined gates.
> [!IMPORTANT]
> **Alpha, gate-first, measured.** Live registry channels, tags, GitHub releases, and audit lifecycle facts are maintained in governed registry and audit records; source documentation records only its own preparation boundary. Runtime injection remains **default-off / opt-in**. See [`docs/current/p3-integrity-roadmap.md`](docs/current/p3-integrity-roadmap.md), [`docs/MEASURED-CLAIMS.md`](docs/MEASURED-CLAIMS.md), and [`injection-value-status.json`](docs/current/injection-value-status.json).
## Measured Behavior
Unlike most agent-harness projects, PH publishes what it has actually measured — including negatives.
- **Simple forged TDD evidence fixture** planted before `workflow finish` → `finish` exits **1**, forged file ignored.
- **Green-only completion** with the TDD rail on → blocked **5/5** (vs allowed 5/5 off).
- **Runtime injection**, 10 paired OpenCode runs → equal success (10/10 both), but PH ON cost more on every pair → kept **default-off**.
Completion-integrity measurements are bounded local fixtures. They are *not*
token-saving, app-quality, product-efficacy, security, GA, or broad
anti-forgery claims. Full boundary and P3 hold:
**[docs/MEASURED-CLAIMS.md](docs/MEASURED-CLAIMS.md)** and
**[docs/current/p3-integrity-roadmap.md](docs/current/p3-integrity-roadmap.md)**.
## What it is
A workflow + evidence CLI (`ph`) with an optional OpenCode plugin, for Java/Spring backend work done by AI agents. It:
- turns a project idea or README into implementation tickets;
- keeps the agent on a repeatable backend workflow;
- runs verification through bounded commands;
- records local evidence of what was read, run, and finished;
- can block completion when required reports or evidence for defined gates are
missing.
It is **not** a code-quality guarantee, a token-saving product, a broad linter,
proof that generated apps are production-ready, or a strong completion-integrity
guarantee before P3 closes. Every claim broader than the measured gates must be
earned by measurement first — see [MEASURED-CLAIMS](docs/MEASURED-CLAIMS.md).
## Install
Requires Node.js 20+, Java 21+ / Gradle, and the OpenCode CLI with a configured provider.
```bash
# OpenCode
curl -fsSL https://opencode.ai/install | bash # or: npm install -g opencode-ai
opencode auth login
# Persona Harness
npm install -D persona-harness
npx ph --help && npx ph doctor
```
## Quick Start
For a clean project directory (not the Persona Harness repo itself):
```bash
mkdir -p /tmp/ph-demo && cd /tmp/ph-demo && npm init -y
npm install -D persona-harness
npx ph init # minimal integration files only
npx ph bootstrap backend # AGENTS.md, profile, plan, report templates
npx ph go "Add a task creation endpoint."
```
For an existing Java/Spring/Gradle project, inspect the inferred draft first,
then accept it explicitly:
```bash
npx ph attach
npx ph attach --yes
# Only for a recognized weak Persona Harness installation, never a ready one:
npx ph attach --repair --yes
```
`attach` refuses unrecognized or corrupt existing Persona Harness files rather
than overwriting them, and it rejects repair for an already-ready attachment.
A successful attach enables PH-run verification while keeping
`runtimeInjection`, `systemConstitution`, `idleContinuation`, and the Ralph
loop off.
`ph go` is the host-neutral single entry for one concrete implementation
requirement after bootstrap and plan acceptance. It captures the requirement,
creates and selects the ticket, and prints the existing implementation rail;
it does not require a runtime hook or enable runtime injection. The agent should
follow that rail and end with `npx ph workflow finish implement`. Its workflow
conflict preservation applies to cooperative local PH/user writers and does not
address hostile same-user filesystem path replacement.
> [!NOTE]
> If `workflow finish` fails, the agent must fix the reported blocker before claiming completion. **That failure is the product working, not a bug.**
Three-beat setup, gate, and goal-entry walkthrough: **[Quick Demo](docs/QUICK-DEMO.md)**.
## TDD Rail (opt-in)
Enable both settings in `.persona/harness.jsonc`:
```json
{ "enforce": { "executeVerification": true, "tdd": true } }
```
`ph workflow test` is intended to record red evidence from PH-run Gradle/JUnit
failures, and `workflow check` / `archive` / `finish` record green evidence for
the same ticket/test id. Current P3 work is strengthening the authority model so
unsigned project-local artifacts cannot satisfy finish authority by themselves.
It is a red-first completion gate; it does not scaffold tests, prove test
sufficiency, run coverage/mutation, or certify app quality.
## Commands
```bash
npx ph attach [--yes] # existing Java/Spring/Gradle project
npx ph go "Add a task creation endpoint." # concrete single entry
npx ph workflow check | implement | finish implement | archive