Harness Engineering Guide

Product Summary

Harness Engineering Guide is a repository-local operating system for AI coding agents. It packages durable instructions, executable checks, session state, versioned prompts, and reusable templates so that an agent can understand how to work, prove its result, and hand off the next step without relying on chat history.

The latest stable guide is guides/HARNESS-v1.0.md. The locally verified v1.1 release candidate is guides/HARNESS-v1.1.md. Use HARNESS.md as the stable entry point for the latest version. The Korean source originals are archived under docs/originals/ko/.

Main Use Cases

• Recommend project-specific operating rules before planning starts.
• Create durable context packets for multi-agent coding work.
• Bootstrap a repository with agent-readable instructions and state files when explicitly requested.
• Copy templates for feature, progress, decision, and quality tracking.
• Run deterministic checks that enforce the required harness structure.
• Connect the Harness Engineering Enforcer prompt to agent skill discovery.
• Validate harness changes in GitHub Actions with AgentLint and local checks.

Repository Map

• guides/: versioned Harness Engineering guides.
• prompts/enforcer/: versioned Enforcer prompts.
• docs/usage.md: quick start and recommended operation flow.
• docs/commands.md: command-by-command behavior reference.
• docs/examples/: example Harness strategies for common project shapes.
• docs/templates/: copy-ready state document templates.
• .agents/skills/harness-enforcer/: agent skill entry point.
• bin/: npm/npx CLI wrapper for skill installation.
• scripts/: setup, validation, and cleanup commands.
• tests/: distribution and installer smoke checks.

See ARCHITECTURE.md for boundaries and placement rules.

Tech Stack

• Content: Markdown
• Automation: POSIX shell
• CI: GitHub Actions
• Harness linting: AgentLint CLI
• Testing: shell syntax, repository contract checks, and template smoke tests

Local Setup

Requirements:

• Git
• A POSIX-compatible shell
• Node.js 20+ only when running AgentLint locally

./scripts/setup.sh

No package installation is required for the repository's custom checks.

Development Commands

./scripts/check-harness.sh  # fast structural and policy check
./tests/template-smoke.sh   # consumer-level template test
./scripts/check.sh          # integrated local verification
./scripts/clean.sh          # remove known temporary check artifacts

Optional AgentLint:

npx --yes [email protected] agentlint check

Test Commands

Static verification:

sh -n scripts/*.sh tests/*.sh
./scripts/check-harness.sh

Distribution contract verification:

./tests/template-smoke.sh

This repository has no application server, database, browser UI, or deployment runtime. Runtime verification therefore means executing the setup and integrated check paths successfully.

Deployment / Runtime Notes

There is no deployed service. GitHub Actions runs AgentLint and the custom harness check on pushes and pull requests. The workflow uses read-only repository permissions and does not require secrets.

User Guides

• Quick start and workflow: docs/usage.md
• Command reference: docs/commands.md
• Examples: docs/examples/

Start a Harnessed Repository

1. Read HARNESS.md.
2. Copy the files in docs/templates/ into the target root.
3. Adapt commands and architecture documents to the target stack.
4. Copy scripts/check-harness.sh and tailor its required-file contract.
5. Run all three verification layers before marking the bootstrap feature passing.

Use from Any Repository

Install the Enforcer once into your Codex skills directory:

./scripts/install-skill.sh

The current public npm release is 1.0.4:

npx -y harness-enforcer-install

Until 1.1.0 is intentionally published, use ./scripts/install-skill.sh from this repository to test the v1.1 release candidate.

Open a new Codex session in any repository and invoke:

$harness-enforcer

The unqualified command is always a read-only audit. To initialize project planning and multi-agent coordination:

$harness-enforcer start

This creates a minimal durable context packet with the objective, non-goals, agent roles, ownership, dependency order, verification responsibilities, and handoff rules. It does not bootstrap the full Harness structure.

To ask what rules should govern a project before planning:

$harness-enforcer advise

Adopted advice becomes a sticky Principles Layer that later start, resume, coordinate, and finish operations must preserve.

To explicitly add the baseline Harness v1.1 structure:

$harness-enforcer bootstrap this repository without overwriting existing files

Only explicit bootstrap runs the bundled bootstrap-repo.sh, vendors the versioned guide and prompt, creates missing state files, installs a project-local skill, and adds the default harness lint workflow. Existing project documents are preserved.

If you want a one-shot prompt for a fresh session instead of repeating $harness-enforcer, use:

./scripts/print-session-start.sh

That prints docs/session-start-prompt.md.

Preview a bootstrap directly:

~/.codex/skills/harness-enforcer/scripts/bootstrap-repo.sh \
  --target /path/to/project \
  --dry-run

Use --no-ci when the target repository must integrate the checks into an existing workflow manually.