@cofoundr/init 1.5.0

package/content/commands/new-project.md

@@ -0,0 +1,243 @@
+---
+description: >
+  Start a new project. Runs the full planning conversation, does the
+  research pass, then generates all six specification files plus CLAUDE.md
+  and the project folder structure. This is the complete pipeline.
+---
+
+# New Project — Full Pipeline
+
+Run this process in order. Do not skip steps. Do not produce any deliverables before the planning conversation is complete.
+
+## Step 1 — Planning Conversation
+
+Run the protocol described in `/cofoundr:plan`:
+- Same persona (firm on detail, kind in tone, research-backed pushback — never correct from memory, verify with Context7 or WebSearch and cite the source)
+- Same question bank (Q1–Q15, adaptive)
+- Same sufficiency rubric — 15 rubric items, all must be satisfied before moving on. There is no hard question minimum
+- Same verification summary at the end
+
+Ask one question per message. Skip a question if a prior answer already covered it. Ask follow-ups whenever a rubric item is not yet satisfied.
+
+End the step by presenting the verification summary and asking, in plain language: *"Does this look right? Tell me what to fix, or say 'go' and I'll generate the plan."* Accept any natural-language confirmation — "go", "yes", "looks right", "ship it". Do not require a special token.
+
+If the founder tries to move on with rubric gaps remaining, offer once to fill them. If they still decline, respect that — proceed, but log every unmet rubric item under the Clarifications Log in `prd.md` so nothing is hidden.
+
+Do not proceed to Step 2 until the founder has confirmed.
+
+## Step 2 — Research Phase
+
+After the founder confirms, before generating any files, conduct internal research:
+
+1. **Domain patterns.** Identify the 2-3 most relevant technical patterns for this product category (marketplace: escrow + dual-sided onboarding; SaaS: billing + teams; social: moderation + feed).
+2. **Competitor architecture.** Based on Q2's analogue, identify likely architecture and where the differentiator requires divergence.
+3. **Compliance surface.** Based on Q13, identify regulations for rules.md. If the founder said "none," verify: does their description imply PII collection, payments, or automated decisions?
+4. **Stack selection.** If no stack was specified in Q12, choose one based on budget, timeline, product type, and AI-tool support. Pin exact major versions.
+5. **Risk identification.** Name the top 3 likely failure modes: missing auth, secrets in client bundles, destructive commands, fix loops, wrong libraries, version drift, no git, missing validation.
+6. **Complexity calibration.** Based on Q11's answer, set the phase granularity: simple tool → 2-3 phases with 2-3 tasks each; standard app → 3-5 phases with 3-5 tasks each; complex platform → 5-8 phases with 4-6 tasks each. Fewer phases for simpler products — don't impose enterprise ceremony on a landing page.
+7. **Billing derive (from Q6).** If Q6 names any paid model (subscription, one-time, usage-based, tiered), `tech.md`'s Third-Party Integrations table MUST include a billing provider entry — Stripe by default, LemonSqueezy if the founder explicitly asked for it or the compliance picture favors tax-handled. Include the provider's exact secret key names in the integrations table and in a Never rule in `rules.md`. If Q6 says "free," "open source," or "none," `tech.md` MUST NOT include a billing provider. This derivation is not optional — downstream setup tooling reads this table to decide whether to probe a Stripe or LS account during preflight.
+
+Do NOT write code, pseudocode, UI mockups, or marketing strategy.
+
+## Step 3 — Deliverables
+
+Produce EXACTLY SIX files in this order: `product.md`, `prd.md`, `tech.md`, `rules.md`, `phases.md`, `agents.md`. Output each as a complete file. Do NOT skip any file. Every file opens with `## TL;DR` (60 words max). Every claim must trace to a specific planning conversation answer.
+
+### product.md
+
+Sections: TL;DR | Product Definition (from Q1) | Target User (Q4 — name them, give their role, describe the specific situation) | Analogue and Differentiator (Q2 — MUST name a real existing product and state what is different) | Why Now (Q3 — MUST name the specific change, not a generic trend) | What This Is NOT (Q9 — list at least 3 explicit non-goals) | Success Metric (Q5) | Revenue Model (Q6).
+
+IMPORTANT: product.md must be SPECIFIC, not generic. Every section must reference concrete details from the planning conversation.
+
+### prd.md
+
+Sections: TL;DR | P0 Must Have (launch blockers from Q7-Q8; each feature gets: what it does, observable behavior, checkbox acceptance criteria) | P1 Should Have (week 2-4) | P2 Nice to Have (explicitly deferred from Q9, with reason) | Clarifications Log (ambiguities and resolutions).
+
+Write acceptance criteria as observable behaviors a non-technical founder can verify by looking at the screen. Good: "User sees a confirmation email within 30 seconds of signing up." Bad: "POST /api/users returns 201 and triggers email job." Every P0 feature MUST have at least 2 observable acceptance criteria.
+
+### tech.md
+
+Sections: TL;DR | Stack (table: Layer, Technology, exact Version, Rationale) | Data Model (plain SQL CREATE TABLE with id, created_at, updated_at, created_by columns; RLS policy pseudocode per table) | API Endpoints (table: Method, Path, Purpose, Auth Required) | Third-Party Integrations (every external service + its secret keys) | Research Notes (why this stack, not that one).
+
+IMPORTANT: Pin exact major versions in the Stack table. "Tailwind 4.0" not "Tailwind."
+
+### rules.md
+
+Open with YAML frontmatter: `version: "1.0.0"` and `last_amended: [today's date]`. This file is the project's constitution — versioned and append-only.
+
+Three-tier structure using the Always / Ask first / Never syntax.
+
+**Always** — seed entries (add project-specific ones):
+Use TypeScript strict mode. Validate input server-side. Git commit before multi-file changes. RLS on every Supabase table. Secrets from env vars only. Check package.json versions before imports. .env in .gitignore. Validate uploads by magic bytes. CSRF on state-changing routes.
+
+These three document-currency entries are MANDATORY in every project — do not omit them:
+- After completing a task, check off the task in the active feature doc (`docs/features/[slug].md`) and note any decisions made inline.
+- At the end of every session, add a Session Notes entry to the active feature doc — what was done, what's next, any blockers or decisions.
+- When a feature ships, set its status to `Complete` in its feature doc and remove its `@` import from `docs/ACTIVE.md`.
+
+**Ask first** — seed entries:
+Before adding unlisted dependencies. Before migrations or schema changes. Before modifying functions outside current task. Before deleting files. Before major version upgrades. Before changing RLS on user/payment tables. Before new auth flows. Before production commands. Before exec/eval/dynamic SQL.
+
+**Never** — wrap this entire section in `<never>` XML tags. Every entry MUST include a "because" clause. Seed entries:
+NEVER put secret keys in client bundles — because DevTools exposes them. NEVER deploy tables without RLS — because anon key is public. NEVER enforce auth only client-side — because attackers bypass it. NEVER run DROP/TRUNCATE/destroy/rm -rf/--force without confirmation — because agents have destroyed production databases. NEVER commit .env or key files — because git history is permanent. NEVER pass user input to exec/eval/raw SQL — because RCE. NEVER use `any` in TypeScript — because it disables the type system. NEVER hardcode credentials — because scanners harvest them. NEVER modify files outside current task scope — because fix loops. NEVER trust Content-Type headers for uploads — because attackers spoof them.
+
+Add project-specific entries from Q13 compliance requirements.
+
+After the "How to Maintain This File" section, add an **Amendment Log**. Each entry is one line: `[version] — [date] — [what changed and why]`. First entry: `1.0.0 — [date] — Initial constitution generated from planning conversation`. Bump patch for new rules, minor for restructuring, major for framework changes.
+
+### phases.md
+
+Sections: TL;DR | Milestones (phases grouped by milestone) | Phase 0 (MANDATORY) | Phase 1+.
+
+**Milestone structure:** Group phases into milestones. A milestone is a shippable product increment with a name, a one-sentence goal, and a success condition (what the founder can see or measure when it's complete). Derive milestone names from natural delivery stages (e.g., "Milestone 1 — MVP", "Milestone 2 — Growth"). Each milestone contains 1-4 phases. Phase 0 always belongs to Milestone 1. Add a Milestone Summary table at the top of phases.md listing each milestone, its phases, and its success condition.
+
+Calibrate phase count and task granularity based on the Q11 complexity answer (see research phase step 6). Simple tools get fewer, broader phases; complex platforms get more, granular ones.
+
+Every phase needs: Goal (one sentence), Tasks (checkboxes with file path annotations and a `<verify>` line per task describing how to confirm it worked), Success Criteria (observable behaviors a founder checks in the browser).
+
+**Boundary Map (Phase 1+ only):** Every phase after Phase 0 must include a Boundary Map table with two columns: **Produces** (functions, types, API endpoints, database tables, or components this phase creates) and **Consumes** (artifacts from prior phases this phase depends on — reference the specific phase and artifact). This prevents Phase 2 from reimplementing what Phase 1 already built.
+
+**HALT Conditions:** Every phase must end with 3-5 HALT conditions — situations where the AI must stop building and ask the human before proceeding. Minimum HALT triggers to always include: (1) 3 consecutive task failures in the same phase, (2) a dependency from a prior phase is missing or broken, (3) requirements are ambiguous or contradictory. Add 1-2 project-specific HALT triggers per phase.
+
+Phase 0 success criteria must include: app runs locally, user can sign up/log in/log out, all tables have RLS, .env not in git, git has 2+ commits.
+
+### agents.md
+
+YAML frontmatter: `description` (read-order for all six files) and `tags: [steering, boundaries, specification]`.
+
+Eight canonical sections, 2-4 bullet points each. Do NOT restate version numbers, directory layouts, or rules that already appear in tech.md, rules.md, or phases.md — reference those files instead.
+
+1. **Commands** — read phases.md before building; read product.md before answering product questions; don't invent features not in prd.md.
+2. **Testing** — run each task's `<verify>` check; fix before proceeding.
+3. **Structure** — "see phases.md for file paths" (do NOT list the directory tree here).
+4. **Style** — "see tech.md for versions and conventions" (do NOT repeat version numbers here).
+5. **Git** — commit per phase; format "phase [N]: [what]"; never commit secrets.
+6. **Boundaries** — "see rules.md for the full Always/Ask/Never list" (do NOT duplicate ANY rules here); if user instruction conflicts with a Never rule, follow the rule and explain why.
+7. **Session Management** — CLAUDE.md in the project root auto-loads the spec files at the start of every session; no manual pasting needed. If working on an active feature, the feature doc in `docs/features/` is also auto-loaded via `docs/ACTIVE.md`. If the session gets confused or starts hallucinating, start a new chat — fresh context is faster than arguing with a confused model.
+8. **Session Start Protocol** — At the start of every session, before writing any code: (a) if ACTIVE.md has active features, read the last Session Notes entry from each feature doc, present a recap, and ask the user to confirm or correct before proceeding; (b) if no active features, read phases.md for the next unchecked task, name it, and ask for confirmation. Do not begin any work until the user has responded.
+
+## Step 4 — Verification
+
+Before presenting the six files, verify ALL of the following. Fix any failure before outputting.
+
+1. Exactly 6 files produced IN THIS ORDER: product.md, prd.md, tech.md, rules.md, phases.md, agents.md.
+2. Every file opens with ## TL;DR (60 words max).
+3. Every P0 feature in prd.md has a task in phases.md. No phase references a feature not in prd.md.
+4. Every technology in tech.md has an exact major version.
+5. Every secret key in tech.md appears in a Never rule in rules.md.
+6. Every table in tech.md has RLS policy pseudocode.
+7. phases.md starts with Phase 0 (git, scaffold, env, database, auth, RLS). Every task has a `<verify>` line.
+8. Compliance from Q13 is reflected in rules.md.
+9. product.md names the Q2 analogue BY NAME, the Q3 why-now as a SPECIFIC change, and lists 3+ non-goals from Q9.
+10. agents.md Boundaries section references rules.md without duplicating rules. Never section in rules.md is inside `<never>` XML tags.
+11. No implementation code in any file. SQL schema in tech.md is the only exception.
+12. Every phase in phases.md (after Phase 0) has a Boundary Map table with Produces and Consumes columns.
+13. Every phase in phases.md has 3-5 HALT conditions.
+14. rules.md opens with version frontmatter (`version`, `last_amended`) and ends with an Amendment Log.
+15. agents.md includes a Session Management section (section 7).
+16. CLAUDE.md exists in the project root and `@`-imports all six files from `/docs` plus `@docs/ACTIVE.md`.
+17. `docs/ACTIVE.md` exists (empty, with header comment only).
+18. phases.md includes a Milestone Summary table and phases are grouped under named milestones.
+19. CLAUDE.md contains a Session Start Protocol section with the active-feature and no-active-feature branches, and the explicit instruction not to write code until the user confirms.
+
+## Step 5 — Project Folder Setup
+
+After all six files are verified, create the project folder structure:
+
+- `/docs` — move all six spec files here
+- `/builds` — for build output (empty at start)
+- `/ideas` — for out-of-scope items logged by scope-guard (create `FUTURE-IDEAS.md` with header only)
+
+## Step 6 — CLAUDE.md
+
+Create a `CLAUDE.md` file in the project root (not inside `/docs`). This file is how Claude Code automatically loads the spec context at the start of every future session — without it, the rules, stack, and product context are invisible to Claude unless the user manually pastes the files each time.
+
+The file must contain exactly this, with `[Project Name]` replaced by the product name from product.md:
+
+```markdown
+# [Project Name]
+
+@docs/product.md
+@docs/prd.md
+@docs/tech.md
+@docs/rules.md
+@docs/phases.md
+@docs/agents.md
+@docs/ACTIVE.md
+
+## Session Start Protocol
+
+**Run `/cofoundr:resume` as the first command of every session.**
+
+This command reads active feature docs and phases.md to surface exactly where things stand, then waits for your confirmation before any code is written. It is the handoff gate between sessions — do not skip it.
+
+If you choose not to run it explicitly, the fallback protocol is:
+1. Check `docs/ACTIVE.md` for active feature imports.
+2. **If active features exist:** read the most recent Session Notes entry from each feature doc, present a recap, and ask: "Does this still reflect where things stand?" Wait for confirmation before proceeding.
+3. **If no active features:** check `docs/phases.md` for the next unchecked task. Present it and ask for confirmation.
+
+Do not write any code, make any edits, or run any commands until the user has confirmed.
+```
+
+The spec file imports carry the base context. The Session Start Protocol is the gate — it turns every new session into an explicit handoff confirmation before any work begins. `@docs/ACTIVE.md` is the hook for feature-level living documents — it starts empty and gains entries as features are added via `/cofoundr:new-feature`.
+
+Also create `docs/ACTIVE.md` with this content:
+
+```markdown
+# Active Features
+<!-- Features currently in progress. Remove a line when a feature ships. -->
+```
+
+This file starts empty. Every `/cofoundr:new-feature` call appends an `@` import line here.
+
+Confirm with the founder: "Your spec is ready. All six files are in /docs and CLAUDE.md is set up so every future session loads them automatically. Would you like to start building Phase 0, or review the files first?"
+
+## Step 7 — Plain-English Companion (optional, recommended)
+
+Offer: *"Want me to also generate a plain-English version of the plan? It's a single file (`docs/plan-for-humans.md`) that explains what we're building, in what order, and what rules the AI has to follow — no jargon, no acronyms. Good for sharing with a co-founder or advisor, or for re-reading at 11pm when the spec feels dense. Say 'yes' and I'll run `/cofoundr:translate` now, or skip and run it yourself later."*
+
+If the founder says yes, run `/cofoundr:translate`. If they decline, move on.
+
+## Step 8 — Recommended Skills
+
+After confirming the spec, suggest skills to install based on the stack in tech.md. Present these as a single message:
+
+---
+
+**Install your production skill set**
+
+These 10 skills give Claude deep, up-to-date knowledge of the libraries in your stack — sourced from official Supabase, Stripe, Vercel, and Anthropic repos. Install once and they apply to every session automatically.
+
+Run these in your terminal:
+
+```bash
+# Database, auth, RLS, storage
+npx skills add supabase/agent-skills
+
+# Payments — checkout, subscriptions, webhooks
+npx skills add stripe/ai
+
+# Next.js 15 and React
+npx skills add vercel-labs/next-skills
+npx skills add vercel-labs/agent-skills
+
+# UI/UX quality
+npx skills add nextlevelbuilder/ui-ux-pro-max-skill
+
+# Webhooks — Stripe, Clerk, GitHub, and 20+ providers
+npx skills add hookdeck/webhook-skills
+
+# Browser testing — Playwright verifies your app actually works
+npx skills add anthropics/skills
+```
+
+Then add error monitoring — this one installs as a plugin, not a skill. Run it inside Claude Code:
+```
+/install-plugin getsentry/sentry-for-ai
+```
+
+**Or let Claude handle it:** run `/cofoundr:setup-skills` and it will check what's already installed and run the missing installs automatically.
+
+---
+
+Do not block on this step. Skills are optional enhancements — if the founder skips it, proceed.

package/content/commands/next.md

@@ -0,0 +1,129 @@
+---
+description: >
+  The planning driver. Reads the project's filesystem, determines what
+  planning artifact is missing or next, and dispatches to the right
+  subagent. Accepts natural-language targeting: brand, phase [N],
+  research [topic]. State lives on disk — run as many times as you like;
+  it only does work that needs doing.
+---
+
+# /cofoundr:next — Planning Driver
+
+You are the planning-phase driver for CoFoundr. Your job is to read the filesystem, decide what needs to happen next, and dispatch. State is derived from disk every run. There is no state file.
+
+## Argument parsing
+
+The user may invoke this command with or without arguments:
+
+- `/cofoundr:next` — auto-detect. Do the next unblocked thing.
+- `/cofoundr:next brand` — regenerate or fill `docs/brand.md`.
+- `/cofoundr:next phase [N]` — spec the named phase, even if it would not be auto-selected.
+- `/cofoundr:next research [topic]` — produce a research doc for a named topic.
+- `/cofoundr:next map-phases` — rebuild the phase outline.
+
+Strip whitespace, lowercase, match the first token to the list above. If a phase number is given, capture it. If a topic is given, capture it. If the argument does not match a known form, echo back the possibilities and wait.
+
+## Step 1 — Detect Launch Kit posture
+
+Before any planning decision, spawn the `launch-kit-detect` subagent via the Task tool. Pass only the project root (the current working directory).
+
+Store the verdict. Use it for every subsequent routing decision.
+
+If the verdict is `undecided`, ask the user once:
+
+> Is this project built on the CoFoundr Launch Kit (Next.js 16 + Supabase + Turborepo), or a different stack? Say "launch kit", name the stack, or say "still deciding" and I'll help pick.
+
+Wait for the answer. If "launch kit", treat as `launch-kit` downstream. If they name a stack, treat as `other-stack`. If "still deciding", suspend spec work and run the stack-decision branch of `/cofoundr:plan` instead.
+
+## Step 2 — Read filesystem state
+
+In parallel, check for the existence of:
+
+```
+docs/product.md
+docs/prd.md
+docs/tech.md
+docs/rules.md
+docs/phases.md
+docs/agents.md
+docs/brand.md
+docs/phases/
+CLAUDE.md
+docs/ACTIVE.md
+ideas/FUTURE-IDEAS.md
+```
+
+For `docs/phases/`, if it exists, list its children. Each child directory named `phase-N-*` is a spec'd phase. Missing phases are the ones in `phases.md` that do not have a corresponding directory.
+
+## Step 3 — Route based on user argument
+
+### 3a — No argument (auto-detect)
+
+Pick the first unblocked action from this precedence list:
+
+1. **No `docs/product.md`** → say: "You haven't created your project brief yet. Run `/cofoundr:new-project` for the full 15-question run, or `/cofoundr:quick-brief` for the 4-question instant brief." Stop.
+2. **`docs/product.md` exists but not all six top-level docs** → say: "Your top-level spec is incomplete. Run `/cofoundr:new-project` to finish generating it." Stop.
+3. **All six top-level docs exist but `docs/brand.md` is missing** → dispatch to the `brand-intake` subagent (see Step 4 for the brief). When the subagent completes, do not auto-advance; report the gap summary and ask the user whether to continue to phase specs.
+4. **All six top-level docs plus brand.md exist, but `phases.md` has phases without a `docs/phases/<slug>/` directory** → pick the earliest such phase (lowest N), spawn `spec-phase` for it.
+5. **Every phase in `phases.md` has a pack but `docs/data-model.md` is missing** → dispatch to the `consolidate` subagent. It produces the roadmap-level artifacts (data-model.md, api-contracts.md, integrations.json, fixtures.md, sequence-diagrams.md, migration-dependencies.md) plus appends state-transition blocks to relevant decisions.md files. These close the "tactical re-interrogation during build" gap the per-phase packs leave open.
+6. **Every phase has a pack AND `docs/data-model.md` exists** → say: "Planning is complete. All phases have spec packs, and the consolidation artifacts are in place. Run `/cofoundr:resume` to begin the build."
+
+### 3b — Argument is `brand`
+
+Dispatch to `brand-intake`. Brief it with the project root and the Launch Kit verdict from Step 1. If `docs/brand.md` already exists, pass `mode: amend`; otherwise `mode: create`. The subagent asks the user 5-6 questions, writes `docs/brand.md`, and updates `CLAUDE.md` to @-import the file.
+
+### 3b.5 — Argument is `consolidate`
+
+Dispatch to `consolidate`. Brief it with the project root. No user interaction required; the subagent reads every phase pack and every top-level doc, then produces the roadmap-level consolidation artifacts at `docs/`. Abort if any phase in `phases.md` lacks a spec pack at `docs/phases/<slug>/`.
+
+### 3c — Argument is `phase [N]`
+
+Find the phase in `phases.md` matching the number. Confirm its pack does not already exist at `docs/phases/<slug>/`. If it does, ask:
+
+> Phase [N] already has a spec pack at `docs/phases/<slug>/`. Regenerate it? (This overwrites current drafts. Decisions.md is preserved.)
+
+If the user confirms, delete the existing pack except `decisions.md`, then spawn `spec-phase`. Otherwise stop.
+
+If the pack does not exist, spawn `spec-phase` directly.
+
+### 3d — Argument is `research [topic]`
+
+Dispatch to the `research` subagent with the named topic. If the subagent does not exist yet, say so and stop.
+
+### 3e — Argument is `map-phases`
+
+Dispatch to the `map-phases` subagent. If the subagent does not exist yet, say so and stop.
+
+## Step 4 — Brief the subagent
+
+When dispatching to any subagent, brief it with:
+
+- Project root (absolute path).
+- Launch Kit verdict (from Step 1).
+- Whatever the subagent's `description` says it expects. For `spec-phase`, that is `phase_identifier` and `brand_present` (boolean from Step 2).
+
+Do not paste file contents into the brief — subagents read their own inputs.
+
+## Step 5 — Receive the gap summary and present to user
+
+The subagent returns a gap summary. Present it to the user verbatim, then add one line of guidance:
+
+- If gaps are resolvable by running another `/cofoundr:next [target]` command, list those commands.
+- If gaps are resolvable only by answering questions, offer to ask them now.
+- If there are no gaps, say the phase pack is complete and suggest `/cofoundr:review` to audit the full spec before building.
+
+## Step 6 — Offer continuation
+
+After presenting the gap summary, ask:
+
+> Want me to continue? Say "next" to move to the next unblocked action, or tell me what to focus on.
+
+If the user says "next", loop back to Step 1. If they target something specific, treat their answer as the next argument.
+
+## What you must not do
+
+- Do not write a state file. The filesystem is the state.
+- Do not skip `launch-kit-detect`. Every run starts with detection.
+- Do not interrogate the user yourself for planning content. That is the subagents' job when a subagent needs it, or `/cofoundr:plan`'s job for the top-level run.
+- Do not modify files outside the subagent's charter. You dispatch and summarise.
+- Do not auto-continue through multiple phases in one run unless the user explicitly says "spec every remaining phase". One phase per `/cofoundr:next` run is the default.

package/content/commands/onboard.md

@@ -0,0 +1,176 @@
+---
+description: >
+  Map an existing codebase. Reads the file tree, package manifests, framework
+  conventions, and existing docs. Produces .cofoundr/memory/codebase.md (the
+  architecture map), drafts a back-filled spec where the codebase already
+  answers the question, and surfaces every gap that still needs human input.
+---
+
+# /cofoundr:onboard — Brownfield Codebase Mapping
+
+You are running the first session on an existing codebase. The codebase has shipped or has been worked on; what it lacks is a CoFoundr-shaped specification an AI agent can rely on. Your job is to read what's there, write down what's true, and ask the human only about things the code cannot tell you.
+
+This is the slow command. It can take 20-40 minutes of reading. Do not rush. Do not invent. If something is not in the code or in existing docs, mark it as a gap and move on.
+
+## Stance
+
+- **Code is the truth, docs are an assertion.** If `tech.md` says React 18 but `package.json` says `"react": "^17.0.2"`, the code is right. Note the drift.
+- **No fabrication.** If you cannot find evidence in the code or in a real document, do not write it. Use a `<!-- GAP: ... -->` marker.
+- **Light touch.** Do not modify any source file. The only files you write are inside `.cofoundr/`, plus `AGENTS.md` at the root.
+
+## Step 0 — Pre-flight
+
+Refuse to run if any of the following:
+
+- The working tree is dirty (`git status` shows uncommitted changes). Ask the founder to commit or stash first.
+- The repo has no commits yet. Suggest `/cofoundr:new-project` instead.
+- `.cofoundr/memory/codebase.md` already exists and the founder did not pass `--refresh`. Ask whether to refresh or stop.
+
+## Step 1 — Inventory pass
+
+Run, in parallel, all of:
+
+1. **Tree shape.** `find` (or Glob) for top-level files and the first 3 levels of folders. Note: monorepo layout (workspaces, packages/, apps/), single-app layout, multi-language layout.
+2. **Manifests.** Read every `package.json`, `pnpm-workspace.yaml`, `pyproject.toml`, `Cargo.toml`, `go.mod`, `composer.json`, `Gemfile`, `requirements.txt`, `*.csproj` you find. Capture: language, version, dependencies (top-20 by relevance), scripts.
+3. **Framework signals.** Look for `next.config.*`, `nuxt.config.*`, `vite.config.*`, `astro.config.*`, `remix.config.*`, `angular.json`, `Cargo.toml [package]`, `manage.py`, `Gemfile` Rails sigil, `Phoenix` sigil, etc. Note framework + version.
+4. **Database signals.** `prisma/schema.prisma`, `drizzle.config.*`, `migrations/`, `supabase/migrations/`, `db/schema.rb`, Alembic. Capture ORM, dialect, migration path.
+5. **Test setup.** `vitest.config.*`, `jest.config.*`, `playwright.config.*`, `pytest.ini`, `cypress.config.*`. Note framework + scope (unit / integration / e2e).
+6. **CI.** `.github/workflows/`, `.gitlab-ci.yml`, `.circleci/`, `vercel.json`, `netlify.toml`. Capture deploy target.
+7. **Existing docs.** `README.md`, `docs/`, `*.md` at the root, `ARCHITECTURE.md`, `CHANGELOG.md`, `CONTRIBUTING.md`, `AGENTS.md`, `CLAUDE.md`.
+8. **Git posture.** `git log --oneline -50`, `git branch -a`, `git tag --list | tail -20`. Note maturity — pre-launch, shipped, in-progress.
+9. **Env surface.** `.env.example`, `.env.template`, redacted scan of any `.env*` files for variable names (do **not** print values, ever).
+10. **Existing AI surfaces.** `.claude/`, `.cursor/rules/`, `.windsurf/rules/`, `.windsurfrules`, `.clinerules/`, `GEMINI.md`, `.github/copilot-instructions.md`. Note which tools are already in use.
+
+## Step 2 — Pattern pass
+
+Now go deeper. Pick the 5-10 most representative files and read them.
+
+- **Routes / endpoints.** Find the routing surface. For Next.js it's `app/` or `pages/`. For Express, the router file. For Rails, `config/routes.rb`. List every public route.
+- **Auth pattern.** How does the codebase identify users? Find the middleware, the session handler, the JWT verifier. Note where authorization decisions live.
+- **Data model.** From the migrations or schema, list every table or collection. For each: name, primary purpose (one sentence), whether it has RLS or row-level authorization, the foreign keys it has.
+- **External integrations.** Search for `process.env`, `import.meta.env`, `os.environ`, secret-loader calls. List every third-party service the code talks to.
+- **Job system.** Background jobs, cron, queues, webhooks. Note what runs out-of-band.
+- **Frontend surfaces.** Top-level routes, design system folder if present, component library used.
+- **Failure surfaces.** Logging, monitoring, error boundaries, retries.
+
+## Step 3 — Write the codebase map
+
+Write `.cofoundr/memory/codebase.md`. Use this skeleton. Fill what you found. `<!-- GAP -->` what you didn't.
+
+```md
+# Codebase Map — <project name from package.json or repo>
+
+## TL;DR
+<60 words: language, framework, what kind of app, deployed where, who currently uses it>
+
+## Layout
+<tree of the top 3 levels, monorepo or single>
+
+## Stack
+| Layer | Tech | Version | Source |
+|-------|------|---------|--------|
+| Language | <e.g. TypeScript> | <e.g. 5.4> | tsconfig.json / package.json |
+| Framework | ... | ... | ... |
+| Database | ... | ... | ... |
+| ORM | ... | ... | ... |
+| Auth | ... | ... | ... |
+| Testing | ... | ... | ... |
+| CI/Deploy | ... | ... | ... |
+
+## Routes / Surfaces
+<table: Method | Path | File | Auth required>
+
+## Data Model
+<table: Table | Purpose | Has RLS/authorization | Foreign keys>
+
+## External Integrations
+<table: Service | Used for | Env vars referenced>
+
+## Background Work
+<list: cron, jobs, webhooks, scheduled tasks>
+
+## Existing Docs
+<list every doc found, with one-sentence summary>
+
+## Existing AI surfaces
+<list: which tools are already configured>
+
+## Gaps and Open Questions
+- <!-- GAP: <one per missing thing> -->
+```
+
+## Step 4 — Backfill the constitution
+
+If `.cofoundr/constitution.md` does not exist:
+
+- Draft one from observed patterns. Examples of what observation buys you:
+  - If RLS is used everywhere, add an Always rule.
+  - If `any` appears in TypeScript, do **not** assume the project tolerates it — ask.
+  - If `.env.example` is comprehensive, add a Never-commit-secrets rule.
+  - If the repo has destructive scripts, add an Ask-first rule before running them.
+- Mark every clause as `[draft — confirm]` so the founder reviews before it becomes binding.
+- Run the founder through the `/cofoundr:constitution` confirmation flow.
+
+## Step 5 — Backfill the spec (best effort)
+
+If `docs/product.md` and friends do not exist, draft a back-filled set in `.cofoundr/specs/_backfilled/`:
+
+- `product.md` — derive the product definition from `README.md` + repo description. If both are thin, leave a GAP and ask the founder Q1, Q2, Q3, Q9 from `/cofoundr:plan`.
+- `tech.md` — derive entirely from observation. This one should have very few gaps.
+- `prd.md` — list the **observable** features (what the deployed app does). Do not invent P1/P2 — ask the founder which features were last shipped and which are still in flight.
+- `phases.md` — produce a single "Already shipped" milestone listing what's there, and a "Next" milestone left empty for the founder to fill via `/cofoundr:next`.
+
+Stamp the top of every back-filled file with:
+
+```
+<!-- This file was back-filled by /cofoundr:onboard from the existing codebase.
+     Verify before treating as authoritative. Run /cofoundr:audit for drift. -->
+```
+
+## Step 6 — Update AGENTS.md
+
+If `AGENTS.md` does not exist at the project root, create it from `scaffold/AGENTS.md.tmpl`. Append (or fill) a **Codebase** section pointing to `.cofoundr/memory/codebase.md`.
+
+If `AGENTS.md` exists, do not overwrite it. Append a clearly-marked CoFoundr block:
+
+```
+<!-- cofoundr:start -->
+## Codebase Map
+The current architecture map lives at `.cofoundr/memory/codebase.md`.
+Re-run `/cofoundr:onboard --refresh` after any architectural change.
+<!-- cofoundr:end -->
+```
+
+## Step 7 — Report
+
+Hand back to the founder:
+
+```
+Onboard complete.
+
+Wrote:
+  - .cofoundr/memory/codebase.md
+  - .cofoundr/constitution.md (draft, needs confirmation)
+  - .cofoundr/specs/_backfilled/{product.md, tech.md, prd.md, phases.md}
+  - AGENTS.md (created or appended)
+
+Stack detected: <one line>
+Routes: <count>     Tables: <count>     Integrations: <count>
+
+Gaps that need you:
+  - <gap 1>
+  - <gap 2>
+  ...
+
+Recommended next:
+  1. /cofoundr:constitution — confirm and lock the rules.
+  2. /cofoundr:audit — find drift between code, docs, and the back-filled spec.
+  3. /cofoundr:document <module-or-route> — flesh out specific areas.
+```
+
+## What you must not do
+
+- Do not modify any source file. Read-only on `src/`, `app/`, `lib/`, `pages/`, etc.
+- Do not invent stack choices, framework versions, or features. If the code does not say it, do not write it.
+- Do not print or transmit the contents of `.env*` files. Variable names only.
+- Do not delete or replace existing `AGENTS.md`, `CLAUDE.md`, `README.md`. Append within fenced markers only.