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.
npm install -g @shift-zero/harness-kitOr use directly with npx (no install needed):
npx @shift-zero/harness-kit# 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| # | 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 |
| 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 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
MIT — Zero (shift-zero)
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.