hone

hone

A Claude Code plugin that refines a codebase by cutting. A human writes a short Plan; an automated loop then builds, verifies, consolidates, reviews, and lands each change unattended, working in an isolated git worktree. The repo keeps only truth that cannot go stale, and every cycle deletes something.

To hone is to sharpen a blade by grinding material away: refinement through removal.

The full model (artifacts, the loop, the checkers, the invariants) lives in docs/model.md. This README covers install and use.

Install

Add the plugin and enable it in your project's .claude/settings.json:

{
  "enabledPlugins": { "hone@hone": true },
  "permissions": {
    "allow": ["Bash(claude -p:*)"],
    "deny": [
      "Write(./scripts/run-tests.sh)", "Edit(./scripts/run-tests.sh)",
      "Write(./scripts/typecheck.sh)", "Edit(./scripts/typecheck.sh)",
      "Write(./scripts/lint.sh)", "Edit(./scripts/lint.sh)",
      "Write(./.claude/settings.json)", "Edit(./.claude/settings.json)"
    ]
  }
}

The permissions.allow entry lets run's review step invoke the native /code-review in a nested headless Claude Code. Claude Code now disables model invocation of that command, so hone runs it as a print-mode user turn (claude -p "/code-review …"); without the rule that nested call is gated and run can't stay unattended.

The permissions.deny entries are the file-tool half of hone's tamper resistance (see Tamper resistance below). The bash-guard only closes the shell routes around the gate; the guard protects src/, tests/, docs/, and db/ but not the gate's own machinery. These rules stop Write/Edit from mutating the test adapter or settings directly. Extend the list to any other adapter or config your project treats as protected.

Then, once per project, install the test adapter and the durable-docs skeleton:

bash "${CLAUDE_PLUGIN_ROOT}/scripts/setup.sh"

setup.sh picks a test-adapter template for your ecosystem, gitignores the temporary artifacts (.worktrees/ and the markers, though Plans are tracked), and creates docs/decisions/, docs/notes/, docs/open-questions.md, and src/. Add the optional scripts/typecheck.sh and scripts/lint.sh where your language has them; the gate runs each when present. The adapter contract is templates/run-tests/README.md.

hone assumes a src/<area>/ layout: the guard requires a failing test before new code under src/, the nag maps each Note to a src/<area>/, and the gate watches src/ and tests/ for work in flight. Keep production code under src/ (Python packages too: src/<pkg>/ is a supported layout), or that enforcement silently does nothing.

Use

• /hone:plan <change>: author .plans/<change>.md, the one hand-written artifact (what, why, how you'll know it works), and commit it. It is tracked, and the change's landing merge later removes it (git history keeps it).
• /hone:run <change>: execute that Plan through the loop and land it green. /hone:run --all runs every ready Plan, landed one at a time. It first checks the set for independence: disjoint Plans run in parallel worktrees, overlapping ones sequentially.
• /hone:garden: the continuous-maintenance loop. Scans the whole repo for durable-layer drift between changes (orphan Notes, broken Governs: links, redundant tests, dead code, stale open questions) and lands the safe cuts (deletion-only, each proven safe by the suite) through the same worktree loop. Meant to run often and small, on whatever schedule the project already has (a print-mode claude -p "/hone:garden").

Everything after the Plan is automatic. run proceeds unattended and stops only when blocked with no resolution, genuinely ambiguous, or done. On a stop it leaves the worktree as evidence and escalates, and never disables a gate to proceed.

Enforcement

Three hooks run the laws, from hooks/:

• guard (PreToolUse): no production code without a failing test, and no direct edits to src/, tests/, docs/, or db/ in the primary tree (that work belongs in a worktree, landed by a merge). .hone-durable-paths adds project-specific paths to the protected set.
• gate (Stop): the test suite, plus type-check and lint where present, stay green. A failure blocks the turn.
• nag (Stop, advisory): a leftover Plan, an oversized Note, a Note with no matching src/ area, a Decision/Note whose Governs: path no longer exists, a merged hone/* branch land forgot to delete, or a change about to land that deletes nothing.

Two critics, each prompted to find fault rather than approve, fill the judgment slots: plan-critic (checks the Plan at the end of /hone:plan, with the human present to revise a rejection) and consolidate-critic (checks what a change leaves behind in docs and tests). Review reuses Claude Code's built-in /code-review.