// Onboarding and router for the harny plugin. Teaches the harny mental model (run anatomy, .harny/ state, architect role) and routes to focused skills. Use when adopting harny or unsure where to start.
| name | harny |
| description | Onboarding and router for the harny plugin. Teaches the harny mental model (run anatomy, .harny/ state, architect role) and routes to focused skills. Use when adopting harny or unsure where to start. |
| allowed-tools | Bash, Read |
This is the umbrella skill for the harny plugin. Use it when:
The skill teaches the mental model and routes you to the focused skill that does the actual work.
harny is a TypeScript task launcher built on the Claude Agent SDK. It runs a planner → developer → validator loop on your behalf, with the orchestrator (harny) committing only after the validator passes.
In practical terms: instead of telling Claude "do this thing in my repo and figure out when you're done", you tell harny "do this thing, and the validator command tells you when you're done." Harny handles iteration, retries, branch management, and commits.
You stay in the loop as the architect. You decide what to ship, what success looks like, and when to merge. Harny does the execution within your guardrails.
When you invoke harny --name <slug> "<your prompt>":
CLAUDE.md and produces a plan (plan.json) with one or more tasks.git reset --hard to the pre-phase SHA.harny/<slug> with one or more commits. You merge it (or not) when ready.State of the run lives at <cwd>/.harny/<slug>/:
state.json — phases, status, history.plan.json — task list with verdict history.transcripts/ — per-phase SDK transcript pointers..harny/ directory is gitignored — per-clone, never committed.The harny plugin uses the word architect for the human (you) operating from the outer Claude Code conversation — the conversation in your terminal where you interact with Claude. This is distinct from the agents inside a harny run (planner, developer, validator), who are not the architect.
The architect:
/release)./learn for later triage via /drain.The architect does not:
/release).| You want to... | Use |
|---|---|
| Evaluate whether your repo is ready for harny | /check-repo |
| Note something interesting mid-conversation, no analysis | /learn <text> |
| Triage accumulated learnings into Issues / CLAUDE.md edits / discards | /drain |
| Post-mortem a single harny run that surprised you | /review <slug> |
| Operate as release manager across multiple harny runs | /release |
| Have an agent dispatch + monitor a harny run for you in natural language | Task(subagent_type: "orchestrator", ...) |
Prefix all skills with /harny: if your Claude Code resolves them by full namespace (e.g., /harny:check-repo).
If this is the first time you're using harny in a given repo, follow this order:
bun install -g @lfnovo/harny
# or: npm install -g @lfnovo/harny
harny --version # confirm
/check-repo/check-repo
Walk through the 10-dimension readiness checklist. The skill produces a scorecard plus a prep checklist. Do the prep before the first run — it's much cheaper to fix readiness gaps now than to debug them mid-run.
If your repo has accumulated lint/type debt on main, or if your validator command is non-obvious, document it explicitly for harny:
## For Automated Agents
If you are an automated coding agent (harny, Claude Code in headless mode, etc.):
### Validator command
<paste the exact one-liner>
### Do NOT use as gates
<list tools that have pre-existing debt — explain why>
This single section saves hours of mid-run debugging.
Surgical scope. One module. Clear acceptance criteria. Do not start with "rewrite the auth system" — start with a bug fix or a single-file enhancement.
harny --name <some-slug> "<outcome statement + AC + constraints>"
Or have the orchestrator agent do it:
@orchestrator <natural-language intent>
Check the diff before merging. If the run was non-trivial, run /review <slug> to extract learnings. Capture anything noteworthy via /learn.
git checkout main && git merge --no-ff harny/<slug>
Skipping this between runs causes the sibling-branch silent-regress gotcha. Always merge to main between sequential runs unless explicitly stacking.
Each phase (planner, developer, validator) is driven by a markdown prompt that ships bundled with the CLI. You can override any subset per-repo by dropping files into .harny/prompts/<workflow>/<variant>/<actor>.md.
Resolution order (first match wins):
<cwd>/.harny/prompts/feature-dev/<variant>/<actor>.md<cwd>/.harny/prompts/feature-dev/default/<actor>.md<variant> then defaultWhere <actor> is planner, developer, or validator. Override only the actors you want — the rest fall through to bundled defaults.
Two common shapes:
.harny/prompts/feature-dev/default/validator.md with extra acceptance rules (e.g., "every new function must have a test"). Planner and developer keep the bundled defaults.default/ and stash an experimental version at <variant>/, then dispatch with harny --variant <name> .....harny/ is gitignored as a whole — to version overrides, add an exception in .harny/.gitignore for the prompts/ subtree.
harny clean <slug> deletes a single run's state — the .harny/<slug>/ directory, the harny/<slug> git worktree, and the local harny/<slug> branch. It's per-slug only (no batch, no --all, no status filter).
harny clean <slug> # safe path: refuses if the run is active
harny clean <slug> --force # SIGTERM the running process group, then clean
harny clean <slug> --force --kill # SIGTERM, then SIGKILL after 5s, then clean
With no flags, clean refuses if state.json shows status=running with a live PID. Stale PIDs (process already gone) are detected and cleanup proceeds with a warning. --force terminates the process group; add --kill only if the process ignores SIGTERM.
plan.json or state.json from an older harny version may fail validation on a fresh dispatch. Cleaning the offending slug is the official migration path.--name <slug> and the previous run left a worktree/branch behind./review or /drain later. The on-disk state is the only record of what planner/developer/validator actually did — transcripts alone don't reconstruct verdicts and history.Default is preserve. harny ls, harny show, and harny ui all rely on the on-disk state, so a wiped slug disappears from those views too.
ANTHROPIC_API_KEY in target repo's .env. Bun auto-loads .env from cwd. If the target has the API key set, the SDK uses pay-per-use API billing instead of your Claude Code (Max/Pro) subscription. Workaround: prefix invocation with ANTHROPIC_API_KEY= harny ... (empty string overrides).orchestrator agent./check-repo./learn.This skill teaches and routes. The other skills do.
/check-repo.@lfnovo/harny CLI. CLI breaking changes do not bump this plugin and vice-versa..harny/<slug>/ (which is gitignored) unless explicitly requested. They do not modify your code.Walk a repo through the harny readiness checklist. Score 10 dimensions Red/Yellow/Green, surface anti-signals, output a scorecard + prep checklist. Use when adopting harny in a new repo, or troubleshooting why it struggles in a familiar one.
Triage accumulated learnings from the local harny inbox into GitHub Issues, CLAUDE.md edits, or discards. Walks one entry at a time, verifies claims against current code, opens issues with provenance. Sister of /learn.
Append a one-line learning to the local harny inbox. Fast, non-analytical capture — copies text verbatim, no analysis, no follow-ups. Use when the user wants to note something about harny adoption mid-conversation without breaking flow.
Orchestrate a release cycle across multiple harny runs. Dispatch with product-vision prompts, parallelize when safe, code-review every merge, triage findings into NOW-blocks/NOW-quick/BACKLOG. Use as release manager across N runs.
Post-mortem of a single harny run. Reads state.json + plan.json + per-phase transcripts. Emits a leaves-to-trunk review with evidence-backed proposals (triaged NOW-blocks/NOW-quick/BACKLOG). Use after failed, retried, slow, or novel runs.