A self-verifying, full-lifecycle software engineering harness for AI coding assistants.
One repo. Any agent. Any project. From big picture to shipped feature — with human gates, smart templates, and logical phases for large BRDs.
Read the full article: Harness Engineering in Practice — the rationale, design philosophy, worked examples, and limitations.
Open your AI agent in your project directory and paste this:
read https://github.com/AvonS/harness-eng/blob/main/commands/init.md and follow the instructions to initialize harness-eng in this folder
| Folder state | What the agent does |
|---|---|
| Empty | Asks questions, builds requirements from conversation |
| Existing code | Reverse-engineers BRD, constitution, architecture |
| PRD + ADR ready | Derives all documents from existing docs |
| Has .harness-eng/ | Upgrades tooling, preserves customizations |
read https://github.com/AvonS/harness-eng/blob/main/commands/upgrade-harness.md
and follow the instructions to upgrade harness-eng in this folder
Important: The fetched upgrade command may differ from your local version. Always use the FETCHED command's instructions, not your local copy.
Project-specific files are NEVER overwritten: CONSTITUTION.md, BRD.md, ARCHITECTURE.md, technology.yaml, sanity-check.sh, SLICE_LOG.md.
init → define → design → approve → tasks → build → review-pre-verify → verify → release
| Step | Command | What happens | Gate |
|---|---|---|---|
| 1 | /h:init |
Derive constitution, BRD, architecture | — |
| 2 | /h:define |
Create feature spec. Large BRDs auto-organize into phases | — |
| 3 | /h:design |
Design architecture, interfaces, file layout | — |
| 4 | /h:approve |
Human reviews design — approve or request changes | ✅ Human |
| 5 | /h:tasks |
Break into granular tasks with dependencies | — |
| 6 | /h:build |
TDD implementation — one commit per task | — |
| 7 | /h:review-pre-verify |
Sr Tech Lead review — compare design vs code, catch gaps | ✅ Agent |
| 8 | /h:verify |
Run tests, check acceptance criteria, sanity-check | — |
| 9 | /h:release |
Human approves release — PR, merge, archive, update status | ✅ Human |
Three gates: Design approval (step 4), Sr Tech Lead review (step 7), release approval (step 9).
For bugs or CRs, use the shortened workflow:
read https://github.com/AvonS/harness-eng/blob/main/commands/bug.md and follow the instructions
| Type | Branch | Workflow |
|---|---|---|
| Bug | bugfix/BUG-NNN-<slug> |
Skip design, write regression test first (TDD) |
| CR | cr/CR-NNN-<slug> |
Skip full design, simplified spec + approval |
your-project/
├── AGENTS.md ← harness workflow rules
│
└── .harness-eng/
├── CONSTITUTION.md ← principles and rules (never overwritten)
├── BRD.md ← business requirements (never overwritten)
├── ARCHITECTURE.md ← system design (never overwritten)
├── technology.yaml ← toolchain + tech decisions (never overwritten)
├── sanity-check.sh ← integration tests (project-specific)
├── SLICE_LOG.md ← build narrative
│
├── commands/ ← workflow commands
├── scripts/ ← status, check scripts
├── templates/ ← feature templates
├── hooks/ ← pre-commit hook
├── skills/ ← language-specific rules
│
└── specs/ or phases/ ← feature specs and designs
Gate 1: Design Approval — Human reviews design before implementation begins.
Gate 2: Release Approval — Human approves Release Ref: APPROVED in verification.md before creating PR.
Quality comes from:
- Templates — constrain LLM output with structure
- Constitution — principles the agent must follow
- Sanity-check — integration tests that must pass before verification
Read command files from .harness-eng/commands/ and follow them.
| Command | What happens |
|---|---|
/h:init |
Scan docs, derive constitution/BRD/architecture, generate Phase 0 |
/h:define |
Create feature spec from BRD. Large BRDs auto-organize into phases |
/h:design |
Design architecture, interfaces, file layout |
/h:approve |
Human gate — review design, approve or request changes |
/h:tasks |
Break design into granular tasks with dependencies |
/h:build |
TDD implementation — one commit per task |
/h:verify |
Run tests, check acceptance criteria, fill verification report |
/h:release |
Create PR, merge, archive, update status |
/h:upgrade-harness |
Fetch latest instructions from https://github.com/AvonS/harness-eng/blob/main/commands/upgrade-harness.md |
/h:status |
Print project status |
/h:health |
Check agent compliance with harness rules |
/h:bug |
Process bug fixes with shortened workflow |
main ← protected
├── feature/<FID>-<slug> ← /h:define
├── bugfix/BUG-NNN-<slug> ← /h:bug (bugs)
└── cr/CR-NNN-<slug> ← /h:bug (CRs)
Commit convention: type(ID): description
project:
name: "my-project"
stack:
language: "Go"
language_rationale: "Performance, deployment model"
database: "PostgreSQL"
database_rationale: "ACID transactions"Secrets live in ~/.config/<app>/, never in the project directory.
| Skill | Key rules |
|---|---|
| Go | Makefile, go vet, race detection, std-lib-first, graceful shutdown |
| Python | uv, ruff, pytest, std-lib-first, config in ~/.config |
| Node/TS | Strict TypeScript, pnpm, vitest, ESM, Node built-ins |
| SQL | DuckDB dialect, migration testing, idempotent migrations |
| Git | Branch model, commit conventions, pre-commit secret scan |
python scripts/harness-status-server.py [project_dir] [--port PORT]Open http://localhost:8080 — view status, approve designs, auto-refreshes.
The harness is a protocol, not a plugin.
Like HTTP works whether you use Chrome or curl — harness-eng works whether you use Claude, Copilot, or Cursor. It is a file-based convention, not a tool dependency.
The workflow is the tool. The folder structure is the state machine.
The AI Manifesto names the core problem: "The greatest risk of AI is not that it will think for us. It is that it will agree with us — and we will not notice." The harness builds external accountability into every workflow.
- spec-kit — Constitution/spec/plan/tasks separation
- OpenSpec — Iterative flow, archive pattern
- modular/skills — Agent Skills Standard
- BMAD — Structured agentic development
- AI Manifesto — Six principles for thinking clearly with AI
MIT — by Avon Software Labs