@gethmy/harness 1.0.0

package/README.md

@@ -0,0 +1,66 @@
+# @gethmy/harness
+
+Execution motor for [Harmony](https://gethmy.com) playbook stages.
+
+The motor runs **exactly one stage per invocation**, then exits. It sets up the
+worktree, dispatches the stage's subagent under that stage's `role`, places and
+runs a held oracle when the gate asks for one, collects the gate's evidence, and
+prints what it did as newline-delimited JSON.
+
+It deliberately does **not** decide anything. Harmony routes and advances;
+`gateEvaluate` in `@harmony/shared` turns evidence into a verdict. The motor
+never routes, never judges, never pushes.
+
+A *driver* invokes it. Today the drivers are `@gethmy/agent` (unattended) and the
+`hmy` skill (interactive). Installing this package on its own is useful only if
+you are building a driver.
+
+## Prerequisites
+
+- [Node.js](https://nodejs.org) >= 20 or [Bun](https://bun.sh) >= 1.0
+- Git
+- A [Harmony](https://gethmy.com) account with an API key
+- [Claude Code](https://docs.anthropic.com/en/docs/claude-code) available to the
+  agent SDK
+
+## Configuration
+
+Two environment variables, and nothing else. Both are required; the motor
+refuses to start without either, naming the one that is missing rather than
+failing later with a 401.
+
+| Variable | What it is |
+|---|---|
+| `HARMONY_API_URL` | The Harmony API **base** URL, e.g. `https://app.gethmy.com/api`. The motor appends `/v1` per request, so do not include it. A trailing slash is trimmed. |
+| `HARMONY_API_KEY` | A Harmony API key, or an OAuth access token (one starting with `hmy_at_`). Sent as the `X-API-Key` header — the same header `@gethmy/mcp` uses. |
+
+```bash
+export HARMONY_API_URL="https://app.gethmy.com/api"
+export HARMONY_API_KEY="…"
+```
+
+Generate a key with the `harmony_generate_api_key` tool on the Harmony MCP
+server, or from your account settings in Harmony.
+
+> These two variables are **credentials**. A stage whose `role` is `implementer`
+> is launched with both stripped from its environment — see `src/runner.ts` for
+> exactly what that does and does not close.
+
+## CLI
+
+```bash
+harmony-harness stage run \
+  --card <card-id> \
+  --stage <stage-id> \
+  --workspace <workspace-id> \
+  --repo <path-to-worktree> \
+  --session <agent-session-id>
+```
+
+Every flag is required. `--stage` must match the card's `current_stage`: the
+motor refuses to collect evidence for a stage the card is not on, and refuses a
+stage whose `owner` is `human`.
+
+Output is one JSON object per line on stdout — motor events, then a `result`
+object. Diagnostics go to stderr. A driver parses stdout; a human reads the
+driver's rendering of it.