Universal Agent Harness

A reusable document-driven harness for AI agents working on software projects.

This harness is adapted from a Ralphton autonomous development harness, but removes hackathon-only constraints such as fixed time boxes, no-human-keyboard rules, and demo-only judging assumptions.

The goal is to make agent work repeatable, auditable, and safe across many project types: CLI tools, web apps, APIs, mobile apps, libraries, scripts, documentation projects, and internal tools.

Core Idea

Agents must not rely only on memory or confidence. Important decisions, requirements, implementation status, risks, and validation evidence should be recorded in the proper harness documents.

No document.
No evidence.
No completion.

Recommended File Count

This generic version uses 15 core markdown files plus this README:

README.md
AGENTS.md
PROJECT_CONTEXT.md
STATUS.md
TASK_QUEUE.md
BACKLOG.md
ARCHITECTURE.md
SPEC/PRD.md
SPEC/ACCEPTANCE_CRITERIA.md
SPEC/INTERFACE_CONTRACT.md
SPEC/DATA_MODEL.md
TEST/TEST_PLAN.md
VALIDATION/VALIDATION_REPORT.md
VALIDATION/RISK_REGISTER.md
docs/RUNBOOK.md
MIGRATION_MAP.md

How to Use

1. Copy this directory into a project root.
2. Fill PROJECT_CONTEXT.md first.
3. Let the agent read AGENTS.md before doing work.
4. Keep STATUS.md and TASK_QUEUE.md current during implementation.
5. Record test/build/run evidence in VALIDATION/VALIDATION_REPORT.md.

Design Principles

• Prefer small verified changes over large speculative changes.
• Prefer project-specific overrides over rewriting the harness.
• Prefer evidence over agent confidence.
• Prefer local, reproducible validation before deployment.
• Keep destructive actions explicit and reversible whenever possible.