# Adoption Guide

How an agent team installs UX3 Product Design Harness, and what "installed"
means for a repository.

The goal is not more process. The goal is fewer polished artifacts built on
weak assumptions.

## 1. Install

| Step | Action |
|---|---|
| 1 | Clone or vendor this repository. It is prompts, schemas, and agent definitions; there is no runtime service to deploy. |
| 2 | Confirm the copy is intact: `python3 -m venv .venv`, then `.venv/bin/python -m pip install -r requirements-dev.txt`, `.venv/bin/python -m unittest discover -s tests`, `.venv/bin/python scripts/validate.py`, and `.venv/bin/python scripts/check_review.py examples/quick-gate-review.json`. |
| 3 | Install with `npx skills add cis2042/product-design-harness -g -y`, or copy `skills/product-design-harness/SKILL.md` together with its `resources/` directory into the agent configuration. |
| 4 | Wire `prompts/start-review.md` from a full clone, or `resources/prompts/start-review.md` from an installed skill, as the entry prompt for every product review. It selects Quick Gate, Standard Gate, or UX3 Council. |
| 5 | Register the reviewer agents from `agents/registry.json` in a full clone, or `resources/agents/registry.json` from an installed skill. Each entry names its instruction file, input schema, and output schema, so any agent runtime can load them. |
| 6 | Validate every review output with `scripts/check_review.py` in a full clone, or `resources/scripts/check_review.py` from an installed skill, and reject anything invalid. JSON Schema checks shape and conditional branches; `check_review.py` also enforces worst-verdict, weakest-flow, and headline-tier semantics. |

## 2. Continuous Validation In CI

- Add a CI job that validates stored review results with `scripts/check_review.py`
  before anyone acts on them.
- Reuse this repository's workflow as a template:
  `.github/workflows/validate.yml` runs the test suite plus
  `scripts/validate.py` on every push and pull request.
- Use the golden examples as fixtures: `examples/quick-gate-review.json`,
  `examples/standard-gate-review.json`, `examples/ux3-council-review.json`.
- Record human decisions with `schemas/human-decision.schema.json` so every
  review links to an accountable decision record and back, with reversal
  conditions.

## 3. First Integration: Standard Gate On One Feature

Do not roll the harness out everywhere at once. Run one real feature through
Standard Gate:

1. Pick one upcoming feature.
2. Fill `templates/product-brief.md`.
3. Run `prompts/gate-review.md` in Standard Gate mode.
4. Validate the result with `scripts/check_review.py`.
5. Record the human decision in `templates/decision-log.md` (machine form:
   `schemas/human-decision.schema.json`).
6. If the verdict is `continue`, create `templates/context-pack.md` and hand
   it to execution.

Then widen: Quick Gate before small reversible changes, UX3 Council for
high-uncertainty or expensive decisions.

## 4. Live Coding Adoption

Live coding teams should use `docs/LIVE-CODING.md` as the operating guide.
The shortest safe path is:

| Step | Action |
|---|---|
| 1 | Select the working language and keep identifiers in English. |
| 2 | Convert the request into a product brief before coding. |
| 3 | Run the smallest responsible review mode. |
| 4 | Validate the review with `scripts/check_review.py`. |
| 5 | If the verdict is `continue`, create and validate a context pack. |
| 6 | Implement only inside the context-pack execution boundary. |
| 7 | If scope, data, risk, or affected people change, pause and run review again. |
| 8 | Classify post-build feedback as evidence for the next iteration. |

Use the golden chain as the first fixture:
`examples/live-coding-product-brief.json`,
`examples/live-coding-review.json`, and
`examples/live-coding-context-pack.json`.

## 5. What "Installed" Means

A repository has installed the harness when all of the following are true:

| Check | Evidence |
|---|---|
| Entry prompt wired | Agent configuration references `resources/prompts/start-review.md`, directly or via the installed skill. |
| Outputs validated | Every review result is validated with `scripts/check_review.py` before it is acted on. |
| CI rejects invalid results | A CI job fails on invalid review results, including semantic weakest-flow and headline-tier mismatches. |
| Decisions traceable | Human decisions are recorded against `schemas/human-decision.schema.json` with the review id, an accountable owner, and reversal conditions. |
| Context packs gated | Context packs are created only after a `continue` verdict. |
| Live coding bounded | Coding begins only from a validated `schemas/context-pack.schema.json` artifact. |

## 6. Team Ritual

| Moment | Harness action |
|---|---|
| Before writing requirements | Fill product brief. |
| Before prototype or build | Run gate review. |
| Before launch | Run uncertainty review. |
| After learning | Update decision log and evidence ledger. |
| Before scaling | Run UX3 Council. |

## 7. Common Anti-Patterns

| Anti-pattern | Correction |
|---|---|
| Building because it is easy. | Run Business Flow and Evidence Flow. |
| Treating a quote as proof. | Separate quote, behavior, log, and counter-signal. |
| Averaging reviewer verdicts. | Let the weakest flow control the next step. |
| Skipping human judgment. | Route taste, risk, strategy, ethics, and meaning to humans. |
| Creating broad context packs. | Narrow scope and add stop conditions. |
| Treating live-coding prompts as approval. | Require a valid review and context pack before implementation. |