create-harness-spec

Create Harness Spec

Grill a Hedera feature idea into a complete recipe for hedera-harness.

Load the shared vocabulary first: read ../harness-spec-anatomy/SKILL.md and its GLOSSARY.md. Use those terms exactly.

Targets hedera-harness schemaVersion 3.

These skills are for authoring. Recipes do not list skills — product plugins from hedera-skills are discovered per run and the generator picks. Keep the run blind: the PRD carries journeys and outcomes; numbered assertions live in the evaluate checklist.

Works in Claude Code (marketplace plugin) and Cursor / other agents that load SKILL.md. Prefer /grilling when that skill is installed; otherwise use the inline protocol — Claude Code typically takes the inline path.

Step 1: Locate the target

A recipe lives at .harness/ inside a scaffolded app. There is no other layout.

Situation	What to do
Cwd is a scaffolded app (Scaffold HBAR or hedera-harness init)	Author into its .harness/
Cwd is an app without .harness/	hedera-harness init adopts the harness in place
No app yet	hedera-harness init <dir> (optionally --template <name>)
Cwd already has .harness/spec.yaml	Check schemaVersion. If absent, 1, or 2, rewrite to v3 (or regenerate with init and reapply edits). hedera-harness migrate is gone.

Never treat a v1/v2 recipe as loadable. contract: → eval:, drop skills:, set schemaVersion: 3.

Paths in the recipe file are relative to the project root.

Step 2: Grill

Follow references/grilling.md. Prefer /grilling if available; otherwise use the inline protocol there.

Do not write files until the user confirms shared understanding.

Step 3: Emit the recipe

Prefer copying the shipped skeleton — it is always current:

cp -r "$(npm root -g)/hedera-harness/skeletons/project-harness/." .harness/

Then:

1. Write .harness/prd.md (or one file per increment under .harness/prds/) from the grill. Product-facing only — keep the run blind.
2. Fill .harness/spec.yaml. Required: schemaVersion: 3, name, description, and baseline with a command literally named install. Leave every default commented out. A four-key recipe is complete. Omit agent: unless the user wants Cursor (default is Claude).
3. Write .harness/validators/static.json and .harness/validators/yarn.json against the feature deliverables. Do not assert on template.json — create-scaffold-hbar removes it when scaffolding.
4. Do not add a skills: list. Mention relevant Hedera services in the PRD so the generator can pick product skills.
5. Add SMOKE / EVALUATE / CHAIN only if the user opted in during the grill — see harness-spec-anatomy → references/stage-strategy.md. If prd: is a list and EVALUATE is on, write a matching eval: list.
6. Install the SMOKE host package if you just enabled it — at the project root, not only inside a workspace. Doctor imports playwright from next to hedera-harness, and Yarn nmHoistingLimits: workspaces hides packages/nextjs installs.
   • SMOKE → yarn add -D playwright (or npm/pnpm equivalent) Skip the add if the root package.json already lists it. Do this as part of emit, not as a follow-up after doctor fails. CHAIN does not need a project install: @hiero-ledger/sdk ships with hedera-harness. Only the operator env vars are host-provided.

Reconstruct bodies by hand only when the skeleton is unavailable: harness-spec-anatomy → references/spec-files.md.

Step 4: Completion criterion

Two checks, in order:

# 1. Does the recipe load? (authoritative — schema, defaults, baseline, network)
hedera-harness doctor .harness/spec.yaml --recipe-only

# 2. Is it coherent across files? (traceability, stage pairing, blind rule)
bash <path-to>/harness-spec-anatomy/scripts/check-spec.sh <project-root>

check-spec.sh runs doctor itself, so running it alone is enough when the harness CLI is installed. If it reports that the schema was not validated, that is a partial result — install or upgrade the harness and rerun.

Done when check-spec.sh exits clean.

Then hand off:

# Prefer /review-harness-spec next, then:
hedera-harness run .harness/spec.yaml --max-attempts 3
# or: yarn harness:run

Point at the harness README for install, agent auth, and stage host prerequisites. hedera-harness doctor (without --recipe-only) checks those. Do not expand CLI teaching beyond these next commands.

Additional resources

• references/grilling.md
• Companion: /review-harness-spec
• Vocabulary: /harness-spec-anatomy
• Upstream: docs/authoring-a-recipe.md