# v0.3.0 External Tester Guide

## Goal

Check whether Persona Harness can help a different user drive OpenCode through a Java/Spring backend workflow rail with observable read/injection/workflow traces and continuation reports.

This is an npm alpha install pilot for OpenCode users. Persona Harness can create planning files without OpenCode, but the core injection behavior requires OpenCode.

This is not a generated app product quality certification, Clean Code guarantee, AST/linter, or enforcement pilot.

## Test Scope

Run this flow in a clean project:

```text
ph init -> ph intake --interactive -> ph policy init -> ph plan -> OpenCode plan/implementation
```

## Minimal Command Path

Use this path when testing the published alpha package:

```bash
mkdir -p /tmp/persona-harness-external-check
cd /tmp/persona-harness-external-check
npm init -y
npm install -D persona-harness@alpha
cat > README.md <<'EOF'
# Equipment Rental API

- 장비를 등록할 수 있다.
- 장비 목록을 조회할 수 있다.
- 회원을 등록할 수 있다.
- 회원이 장비를 대여할 수 있다.
- 대여 중이거나 수량이 부족하면 실패한다.
- 본인 대여만 반납할 수 있다.
- Java/Spring Boot와 Gradle로 구현한다.
EOF
npx ph init
npx ph intake --interactive
npx ph policy init
npx ph plan
opencode run --dir . --model openai/gpt-5.4-mini-fast --dangerously-skip-permissions "$(npx ph plan --prompt)"
npx ph plan --accept
opencode run --dir . --model openai/gpt-5.4-mini-fast --dangerously-skip-permissions "플랜 보고 구현해줘"
```

If the implementation run stops early, record the stop point. Do not edit the generated project by hand before submitting feedback.

Observe whether the generated backend keeps these boundaries:

- Gradle only
- Java/Spring backend
- `presentation`, `application`, `domain`, `infrastructure`, and common `global` package boundaries where appropriate
- Controller delegates to Application Service
- Application Service orchestrates and does not own storage state or id sequence
- domain repository port lives in domain
- concrete repository implementation lives in infrastructure
- domain model owns behavior and is not just a passive record
- request/response DTO boundaries are visible

## Out Of Scope

Do not use this pilot to evaluate:

- frontend or infra workflow
- TDD workflow
- stable `latest` install
- desktop app
- AST/linter/enforcement behavior
- generated app product-quality certification

A generated app can be useful evidence without proving Persona Harness guarantees product quality.

Evidence here means traces of what the agent read, what context was injected, which workflow rail was selected, and which workflow commands ran. Evidence count must not be interpreted as generated-code quality.

A/B or ON/OFF smoke results are stack-steering signals only. They are limited by small sample size, often `n=1`, non-blind execution, same operator, and model/version/prompt/timeout/continuation behavior.

## Prerequisites

- Node.js 20+
- npm
- OpenCode terminal CLI
- model/provider configured in OpenCode

Install OpenCode:

```bash
curl -fsSL https://opencode.ai/install | bash
```

Alternative npm install:

```bash
npm install -g opencode-ai
```

Verify:

```bash
opencode --version
opencode
```

Connect a model provider:

```bash
opencode auth login
opencode auth list
```

Alternative TUI flow:

```text
/connect
/models
```

The model used in `opencode run --model <model>` must use OpenCode's `provider/model` format. Example:

```text
openai/gpt-5.4-mini-fast
```

## Install Persona Harness

```bash
mkdir -p /tmp/persona-harness-external-check
cd /tmp/persona-harness-external-check
npm init -y
npm install -D persona-harness@alpha
```

Create the project `README.md` first, then run Persona Harness setup:

```bash
npx ph init
npx ph intake --interactive
npx ph policy init
npx ph plan
```

`npx ph intake --interactive` requires an interactive terminal. Do not pipe answers into it. If you need a non-interactive draft, run `npx ph intake` and edit `.persona/project-profile.jsonc` manually.

Local/tarball install remains useful only for unreleased development builds:

```bash
mkdir -p /tmp/persona-harness-external-check
cd /tmp/persona-harness-external-check
npm init -y
npm install -D /absolute/path/to/persona-harness-0.3.0-alpha.2.tgz
npx ph init
npx ph intake --interactive
npx ph policy init
npx ph plan
```

## Project README Fixture

Create a `README.md` in the clean project before asking OpenCode to work.

Example:

```md
# Equipment Rental API

- 장비를 등록할 수 있다.
- 장비 목록을 조회할 수 있다.
- 회원을 등록할 수 있다.
- 회원이 장비를 대여할 수 있다.
- 대여 중이거나 수량이 부족하면 실패한다.
- 본인 대여만 반납할 수 있다.
- 없는 장비, 회원, 대여에 대해서는 적절한 실패 응답을 반환한다.
- Java/Spring Boot와 Gradle로 구현한다.
```

The domain can be changed. Avoid the old `reservation` or `roomescape` fixture when possible.

## Policy Overlay

After `npx ph policy init`, testers may leave policy files empty or add short backend preferences.

Example company policy:

```md
- Gradle 기반 Spring Boot 실행 앱은 `bootJar`를 끄지 않는다.
- domain repository port는 domain에 두고, 구현체는 infrastructure에 둔다.
```

Example personal philosophy:

```md
- domain model은 단순 record보다 자기 필드로 상태를 판단하는 class를 선호한다.
```

These are planning context only. They are not enforcement gates.

## Plan-Only Prompt

Run OpenCode once to complete the plan without implementation.

```bash
opencode run --dir . --model openai/gpt-5.4-mini-fast --dangerously-skip-permissions \
  "$(npx ph plan --prompt)"
```

Review the plan. If it is acceptable:

```bash
npx ph plan --status
npx ph plan --accept
```

If it is not acceptable:

```bash
npx ph plan --revise
```

Then ask OpenCode to revise the plan before implementation.

## Implementation Prompt

After accepting the plan, run:

```bash
opencode run --dir . --model openai/gpt-5.4-mini-fast --dangerously-skip-permissions \
  "README.md, .persona/project-profile.jsonc, .persona/policies, .persona/workflow/plan.md를 읽고, 계획이 accepted 상태인지 확인한 뒤 Java/Spring Gradle 기반으로 요구사항 전체를 구현해줘. 명령 실행은 가능하면 npx ph bearshell로 하고, 구현 후 npx ph bearshell gradle test, npx ph bearshell gradle build, 실행 가능한 Spring Boot 앱이면 npx ph bearshell --shell 'gradle bootRun --args=\"--server.port=<port>\"', HTTP happy/failure smoke를 실행해줘. .persona/workflow/implementation-report.md와 .persona/workflow/review-report.md를 채우고 npx ph plan --report-filled implementation 및 npx ph plan --report-filled review를 실행해줘."
```

## Evidence To Submit

Ask testers to submit:

- install method used
- exact OpenCode prompts used
- generated file tree under `src/main/java`
- `build.gradle` and `settings.gradle`
- whether `pom.xml` appeared
- `gradle test` result
- `gradle build` result
- whether `bootJar` stayed enabled
- `gradle bootRun` result
- HTTP happy path smoke result
- HTTP failure path smoke result
- `.persona/evidence` file count and examples of target paths
- `.persona/workflow/implementation-report.md`
- `.persona/workflow/review-report.md`
- subjective friction points

## What Not To Submit As Success Evidence

Do not treat these alone as success:

- `npm install` succeeded but no OpenCode run was attempted.
- `ph plan` created files but the plan was never accepted.
- OpenCode generated code but `gradle test` / `gradle build` were not attempted.
- reports are still `Status: template`.
- generated app only works after manual edits not made by OpenCode.

## First Risks To Watch

Prioritize these before code taste:

- install fails
- `npx ph init` fails
- `.opencode/opencode.json` does not connect the plugin
- `.persona/evidence` is not created after OpenCode work
- OpenCode reads installed package internals instead of generated project files
- OpenCode disables `bootJar`
- the tester cannot understand `ph intake -> ph plan`

## Decision Criteria

The pilot is positive when:

- install and `ph init` complete without manual repo editing
- the tester can finish `ph intake --interactive`, `ph policy init`, and `ph plan`
- OpenCode reads the plan/profile/policy files
- generated app uses Gradle and Spring Boot
- generated code shows Controller/Service/domain/repository/DTO boundaries
- independent `gradle test`, `gradle build`, and `gradle bootRun` pass
- at least one HTTP happy path and one failure path are smoke-tested

The pilot is partial when:

- generated code shape is acceptable but setup is confusing
- Gradle works only after workaround
- `bootJar` is disabled
- reports are missing or left as templates
- evidence exists but is noisy

The pilot is negative when:

- install/init fails
- OpenCode does not receive Persona Harness context
- generated project is Maven-based
- Service owns storage/id sequence
- domain model is only passive records despite profile/policy guidance
- the tester cannot complete the flow without project-owner help