# build-your-own-x-harness

This is the well-known **build-your-own-x** index — the compiled list of
"recreate a real technology from scratch" tutorials in `README.md` (Git,
Redis, a shell, a text editor, a database, and dozens more) — plus a
**harness** wrapped around it so a coding agent (Claude Code, or any agent
that reads an `AGENTS.md`) can actually build one of those challenges to
completion across multiple sessions without losing the thread or drifting
out of scope.

## Why this exists

`README.md` alone is just a reading list. Hand it to a coding agent with no
structure and you get one of two failure modes: the agent starts three
different tutorials and finishes none of them, or it claims "done" on a step
it never actually tested. This harness fixes both:

- `feature_list.json` is the single source of truth for what's done, what's
  next, and what depends on what.
- `init.sh` is a verification gate — it re-runs the *entire* test suite for
  the active challenge every time, so an agent can't silently regress an
  earlier step while working on a later one.
- `progress.md` and `session-handoff.md` carry state between sessions, so a
  fresh agent invocation (new context window, new day, different machine)
  picks up exactly where the last one left off instead of re-deciding
  everything from scratch.
- `AGENTS.md` is the actual instruction file the agent reads first — startup
  workflow, working rules, definition of done, end-of-session routine.

This repo ships preconfigured for **"Build your own Git" in Python**
(`active_challenge` in `feature_list.json`), with six features already
scoped: `init`, `hash-object`, `cat-file`, `write-tree`, `commit-tree`,
`log`. You can swap to any other tutorial in `README.md` — the swap
procedure is documented at the bottom of `AGENTS.md`.

## Quickstart

1. Read `AGENTS.md` first. It is written for the agent, but read it yourself
   too — it tells you exactly what the agent will and won't do.
2. Run `./init.sh`. On a fresh clone this exits with code `2` and a note
   that `workspace/git-python/` doesn't exist yet — that's expected, not a
   bug. It means no feature has been built yet.
3. Point your coding agent at this directory and tell it to start. A
   well-behaved agent will read `progress.md`, then `feature_list.json`,
   then `session-handoff.md`, run `./init.sh`, and pick up the first
   `todo` feature (`init`).
4. Requirements: `python3` on PATH, `pytest` installed
   (`python3 -m pip install pytest`), and real `git` installed (some tests
   compare your implementation's output byte-for-byte against real git's).

## Make it your own

- **Swap the challenge.** Pick any tutorial from `README.md` — Redis in Go,
  a shell in C, a text editor, a database — get your agent's go-ahead per
  the "Swapping challenges" section of `AGENTS.md`, update
  `active_challenge` in `feature_list.json`, reseed the `features` array
  with that challenge's steps, and reset `progress.md`.
- **Extend the feature list.** The Git challenge here only covers six
  plumbing commands. Add `checkout`, `branch`, `merge`, or whatever else the
  tutorial covers next as additional entries in `feature_list.json`, each
  with its own `verify` command and `done_criteria`.
- **Reuse the harness pattern elsewhere.** `AGENTS.md` + `feature_list.json`
  + `init.sh` + `progress.md` + `session-handoff.md` is a general pattern
  for keeping any multi-session coding-agent project honest — it isn't
  specific to build-your-own-x.

## What's original here vs. upstream

`README.md`, `ISSUE_TEMPLATE.md`, `.gitattributes`, and
`codecrafters-banner.png` are the unmodified upstream build-your-own-x
index — leave them alone, they're just the reading list. `AGENTS.md`,
`feature_list.json`, `init.sh`, `progress.md`, and `session-handoff.md` are
the harness layer added on top.