AI Agent Harness Template Repository

A ready-to-use, stack-agnostic template for running AI coding agents through a full delivery loop: understand -> plan -> implement -> test -> human validation -> iterate -> PR.

What You Get

• Agent entrypoint and navigation map: AGENTS.md
• Agent control plane under agent/ for project profile + evolution log
• Durable engineering standards under docs/
• Scope boundary policy: docs/SCOPES.md
• Execution plan workflow under docs/exec-plans/
• Shared human-agent validation loop in VALIDATION.md
• PR template under .github/PULL_REQUEST_TEMPLATE.md
• CI entrypoint under .github/workflows/ci.yml
• Automation scripts:
  • scripts/agent/bootstrap-project.sh
  • scripts/agent/scope-check.sh
  • scripts/agent/validate.sh
  • scripts/agent/create-pr.sh

Repository Structure

agent-harness-template/
|-- AGENTS.md
|-- ARCHITECTURE.md
|-- agent/
|   |-- README.md
|   |-- project.env
|   `-- evolution-log.md
|-- docs/
|   |-- DESIGN.md
|   |-- PLANS.md
|   |-- SCOPES.md
|   |-- CODING_STYLE.md
|   |-- QUALITY_SCORE.md
|   |-- SECURITY.md
|   |-- RELIABILITY.md
|   |-- design-docs/
|   |   |-- index.md
|   |   `-- core-beliefs.md
|   |-- exec-plans/
|   |   |-- active/
|   |   |   `-- .gitkeep
|   |   |-- completed/
|   |   |   `-- .gitkeep
|   |   `-- tech-debt-tracker.md
|   `-- references/
|       `-- .gitkeep
|-- .github/
|   |-- PULL_REQUEST_TEMPLATE.md
|   `-- workflows/
|       `-- ci.yml
|-- scripts/
|   `-- agent/
|       |-- bootstrap-project.sh
|       |-- scope-check.sh
|       |-- validate.sh
|       `-- create-pr.sh
`-- VALIDATION.md

Quick Start

1. Initialize git and first commit if needed.
2. Open AGENTS.md and use it as the first file every agent reads.
3. Run scripts/agent/bootstrap-project.sh to detect stack/language and generate agent/project.env.
4. For a new task, create docs/exec-plans/active/[task-slug].md using the template in docs/PLANS.md.
5. Implement in small commits using:
   • [task-slug] step-N: description
6. Run:
   • scripts/agent/validate.sh
7. Update VALIDATION.md and set status to awaiting-review.
8. After human approval (status: approved), run:
   • scripts/agent/create-pr.sh [task-slug]

Stack-Specific Setup

This template is intentionally stack-agnostic. Primary setup is profile-driven:

scripts/agent/bootstrap-project.sh

This writes agent/project.env with detected defaults for:

• stack/language
• test and lint commands
• project-code roots vs agent-structure roots

You can still override validation commands ad hoc with env vars:

export AGENT_TEST_CMD="<your test command>"
export AGENT_LINT_CMD="<your lint command>"

Examples:

• Node: AGENT_TEST_CMD="npm test", AGENT_LINT_CMD="npm run lint"
• Python: AGENT_TEST_CMD="pytest", AGENT_LINT_CMD="ruff check ."
• Go: AGENT_TEST_CMD="go test ./...", AGENT_LINT_CMD="go vet ./..."

Human-in-the-Loop Contract

• Agent writes/updates VALIDATION.md.
• Human executes listed steps and records issues in the same file.
• Agent resolves issues one by one, appends iteration logs, resets status to awaiting-review.
• Human sets status to approved when satisfied.

Notes

• Keep AGENTS.md concise and navigational.
• Keep execution plans and validation history append-only.
• Keep docs and behavior aligned in the same change set.
• Use scripts/agent/scope-check.sh to classify changed paths before committing.