# Persona Harness
**Project philosophy, conventions, and evidence-first workflows for AI coding agents, with portable skills and a Java/Spring workflow rail.**
[](https://www.npmjs.com/package/persona-harness)
[](https://www.npmjs.com/package/persona-harness)
[](https://nodejs.org)
[](./LICENSE)
[English](https://github.com/jyt6640/persona-harness/blob/main/README.md) | [한국어](https://github.com/jyt6640/persona-harness/blob/main/docs/current/README.ko.md) | [日本語](https://github.com/jyt6640/persona-harness/blob/main/docs/current/README.ja.md) | [简体中文](https://github.com/jyt6640/persona-harness/blob/main/docs/current/README.zh-cn.md)
**[Start Here](docs/START-HERE.md) · [Quick Demo](docs/QUICK-DEMO.md) · [Measured Claims](docs/MEASURED-CLAIMS.md)**
[Astra migration, prompts, and AGENTS.md (한국어)](docs/current/astra-migration-guide.ko.md)
## See it in 30 seconds
**The problem:** an AI coding agent says "Done!" after a Java/Spring change,
but the test, build, and review evidence behind that claim is missing or stale.
**Install from a project directory:**
```bash
npm install -D persona-harness && npx ph init && npx ph bootstrap backend
```
**Give the agent one concrete backend goal, then ask the gate to verify it:**
```bash
npx ph go "Add a task creation endpoint."
npx ph workflow finish implement
```
For an explicitly selected product-discovery conversation that can carry only
approved decisions across Codex, Claude Code, OpenCode, and Antigravity:
```bash
npx ph interview start --json
```
**What has actually been observed:** a simple forged-evidence fixture is
ignored and `finish` exits `1`; the opt-in TDD rail blocked green-only
completion in 5/5 measured runs. Runtime injection did not improve the paired
OpenCode measurements and added cost, so it remains default-off. Compact
shared-skill routing is separate, defaults on after `ph init`, and can be
disabled with `features.sharedSkillRouting: false`.
**Built for:** Java/Spring/Gradle projects with explicit workflow gates and
evidence checks. `ph init` materializes portable, project-local skill adapters
for Codex, Claude Code, OpenCode, and Antigravity. Static adapter installation
is package behavior; a host's live skill selection and delivery are separate
observation boundaries.
**Not a promise of:** automatic implementation, generated-app quality,
production readiness, token savings, or broad security guarantees.
**Start with:** [Quick Demo](docs/QUICK-DEMO.md) · [Measured Claims](docs/MEASURED-CLAIMS.md) · [Install guide](docs/START-HERE.md)
> [!IMPORTANT]
> **Versioned, evidence-first.** Live registry channels, tags, GitHub releases,
> and audit lifecycle facts are maintained by governed workflows and release
> records; source release notes are inputs, not standalone proof. 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). Measured against the pre-authority gate; `finish` now also requires external authority in every configuration, so the "allowed" arm is no longer reproducible as written.
- **Runtime injection**, 10 paired OpenCode runs → equal success (10/10 both), but PH ON cost more on every pair → kept **default-off**.
- **Observer findings surfaced to the agent**, 10 paired OpenCode runs → remaining violations did not drop (3.50 off vs 3.80 on) → 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.
Persona Harness exposes two deliberately separate tracks:
- **Workflow Integrity** is the existing evidence and completion-gate product.
- **Context Personalization (Experimental)** is a local, default-off path for
targeted convention guidance. Enabled adapters offer a bounded Context block
after safe observed file targets. Version 1.1.0 adds
Codex and Claude plugin hooks alongside OpenCode; this does not establish
live model receipt or grant completion authority.
### Context Boundary
- **Activation:** `context.enabled` is explicit and `default-off`; it does not
inherit broad runtime guidance switches.
- **Authority:** Context is `non-authoritative`: it cannot grant completion or
verification authority.
- **Isolation:** Context-only paths do not execute project commands or contact
GitHub/network.
- **No inferred skill route:** for the existing OpenCode route, a Context-only or partial `.persona` directory
without the regular manifest created by `ph init` does not enable automatic
shared-skill routing or an interview. Resolve the project state explicitly
before enabling those routes.
- **Host:** `ph init` installs static skill adapters for Codex, Claude Code,
OpenCode, and Antigravity. The packaged Codex/Claude hooks add
bounded session guidance and targeted Context transport after host trust.
Actual delivery and behavior remain separate observations; see the
[portable host boundary](docs/current/portable-host-adapters.md).
- **Evidence:** Context usefulness remains `INCONCLUSIVE` until independent
external evidence exists.
- **Product focus:** the productized workflow focus is Java/Spring. The
TypeScript reference implementation and fixtures support this experimental
Context boundary; they are not a TypeScript code-quality claim.
Context configuration is separate from legacy runtime guidance switches. A
missing block stays disabled. An explicit `context.enabled` setting controls
only the targeted Context adapter; it does not enable legacy runtime guidance,
write configuration, or create workflow/evidence/authority state:
```jsonc
{
"context": {
"enabled": false,
"mode": "targeted",
"maxCapsules": 8,
"maxChars": 1600
}
}
```
Only `targeted` is accepted. Invalid or unknown Context fields leave Context
disabled with a bounded diagnostic; they do not inherit enablement from
`features.runtimeInjection` or `features.projectPhilosophyInjection`.
`ph context status` is available as a read-only local inspection of that
configuration and an optional safe Team Profile. `ph context preview