harness-engineering

Audit, scaffold, and maintain agent harnesses across multi-repo clusters with a 12-dimension rubric.

Updated Feb 6, 2026
One-click install
npx skills add https://github.com/maycuatroi1/agent-skills --skill harness-engineering-maycuatroi1
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: harness-engineering
Source: https://github.com/maycuatroi1/agent-skills/tree/main/skills/harness-engineering
Command: npx skills add https://github.com/maycuatroi1/agent-skills --skill harness-engineering-maycuatroi1

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill requires pyyaml, and includes scripts (resource) and references (resource) components.

What problem does it solve? Coding agents underperform when their environment is underspecified: they re-derive how to run the app every session, break sibling repos because nothing registered the seam between them, and drift across long sessions with no memory. This Skill builds and maintains the harness around the agent - AGENTS.md maps, boot scripts, acceptance specs, seam registries, and cross-repo execution plans - for clusters of tightly-related repositories. ## Core Features & Use Cases - Audit and doctor: Score a repo cluster against a 12-dimension rubric (map, bootability, inter-session memory, contract registry, deployment topology, and more) and detect drift such as dangling cross-repo links, duplicated skills, and plans that disagree with actual git branches. - Maintain loop (garden): A SessionEnd hook records raw session facts as JSON; the garden command batches that evidence into cited proposals for missing harness artifacts, which you review and apply onto branches - nothing is ever pushed or merged automatically. - Cross-repo exec-plans: Create plans with explicit merge orders for changes spanning multiple repos, then diff the plan against real git state with plan status. - Use Case: You manage a docs repo, a backend, and an e2e suite where spec moves keep breaking consumers. Run init to generate the cluster manifest, audit to find that no seam registry exists, then register each shared document in contracts.yaml with a verification command so drift fails a check instead of silently breaking e2e. ## Quick Start Ask the agent to run python harness.py init --workspace <your workspace dir> --name <cluster-name> from this skill's scripts directory, then run python harness.py audit to see the top harness gaps.

Frequently Asked Questions about harness-engineering

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I audit my agent setup across multiple repos?

Run python harness.py init --workspace <dir> --name <cluster> to discover the git repos and write harness.yaml, then run python harness.py audit. It scores the cluster against a 12-dimension rubric and prints the top gaps with a concrete next artifact for each.

How do I stop Claude from forgetting how to run my app every session?

Create an init.sh or init.ps1 boot script and name it in the repo's AGENTS.md map. The rubric's bootability dimension scores this directly, and the garden loop proposes an init script when session evidence shows repeated boot-command fumbles.

What is a cross-repo seam and how do I track one?

A seam is anything crossing a repo boundary: an API schema, shared spec document, event name, env var, or generated client. Register each in contracts.yaml with an owner, consumers, and a verify command; a seam without verification is documentation, not a harness.

Does harness-engineering work on Windows?

Yes. The harness.py CLI is cross-platform Python requiring only PyYAML, and the SessionEnd hook ships in both PowerShell (session-end.ps1) and POSIX shell (session-end.sh) variants.

When should I not use a cluster harness?

Skip it for a single repo, for repos that never force changes in each other, or when every change touches all repos with the same merge order - that last case means the cluster should be a monorepo, and scaffolding will not fix it.

Why does the garden loop produce vague proposals?

Vague proposals mean the evidence threshold is too low. Raise min_occurrences in harness.yaml so single-session stumbles are treated as noise; a proposal that does not cite a specific command, error, or user correction is slop and should be rejected.