@slowcook-ai/cli

The slowcook CLI. Turn a user story into frozen tests, then let an agent iterate until they're green — without letting it move the goalposts.

Tests are written and approved before the agent starts, and it cannot edit them. Each iteration is scored: a test flipping red → green is committed, a broken green test reverts the whole iteration, and nothing-changed keeps the code as the next turn's base without a checkpoint. Progress only goes one way.

⚠️ 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>]

• analyze [alpha] — Deterministic cross-spec + as-built consistency gate for one spec: same endpoint declared with contradictory request fields/responses in another active spec (param names normalized), two specs creating the same table, and cited entities or altered tables that exist nowhere. Exit 1 on findings; taste's spec reviews receive the findings as evidence. Adapted from Spec Kit (github/spec-kit, MIT).

  slowcook analyze --spec <id> [--cwd <path>] [--json]

• rule [alpha] — Manage the project constitution (.brewing/constitution.md) — the law file every agent stage loads (refine, taste, brew, sift, plate). Three-state decision slots (ticked / deliberately blank with justification / unaddressed) filled lazily; add appends a VERBATIM ruling with date, author, and source link. Adapted from Spec Kit (github/spec-kit, MIT) — see docs/plans/spec-kit-borrowings.md.

  slowcook rule init | slowcook rule add "<verbatim ruling>" [--source <url>] [--by <name>] [--cwd <path>]

• taste [alpha] — Reviewer agent for pipeline PRs: reads the story lineage (source issue + PM Q&A + spec + diff), posts a structured verdict as the agent identity, and with --merge merges on approve. Fail-closed: unparseable verdicts merge nothing; blocking findings never approve. The worker derives taste jobs from open agent PRs with no submitted review — the PR is the trigger.

  slowcook taste --pr <n> [--merge] [--cwd <path>] [--owner <o>] [--repo <r>] [--model <id>]

• 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: spec validators on PR amendments, the mock-vs-prod import boundary, mock data leaking into production paths, and mock/prod surface drift.

  slowcook check (mock-isolation|prod-honesty|prod-bundle|surface-parity|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; reprice settles entries against the current pricing table from their stored token counts.

  slowcook cost log --story <id> --usd <n> --agent <name> [--apply-to-spec] · slowcook cost reprice (--story <id>|--all) [--dry-run]

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

• app [alpha] — Create an org-owned GitHub App for slowcook agents via GitHub's one-click App-Manifest flow — writes the PEM + env snippet and prints the install URL; agents then post as [bot] on every repo the owner installs it on.

  slowcook app init [--org <org>] [--name <app-name>] [--public] [--out-dir <dir>] [--port <n>]

• worker [alpha] — Label-triggered agent worker: scan agent:* triggers on open issues, derive the workload, evaluate each agent's preconditions, trace the pass. --enable runs a stage live (label off → spawn → trace → result label / failure comment); stages beyond refine land one verified handoff at a time. worker systemd prints the box units; worker deploy --host <ssh> ships the checkout (G1 exclusions, forced remote build, deterministic dist-freshness assertion).

  slowcook worker run (--dry-run | --enable refine) [--cwd <path>] [--owner <login>] [--repo <name>] [--logs-dir <path>] [--lock <path>] [--job-timeout-mins <n>] [--json]

• workload [alpha] — Read-only view of what the worker sees: derived jobs in priority order, each precondition with status and responsible upstream agent, and what the next pass would run. Never mutates the checkout — a mismatched checkout is reported, not repaired.

  slowcook workload [--cwd <path>] [--owner <login>] [--repo <name>] [--json]

• provenance [alpha] — One-time ratchet baseline: sanction every owned artifact (specs, manifest tests) as it stands, in one ledger entry + baseline header. Strict enforcement from the next commit; refuses to run twice (re-baselining would launder hand edits).

  slowcook provenance init [--cwd <path>] [--by <name>]

• doctor [alpha] — Verify and NAME every worker precondition, one line each: checkout sync, worktree hygiene, forge identity (live App-token mint, not a file check), LLM seam (including the ANTHROPIC_API_KEY-outranks-OAuth trap), pricing coverage for default models, installed dependencies. Fail-closed: exit 1 on any failure.

  slowcook doctor [--cwd <path>] [--owner <login>] [--repo <name>]

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

Which backend does which command support?

SLOWCOOK_LLM=claude-cli runs slowcook on your local claude login's subscription instead of an API key — no API billing.

| Backend | Set | Supported by | |---|---|---| | Anthropic API | ANTHROPIC_API_KEY | every command | | Local Claude CLI | SLOWCOOK_LLM=claude-cli | refine, brew |

brew reaches its tools over an MCP bridge that exposes slowcook's own tool set (read_file, write_file, outline_file, …) to the headless session, with the CLI's built-in tools fenced off. Other tool-use commands still need the API.

Spend is still recorded, at Anthropic list price, so cost reporting and budget caps keep working on subscription auth — the ledger says what the run would have cost, and nothing is billed to your API account.

Two things that bite in practice:

• A stale ANTHROPIC_API_KEY outranks the OAuth token. If both are set, the CLI uses the key; a dead key then produces an opaque error_during_execution. Check apiKeySource in the session's init line, and unset ANTHROPIC_API_KEY when you mean to use the subscription.
• An expired login halts immediately (exit 77) naming the fix, rather than burning iterations as a phantom agent stall. Re-auth with claude setup-token and export the printed token as CLAUDE_CODE_OAUTH_TOKEN — setup-token prints a token, it does not save one.

Running slowcook on a remote host

ssh host 'nohup slowcook brew … &' hangs until the child exits, even with redirects — ssh holds the channel open while any process has the tty. Detach properly instead:

ssh host "setsid slowcook brew --story 001 < /dev/null > brew.log 2>&1 &"

Cost accounting

Every LLM call is logged to specs/story-<id>.cost.jsonl with its token counts. A model missing from the pricing table records usd: null — unknown spend, never $0 — with one warning naming the model. Because the tokens are stored, the gap is recoverable:

slowcook cost reprice --all --dry-run   # preview
slowcook cost reprice --all             # settle against the current table

This also normalizes a price basis across runs made days apart.

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