coleam00/harness-engineering-demo

This repository is a companion to a YouTube video explaining harness engineering, a concept about how to structure the environment surrounding an AI coding agent so it behaves like a reliable team member rather than a capable but unpredictable tool. The harness is everything that wraps the agent: the rules it reads, the workflows it follows, the checks that prevent it from finishing until its output meets quality standards, and the hooks that run automatically in the background. The demo uses a real web application called Schedulr, included in the repository, as the target codebase. Around it, the demo builds a three-step loop called PIV: Plan, Implement, and Validate. In the Plan step, the agent reads the codebase and a feature request, then writes a detailed plan to a file. In the Implement step, the agent reads that plan and carries out each task, running a quick code check after every file it edits. In the Validate step, the full test suite and type checks must pass before the agent is allowed to stop. The self-validating behavior comes from hooks: small scripts wired into Claude Code that fire automatically before or after tool calls. One hook runs a code linter after every file edit. Another blocks the agent from ending its turn until tests are green. A third prevents the agent from reading secret files or deleting entire directories, even when running unattended. A separate automation script called Ralph strings multiple Claude Code sessions together end to end, feeding a specification file into each fresh session until a completion marker appears. This allows longer tasks to be handled across several sessions without manual intervention between them. The repository also includes a sub-agent configuration for code review and a custom search tool that lets the agent navigate the codebase by symbol name rather than by file path.