Skip to content

harness-toolkit

Harness Engineering Toolkit for agent-ready repositories.

Use hk / harness-kit for portable planning, validation, and handoff workflow in existing repos. Use harness-scaffold to start a new repo with the workflow, docs, CI, and stack defaults already wired in.

For the product philosophy behind HK's lifecycle, config, and readiness model, see Harness Kit: Dumb Tasks, Smart Agents.

What it is

harness-scaffold is a clone-and-init template. You clone it, run mise run init, and it transforms itself into your project — removing scaffold scaffolding, applying your project name, and verifying the golden path passes before handing control over.

Every generated project ships with a three-surface split:

  • SPEC.md — correctness envelope (requirements, contracts, invariants)
  • AGENTS.md — how to work here (commands, repo map, workflow)
  • docs/ — routed durable docs with explanation/reference/tutorial/how-to structure

The key insight: agents (and humans) benefit from a fixed command surface. Regardless of language, repo shape, or tooling choices, every project initialized from this scaffold exposes the same stable task contract:

mise run fmt        # format
mise run lint       # lint
mise run typecheck  # type checking
mise run test       # unit tests
mise run check      # all of the above (fast gate)
mise run plan       # create a plan directory for a unit of work on a feature branch
mise run sync-check # verify the slice is fully planned, evidenced, and reviewed
mise run verify     # heavy validation (integration, docker, etc.)

Why mise

mise manages both tool versions (Python, Go, uv, gofumpt, golangci-lint) and task definitions in one config file. It replaces Makefiles, shell scripts, and per-language task runners with a unified interface that works the same locally and in CI.

Quick start

Install the CLIs for portable use in existing repos:

uv tool install git+https://github.com/safurrier/harness-toolkit.git
hk --version

Initialize a new repo from the scaffold:

# 1. Install mise (only prerequisite)
curl https://mise.run | sh

# 2. Clone
git clone https://github.com/safurrier/harness-toolkit.git my-project
cd my-project

# 3. Install tools
mise install

# 4. Initialize
mise run init

See Getting Started for the full walkthrough and Release and Installation for uv tool installs and tag releases.

Supported stacks

Stack Format Lint Typecheck Test Status
Python ruff format ruff check ty pytest ✅ Available
Go gofumpt golangci-lint go vet go test ✅ Available
Rust cargo fmt cargo clippy cargo check cargo test ✅ Available
Web prettier eslint tsc vitest ✅ Available