harness-kit 🛠️

A distilled reference, scaffold generator, and checklist for the 12 theses of harness engineering.

Harness engineering is the practice of improving agent output by shaping the environment around the agent — context and tools — while holding the model constant. This kit distills Ryan Lopopolo's 12 theses into actionable reference files you can use at the moment of an unresolved decision.

Install

npm install -g @shift-zero/harness-kit

Or use directly with npx (no install needed):

npx @shift-zero/harness-kit

Usage

# List all 12 theses
npx @shift-zero/harness-kit

# Read thesis 6: "Make the repository teach the agent"
npx @shift-zero/harness-kit thesis 6

# Generate AGENTS.md + ARCHITECTURE.md scaffolding for your repo
npx @shift-zero/harness-kit scaffold

# With custom name
npx @shift-zero/harness-kit scaffold --name my-project --dir ../my-repo

# Run a repository review (diagnostic)
npx @shift-zero/harness-kit review

# Run the guided job-improvement playbook
npx @shift-zero/harness-kit improve

# Read the ICM ↔ Harness Engineering cross-reference
npx @shift-zero/harness-kit crossref

The 12 Theses

| # | Thesis | Use when... | |---|--------|-------------| | 1 | Hold the worker constant | Choosing/upgrading a model; requalifying environment | | 2 | Deploy into the private process-data iceberg | Deciding what context belongs in the repo | | 3 | Give one agent the whole job | Defining ownership; closing the lifecycle | | 4 | Route context just in time | Writing AGENTS.md; designing progressive disclosure | | 5 | Make capabilities legible and operable | Building tools, CLIs, MCP servers | | 6 | Make the repository teach the agent | Structuring code; encoding quality requirements | | 7 | Maximize autonomy inside explicit authority | Setting permissions and approval gates | | 8 | Prove the outcome in the real environment | Designing verification past "CI passes" | | 9 | Turn feedback into infrastructure | Making review comments and failures durable | | 10 | Preserve coherence and own lifetime risk | Planning migrations; managing dependencies | | 11 | Run known work as a continuous loop | Automating settled tasks | | 12 | Optimize for measured effectiveness | Evaluating whether a harness change is worth it |

Playbooks (new in v1.1.0)

| Command | Playbook | What it does | |---------|----------|--------------| | harness-kit review | Repository Review | Assess whether a repo's context, tools, architecture, proof, and authority let an agent complete real jobs. Follows Lopopolo's repository-review playbook. | | harness-kit improve | Improve One Job | Baseline → locate gap → intervention → verify → rerun. Closes one operational loop. | | harness-kit crossref | ICM Mapping | Cross-references harness engineering principles with ICM methodology (Identity, Coherency, Modularity). Shows how the two frameworks complement each other. |

This repo practices what it preaches

This repository follows the principles it teaches:

• AGENTS.md is a map, not a manual — short routing with linked theses
• One concept, one owner — each thesis is exactly one file
• Just-in-time routing — don't preload the whole corpus; read only what you need
• Progressive disclosure — summary → argument → sources → checklist

License

MIT — Zero (shift-zero)

Not a substitute

This is a study guide and practical reference, not a substitute for reading the full anthology. When you need depth, follow the source links in each thesis.