harness-engineering

Harness Engineering

Use this skill to shift engineering work from hand-written code toward designing the environment where agents can reliably do the work.

Operating Model

Treat every agent failure as a systems signal:

1. Identify what capability, context, tool, invariant, or feedback loop was missing.
2. Add the missing piece to the repo, local tooling, CI, observability, or skills.
3. Validate that a future agent can discover and use it without private human context.
4. Prefer mechanical enforcement over prose when the rule needs to hold repeatedly.

Humans should steer priorities, acceptance criteria, and judgment calls. Agents should execute implementation, validation, review response, documentation updates, and cleanup wherever the repo gives them enough context and tools.

Repository Checklist

Start with the current repo, not a generic template.

• Verify pwd, branch, dirty state, package manager, CI, and test commands.
• Find or create a short AGENTS.md that maps to deeper docs instead of becoming a manual.
• Put durable knowledge in versioned files: architecture maps, product specs, quality scorecards, reliability constraints, security notes, and execution plans.
• Expose local app startup, tests, logs, metrics, traces, screenshots, and browser automation through commands an agent can run.
• Make each command self-describing: include examples, environment requirements, expected output, and common failure remediation.
• Encode repeated preferences into linters, type checks, structural tests, review bots, or scripts.
• Keep build and validation loops fast enough that agents can iterate without human babysitting.

Intervention Pattern

When a task stalls, do not only reprompt. Ask:

• Can the agent inspect the thing that matters?
• Can it reproduce the failure locally?
• Can it validate the fix without a human copying evidence into the prompt?
• Is the expected architecture or taste encoded in a check?
• Did the repo record the decision so a later agent can reuse it?

If the answer is no, improve the harness first or as part of the fix.

Deliverables

For an audit or setup task, produce:

• A prioritized list of missing agent capabilities.
• Specific repo files or commands to add.
• Mechanical checks to enforce non-negotiable rules.
• A short migration path from current workflow to agent-first workflow.

See references/source-notes.md for the distilled source basis.