claude-skill-hill-climbing

npm package that adds structured hill-climbing iteration to Claude Code. Define measurable fitness dimensions, improve one step at a time, and let an overseer keep you honest.

Install

npm install claude-skill-hill-climbing

Postinstall copies skills and commands into your project's .claude/ directory automatically.

What's Included

| Component | Type | Purpose | |-----------|------|---------| | hill-climbing | Skill | Execute ONE iteration: measure, plan one change, execute, measure again, pause | | climb-overseer | Skill | Monitor active climbs for plateaus, regressions, and goal completion | | /climb | Command | Launch a supervised session with worker + overseer cron loops |

Quick Start

Single iteration

/hill-climbing improve test coverage for TokenSwap

Claude measures baseline, plans one focused change, executes it, measures again, logs results, and pauses.

Supervised session

/climb improve test coverage for TokenSwap

This sets up recurring crons: a worker every 5m, an overseer every 25m, and auto-expiration at 1h. The overseer detects plateaus, regressions, and goal completion — nudging or terminating as needed.

/climb 10m expires:3h improve test coverage for TokenSwap

Custom timing: 10m worker interval, 50m overseer interval, 3h expiration.

Fitness Dimensions

Each climb tracks measurable dimensions with direction indicators:

• ↑ — higher is better (e.g. branch coverage %)
• ↓ — lower is better (e.g. revert rate, LoC)
• = — must not change (e.g. test count stays passing)

Progress is logged to .hill-climb/<slug>.md artifacts that persist across sessions.

How It Works

1. Worker (hill-climbing) runs one iteration per session — measure, change, measure, log, stop
2. Overseer (climb-overseer) checks artifacts periodically and detects:
   • Goal met — all targets reached, terminates the climb
   • Regression — a dimension moved the wrong way, warns
   • Plateau — 3+ iterations with no progress, nudges with alternatives
   • Stuck — second consecutive nudge without improvement, terminates
3. Launcher (/climb) wires both together via crons with automatic expiration

Development

Edit skill files in skills/. The local .claude/skills/ symlinks to this directory so Claude Code picks up changes without a copy step.

Local Testbed

This repo includes a Solidity project used to test the hill-climbing skills, commands, and hooks locally. These directories are not part of the published npm package:

| Directory | Purpose | |-----------|---------| | contracts/, test/ | Foundry project — target codebase the skill iterates on | | smart_contracts/, src/ | Additional contract/app source for testing varied scenarios | | hooks/ | Event hooks (subagent lifecycle) used during supervised climbs | | foundry.toml | Foundry config for the testbed | | lib/, out/, cache/ | Foundry build artifacts (gitignored) | | .hill-climb/ | Climb artifacts generated during test runs |

Only skills/, agents/, commands/, and install.js are published to npm (see files in package.json).

forge test        # run Solidity tests
npm pack --dry-run # verify published file list

License

MIT