# AGENTS.md — build-your-own-x harness

This repo is a curated **index** of "build your own X" tutorials (see `README.md`).
This harness turns it into a disciplined **workspace** for actually building one
challenge to completion with a coding agent, across sessions, without drift.

## Startup Workflow (every session, in order — do this Before writing code)

1. Read `progress.md` — it holds the active challenge, the current feature, and the last verified state.
2. Read `feature_list.json` — the single source of truth for what's done and what's next.
3. Read `session-handoff.md` if present — it captures anything not obvious from the two files above.
4. Run `./init.sh` — this is the verification gate. Do not trust prior "done" claims; re-run it.
5. Pick up the **one** feature whose `status` is `in_progress`, or the first `todo` whose dependencies are all `done`.

## Working rules

- **One feature at a time.** One active feature only — do not start a second feature until the current one is `done` with evidence.
- **Stay in scope.** Stay in the active challenge, which lives in `progress.md`. Do not scaffold a different challenge from `README.md` without the user's go-ahead.
- **Build inside `workspace/`.** All challenge code goes in `workspace/<challenge>/`. Never modify `README.md`, `ISSUE_TEMPLATE.md`, or the upstream files — this stays a clean fork of the index.
- **Reference the tutorial, don't paste it.** Tutorial links are in `progress.md`. Read them for guidance; write your own code.
- **Small commits, one feature each.** Commit message names the feature id, e.g. `git: cat-file (blob read)`.

## Definition of Done (per feature)

A feature is `done` only when ALL are true:

1. Its `verify` command in `feature_list.json` exits 0.
2. `./init.sh` still passes end-to-end (no regressions in earlier features).
3. `feature_list.json` is updated: `status: "done"` + a one-line `evidence` string (what command proved it).
4. `progress.md` "Last verified" line is updated.

If you cannot produce evidence, the feature is **not** done — leave it `in_progress` and write the blocker in `progress.md`.

## End of Session routine (Before ending)

1. Update `feature_list.json` status/evidence for anything you touched.
2. Update `progress.md`: active feature, last verified command + result, next step.
3. Write/refresh `session-handoff.md` with anything the next session needs that isn't obvious.
4. Leave the tree in a runnable state (or clearly mark the broken feature `in_progress` with the failure).

## Swapping challenges

To target a different challenge from `README.md`:
1. Get the user's explicit go-ahead.
2. Update the `active_challenge` block in `feature_list.json` (id, tutorial url, verify command).
3. Reseed the `features` array with that challenge's steps.
4. Point `init.sh` `WORKSPACE`/verify at the new `workspace/<challenge>/`.
5. Reset `progress.md`.