Runbook: how to run the overnight spec run

[khaliqgant]

How to drive the spec programs in this repo via Ricky overnight. Specs are implemented one at a time, in dependency order, each gated by an implement → review → fix cycle (the reviewer is a different persona). Full reference: README.md and specs/*/PROGRAM.md.

Prerequisites

• Ricky CLI installed and on PATH (ricky --version), able to run ricky local --spec-file <f> --run. Verify with ricky --help.
• relayfile read/write access for the workspace the specs use (the watcher + writer need it).
• gh authed (gh auth status) — the runner pushes branches and opens draft PRs.
• Phase 2 only: local clones of the sibling repos at the expected paths (sage, nightcto, pear beside this repo; My-Senior-Dev/app). Override any with REPO_<slug> env.

Phase 1 — self-contained (start here)

Lives entirely in this repo: a watcher synthesizes stories from relayfile + a standalone viewer. No other repo is touched. Single-repo mode → a draft PR per wave.

# 1) inspect the plan — NO side effects
./scripts/run-overnight.sh storybook --dry-run

# 2) run it — implement → review → fix each spec, commit, open a draft PR per wave
./scripts/run-overnight.sh storybook

Phase 2 — deferred, cross-repo (optional, after Phase 1 ships)

Per-product emit hooks + Pear/MSD inline embeds. Specs carry a **Repo:** slug, so the runner auto-detects dispatch mode and implements each spec in its target repo (one draft PR per touched repo).

./scripts/run-overnight.sh storybook-phase2 --dry-run   # prints: START <spec> -> <slug> (<repo>)
./scripts/run-overnight.sh storybook-phase2

Requires Phase 1 merged and @code-story published.

Flags & env

Flag / env	Effect
--dry-run	Print the plan + routing; make no changes. Always run this first.
--from <spec-id>	Resume from a spec, e.g. --from 030 (skips earlier specs).
--no-pr	Implement + review but don't open/refresh PRs.
MAX_REVIEW_ITERS (default 3)	Review→fix loop cap before the run stops on a spec.
REVIEW_CMD / FIX_CMD	Override the reviewer/fixer invocation (default: Ricky local with _review.md / _fix.md).
PROJECTS_ROOT, REPO_<slug>	Override where target repos resolve (Phase 2 dispatch).

Monitoring & resume

• Live log: tail -f /tmp/nightcto-storybook.log (or -storybook-phase2.log).
• Per-spec logs: /tmp/nightcto-storybook-logs/<spec-id>.log and <spec-id>.review.log.
• State: cat /tmp/nightcto-storybook-state.env (last spec + status).
• If a spec fails implement or can't reach a review PASS within MAX_REVIEW_ITERS, the run stops on that spec so it can be inspected; resume with --from <spec-id>.

What to expect

• A results/storybook (or results/storybook-phase2) branch on each touched repo.
• Draft PRs: per wave in Phase 1 (one repo); per repo in Phase 2 (dispatch).
• Only specs that reach a review PASS are committed into a PR.
• CI (lint-specs) must stay green — every numbered spec needs the required sections (and a valid **Repo:** slug if present).

Recommended first run

./scripts/run-overnight.sh storybook --dry-run     # confirm 14 specs, single-repo mode
./scripts/run-overnight.sh storybook               # let it build Phase 1 overnight

[kjgbot]

Should use https://diffs.com/