@cofoundr/init 1.5.0

package/content/scaffold/AGENTS.md.tmpl

@@ -0,0 +1,74 @@
+# {{PROJECT_NAME}}
+
+> This is the project's universal AI-agent context file. Every modern coding agent — Claude Code, Cursor, Windsurf, Cline, Codex, Aider, GitHub Copilot, Gemini, Goose, Junie, Kilo, Roo, Zed — reads `AGENTS.md` at the repository root before working on this project.
+>
+> Keep this file short. Detail belongs in the documents it links to.
+
+## Project
+
+{{PROJECT_DESCRIPTION}}
+
+## How to work in this repo
+
+1. **Read the constitution before changing anything.**
+   The project's non-negotiable rules live in `.cofoundr/constitution.md`. The `Never` section is binding. If a user instruction conflicts with a Never rule, follow the rule and explain why.
+
+2. **Use the spec as source of truth.**
+   The active specification lives in:
+   - `docs/product.md` — what the product is and who it's for
+   - `docs/prd.md` — features with acceptance criteria
+   - `docs/tech.md` — stack, data model, integrations
+   - `docs/phases.md` — milestones, phases, HALT conditions
+   - `.cofoundr/specs/` — feature- and phase-level specs
+   - `.cofoundr/memory/codebase.md` — architecture map (refresh with `/cofoundr:onboard`)
+   - `.cofoundr/memory/decisions.md` — append-only decisions log
+
+3. **Use the workflow commands.**
+   The project ships a tool-agnostic command set under `.cofoundr/commands/`. To invoke one, the user will say `/cofoundr:<command>` or `cofoundr <command>` — read the matching `.cofoundr/commands/<name>.md` and follow its instructions exactly. Do not paraphrase. Do not skip steps.
+
+   Available commands:
+
+   - **Planning:** `quick-brief`, `new-project`, `plan`, `next`, `new-feature`
+   - **Spec-driven (SDD):** `constitution`, `specify`, `tasks`, `implement`
+   - **Brownfield:** `onboard`, `document`, `audit`
+   - **Guardrails:** `scope-guard`, `rules-check`, `review`
+   - **Comms / setup:** `translate`, `setup-skills`, `resume`
+
+4. **Pick up where the last session left off.**
+   Always run `/cofoundr:resume` first. It surfaces active feature docs and the next unchecked task and waits for confirmation before any code is written.
+
+## Build, test, run
+
+{{BUILD_INSTRUCTIONS}}
+
+## Code conventions
+
+{{CODE_CONVENTIONS}}
+
+## Commit conventions
+
+- One commit per task. Format: `<phase or feature>: T<N> <imperative summary>`.
+- Never commit `.env`, key files, or secrets.
+- Never use `--no-verify` or skip pre-commit hooks unless the user explicitly authorized it.
+
+## Things to never do
+
+The full Never list lives in `.cofoundr/constitution.md`. Read it. The most-violated rules:
+
+- Never put secrets in client bundles.
+- Never deploy tables without row-level security.
+- Never enforce auth only client-side.
+- Never use `DROP`, `TRUNCATE`, `rm -rf`, or `--force` without explicit user confirmation.
+- Never pass user input to `exec`, `eval`, or raw SQL.
+- Never use `any` in TypeScript.
+
+## Tool-specific notes
+
+This project is configured for the following AI tools. Tool-specific shims live next to this file:
+
+{{TOOL_SHIMS}}
+
+If your tool isn't listed, this file (`AGENTS.md`) is enough — it is the open standard read by every modern coding agent.
+
+---
+<sub>Managed by **CoFoundr**. Run `npx @cofoundr/init sync` to refresh the per-tool shims after a CoFoundr upgrade.</sub>

package/content/templates/agents.md

@@ -0,0 +1,144 @@
+---
+description: "Pointer file — read this first, then follow the read order below"
+tags: [steering, spec, boundaries]
+---
+
+# AI Assistant Configuration
+
+<!-- HOW-TO: This is the first file your AI assistant reads. It tells the AI where to find everything else, what conventions to follow, and what boundaries to respect. Think of it as the AI's onboarding document. -->
+
+## TL;DR
+
+<!-- HOW-TO: ≤60 words. State the assistant's role, its read order, and its single most important constraint. -->
+
+*You are a coding assistant for TaskPilot, a daily planner for solo founders. Read the files below in order before writing any code. Your most important constraint: never use secret keys in client-side code. When in doubt, check rules.md before proceeding.*
+
+## Read Order
+
+<!-- HOW-TO: The AI reads these files in this order at the start of every session. Each file has a single purpose — don't merge them. -->
+
+1. **product.md** — What we're building and why (problem, user, solution, non-goals)
+2. **prd.md** — What ships in v1 with acceptance criteria for every feature
+3. **tech.md** — Stack decisions, database schema, API endpoints, integrations
+4. **rules.md** — Non-negotiable rules, ask-first items, and hard stops
+5. **phases.md** — Build roadmap with milestones, phases, tasks, and verify checkpoints
+6. **docs/ACTIVE.md** — Active feature docs (if any) — loaded automatically, contains current in-progress feature state
+
+## Commands
+
+<!-- HOW-TO: Define what the AI should do when given common instructions. Be explicit — AI assistants follow patterns better than open-ended instructions. -->
+
+**"Start building"** or **"Begin Phase X":**
+1. CLAUDE.md auto-loads the spec files — confirm you can see product.md, prd.md, tech.md, rules.md, phases.md, agents.md in context
+2. Check `phases.md` for the current milestone, current phase, and next incomplete task
+3. If working on a feature, confirm the feature doc in `docs/features/` is loaded via ACTIVE.md
+4. Read the task's file paths and acceptance criteria
+5. Implement the task
+6. Run the verify check and confirm it passes
+7. Check off the completed task in the feature doc and update Session Notes
+8. Commit with a descriptive message referencing the task number
+
+**"Add a feature":**
+1. Check if the feature exists in `prd.md` — if not, ask before proceeding
+2. Check `tech.md` for relevant stack and schema information
+3. Check `rules.md` for any applicable constraints
+4. Implement and verify against acceptance criteria
+5. Commit
+
+**"Fix a bug":**
+1. Reproduce the bug first — don't fix what you can't see
+2. Check `rules.md` before making any changes
+3. Fix with the smallest possible change
+4. Verify the fix doesn't break existing functionality
+5. Commit with a message describing the bug and the fix
+
+## Testing
+
+<!-- HOW-TO: Define your testing expectations. Be specific about what "tested" means for this project. -->
+
+- Run `npx next build` before every commit — if it doesn't build, it doesn't ship
+- Test the happy path manually after every task (use the verify block in `phases.md`)
+- Write unit tests for utility functions in `src/lib/`
+- Write integration tests for API routes in `src/app/api/`
+- Test the happy path first, then edge cases
+- Never commit code that produces TypeScript errors or console warnings
+
+## Structure
+
+<!-- HOW-TO: Define your project's file organization so the AI doesn't invent its own. -->
+
+```
+src/
+  app/                    # Next.js App Router pages and API routes
+    api/                  # Server-side API routes (secrets live here)
+      integrations/       # OAuth connect/callback routes per provider
+      pull/               # Morning pull trigger
+      tasks/              # Task CRUD operations
+      webhooks/           # Inngest, Stripe webhook receivers
+    login/                # Auth pages
+    settings/             # User settings (integrations, pull time)
+    page.tsx              # Main daily focus view
+  components/             # React components (no server-side logic)
+  lib/                    # Shared utilities, clients, types
+    integrations/         # Provider-specific fetchers (Slack, Trello, Linear)
+    inngest/              # Background job definitions
+    supabase.ts           # Supabase client (browser + server)
+  types/                  # TypeScript type definitions
+supabase/
+  migrations/             # SQL migration files (numbered)
+```
+
+## Style
+
+<!-- HOW-TO: Code style rules the AI must follow. Be opinionated — vague style guides produce inconsistent code. -->
+
+- TypeScript strict mode — no `any`, no `@ts-ignore`, no type assertions unless truly necessary
+- Use `async/await` over `.then()` chains
+- Use named exports, not default exports (except for Next.js pages)
+- Component files: PascalCase (`TaskList.tsx`)
+- Utility files: camelCase (`formatDate.ts`)
+- API routes: kebab-case directories (`/api/integrations/slack/connect/`)
+- Use early returns to reduce nesting
+- Maximum function length: 40 lines — extract helpers if longer
+- All user-facing strings in component files, not buried in utility functions
+
+## Git
+
+<!-- HOW-TO: Git conventions for consistent history. The AI should follow these for every commit. -->
+
+- **Commit message format:** `type(scope): description` (e.g., `feat(auth): add Supabase login flow`)
+- **Types:** `feat`, `fix`, `refactor`, `chore`, `docs`, `test`
+- **Branch naming:** `phase-X/task-description` (e.g., `phase-1/slack-oauth`)
+- Commit after every completed task, not at the end of a session
+- Never commit with failing TypeScript checks
+- Never commit `.env` files or secrets
+
+## Boundaries
+
+<!-- HOW-TO: This section exists to prevent the AI from reinventing rules that already live in rules.md. Point there, don't duplicate. Duplication leads to contradictions when one copy gets updated and the other doesn't. -->
+
+See `rules.md` for the full **Always / Ask First / Never** rule set. Do not duplicate rules here — `rules.md` is the single source of truth for behavioral constraints.
+
+When uncertain about whether an action is allowed, check `rules.md` before proceeding. If the action isn't covered by any rule, ask the user.
+
+## Session Management
+
+<!-- HOW-TO: AI coding tools degrade over long conversations — they start hallucinating, forgetting context, and making mistakes. Starting a fresh chat for each phase prevents this. The CLAUDE.md file in the project root auto-loads all spec files and runs the Session Start Protocol automatically. -->
+
+- **Run `/cofoundr:resume` at the start of every session.** This is the first command you type, before anything else. It reads the active feature docs (or phases.md if no active feature), presents a recap of where things stand, and waits for your confirmation before any code is written. Do not skip it — without it the AI starts with stale assumptions.
+- **CLAUDE.md handles spec context automatically.** All six spec files and active feature docs load the moment you open a session in the project folder. No manual pasting.
+- **Start a fresh chat for each phase.** Long sessions degrade model quality — close and reopen when you move to the next phase.
+- **Update the feature doc before ending a session.** Add a Session Notes entry: what was done, what's next, decisions made, risks. This is what the next session's recap will read.
+- **If the AI gets confused, start over.** Close the chat and open a new one. A fresh context is faster than correcting a confused model.
+
+## Session Start Protocol
+
+<!-- HOW-TO: This section is also encoded in CLAUDE.md, so it runs automatically. It is repeated here so the AI has the rationale, not just the rule. -->
+
+At the start of every session, before any code, edits, or commands:
+
+1. Check `docs/ACTIVE.md` for active feature imports.
+2. **Active features present:** Read the most recent Session Notes entry from each feature doc. Present a recap (what was done, what is next, any blockers). Ask: "Does this still reflect where things stand?" Wait for confirmation or corrections.
+3. **No active features:** Read `docs/phases.md`. Find the last checked task and first unchecked task. Present: "You are on [Milestone / Phase]. Next task: [name and file]. Ready to continue?" Wait for confirmation.
+
+The purpose of this gate: the session notes were written by the last session's AI, which had context this session does not have. The recap surfaces that context explicitly and gives the human a chance to correct anything that has changed — a decision made offline, a blocker resolved, a direction change. Skipping this step means the AI starts with stale assumptions.

package/content/templates/brand.md

@@ -0,0 +1,180 @@
+---
+description: >
+  Brand spec for the product. Generated by the brand-intake subagent during
+  planning. Every ui-spec.md across phases references this file for color,
+  type, voice, and kit integration tokens. Keep this file authoritative —
+  if a component contradicts brand.md, the component is wrong.
+---
+
+# Brand — [Product Name]
+
+## TL;DR
+
+<!-- ≤60 words: the voice in one phrase, the accent color by name, the type system by name, and the three reference products. Example: "Confident and plain-spoken. Deep green accent ('#0C8A4E', 'forest'). Inter for UI, Source Serif for marketing long-form. Sits between Linear's precision and Basecamp's warmth, next to Stripe." -->
+
+---
+
+## Voice
+
+<!-- One paragraph describing how the product sounds. Pull from product.md's TL;DR and target-user paragraphs. Then 3 do/don't examples specific to this product's domain. -->
+
+**Tone:** [one-line descriptor]
+
+**Do:**
+
+- [Example of on-brand copy: "Your Meta ads, on autopilot."]
+- [Example of on-brand copy: "Dana runs her ads in 2 minutes a day."]
+- [Example of on-brand copy: "We spotted a fatigued ad. Here's what to do about it."]
+
+**Don't:**
+
+- [Off-brand: "Revolutionize your ads with AI-powered analytics!"]
+- [Off-brand: "Leverage cutting-edge machine learning…"]
+- [Off-brand: "Unlock the full potential of your marketing funnel."]
+
+---
+
+## Palette
+
+<!-- Every color is a hex value. If Launch Kit, these feed the Kit integration block below. -->
+
+- **Accent primary:** `#______` (name: _________)
+- **Accent secondary / hover:** `#______`
+- **Neutral 50 (background):** `#______`
+- **Neutral 500 (body text):** `#______`
+- **Neutral 900 (headings):** `#______`
+- **Success:** `#______`
+- **Warning:** `#______`
+- **Error:** `#______`
+
+<!-- HOW-TO: the accent is used sparingly (primary CTAs, active tab indicators, key metric callouts). Overusing it kills the signal. Neutrals do 80% of the visual work. -->
+
+---
+
+## Type
+
+- **Heading family:** [font name + weight, e.g. `Inter 600`]
+- **Body family:** [font name + weight, e.g. `Inter 400`]
+- **Mono family (if dev-facing):** [font name, e.g. `JetBrains Mono`]
+- **Scale:**
+  - `display` — [size/line-height, e.g. 48/56]
+  - `h1` — [e.g. 32/40]
+  - `h2` — [e.g. 24/32]
+  - `h3` — [e.g. 20/28]
+  - `body` — [e.g. 16/24 default]
+  - `small` — [e.g. 14/20]
+
+<!-- HOW-TO: name real fonts, not generic categories. If a custom font was named, verify it is available on a free source (Google Fonts, Fontshare) and cite the source URL. -->
+
+---
+
+## Spacing
+
+<!-- Grid the kit already uses. Default: 4px base, Tailwind-compatible steps 1-24 (0.25rem to 6rem). Only change if the reference products signal tighter or looser density. -->
+
+- **Base unit:** 4px
+- **Default step:** 16px (4)
+- **Section padding:** 48px (12) mobile, 96px (24) desktop
+- **Card padding:** 24px (6)
+- **Form gap:** 16px (4) between fields, 24px between groups
+
+---
+
+## Imagery
+
+<!-- One paragraph. Photography, illustration, or both? Style descriptors. If the product needs AI-generated creative (AdPilot-style), note the prompt anchors. -->
+
+**Primary medium:** [photography | illustration | both]
+
+**Style descriptors:** [e.g. "clean product shots on neutral backgrounds, soft natural light, no flat-lay, no stock-photo staging"]
+
+**AI-generation prompt anchors (if applicable):** [e.g. "minimal, DTC-indie, warm tones, brand-consistent with the three reference products named above"]
+
+---
+
+## Reference material
+
+<!-- The three products named during intake. One line each describing what they contribute to the feel. -->
+
+1. **[Product 1]** — [what it contributes, e.g. "precision typography and zero visual noise"]
+2. **[Product 2]** — [what it contributes]
+3. **[Product 3]** — [what it contributes]
+
+---
+
+## Copy rules
+
+**Use:**
+
+- [Pattern, e.g. "State the numbers. 'CTR dropped 28%' beats 'performance declined'."]
+- [Pattern, e.g. "Write for Dana specifically, not 'marketers' as a category."]
+- [Pattern, e.g. "One idea per sentence. Two at most."]
+
+**Avoid:**
+
+- [Anti-pattern, e.g. "Jargon: 'leverage,' 'synergy,' 'unlock'"]
+- [Anti-pattern, e.g. "Superlatives: 'best-in-class,' 'revolutionary,' 'industry-leading'"]
+- [Anti-pattern, e.g. "Promise language without evidence: 'AdPilot will grow your revenue'"]
+
+---
+
+## Kit integration
+
+<!-- Only populated when launch-kit-detect returns `launch-kit`. The blocks below paste into apps/web/styles/globals.css and apps/web/tailwind.config.ts. -->
+
+### globals.css — CSS custom properties
+
+```css
+:root {
+  --brand-accent: #______;
+  --brand-accent-hover: #______;
+  --brand-neutral-50: #______;
+  --brand-neutral-500: #______;
+  --brand-neutral-900: #______;
+  --brand-success: #______;
+  --brand-warning: #______;
+  --brand-error: #______;
+}
+
+:root.dark {
+  /* Dark-mode overrides. Only override what changes. */
+  --brand-neutral-50: #______;
+  --brand-neutral-500: #______;
+  --brand-neutral-900: #______;
+}
+```
+
+### tailwind.config.ts — theme extension
+
+```ts
+// apps/web/tailwind.config.ts
+export default {
+  theme: {
+    extend: {
+      colors: {
+        brand: {
+          DEFAULT: 'var(--brand-accent)',
+          hover: 'var(--brand-accent-hover)',
+          success: 'var(--brand-success)',
+          warning: 'var(--brand-warning)',
+          error: 'var(--brand-error)',
+        },
+      },
+      fontFamily: {
+        sans: ['[heading family]', 'ui-sans-serif', 'system-ui'],
+        serif: ['[body family]', 'ui-serif'],
+        mono: ['[mono family]', 'ui-monospace'],
+      },
+    },
+  },
+};
+```
+
+<!-- When ui-spec.md files reference `brand.accent` or `brand.type.heading`, they map to these tokens. -->
+
+---
+
+## Maintenance
+
+- This file is append-only for copy rules and reference material. Colors and type can be revised but log the change inline (`<!-- revised YYYY-MM-DD: accent shifted from #X to #Y because … -->`).
+- Any ui-spec.md that hardcodes a color or font name instead of referencing a brand token is a violation. `/cofoundr:review` should flag these.

package/content/templates/feature.md

@@ -0,0 +1,70 @@
+---
+description: >
+  Living document for [Feature Name]. Created by /cofoundr:new-feature.
+  Update this file as work progresses — at the end of every session, before
+  every commit, and whenever a blocker is hit or resolved.
+  Loaded automatically in every Claude session via ACTIVE.md.
+---
+
+# Feature: [Feature Name]
+
+## TL;DR
+<!-- ≤30 words: what this feature does, who it's for, and which milestone it belongs to -->
+
+**Status:** `In Progress`
+**Milestone:** Milestone [N] — [Milestone Name]
+**Phase:** Phase [N.N] — [Phase Name]
+**Added:** [date]
+**Last updated:** [date]
+
+---
+
+## Acceptance Criteria
+<!-- Observable behaviors a non-technical founder can verify by looking at the screen.
+     Good: "User sees a confirmation message within 5 seconds of submitting."
+     Bad: "POST /api/feature returns 200." -->
+
+- [ ] ...
+- [ ] ...
+- [ ] ...
+
+## Dependencies
+<!-- What must already exist before this feature can be built. Reference the phase that provides each dependency. -->
+
+- [Phase N] provides: ...
+- External: ...
+
+## Scope Boundaries
+<!-- What this feature explicitly does NOT do. Every boundary here prevents a future scope-creep argument. -->
+
+- Not ...
+- Not ...
+
+---
+
+## Build Progress
+
+### Tasks
+<!-- Check off as work is completed. Add the date completed in brackets. Add [BLOCKED: reason] inline for blockers. -->
+
+- [ ] Task 1 — `[file/path]`
+- [ ] Task 2 — `[file/path]`
+- [ ] Task 3 — `[file/path]`
+
+### Blockers
+<!-- Active blockers only. Remove the line when resolved. -->
+
+*None*
+
+---
+
+## Session Notes
+<!-- One entry per session. Newest at top. This is the handover mechanism — the next session
+     reads this section first to know exactly where things stand. Be specific: what was done,
+     what decision was made and why, what is next, what is risky. -->
+
+**[date] — [Status: started / continued / completed / blocked]**
+Done: ...
+Next: ...
+Decisions: ...
+Risks: ...

package/content/templates/phases/phase-template/README.md

@@ -0,0 +1,65 @@
+---
+description: >
+  Plain-English spec for Phase [N]. Written before any code. The AI reads
+  spec.md to build; humans read this to gut-check we're building the right
+  thing. Generated by /cofoundr:next during planning.
+---
+
+# Phase [N] — [Phase Name]
+
+## TL;DR
+<!-- ≤60 words in plain English. What ships at the end of this phase, who it's for, and why it matters. No acronyms, no jargon. -->
+
+---
+
+## What ships
+
+<!-- One paragraph. The observable outcome when this phase completes. A non-technical founder should read this and be able to describe the phase's output to an investor without opening any other file. -->
+
+---
+
+## Who this is for
+
+<!-- Which user persona does this phase move forward? Reference the user from product.md by name and situation. If this phase only benefits a subset of users, say which. -->
+
+---
+
+## What's in scope
+
+<!-- 3-6 bullets. Concrete capabilities that exist when this phase is done. Each line should be something a human can click or see. -->
+
+- ...
+- ...
+- ...
+
+## What's explicitly out of scope
+
+<!-- 2-4 bullets. Things a founder might expect from this phase that are deferred. Name the phase or milestone where each deferred item is handled. -->
+
+- Not ... (deferred to Phase [N])
+- Not ... (deferred to Phase [N])
+
+## Dependencies
+
+<!-- What earlier phases must be complete for this one to start. Name the phase and the specific artifact it provides. -->
+
+- Phase [N] provides: [artifact]
+- External: [e.g. Meta App registered in developer.facebook.com]
+
+## Success looks like
+
+<!-- 3-5 observable success criteria. A founder running through the app should be able to tick each one. Copy these into tests.md as the happy-path checklist. -->
+
+- [ ] ...
+- [ ] ...
+- [ ] ...
+
+## Effort estimate
+
+<!-- Rough calendar estimate for a solo founder with AI tooling. Cite the complexity calibration from tech.md (simple / standard / complex). If Launch Kit, estimate assumes kit subagents and helpers are available. -->
+
+*Estimate: [N] days. Calibration: [simple | standard | complex].*
+
+---
+
+<!-- When this file is complete, spec.md starts. README.md is the pre-build gut-check; spec.md is the AI's build manual. -->

package/content/templates/phases/phase-template/decisions.md

@@ -0,0 +1,52 @@
+---
+description: >
+  Decision log for Phase [N]. Every non-trivial choice that shaped the spec,
+  with its rationale and the alternatives considered. Append-only during
+  planning; append-only during build. Generated by /cofoundr:next during planning.
+---
+
+# Phase [N] — Decisions Log
+
+## TL;DR
+<!-- ≤60 words. The 2-3 most load-bearing decisions for this phase. These are the ones future-you will thank present-you for writing down. -->
+
+---
+
+## Decisions
+
+<!-- One block per decision. Append, do not edit. If a decision is later reversed, add a new "Reversed" block rather than deleting. -->
+
+### [YYYY-MM-DD] — [Decision name]
+
+- **Decision:** ...
+- **Rationale:** ...
+- **Alternatives considered:**
+  - ... (rejected because ...)
+  - ... (rejected because ...)
+- **Decided by:** [founder | AI-with-founder-confirmation]
+- **Reversible?** [yes | no | costly]
+
+---
+
+## Open decisions
+
+<!-- Decisions still unresolved. Each has a target resolution date and the blocker. Move to the main list above once resolved. -->
+
+- **[Open decision name]**
+  - Target: [YYYY-MM-DD]
+  - Blocker: ...
+  - Options under consideration: ...
+
+## Reversed
+
+<!-- Decisions that were made and later changed. Each names the original decision, what was wrong about it, and what replaced it. These are the most valuable history entries — they prevent repeating a mistake. -->
+
+### [YYYY-MM-DD] — [Decision name] — Reversed
+
+- **Original:** ...
+- **Why reversed:** ...
+- **Replaced by:** ...
+
+---
+
+<!-- decisions.md is the memory of this phase's judgement calls. Treat it as append-only. A thin decisions.md is fine; a missing one is not. -->

package/content/templates/phases/phase-template/research.md

@@ -0,0 +1,59 @@
+---
+description: >
+  Research notes for Phase [N]. Competitor findings, prior art, API quirks,
+  and gotchas. Written before the spec so the spec can benefit. Generated by
+  /cofoundr:next during planning.
+---
+
+# Phase [N] — Research
+
+## TL;DR
+<!-- ≤60 words. The 2-3 most important findings from research that shaped the spec. If there were no surprises, say so and cite what was confirmed. -->
+
+---
+
+## Competitor findings
+
+<!-- How do other products solve the same problem this phase addresses? Name them. What works well, what is clunky, what we'll copy, what we'll deliberately avoid. At least 2 competitors, each with specifics — no hand-waving. -->
+
+### [Competitor 1]
+
+- **Approach:** ...
+- **Works well:** ...
+- **Clunky:** ...
+- **Our response:** ...
+
+### [Competitor 2]
+
+- ...
+
+## Prior art
+
+<!-- GitHub projects, blog posts, documentation pages, existing kit patterns that inform this phase. Link each. If a pattern from the Launch Kit's subagents (kit-db-expert, kit-guardrails, etc.) applies, name it and what it gives us. -->
+
+- [Link / ref] — [what it gives us]
+- ...
+
+## API specifics
+
+<!-- Quirks and gotchas of any external API this phase talks to. Rate limits, auth flows, sandbox-vs-production differences, deprecation timelines. Cite the source (docs URL + date read). -->
+
+- **[API name]**
+  - Quirk: ...
+  - Source: [URL], read [date]
+
+## Gotchas
+
+<!-- Things we'd have hit mid-build if we hadn't done this research. One bullet per gotcha, with the evidence and the mitigation we're adopting. -->
+
+- ...
+
+## Open questions
+
+<!-- Items that research couldn't resolve and need a decision before or during the spec. Move each to decisions.md once resolved. -->
+
+- ...
+
+---
+
+<!-- When research.md is complete, the spec and UI spec can use it as a grounding reference. If new questions arise during spec.md authoring, add them here and either resolve or log in decisions.md. -->