# Setup

This repo is the **build-your-own-x** tutorial index (`README.md`) wrapped in
a **harness** (`AGENTS.md`, `feature_list.json`, `init.sh`, `progress.md`,
`session-handoff.md`) that lets a coding agent build one tutorial to
completion, across sessions, without losing the thread. It ships
preconfigured for **"Build your own Git" in Python**.

There is nothing to compile or serve. Setup here means: get the three tools
on your machine that `init.sh` and the preconfigured challenge actually use.

## What you need

| Requirement | Why | Have it already? |
|---|---|---|
| `git` (any recent version) | `init.sh` warns if missing; the git-python challenge's tests compare your implementation's output byte-for-byte against real git | Run `git --version` |
| `python3` (any recent version) | Runs `init.sh`'s checks and the challenge's `pytest` test suite | Run `python3 --version` |
| `pytest` (Python package) | `init.sh` requires it to run the challenge's test suite | Run `python3 -c "import pytest"` |
| `bash` | `init.sh` is a bash script (`#!/usr/bin/env bash`) | macOS/Linux ship one already — run `bash --version` |
| A coding agent (Claude Code recommended) | `AGENTS.md` is written for an agent to read first and follow the workflow; you can also do it by hand | Not required to have one — you can read `AGENTS.md` yourself and code manually |

**NOT needed:** Docker. No account or sign-up of any kind. No GPU. No paid
API or API key of any kind — nothing in this repo calls out to a network
service. No Node/npm (only pulled in if you later swap to a JS/TS
challenge — see `.gitignore`'s node note, which is just future-proofing).

## Install, step by step

### 1. Install Homebrew (macOS only, skip if you already have it)

```bash
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
```
Installs the Homebrew package manager, used below to install git/python3 if needed.

Check it worked:
```bash
brew --version
```
Expected: a line like `Homebrew 4.x.x`.

### 2. Install git

macOS:
```bash
brew install git
```
Linux (Debian/Ubuntu):
```bash
sudo apt-get update && sudo apt-get install -y git
```
Windows:
```powershell
winget install --id Git.Git -e
```
This installs the real `git` binary the challenge's tests will diff your output against.

Check it worked:
```bash
git --version
```
Expected: `git version 2.x.x` (any recent 2.x is fine).

### 3. Install Python 3

macOS:
```bash
brew install python3
```
Linux (Debian/Ubuntu):
```bash
sudo apt-get install -y python3 python3-pip
```
Windows: download the installer from python.org and run it (check "Add python.exe to PATH").

Check it worked:
```bash
python3 --version
```
Expected: `Python 3.x.x`.

### 4. Install pytest

```bash
python3 -m pip install pytest
```
This is the test runner `init.sh` invokes (`python3 -m pytest tests -q`) once a challenge workspace with tests exists.

Check it worked:
```bash
python3 -c "import pytest; print(pytest.__version__)"
```
Expected: a version number printed, no `ModuleNotFoundError`.

### 5. Clone this repo

```bash
git clone <this-repo-url>
cd build-your-own-x-harness
```

Check it worked:
```bash
ls AGENTS.md feature_list.json init.sh
```
Expected: all three filenames echoed back with no "No such file" error.

## Configure

Nothing to configure. No environment variables, no config files, no API
keys — the harness and the preconfigured git-python challenge are fully
local and offline.

## Run it

```bash
./init.sh
```

On a fresh clone, expected output ends with:
```
NOTE: workspace/git-python does not exist yet.
      This is expected before the first feature is started.
      Create it, add your implementation + tests/, then re-run ./init.sh
```
and the script exits with code `2`. That is success for a fresh clone — it
means the harness is wired up correctly and no feature has been built yet.

From here, either:
- Point a coding agent (e.g. Claude Code) at this directory and tell it to
  start — a well-behaved agent reads `progress.md`, `feature_list.json`,
  `session-handoff.md`, runs `./init.sh`, and begins the `init` feature
  itself, per `AGENTS.md`.
- Or follow `AGENTS.md` and `progress.md` by hand: create
  `workspace/git-python/tests/`, write `tests/test_init.py` against the
  `init` feature's `done_criteria` in `feature_list.json`, implement `init`,
  then re-run `./init.sh`.

`init.sh` exit codes, so you always know what state you're in:
- **0** — all tests in the active challenge's `tests/` directory pass.
- **1** — a real failure: a required tool is missing (`python3`, or `pytest`
  not importable), or the test suite ran and is red.
- **2** — nothing to run yet: `workspace/<challenge>/` doesn't exist, or it
  exists but has no `tests/` directory. Not a bug — expected before the
  first feature is scaffolded.

## Troubleshooting

1. **`FAIL: python3 not found on PATH`** — Python isn't installed or isn't
   on PATH. Re-run step 3 above, then open a new terminal so PATH updates
   take effect.
2. **`FAIL: pytest not importable`** — `pytest` isn't installed for the
   `python3` that's first on your PATH. Run
   `python3 -m pip install pytest` (step 4), and if you have multiple Python
   installs, make sure you're installing into the same `python3` that
   `init.sh` will call (check with `which python3`).
3. **`./init.sh` exits `2` and never seems to progress past it** — this
   means `workspace/git-python/tests/` doesn't exist yet. That directory is
   created by whoever (you or your agent) implements the first feature
   (`init`) — it isn't pre-seeded. See "Run it" above for the next step.