@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 before bumping, and treat it as a partnership — feedback from real consumers is what drives the next cut.

Install

npm i -D @slowcook-ai/cli

Or pin a specific version (recommended for consumers):

npm i -D @slowcook-ai/[email protected]

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 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 ..

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] | journeys [--concept <path>] [--dry-run] | tell [--journey <id>] [--seed <n>] [--dry-run] | check [--regen-worlds] [--dry-run] | --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. Overrides require a stated reason AND the owning story's amendment in the same diff.

  slowcook guard --base <ref> --head <ref> [--override --reason <why>] [--config <path>]

• amend — Record a frozen-contract amendment ON the owning story spec (amendments: entry) — the backprop half of guard --override.

  slowcook amend --story <id> --reason <why> [--pr <#>] [--files a,b]

• 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>]

• reviewer-auth — Run the GitHub device-flow sign-in helper standalone — point the review overlay's authBase at it (QA on a real backend, no run-mock).

  slowcook reviewer-auth [--port 4200] [--expose] [--client-id <id>] [--scope repo]

• recall — Recall prior agent sessions (via ctxrs/ctx) as a compact context brief — so agents don't re-investigate settled work.

  slowcook recall <query> | --file <path> [--limit n] [--since 30d] [--workspace <path>] [--json]

• 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 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-.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>]

• bench-browser — Benchmark the browser engines — Playwright (default) vs rustwright (option) — on the eye-capture + QA-replay workloads, per-process RSS + wall-time + oracle pass/fail agreement.

  slowcook bench-browser [eye|qa|both] [--iters <n>] [--plan <file.json>]

• 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/tokens (fast), --survey (deterministic doc/work catalog), --as-built (LLM, cited), --history (mine the agent sessions that BUILT the repo, via ctxrs/ctx).

  slowcook extract [--schema] [--tokens] [--survey] [--as-built] [--history] [--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>]

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