# @slowcook-ai/cli

The `slowcook` CLI — TDD-first agentic development harness. Turns a detailed user story into frozen tests, then lets agents iterate under strict guardrails until every test is green.

> ⚠️ **Active development — expect breaking changes.** Slowcook is pre-1.0 and the architecture itself is iterating in public. CLI commands, file layouts, prompt contracts, and the package surface can and will change between point versions.
>
> If you're adopting slowcook today: pin exact versions in your consumer (`.brewing/slowcook-cli-version`), read each release entry in [the changelog](https://github.com/aminazar/slowcook/blob/main/CHANGELOG.md) before bumping, and treat it as a partnership — feedback from real consumers is what drives the next cut.

## Install

```bash
npm i -D @slowcook-ai/cli
```

Or pin a specific version (recommended for consumers):

```bash
npm i -D @slowcook-ai/cli@0.19.5
```

The `latest` tag points at the most recent stable cut. Stamp your pinned version in `.brewing/slowcook-cli-version` after `slowcook init`.

## Start here

If you're an AI agent (Claude Code, Cursor, etc.) or a developer driving slowcook in a consumer repo, the canonical pipeline reference is **[AGENTS.md](https://github.com/aminazar/slowcook/blob/main/AGENTS.md)** at the repo root. It has the decision tree, the pipeline at a glance, per-command quick reference, and an empirical pitfalls list that saves real money + time on your first session.

This README covers install + the top-level command surface. AGENTS.md covers WHEN to reach for which command, the pipeline flow, and the failure modes you're likely to hit.

## Command catalog

The pipeline is **refine → testgen → vibe → plate → recipe → brew → chef**. Each stage is an agent invocation that consumes the previous stage's output + commits its own PR.

The catalog below is **auto-generated from the cli's command manifest** (`packages/cli/src/commands.manifest.ts`). It is kept in sync with `slowcook help` output by `scripts/sync-readme-help.sh` + a CI gate. Adding a command in the manifest updates BOTH this catalog AND the `slowcook help` output in one shot.

Run `slowcook help <command>` or `slowcook <command> --help` for per-command details. All commands accept `--cwd <path>` to operate against a directory other than `.`.

<!-- COMMANDS BLOCK BEGIN — auto-generated by scripts/sync-readme-help.sh, do not edit by hand -->
### Pipeline (agent-driven)

- **`menu`** — GUCDI greenfield entry: decompose a PRD into a comprehensive, anchored, data-contracted story set under specs/.
  ```
  slowcook menu [--prd <path>] [--cwd <dir>] [--model <id>] [--dry-run]
  ```
- **`greenfield`** — GUCDI scope-completeness dashboard: where the project is in PRD → stories → brand → LCR → trace, and the single next action.
  ```
  slowcook greenfield status [--prd <path>] [--cwd <dir>]
  ```
- **`refine`** — Drive a GitHub issue through a clarifying-question loop until a frozen spec PR is emitted.
  ```
  slowcook refine --issue <number> [--cwd <path>] [--owner <login>] [--repo <name>]
  ```
- **`recipe`** — Generate Vitest tests from merged specs — the test contract brew follows.
  ```
  slowcook recipe [--spec <id>] [--all] [--cwd <path>]
  ```
- **`vibe`** — Design-first mock generator. `vibe plan`/`schema`/`seed` build the whole-app LCR data adaptor (deterministic data model + Drizzle schema + real sql.js SQLite + LLM seed/queries). `vibe app` (deterministic) scaffolds the runnable, navigable LCR: Vite app + router (every surface reachable, BrowserRouter) + the slowcook review-overlay (persona switch + EPSS epic/persona/scenario/state router, from a generated testing-surfaces.json) + a stub page per route; sets review_mode: lcr. `vibe --spec <id>` (legacy per-story) emits a React mockup PR.
  ```
  slowcook vibe (plan | schema [--stdout] | seed [--dry-run] | app [--force] | --spec <id> [--owner <login>] [--dry-run]) [--cwd <path>]
  ```
- **`plate`** — Mockup amendment agent. Triggered by /plate PR comments on slowcook-mockup PRs; force-pushes amendments.
  ```
  slowcook plate --pr <number> [--cwd <path>] [--owner <login>] [--repo <name>] [--review-comment-id <id>]
  ```
- **`brew`** — Ratcheted implementation loop: iterate src/ until all of one story's tests are green.
  ```
  slowcook brew --story <id> [--budget-usd <n>] [--max-iterations <n>] [--model <id>]
  ```
- **`chef`** — PR-CI failure classifier — dispatches retry / escalate based on check status.
  ```
  slowcook chef --pr <number> [--cwd <path>]
  ```
- **`chef-drift`** — Surgical drift-fixer. Triggered by mock-isolation / recon / brew / navigator halts.
  ```
  slowcook chef-drift [--pr <number>] [--story <id>] [--cwd <path>]
  ```
- **`chef-orchestrate`** — Pipeline orchestrator. Decides redispatch_brew / rebase / escalate / close on a halted PR.
  ```
  slowcook chef-orchestrate --pr <number> --story <id> [--cwd <path>]
  ```
- **`brand`** — Design-system foundation agent. Emits mock/src/design-system/{tokens.ts, css.ts} from a brand brief. `brand logo` tokenizes a supplied SVG / deterministically traces a PNG (vtracer/potrace — no LLM path-authoring).
  ```
  slowcook brand [--brief <prose>] [--refresh] [--dry-run] [--model <id>] [--cwd <path>]  ·  slowcook brand logo --in <svg|png> [--out <dir>] [--map #hex=token,...]
  ```

### Checks + guards

- **`guard`** — Check for frozen-path violations between two git refs. CI step.
  ```
  slowcook guard --base <ref> --head <ref> [--override] [--config <path>]
  ```
- **`manifest`** — Record or verify the set of discoverable tests so agents can't silently exclude them.
  ```
  slowcook manifest (record|verify) [--stack-config <path>] [--manifest <path>] [--story <id>]
  ```
- **`check`** — Static structural checks. `check spec` re-runs spec validators on PR amendments; `check mock-isolation` enforces the mock-vs-prod boundary.
  ```
  slowcook check (mock-isolation|spec) [file...] [--cwd <path>]
  ```
- **`recon`** — Pre-brew structural divergence check. Surfaces missing components / testid gaps / brownfield rename hazards.
  ```
  slowcook recon [--story <id>] [--cwd <path>] [--reuse-scan] [--stub-scan] [--exclude <glob>]
  ```
- **`trace`** — GUCDI traceability lint over the spine. check: provenance (forward — every spec/LCR node has a why; orphans/dangling fail), coverage (inverse — stories with no LCR surface; --coverage to fail), persona surfaces (declared routes resolve), and freshness (specs whose PRD section changed since stamping; --strict to fail). stamp: baseline each spec's PRD-anchor fingerprint (prd_ref.sha). impact: which stories a PRD change touches (--since <ref> diffs the PRD; or --anchors a,b). Brownfield-safe (never demands a PRD).
  ```
  slowcook trace <check|stamp|impact> [--prd <path>] [--cwd <dir>] [--coverage] [--strict] [--since <ref>] [--anchors a,b]
  ```
- **`reconcile`** — PRD↔spec interdependency (LLM). When a PRD section a spec anchors to has changed (see `trace impact`/`trace check`), propose a minimum-diff corrected spec: enumerate which invariants/scenarios/actors/api now contradict the PRD, and report one-hop cross-impact as notes. Propose-not-apply by default (writes specs/story-<id>.reconcile.yaml); --apply accepts it (schema-validated) and re-stamps freshness.
  ```
  slowcook reconcile --story <id> [--prd <path>] [--cwd <dir>] [--apply] [--dry-run] [--model <id>]
  ```
- **`eye`** — Fidelity eye (design #8). Renders mock + brewed URLs across the viewport×scheme matrix, grades visual drift, screenshots, exits 1 on drift.
  ```
  slowcook eye --reference <url> --candidate <url> [--story <id>] [--out <dir>] [--viewport <m>] [--scheme <s>] [--max-violations <n>] [--fail-on <axes>] [--watch [--interval <ms>] [--until-converged] [--max-passes <n>]]
  ```
- **`gate`** — HITL review halt (design #9). Refuses to advance a stage until a human in the required role has approved on the PR; bot/agent reviews never satisfy it.
  ```
  slowcook gate check --stage <refine|plate|brew> --pr <n> [--repo <owner/name>]
  ```
- **`map`** — Generate / check the repo-wide code map (APIs, pages, components, helpers, types).
  ```
  slowcook map (generate|check) [--cwd <path>] [--out <path>] [--md <path>]
  ```
- **`fixtures`** — Sanity-check the test-fixture set against the spec.
  ```
  slowcook fixtures check [--max-age-days <n>] [--story <id>]
  ```
- **`eval`** — Run the agent eval suite against committed fixtures.
  ```
  slowcook eval (--all | --fixture <id> | --list) [--fixtures-dir <path>]
  ```

### Setup + lifecycle plumbing

- **`init`** — Scaffold .brewing/, .github/workflows/slowcook-*, and CODEOWNERS in a consumer project.
  ```
  slowcook init [--owner <handle>] [--force] [--dry-run] [--cwd <path>]
  ```
- **`refresh-knowledge`** — Rebuild .brewing/repo-knowledge/{auto,curated}/ — code-shape digests + git-history mining.
  ```
  slowcook refresh-knowledge [--cwd <path>] [--auto-only] [--curated-only]
  ```
- **`upsert-agent-docs`** — Write the managed slowcook block in the consumer's AGENTS.md (or create one).
  ```
  slowcook upsert-agent-docs [--cwd <path>] [--dry-run]
  ```
- **`on-spec-merged`** — Transition source-issue labels + post audit-trail comment after a spec PR merges.
  ```
  slowcook on-spec-merged --pr <number> [--cwd <path>]
  ```
- **`on-tests-merged`** — Post audit-trail comment after a tests PR merges.
  ```
  slowcook on-tests-merged --pr <number> [--cwd <path>]
  ```
- **`on-brew-merged`** — Post final "shipped" audit-trail comment after a brew PR merges. Warns when merge target isn't main.
  ```
  slowcook on-brew-merged --pr <number> [--cwd <path>]
  ```
- **`on-mockup-approved`** — Hook fired when a mockup PR gets the slowcook-mockup-approved label.
  ```
  slowcook on-mockup-approved --pr <number> [--cwd <path>]
  ```
- **`catchup`** — Detect + run pipeline steps that should have triggered but didn't.
  ```
  slowcook catchup [--dry-run] [--cwd <path>]
  ```
- **`budget`** — Manage the project monthly budget for the fuel gauge.
  ```
  slowcook budget [show|set|rm] [--monthly <usd>] [--start-day <1-31>] [--story <usd>] [--cwd <path>]
  ```
- **`docs`** — Docs generation helper.
  ```
  slowcook docs [--cwd <path>]
  ```

### Knowledge + accounting

- **`knowledge`** — Add a curated entry to .brewing/repo-knowledge/curated/.
  ```
  slowcook knowledge add <topic> "<entry>" [--evidence-pr <n>] [--evidence-file <path>]
  ```
- **`cost`** — Stamp a cost marker on a story for non-Actions agents (Claude Code, Cursor, manual runs).
  ```
  slowcook cost log --story <id> --usd <n> --agent <name> [--apply-to-spec]
  ```
- **`stories`** [alpha] — Per-story pipeline-stage table (refine / testgen / vibe / brew / chef) from specs/_index.yaml + GitHub state.
  ```
  slowcook stories status [--cwd <path>] [--owner <login>] [--repo <name>] [--json]
  ```
- **`extract`** — Brownfield extracts (schema.mmd, tokens.md) for refine/investigate context. Fast, no node_modules.
  ```
  slowcook extract [--schema] [--tokens] [--cwd <path>]
  ```

### Ops (preview, dev-env, etc.)

- **`serve`** [alpha] — Multi-mode dev / mock / staging on a shared box. `dev` bind-mounts source; `mock` runs vite-dev (auto-skip if no scripts.dev); `staging` is built-image with named-scenario seed reset.
  ```
  slowcook serve <profile> (up|sync|down|logs|reset) [--branch <name>] [--scenario <name>] [--service <name>] [--follow] [--prune]
  ```
- **`dev-env`** [DEPRECATED] — Legacy alias for `slowcook serve dev`. Bind-mount source push + per-story preview switch. Kept for backward compat.
  ```
  slowcook dev-env (push|switch|up|sync|reset) [--story <id>] [--branch <name>]
  ```
- **`preview`** — SSH preview deploy. `deploy --pr N`: build + run the mock app on the consumer's box; post URL to PR.
  ```
  slowcook preview (deploy|teardown) --pr <number> [--ssh-key <path>] [--cwd <path>]
  ```
- **`run-mock`** — One-command mock launch + auto-pull. Polls origin + git pull --ff-only on plate amendments.
  ```
  slowcook run-mock <story-id> [--no-poll] [--poll-seconds <n>] [--branch <ref>]
  ```
- **`dispatch`** — Trigger a slowcook GitHub Actions workflow remotely (brew / testgen / refine).
  ```
  slowcook dispatch <step> [inputs...]
  ```
- **`port`** — Deterministic mock/ → src/ copy. Pre-brew CI step; applies the useScenarioFixture → useDataDomain rewrite.
  ```
  slowcook port --story <id> [--cwd <path>] [--dry-run] [--force]
  ```

### Experimental

- **`investigate`** [alpha] — Diagnose a bug from a GitHub issue and emit a bug-profile.
  ```
  slowcook investigate --issue <number> [--cwd <path>]
  ```
- **`sift`** [alpha] — Narrow red→green ratchet for a bug fix; bounded by bug-profile fix_scope.
  ```
  slowcook sift --bug-profile <path> [--cwd <path>]
  ```
- **`refactor`** — Rank refactor proposals from .brewing/refactor/proposals.json by benefit/cost.
  ```
  slowcook refactor [--scope <name>] [--cwd <path>]
  ```
- **`garnish`** — Local commit-gate for human tweaks on agent work. Runs tests, commits with learning-signal trailers.
  ```
  slowcook garnish [--cwd <path>]
  ```
<!-- COMMANDS BLOCK END -->

## Required environment

Most pipeline commands invoke the Anthropic API and act on GitHub:

- `ANTHROPIC_API_KEY` — LLM calls (refine, testgen, vibe, plate, recipe, brew, chef)
- `GITHUB_TOKEN` — `contents: write`, `issues: write`, `pull-requests: write` for PR + comment work

`slowcook init`, `guard`, `manifest`, and `check` run locally without API/network access.

## What ships in this package

- `slowcook` binary (entry point: `dist/cli.js`)
- Pipeline commands listed above
- Programmatic API exports for the validators (`validateEntityFieldReferences`, `validateComponentReuseShape`, `validateRouteCollisions`, `validatePlateDtoColumns`) — useful if you want to wire the lint chain into a custom CI

The companion packages (`@slowcook-ai/core`, `@slowcook-ai/llm-anthropic`, `@slowcook-ai/forge-github`, `@slowcook-ai/stack-ts`, `@slowcook-ai/mock-runtime`) install transitively as workspace deps. The cli is the only one you `npm i` directly.

## License

MIT