Agent instructions (GTM Groundwork)

This repo was created from the GTM Groundwork starter. The full standards ship IN THIS REPO at standards/ — read ui-ux.md, stack.md, models-and-clis.md, new-tool-checklist.md, and prd-interview.md there; reference-app.html is the working proof of the UI rules. The essentials are condensed below for quick orientation, but the standards folder is the law.

Commands that ship with this repo

• /new-gtm-tool <name> — run from a template clone: creates a NEW project from it (GitHub repo when logged in, local folder copy otherwise), then hands off to /kickoff in the new repo.
• /kickoff — fresh project: runs the kickoff questions, then the checklist.
• /refine-prd — objective -> interview rounds -> Codex pass -> locked PRD.
• /grill — stress-test any plan or decision: frontier-ordered interview rounds until shared understanding (general-purpose version of the PRD interview; adapted from Matt Pocock's grilling skill).
• /mockup — design drafts: Paper canvas first (MCP), Claude artifact as fallback, gitignored design-drafts/ HTML as last resort. Key screens in the house tokens; approval before code.
• /next — where are we? Reads the Stage line, says what's next, offers to run it. The only command the user needs to remember mid-project.

All of these live in .claude/skills/ in this repo, so they work on any machine with no setup. If the harness doesn't surface them, run the same flows from standards/new-tool-checklist.md and standards/prd-interview.md directly.

Session start: orient first

At the start of any session in this repo, read the Stage line in prd.md and tasks.md, then tell the user in plain language where the project stands and offer the next pipeline step (same logic as /next). When you complete a stage, update the Stage line and end by offering the next step by name. The user should never have to remember what comes next — the repo remembers.

Project state

• prd.md — what we're building and why (living doc; keep it current).
• tasks.md — the work, checked off as built.
• If both are still template placeholders, run the kickoff conversation from new-tool-checklist.md step 0 before writing code.

Hard rules (condensed from the standards)

Stack: TypeScript strict, Next.js App Router, HeroUI + Tailwind, Supabase (auth via supabase-js ONLY), Drizzle for ALL server-side data access. Schema in src/db/schema.ts; changes via npm run db:generate + db:migrate; never edit an applied migration. RLS stays enabled on every table.

Auth: Google OAuth default, magic-link fallback. Access control is enforced server-side in src/lib/allowlist.ts + auth/callback — never weaken it.

Observability: every runtime AI call goes through generateForFeature() (src/lib/ai.ts) so cost lands in ai_usage; log logins and key actions via logEvent(). The /admin panel ships in v1.

Models: src/models.ts mirrors the canonical registry (standards/models-and-clis.md). Copywriting is Anthropic-only. Bulk/cheap model is decided per project at kickoff. AI layer (Vercel AI SDK vs Anthropic SDK) is also a kickoff decision — ask the user.

AI features: prompts live in src/prompts/ as versioned files; every AI feature ships with >=10 golden eval examples in evals/ BEFORE it ships; AI output that reaches a real human goes through review-before-send.

UI: borderless cards on the deep ground, ink actions / green data only, mono tabular numerals (.num), sentence case, lucide icons (never sparkles, never emojis in UI), quiet motion (no route transitions, no hover scales), toasts top-center, rounded row hovers, cursor-pointer on everything clickable, light + dark both, fully responsive. Verify UI with Playwright screenshots.

Checkpoints: build per feature; after each, screenshot (both themes) and show the user before continuing. Check off tasks.md.

Pre-deploy: RLS on all tables, allowlist verified, cursors checked, both themes + phone width verified, evals passing, admin panel showing data, no secrets committed.

PRD comes from the interview protocol

If prd.md is a placeholder, run /refine-prd (protocol: standards/prd-interview.md): brain dump -> Fable interview rounds across 12 facets -> Codex adversarial pass -> resolve -> the user locks. No code or mockups before the PRD is locked.

Tooling in this repo

• Evals: npm run evals (needs ANTHROPIC_API_KEY). Write the eval file AS you build each AI feature, never after. CI runs build + evals on every push — never leave the repo red between sessions.
• Screenshots: npm run screenshot -- /route name (dev server running; first time: npx playwright install chromium). Browserbase is the alternative when the user provides it — kickoff question.
• Supabase: Drizzle for data; Supabase CLI for the rest; MCP inspection via .mcp.json (copy from .mcp.json.example, ALWAYS read-only). Token comes from the user, never committed.
• Env: .env.local is created by the user manually. If it's missing or a key is empty, STOP and ask the user — never invent values, never commit secrets.
• Admin "Built with": src/toolstack.ts lists the tools this app uses; keep it current when adding one.

Working with the user

Speak plainly: assume the user understands architectures, schemas, and abstractions, but define jargon and skip implementation minutiae unless it changes their decision. Concise; most important details first.

Estimates are agent-time, never human-developer-time. Do not quote "3 days" for a component or "2 weeks" for a migration — that's human-team time from training data, and it's wrong here: agents build in minutes-to-hours per session. Estimate as (1) agent working time (sessions/hours) plus (2) the actual bottlenecks — the user's review checkpoints, accounts/credentials that must be created, external waits. Those bottlenecks usually dominate; name them explicitly.

Prompts may arrive via voice dictation — expect transcription typos; proceed on the obvious reading, confirm when ambiguity would change a decision. When the user asks a question, answer it — don't convert the answer into changes until they agree. No em-dashes in any outbound copy this tool generates.