agent-harness
Agent Harness
The agent harness is repo-level infrastructure that makes repositories agent-ready with self-sustaining enforcement. This skill is the installer; the harness enforces itself via CI, hooks, and conventions once installed.
Modes
1. Verify (primary)
Always start here. Run the verification script against the target repo:
scripts/verify-harness.sh /path/to/target-repo
Analyse the output. Fix issues directly or suggest fixes to the user. Verification checks for dead references, line count limits, missing artefacts, and command/target alignment.
2. Bootstrap
When artefacts are missing, create them from templates:
| Artefact | Template | Platform |
|---|---|---|
AGENTS.md |
templates/AGENTS.md.tmpl |
All |
docs/ARCHITECTURE.md |
templates/ARCHITECTURE.md.tmpl |
All |
docs/exec-plans/{active,completed}/ |
Create directories | All |
.github/workflows/harness-verify.yml |
templates/harness-verify.yml.tmpl |
GitHub |
.gitlab-ci.yml (harness-verify job) |
templates/gitlab-ci-harness-verify.yml.tmpl |
GitLab |
.github/pull_request_template.md |
templates/pull_request_template.md.tmpl |
GitHub |
.gitlab/merge_request_templates/Default.md |
templates/merge_request_template.md.tmpl |
GitLab |
.envrc |
templates/envrc.tmpl |
All |
| Makefile harness targets | templates/Makefile.harness.tmpl |
All |
scripts/verify-harness.sh |
scripts/verify-harness.sh (copy directly) |
All |
Populate templates with repo-specific values (project name, tech stack, existing conventions). Do not overwrite files that already exist without user confirmation.
3. Audit
Report the repo's maturity level (1, 2, or 3) and show what is needed to reach the next level. See references/maturity-levels.md for detailed criteria.
Key Principles
- AGENTS.md is an index, not an encyclopedia. Keep it under 150 lines. Put detail in
docs/. - Enforcement is project-level. CI workflows, git hooks, and branch protection enforce the harness -- not this skill at runtime.
- Verify first, bootstrap second. Always run verification before creating artefacts. The skill checks artefacts, not tools.
- Delegate specialist work. Route concerns to the appropriate skill:
- AGENTS.md content rules:
@agent-rules - Branch protection / merge checks setup:
@github-project(GitHub) or manual GitLab settings - Quality gates and CI pipelines:
@enterprise-readiness
- AGENTS.md content rules:
Maturity Levels
Level 1 -- Basic: AGENTS.md exists, serves as an index (not a wall of text), and documents available commands.
Level 2 -- Verified: CI checks enforce harness integrity, all AGENTS.md references resolve, documented commands match actual Makefile/script targets, and ARCHITECTURE.md exists.
Level 3 -- Enforced: Branch protection requires harness CI to pass, git hooks auto-activate on clone, PR template includes harness checklist, and drift detection runs on every push.
See references/maturity-levels.md for the full breakdown.
References
references/maturity-levels.md-- Detailed maturity level criteria and progression guidancereferences/agents-md-rules.md-- AGENTS.md authoring rules and anti-patternsreferences/artefact-inventory.md-- Complete list of harness artefacts with purposesreferences/delegation-map.md-- Which skill handles which concern