hoangnb24/repository-harness

What it solves

Coding agents often fail due to a lack of clear constraints, ambiguous authoritative documentation, and a loss of progress during long-term tasks. repository-harness addresses these by transforming a software repository into a structured, agent-ready workspace where the repository itself serves as the system of record rather than an external database.

How it works

It installs a standardized set of documentation files and scripts into a project. This creates a small, stable entrypoint for agents (via AGENTS.md) and a map of authoritative knowledge (such as architecture, workflow, and product behavior) located in the docs/ directory. For complex tasks, it implements a durable execution plan system where progress and decisions are recorded in Git-tracked Markdown files. It also emphasizes mechanical validation through repository-native tests.

Who it’s for

Software engineers and teams using AI coding agents to maintain and evolve their codebases, who want to ensure agents have the right context and follow architectural rules without relying on heavy mandatory workflows.

Highlights

• Agent-Ready Entrypoints: Uses a compact AGENTS.md to reduce instruction loading and drift.
• Durable Execution Plans: Provides a system for tracking multi-session or coordination-heavy changes in docs/plans/.
• Repository-as-Truth: Keeps all product behavior, decisions, and plans within the repository for full inspectability.
• Mechanical Validation: Focuses on proving completion via behavior and tests rather than bookkeeping.
• Onboarding Tooling: Includes a $onboard-repository skill to help agents map brownfield repositories.