# foreman build prompts

This directory drives the autonomous Claude Code build of foreman.

## How to run

Start with **`phase-0-kickoff.md`** — it is the master driver. Paste it (or the
command below) into Claude Code from the repo root. It reads `CLAUDE.md`, the
ADRs in `docs/adr/`, and the `go-llm` / `steveternet` sources, then runs phases
1 → 6 **autonomously** to a finished, deployable foreman. You do **not** paste the
individual phase files — the kickoff reads them as it goes.

Kickoff command:

```
Read and follow prompts/phase-0-kickoff.md. The per-phase specs it references
(prompts/phase-1.md … phase-6.md) are in this same prompts/ directory. This is a
fully autonomous run: execute all six phases in order to a finished, working
deliverable without pausing between them. Honor docs/adr/ (note the new 0013) and
CLAUDE.md as source of truth. For the two cross-repo changes (llm.Foreman() in
steve/go-llm and the docker-compose in steve/steveternet), open a branch and PR
on each for my review — do not commit to their main. When done, report what each
phase built, the PR links, any ADRs you added, and a smoke-test checklist.
```

## What each phase produces

1. `phase-1` — scaffold, config, SQLite store, health, CI, Dockerfile.
2. `phase-2` — Ollama client + model poller + native passthrough + embedding
   bypass. The Mac is usable as a `go-llm` target after this.
3. `phase-3` — durable queue + single worker + drain-by-model. **M0 complete.**
4. `phase-4` — async `/jobs` + job IDs + state webhooks + artifacts. The headline
   queue-and-webhooks capability.
5. `phase-5` — Go client package (sync facade) + `llm.Foreman()` in `go-llm`.
6. `phase-6` — deploy: steveternet compose + Traefik, `.env.example`, deploy
   docs, model-pull script.

## Conventions during the run

- Each phase must pass the gates before continuing: `go build ./...`,
  `go vet ./...`, `go test -race -count=1 ./...`, and `go mod tidy` +
  `git diff --exit-code go.mod go.sum`.
- Commits go to foreman's `main` with conventional-commit messages; `progress.md`
  gets a dated entry each phase.
- A decision not covered by `CLAUDE.md` or an ADR → record a new ADR
  (append-only, next number after 0013) and continue.

## Cross-repo caveat (phases 5 & 6)

The `llm.Foreman()` constructor lives in **steve/go-llm** and the deploy compose
in **steve/steveternet**. Those changes go on a **branch + PR for review — never
their main.**

## Known caveat (phase 6)

Phase 6 mirrors the Traefik/compose conventions from sibling services
(`kalimdor/orgrimmar/warhol-queue`, `ratchet`, `mort`) read via the gitea MCP.
Those reads were intermittently erroring during planning. **If phase 6 can't read
them, paste a sibling `docker-compose.yml` (e.g. ratchet's) straight into the
session** so it can mirror the network name, entrypoint, certresolver, and
router/service labels rather than inventing them.