onboard

Your working contract is the 4 rules; their digest is injected at session start - read ${CLAUDE_PLUGIN_ROOT}/core/RULES.md in full only if that digest is not in your context.

Attach Harmonia to a repository it did not scaffold. You capture the repo's own verify and coverage commands into .harmonia/project.yaml so the scoper authors success criteria against the repo's real commands and the coverage gate measures the repo with the repo's own tool instead of falling back to a built-in adapter.

This is not a lifecycle stage: it mints no task workspace and writes no marker or receipt. It writes exactly one file - .harmonia/project.yaml at the repo root - which the onboarded repo is meant to commit. On a second run it refines that file in place; see step 5.

What you write is a PROPOSAL. The coverage gate will not run the coverage: value until the developer records their consent to it with /harmonia:trust, which keeps that consent in a file under ${HARMONIA_HOME:-$HOME/.harmonia}, outside every repository unless HARMONIA_HOME itself is relative. Onboarding never records that consent on the developer's behalf, and never runs the recorder itself: writing the file and agreeing to run it are two acts, and the second one is theirs. Say so when you hand back - a repo whose project.yaml you just wrote is refused by the gate, by name, until they run it once.

That consent covers the command STRING and no file, which is why the value's words matter: a value naming a script means the developer is trusting that script for whatever it contains at the moment the gate runs it, including contents that arrive after they agreed.

Propose only a coverage: value consent can be recorded for, or the developer's next step fails in front of them. The recordable shapes: an optional leading cd <dir> && with a relative operand, then parts joined by ;, &&, || or | that each begin with one of nine words - a card interpreter below, bare and exact, followed by the script it runs, which carries a / and is not under /dev/ or /proc/; or an inert word.

interpreters: sh bash dash python python3 node
inert: echo true
bytes: 1024
words-per-part: 64
byte-class: 0x20-0x7e

Everything else is refused at /harmonia:trust. A path is not a program: a first word carrying a / is refused whatever it points at - ./gradlew, ./node_modules/.bin/vitest, /bin/sh, /usr/bin/env. So are make cov, npx vitest --coverage, pytest --cov=src, go test ./..., V=1 sh ./cov.sh, an option (-x, +x) where a script or directory belongs, a .. path component (../x, src/../lib; --out=../x and a..b are fine), a slash-less operand (sh cov.sh), cd /etc, a redirection, a glob, a $(...), a trailing # comment, a byte outside the card's class. Two rewrites bring a value back: a card interpreter in front of the file (sh ./gradlew jacoco, node ./node_modules/.bin/jest --coverage), or the command in a script the repository commits (sh ./.harmonia/cov.sh && echo cov.xml). Both end in && echo <report> with nothing else on stdout. Read the file's first line to choose the word: an npm shim is JavaScript, a pnpm shim is #!/bin/sh, a native binary or perl script takes the wrapper. Certify what you propose, not what you started from.

The interview, the run-before-record step, the end-to-end coverage certification, and the refine step are yours to carry out honestly. They are a prose contract, on the same footing as human acceptance today, not a technical guarantee.

The file you write

.harmonia/project.yaml is flat: one scalar per line, known keys only, no nesting and no arrays. Its reader is a bash line-reader, not a YAML parser, so each value sits on a single physical line.

# .harmonia/project.yaml - this repo's canonical verify commands and its own
# coverage command. Read by the scoper (the four verify commands) and by the
# coverage gate (the coverage command). Written by /harmonia:onboard; safe to
# hand-edit; commit it.
test: <shell command>
lint: <shell command>
typecheck: <shell command>
build: <shell command>
coverage: <shell command>