cook-with-freebuff

Imported from LCHEROURI/cook-with-freebuff (AGENTS.md). Install upstream with npx skills add LCHEROURI/cook-with-freebuff. Copyright stays with the author.

Cook With Freebuff

Universal repository lock and delivery gates

This project-specific guide is governed by the universal safety constitution in WORKFLOW.md. Before every substantive task, verify the repository rather than trusting a directory name, preview URL, previous conversation, or similarly named checkout:

pwd
git rev-parse --show-toplevel
git remote -v
git branch --show-current
git log -1 --oneline
git status --short

The verified git rev-parse --show-toplevel directory is the only permitted scope. Do not edit sibling repositories, parent checkouts, nested checkouts, other worktrees, or external projects. Re-check the root, remote owner/name, branch, HEAD, and target environment before GitHub, Firebase, database, or deployment actions. Preserve unrelated working-tree changes; do not reset, clean, stash, overwrite, or stage changes you did not make.

Follow this action-specific sequence: inspect → plan → implement → test → review → report → STOP; then separately authorized commit → STOP → push → STOP → PR → STOP → merge → STOP → deploy. A merge does not authorize deployment. Never expose secrets or weaken auth, App Check, Firestore rules, or production safeguards. Read nested AGENTS.md files that apply, and report exact verification evidence. WORKFLOW.md is the detailed 43-section policy and may be stricter, never weaker, than this project guide.

A voice first cooking companion that guides you step by step from "what do I have?" to a plated dinner.

Stack

• Language / Runtime: TypeScript, Node 22
• Framework: Next.js 15 (App Router)
• Key dependencies: Firebase (auth + Firestore), Gemini (AI generation + live voice), Zod (schemas)
• Package manager: npm
• Testing: Vitest + Testing Library + jsdom

Build approach

Contract-locked CI changes: every meaningful change lands through the branch + PR path under the required checks (validate, Codex P1 gate, emulator-compare smoke on pushes). Specs in docs/specs/ record decisions; plans in docs/plans/ track implementation; AGENTS.md files record conventions. No docs/scope/ directory — status is advanced by the engineer/architect, not a scope reconciler.

Commands

# Install
npm install

# Dev server
npm run dev

# Build
npm run build

# Typecheck
npm run typecheck

# Test
npm test

# Local green gate (typecheck → lint → test → build, mirrors CI validate)
npm run check

Specs

Stored in docs/specs/NNNN-title.md. Current: 0001 App Hosting primary host, 0002 probe grace constants, 0003 recipe detail page, 0004 voice everywhere. Implementation plans live in docs/plans/NNNN-title.md, numbered to match their spec.

Rules

• Server code lives under lib/server/ and never imports client code; client code never imports server modules (server-only guards enforce this)
• Every API route resolves the Firebase ID token server side via resolveUserId — the client never supplies the user id
• All Firestore writes are schema validated (Zod) at the repository layer before persisting
• Quota-bearing routes gate with App Check before authentication, parsing, or quota/provider work; production enforcement fails closed and voice/vision use fresh single-use tokens
• firestore.rules is a shared union: change only Cook clauses, preserve non-Cook union rules byte-for-byte, keep the catch-all deny last, and never deploy before the separately authorized sibling-rules synchronization gate
• Production proof scripts may write only uniquely prefixed temporary data, must guarantee cleanup, and must not run until /api/build-info reports the intended guarded revision
• Tool calls are the only way the AI model touches state — every tool logs latency and error codes to agent_tool_logs
• Gemini model names resolve from one shared table (lib/ai/model-roles.ts) in the order Remote Config, then env var, then hardcoded default, so a model version can change without a deploy; call sites never hardcode a model name
• Voice flows through hooks (useVoiceInput, useGeminiLive, useLiveDictation); the reusable VoiceInputButton (spec 0004) wraps useVoiceInput as the transcription entry point on form fields, so no call site touches the raw Web Speech API
• Components use controlled inputs with useState, not react-hook-form
• Tests use // @vitest-environment jsdom pragma on component files; default environment is node
• Probe cleanup grace durations are declared per driver (scripts/verify-live.mjs, scripts/drive-live-voice.mjs) with a rationale comment at each declaration, and the shared 15 minute seed grace is pinned identical across both files by the lockstep contract in scripts/verify-live-cleanup.test.ts; never introduce a shared constants module (spec 0002)
• For meaningful development decisions, failures, regressions, major review findings, security discoveries, or reusable patterns, run skills/progressive-distillation/SKILL.md before closing the task. Distilled principles may add stricter guidance, but must never weaken or override existing project safety, CI, security, deployment, or repository rules.

Output style

The reader has ADHD. Shape every response so it can be acted on:

1. Lead with the answer or next action: command, path, or snippet first.
2. Number multi-step work; one bounded action per step.
3. End with one next action doable in under two minutes, when work remains; for a finished task, say so in one plain line instead.
4. Finish the current issue before raising a new one; hold follow-up offers until the task completes.
5. Restate progress each turn ("step 3 of 5 done").
6. Give time estimates in concrete units, never "a bit".
7. After a change, show what now works.
8. Errors: state location, cause, and fix. No drama.
9. Cap lists to 5 items.
10. No preamble, no recaps, no closers.

Exceptions: explain fully when asked to explain. Confirm before destructive actions. After three failed fixes, stop and name the doubtful assumption. If the request is ambiguous, ask one short question.

Google Cloud & Tooling

• Active plugin: google-cloud-developer (includes gcloud, developer-knowledge MCP server, google-cloud-recipe-auth, google-cloud-recipe-onboarding, and finding-google-skills).
• gcloud CLI operations must adhere to safety-critical validations (explicit project verification, non-destructive flags, no broad modifications).
• Query official Google documentation grounded through the developer-knowledge MCP server (https://developerknowledge.googleapis.com/mcp) before making architectural or API assumptions.
• For deeper or uninstalled Google Cloud skills, use finding-google-skills to discover entries from the official catalog (https://github.com/google/skills).

Context files

• ARCHITECTURE.md: layered architecture, request flow, and the Mermaid diagram
• DATA_MODEL.md: domain types, schemas, and Firestore collection layout
• AGENT_TOOLS.md: tool registry and the model's structured tool calling surface
• skills/progressive-distillation/SKILL.md: experiential reflection workflow that converts meaningful development outcomes into reusable principles, experiments, and automation candidates
• lib/ai/AGENTS.md: AI provider boundary, model resolution, and structured JSON conventions
• scripts/AGENTS.md: deploy-verification drivers, the Codex review pipeline, and the landing path conventions
• components/AGENTS.md: presentational client components (CookScreen, voice indicator, starter tour) and their accessibility conventions
• lib/server/AGENTS.md: Firestore repositories, the session-service state machine, the tool registry, and server-only wiring
• dataconnect/AGENTS.md: the Firebase SQL Connect (Data Connect) twin of the Firestore data layer — migrations target it, the running app still uses Firestore
• app/AGENTS.md: pages and API routes, the shared auth pattern, and the route-handler conventions
• STATE_MACHINE.md: cooking session phase machine and state transitions
• VOICE_ARCHITECTURE.md: realtime voice provider abstraction and Gemini Live integration
• TESTING.md: test conventions, jsdom pragma, and the verify driver pattern
• SECURITY.md: auth architecture, token flow, and tool call logging

Drafted by /audit from the repo, worth a quick human pass. Edit freely: once a line stops matching this draft, later runs treat it as curated and will flag rather than overwrite it.