@cofoundr/init 1.5.0

package/content/templates/rules.md

@@ -0,0 +1,99 @@
+---
+version: "1.0.0"
+last_amended: YYYY-MM-DD
+---
+
+# AI Rules
+
+<!-- HOW-TO: This file is the single most important file for preventing the AI from breaking your app. Every rule here exists because a real founder lost real time to the mistake it prevents. Paste this into your AI assistant's context on every session. The three sections — Always, Ask First, Never — form a behavioral contract. "Always" is autopilot. "Ask First" is a speed bump. "Never" is a hard wall. -->
+
+## TL;DR
+
+<!-- HOW-TO: ≤60 words. State the purpose of this file plainly. -->
+
+*These rules govern every action the AI assistant takes in this project. "Always" rules are non-negotiable. "Ask First" rules require explicit human approval before proceeding. "Never" rules are hard stops — violating one can break the app, leak secrets, or destroy data.*
+
+## ✅ Always
+
+<!-- HOW-TO: These 10 rules are non-negotiable. The AI must follow them on every prompt, every session, no exceptions. They're ordered by how early in a session they matter — setup rules first, then code-writing rules. Add your own project-specific rules at the end and number them 11, 12, etc. -->
+
+1. Initialize git and commit before the first AI prompt.
+2. Commit working state before any multi-file prompt.
+3. Read `tech.md` and `package.json` before writing import statements.
+4. Use server routes or Edge Functions for any call needing a secret key.
+5. Add `.env*` and `*.local` to `.gitignore` before the first commit.
+6. Add an RLS policy to every Supabase table on creation.
+7. Validate file uploads by magic bytes, not `Content-Type` header.
+8. Add CSRF middleware to every state-changing route.
+9. Pin major versions of key frameworks in this file: *Next.js 15, TypeScript 5, Supabase latest, Inngest 3*.
+10. Confirm rate-limit tier of any third-party API before integrating.
+
+11. After completing a task, update the feature doc in `docs/features/` — check off the task and note any decisions made.
+12. At the end of every session, add a Session Notes entry to the active feature doc — what was done, what's next, any blockers.
+13. When a feature ships, set its status to `Complete` in its feature doc and remove its `@` import from `docs/ACTIVE.md`.
+
+<!-- HOW-TO: Add further project-specific "Always" rules below this line. Number them starting at 14. Example: "14. Always use the date-fns library for date formatting — no raw Date methods." -->
+
+## ⚠️ Ask First
+
+<!-- HOW-TO: These 10 items require the AI to stop and ask you before proceeding. "Ask First" is a speed bump, not a wall — the answer might be "yes, go ahead," but the AI must ask. This prevents silent drift where the AI makes 5 reasonable-sounding decisions that compound into a mess. The AI should phrase the question clearly, explain what it wants to do and why, and wait for your answer before acting. -->
+
+1. Before adding any dependency not listed in `tech.md`.
+2. Before any database migration or schema change.
+3. Before modifying a function not named in the current task.
+4. Before deleting any file.
+5. Before upgrading a major package version.
+6. Before writing any new auth flow.
+7. Before introducing `exec`, `eval`, or dynamic SQL.
+8. Before changing RLS policies on tables containing PII or payment data.
+9. Before touching files with `prod`, `production`, or `live` in the path.
+10. Before adding a new SDK that requires a secret key.
+
+<!-- HOW-TO: Add project-specific "Ask First" items below this line. Number them starting at 11. These should be things that are sometimes fine but need human judgment — for example: "11. Before adding a new API endpoint not listed in tech.md." -->
+
+<never>
+## 🚫 Never
+
+<!-- HOW-TO: These 10 rules are hard stops. Each one includes a reason after the em-dash because the AI needs to understand WHY, not just WHAT. Rules without reasons get ignored when the AI "reasons" its way around them. The reason is load-bearing — without it, the AI will rationalize exceptions. -->
+
+1. 🚫 Never reference `sk_live_*`, `SUPABASE_SERVICE_ROLE_KEY`, or any secret outside `/api`, `/server`, or an Edge Function — the type system can't catch a leaked key; your Stripe bill can.
+2. 🚫 Never run `DROP`, `TRUNCATE`, `terraform destroy`, `--force`, or `rm -rf` without explicit human confirmation — one command deletes what took weeks to build.
+3. 🚫 Never store secrets in client-side code, localStorage, or cookies — browser storage is readable by any script on the page.
+4. 🚫 Never disable RLS policies, even temporarily — "I'll re-enable it later" is how every data leak starts.
+5. 🚫 Never commit `.env` files, API keys, or credentials to git — once pushed, secrets live in git history forever even after deletion.
+6. 🚫 Never bypass auth checks with hardcoded user IDs or admin tokens — every bypassed check becomes a production backdoor.
+7. 🚫 Never use `any` as a type in TypeScript — it defeats the purpose of type safety and hides bugs the compiler would otherwise catch.
+8. 🚫 Never auto-approve or auto-merge pull requests without human review — AI-generated code needs human eyes on every merge.
+9. 🚫 Never modify database schemas in production without a migration file — untracked schema changes make rollbacks impossible.
+10. 🚫 Never install packages from unverified sources or with known vulnerabilities — check npm audit output before adding any dependency.
+
+<!-- HOW-TO: Add project-specific "Never" rules below this line. Number them starting at 11. Every rule MUST include a reason after the em-dash. A rule without a reason will be ignored by the AI when it conflicts with what the AI thinks is a good idea. -->
+</never>
+
+---
+
+## How to Maintain This File
+
+<!-- HOW-TO: This section is for the founder, not the AI. It explains how to keep rules.md useful over time. -->
+
+**Adding rules:** When your AI assistant makes a mistake you don't want repeated, add a rule. Put it in the right section:
+- Did the AI do something that should always happen? Add to **Always**.
+- Did the AI make a judgment call it shouldn't have? Add to **Ask First**.
+- Did the AI do something that should never happen again? Add to **Never** with a reason.
+
+**Rule format for Never:** Every Never rule needs a reason after the em-dash. Without the reason, the AI will eventually "reason" its way around the rule. The reason should describe the real-world consequence, not just restate the rule.
+
+**Good:** *"Never disable TypeScript strict mode — non-strict mode hides null reference bugs that crash in production."*
+**Bad:** *"Never disable TypeScript strict mode — because it should stay enabled."*
+
+**Updating rules:** If a rule no longer applies (e.g., you changed frameworks), delete it rather than commenting it out. Commented-out rules confuse AI assistants that read the full file.
+
+**Pinned versions:** Update line 9 in the Always section whenever you upgrade a major framework version. This line is the AI's source of truth for what versions to use.
+
+## Amendment Log
+
+<!-- HOW-TO: Every time you add, remove, or change a rule, add a line here. This creates an audit trail so you (and the AI) know what changed and when. Bump the patch version (1.0.0 → 1.0.1) for new rules, minor version (1.0.0 → 1.1.0) for restructuring sections, major version (1.0.0 → 2.0.0) for framework changes. Update the `version` and `last_amended` fields in the frontmatter above to match. -->
+
+| Version | Date | Change |
+|---------|------|--------|
+| 1.0.0 | *YYYY-MM-DD* | *Initial constitution generated from planning conversation* |

package/content/templates/tech.md

@@ -0,0 +1,129 @@
+# Technical Specification
+
+<!-- HOW-TO: This file is your AI assistant's ground truth for every technical decision. If it's not here, the AI will guess — and guesses cause rework. Pin versions, name services, and specify schemas up front. -->
+
+## TL;DR
+
+<!-- HOW-TO: ≤60 words. Name the stack, the hosting, and the one architectural decision that matters most. -->
+
+*Next.js 15 App Router on Vercel, Supabase Postgres for data + auth, Inngest for scheduled morning pulls. The key architectural decision: all third-party API calls go through server routes — no client-side secrets, ever.*
+
+## Stack
+
+<!-- HOW-TO: Pin exact major versions. "Next.js 15 App Router" not "Next.js". "Postgres 16 + Supabase" not "a database". Your AI assistant will install whatever you write here — be specific or you'll get version conflicts on day one. -->
+
+| Layer | Technology | Version | Why this choice |
+|-------|-----------|---------|-----------------|
+| Framework | *Next.js App Router* | *15.x* | *Server components reduce client bundle; App Router is the stable default* |
+| Language | *TypeScript* | *5.x (strict mode)* | *Catches integration bugs at compile time; AI assistants produce better TS than JS* |
+| Database | *Postgres + Supabase* | *Postgres 16, Supabase latest* | *Managed auth + database in one service; generous free tier for MVP* |
+| Auth | *Supabase Auth* | *latest* | *Built-in OAuth flows for Slack; no separate auth service needed* |
+| Hosting | *Vercel* | *latest* | *Zero-config Next.js deploys; preview URLs for every PR* |
+| Payments | *Stripe* | *API v2024-12* | *Industry standard; strong docs; test mode for development* |
+| File Storage | *Supabase Storage* | *latest* | *Same project as database; RLS policies apply to files too* |
+| Background Jobs | *Inngest* | *3.x* | *Scheduled functions for morning pulls; retries and logging built in* |
+| Styling | *Tailwind CSS* | *4.x* | *Utility-first; consistent with AI-generated component patterns* |
+
+## Schema
+
+<!-- HOW-TO: Write plain SQL CREATE TABLE statements. Include ownership columns (created_by, updated_at) on every table. Include RLS policy stubs — every table touching user data needs a policy. Your AI assistant will copy-paste these into migrations, so make them runnable. -->
+
+```sql
+-- Users (managed by Supabase Auth, extended here)
+CREATE TABLE public.profiles (
+  id UUID PRIMARY KEY REFERENCES auth.users(id) ON DELETE CASCADE,
+  display_name TEXT NOT NULL,
+  timezone TEXT NOT NULL DEFAULT 'UTC',
+  pull_time TIME NOT NULL DEFAULT '07:00',
+  created_at TIMESTAMPTZ NOT NULL DEFAULT now(),
+  updated_at TIMESTAMPTZ NOT NULL DEFAULT now()
+);
+
+ALTER TABLE public.profiles ENABLE ROW LEVEL SECURITY;
+CREATE POLICY "Users read own profile"
+  ON public.profiles FOR SELECT
+  USING (auth.uid() = id);
+CREATE POLICY "Users update own profile"
+  ON public.profiles FOR UPDATE
+  USING (auth.uid() = id);
+
+-- Connected integrations
+CREATE TABLE public.integrations (
+  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+  user_id UUID NOT NULL REFERENCES public.profiles(id) ON DELETE CASCADE,
+  provider TEXT NOT NULL CHECK (provider IN ('slack', 'trello', 'linear')),
+  access_token TEXT NOT NULL,
+  refresh_token TEXT,
+  workspace_name TEXT,
+  connected_at TIMESTAMPTZ NOT NULL DEFAULT now(),
+  created_by UUID NOT NULL REFERENCES auth.users(id),
+  updated_at TIMESTAMPTZ NOT NULL DEFAULT now(),
+  UNIQUE(user_id, provider)
+);
+
+ALTER TABLE public.integrations ENABLE ROW LEVEL SECURITY;
+CREATE POLICY "Users manage own integrations"
+  ON public.integrations FOR ALL
+  USING (auth.uid() = user_id);
+
+-- Daily task items
+CREATE TABLE public.tasks (
+  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+  user_id UUID NOT NULL REFERENCES public.profiles(id) ON DELETE CASCADE,
+  source TEXT NOT NULL CHECK (source IN ('slack', 'trello', 'linear')),
+  external_id TEXT NOT NULL,
+  title TEXT NOT NULL,
+  body TEXT,
+  source_url TEXT,
+  priority INTEGER NOT NULL DEFAULT 0,
+  is_focus BOOLEAN NOT NULL DEFAULT false,
+  is_completed BOOLEAN NOT NULL DEFAULT false,
+  snoozed_until DATE,
+  pulled_at DATE NOT NULL DEFAULT CURRENT_DATE,
+  created_by UUID NOT NULL REFERENCES auth.users(id),
+  updated_at TIMESTAMPTZ NOT NULL DEFAULT now(),
+  UNIQUE(user_id, source, external_id, pulled_at)
+);
+
+ALTER TABLE public.tasks ENABLE ROW LEVEL SECURITY;
+CREATE POLICY "Users manage own tasks"
+  ON public.tasks FOR ALL
+  USING (auth.uid() = user_id);
+```
+
+## API Endpoints
+
+<!-- HOW-TO: List every endpoint your app exposes. Auth column should say "public", "authenticated", or "admin". This table is your AI assistant's map — if it's not listed here, it shouldn't be built. -->
+
+| Method | Path | Auth | Description |
+|--------|------|------|-------------|
+| *GET* | */api/integrations* | *authenticated* | *List user's connected integrations* |
+| *POST* | */api/integrations/[provider]/connect* | *authenticated* | *Initiate OAuth flow for a provider* |
+| *POST* | */api/integrations/[provider]/callback* | *authenticated* | *Handle OAuth callback, store tokens* |
+| *DELETE* | */api/integrations/[provider]* | *authenticated* | *Disconnect an integration* |
+| *POST* | */api/pull* | *authenticated* | *Trigger manual morning pull* |
+| *GET* | */api/tasks* | *authenticated* | *Get today's task list* |
+| *PATCH* | */api/tasks/[id]* | *authenticated* | *Update task (reorder, focus, complete, snooze)* |
+| *POST* | */api/webhooks/inngest* | *public (signed)* | *Inngest webhook receiver for scheduled pulls* |
+| *POST* | */api/stripe/webhook* | *public (signed)* | *Stripe webhook receiver for payment events* |
+
+## Third-Party Integrations
+
+<!-- HOW-TO: Any row with "Yes" in Secret Key means this call MUST go through a server route, not client code. If you see "Yes" and the code imports it in a component file, something is wrong. -->
+
+| Service | Purpose | Secret Key Required? |
+|---------|---------|---------------------|
+| *Slack API* | *Pull channel messages and mentions* | *Yes — OAuth token stored server-side* |
+| *Trello API* | *Pull cards from user's boards* | *Yes — API key + OAuth token* |
+| *Linear API* | *Pull issues assigned to user* | *Yes — API key* |
+| *Inngest* | *Schedule and run morning pull jobs* | *Yes — signing key for webhooks* |
+| *Stripe* | *Process subscription payments* | *Yes — sk_live never in client code* |
+| *Supabase* | *Database, auth, storage* | *No — uses anon key client-side, service role key server-side only* |
+
+## Research Notes
+
+<!-- HOW-TO: Use this section during the research phase to capture technical findings, API limitations, rate limits, or alternative approaches you evaluated. This prevents re-researching the same questions later. -->
+
+*- Slack conversation.history API is rate-limited to 50 requests/minute per token — need to batch pulls for users with many channels.*
+*- Linear's GraphQL API returns max 250 nodes per query — pagination needed for power users.*
+*- Inngest free tier supports up to 25,000 function runs/month — sufficient for ~800 daily users.*

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "@cofoundr/init",
+  "version": "1.5.0",
+  "description": "Universal installer for the CoFoundr starter kit. Drops a tool-agnostic spec-driven workspace into any project — Claude Code, Cursor, Windsurf, Cline, Codex, Aider, Copilot, Gemini.",
+  "keywords": [
+    "spec-driven-development",
+    "sdd",
+    "claude-code",
+    "cursor",
+    "windsurf",
+    "cline",
+    "codex",
+    "aider",
+    "copilot",
+    "gemini",
+    "agents.md",
+    "scaffold"
+  ],
+  "homepage": "https://cofoundr.ai",
+  "license": "SEE LICENSE",
+  "type": "module",
+  "bin": {
+    "cofoundr": "./bin/cofoundr.mjs"
+  },
+  "engines": {
+    "node": ">=20.0.0"
+  },
+  "files": [
+    "bin/",
+    "src/",
+    "content/",
+    "README.md"
+  ],
+  "scripts": {
+    "prepack": "node scripts/bundle-content.mjs",
+    "test": "node --test test/license.test.mjs && node test/smoke.mjs"
+  },
+  "dependencies": {}
+}

package/src/adapters/aider.mjs

@@ -0,0 +1,35 @@
+// Aider adapter.
+// Aider reads AGENTS.md natively. We additionally drop a .aider.conf.yml that
+// pre-loads the constitution and AGENTS.md as read-only context for every Aider session.
+
+import { join } from 'node:path';
+import { writeIfChanged } from '../core/fs.mjs';
+
+export const adapter = {
+  id: 'aider',
+  name: 'Aider',
+
+  async apply({ repoPath, manifest, opts }) {
+    const dest = join(repoPath, '.aider.conf.yml');
+    const body = `# CoFoundr-aware Aider config.
+# Pre-loads the project constitution, AGENTS.md, and decisions log as read-only
+# context so every Aider session knows the rules without manual /add.
+
+read:
+  - AGENTS.md
+  - .cofoundr/constitution.md
+  - .cofoundr/memory/project.md
+  - .cofoundr/memory/decisions.md
+
+# When the user says /cofoundr:<name>, Aider should /add .cofoundr/commands/<name>.md
+# and follow it step-by-step. Aider does not have native slash commands, so the user
+# can paste:
+#   /run cat .cofoundr/commands/<name>.md
+# or just /add the file and ask Aider to follow it.
+`;
+    const r = await writeIfChanged(dest, body, opts);
+    return r.wrote
+      ? { written: [r.path], skipped: [] }
+      : { written: [], skipped: [{ path: r.path, reason: r.reason }] };
+  },
+};

package/src/adapters/claude-code.mjs

@@ -0,0 +1,114 @@
+// Claude Code adapter.
+// Strategy: Claude Code's project-level slash commands live at .claude/commands/<name>.md
+// and project-level agents at .claude/agents/<name>.md. We copy each canonical command
+// and agent into those directories with a "cofoundr-" prefix, and append a CLAUDE.md
+// block that imports the .cofoundr/ workspace via @-references.
+
+import { join } from 'node:path';
+import { readSourceFile } from '../core/source.mjs';
+import { writeIfChanged, readIfExists } from '../core/fs.mjs';
+
+export const adapter = {
+  id: 'claude-code',
+  name: 'Claude Code',
+  detect(repoPath) {
+    return ['/.claude/', '/CLAUDE.md', '/.claude-plugin/'].some(() => true) && true;
+  },
+
+  async apply({ repoPath, source, manifest, opts }) {
+    const written = [];
+    const skipped = [];
+
+    for (const cmd of manifest.commands) {
+      const body = await readSourceFile(source, cmd.file);
+      const out = `${frontmatterFor(cmd)}\n${stripFrontmatter(body)}`;
+      const dest = join(repoPath, '.claude', 'commands', `cofoundr-${cmd.id}.md`);
+      bump(await writeIfChanged(dest, out, opts), written, skipped);
+    }
+
+    for (const agent of manifest.agents) {
+      const body = await readSourceFile(source, agent.file);
+      const dest = join(repoPath, '.claude', 'agents', `${agent.id}.md`);
+      bump(await writeIfChanged(dest, body, opts), written, skipped);
+    }
+
+    // CLAUDE.md context block: append-only inside fenced markers so the user's existing
+    // content is preserved across syncs.
+    const claudeMdPath = join(repoPath, 'CLAUDE.md');
+    const existing = (await readIfExists(claudeMdPath)) ?? '';
+    const updated = upsertCofoundrBlock(existing, COFOUNDR_CLAUDE_BLOCK);
+    if (updated !== existing) {
+      bump(await writeIfChanged(claudeMdPath, updated, { ...opts, force: true }), written, skipped);
+    }
+
+    return { written, skipped };
+  },
+};
+
+const COFOUNDR_BEGIN = '<!-- cofoundr:start -->';
+const COFOUNDR_END = '<!-- cofoundr:end -->';
+
+const COFOUNDR_CLAUDE_BLOCK = `${COFOUNDR_BEGIN}
+## CoFoundr Workspace
+
+This project uses **CoFoundr** — a tool-agnostic spec-driven development workspace.
+Source of truth for specs, rules, and workflow commands lives in \`.cofoundr/\`.
+
+@.cofoundr/constitution.md
+@.cofoundr/memory/project.md
+@.cofoundr/memory/decisions.md
+@AGENTS.md
+
+### Session Start Protocol
+
+Before any code: run \`/cofoundr:resume\`. It surfaces the active feature doc(s)
+and the next unchecked task, and waits for confirmation.
+
+### Workflow commands
+
+Project-level slash commands (each maps to \`.claude/commands/cofoundr-*.md\`):
+
+- **Planning:** \`/cofoundr:quick-brief\`, \`/cofoundr:new-project\`, \`/cofoundr:plan\`, \`/cofoundr:next\`, \`/cofoundr:new-feature\`
+- **Spec-driven (SDD):** \`/cofoundr:constitution\`, \`/cofoundr:specify\`, \`/cofoundr:tasks\`, \`/cofoundr:implement\`
+- **Brownfield:** \`/cofoundr:onboard\`, \`/cofoundr:document\`, \`/cofoundr:audit\`
+- **Guardrails:** \`/cofoundr:scope-guard\`, \`/cofoundr:rules-check\`, \`/cofoundr:review\`
+- **Comms / setup:** \`/cofoundr:translate\`, \`/cofoundr:setup-skills\`, \`/cofoundr:resume\`
+
+Refresh shims after a CoFoundr upgrade with \`npx @cofoundr/init sync\`.
+${COFOUNDR_END}`;
+
+function upsertCofoundrBlock(existing, newBlock) {
+  if (!existing.trim()) return `${newBlock}\n`;
+  const startIdx = existing.indexOf(COFOUNDR_BEGIN);
+  const endIdx = existing.indexOf(COFOUNDR_END);
+  if (startIdx !== -1 && endIdx !== -1 && endIdx > startIdx) {
+    const before = existing.slice(0, startIdx).trimEnd();
+    const after = existing.slice(endIdx + COFOUNDR_END.length).trimStart();
+    const sep = before ? `${before}\n\n` : '';
+    return `${sep}${newBlock}${after ? `\n\n${after}` : '\n'}`;
+  }
+  // No existing block — append at end.
+  const trimmed = existing.trimEnd();
+  return `${trimmed}\n\n${newBlock}\n`;
+}
+
+function frontmatterFor(cmd) {
+  const desc = cmd.summary.replace(/\n/g, ' ').trim();
+  return `---
+description: >
+  ${desc}
+allowed-tools: Read, Write, Edit, Glob, Grep, Bash, Task
+---`;
+}
+
+function stripFrontmatter(md) {
+  if (!md.startsWith('---')) return md;
+  const end = md.indexOf('\n---', 3);
+  if (end === -1) return md;
+  return md.slice(end + 4).replace(/^\s+/, '');
+}
+
+function bump(result, written, skipped) {
+  if (result.wrote) written.push(result.path);
+  else skipped.push({ path: result.path, reason: result.reason });
+}

package/src/adapters/cline.mjs

@@ -0,0 +1,46 @@
+// Cline / Roo Code adapter.
+// Both read .clinerules/ as a directory of markdown files. We drop a single cofoundr.md.
+
+import { join } from 'node:path';
+import { writeIfChanged } from '../core/fs.mjs';
+
+export const adapter = {
+  id: 'cline',
+  name: 'Cline / Roo Code',
+
+  async apply({ repoPath, manifest, opts }) {
+    const dest = join(repoPath, '.clinerules', 'cofoundr.md');
+    const body = render(manifest);
+    const r = await writeIfChanged(dest, body, opts);
+    return r.wrote
+      ? { written: [r.path], skipped: [] }
+      : { written: [], skipped: [{ path: r.path, reason: r.reason }] };
+  },
+};
+
+function render(manifest) {
+  const cmds = manifest.commands.map((c) => `- \`/cofoundr:${c.id}\` — ${c.summary}`).join('\n');
+  return `# CoFoundr workspace
+
+Read \`AGENTS.md\` and \`.cofoundr/constitution.md\` before any change.
+
+## Following a CoFoundr command
+
+When the user says \`/cofoundr:<name>\` or \`cofoundr <name>\`:
+
+1. Read \`.cofoundr/commands/<name>.md\`.
+2. Execute step-by-step. Do not paraphrase.
+3. The Never list in \`.cofoundr/constitution.md\` is binding.
+
+## Reading order
+
+1. \`AGENTS.md\`
+2. \`.cofoundr/constitution.md\`
+3. \`.cofoundr/memory/project.md\`
+4. \`.cofoundr/memory/decisions.md\`
+
+## Commands
+
+${cmds}
+`;
+}

package/src/adapters/codex.mjs

@@ -0,0 +1,29 @@
+// OpenAI Codex CLI adapter.
+// Codex reads AGENTS.md (which scaffold.mjs already writes). All this adapter does is
+// confirm AGENTS.md will be written and optionally drop a .codex/instructions.md
+// for project-scoped overrides.
+
+import { join } from 'node:path';
+import { writeIfChanged } from '../core/fs.mjs';
+
+export const adapter = {
+  id: 'codex',
+  name: 'OpenAI Codex CLI',
+
+  async apply({ repoPath, manifest, opts }) {
+    const dest = join(repoPath, '.codex', 'instructions.md');
+    const body = `# Codex — CoFoundr instructions
+
+The canonical instructions for this project live in \`AGENTS.md\` at the repo root.
+This file exists only as an explicit signal for the Codex CLI. Read \`AGENTS.md\` and
+\`.cofoundr/constitution.md\` before making any change.
+
+When the user says \`/cofoundr:<name>\` or \`cofoundr <name>\`, read
+\`.cofoundr/commands/<name>.md\` and follow it step-by-step.
+`;
+    const r = await writeIfChanged(dest, body, opts);
+    return r.wrote
+      ? { written: [r.path], skipped: [] }
+      : { written: [], skipped: [{ path: r.path, reason: r.reason }] };
+  },
+};

package/src/adapters/copilot.mjs

@@ -0,0 +1,54 @@
+// GitHub Copilot adapter.
+// Copilot reads .github/copilot-instructions.md as the repo-scoped instruction file.
+// Like Cursor/Windsurf, it has no slash commands — it follows the instructions file.
+
+import { join } from 'node:path';
+import { writeIfChanged } from '../core/fs.mjs';
+
+export const adapter = {
+  id: 'copilot',
+  name: 'GitHub Copilot',
+
+  async apply({ repoPath, manifest, opts }) {
+    const dest = join(repoPath, '.github', 'copilot-instructions.md');
+    const body = render(manifest);
+    const r = await writeIfChanged(dest, body, opts);
+    return r.wrote
+      ? { written: [r.path], skipped: [] }
+      : { written: [], skipped: [{ path: r.path, reason: r.reason }] };
+  },
+};
+
+function render(manifest) {
+  const cmds = manifest.commands.map((c) => `- **${c.id}** — ${c.summary}`).join('\n');
+  return `# Copilot instructions — CoFoundr workspace
+
+This project uses **CoFoundr** — a tool-agnostic spec-driven workspace at \`.cofoundr/\`.
+
+## Read first
+
+1. \`AGENTS.md\` — universal project context.
+2. \`.cofoundr/constitution.md\` — binding rules. The \`Never\` section is non-negotiable.
+3. \`.cofoundr/memory/project.md\` — project facts.
+4. \`.cofoundr/memory/decisions.md\` — append-only decisions log.
+
+## Workflow commands
+
+When a user references one of these (\`/cofoundr:<name>\` or \`cofoundr <name>\`),
+read \`.cofoundr/commands/<name>.md\` and follow it step-by-step.
+
+${cmds}
+
+## Conventions
+
+- Validate input server-side. Client-side validation is a UX hint, not a security control.
+- Pin exact major versions. No \`^\` for security-sensitive deps.
+- One commit per task: \`<phase or feature>: T<N> <imperative summary>\`.
+- Never put secrets in client bundles. Never commit \`.env\`. Never use \`any\` in TypeScript.
+- Always run \`/cofoundr:resume\` at the start of a session before writing any code.
+
+## Refresh
+
+\`npx @cofoundr/init sync\` updates this file and all per-tool shims after a CoFoundr upgrade.
+`;
+}

package/src/adapters/cursor.mjs

@@ -0,0 +1,69 @@
+// Cursor adapter.
+// Cursor reads .cursor/rules/*.mdc with frontmatter ({ description, globs, alwaysApply }).
+// We write a single rule file that points the Composer/agent to .cofoundr/.
+
+import { join } from 'node:path';
+import { writeIfChanged } from '../core/fs.mjs';
+
+export const adapter = {
+  id: 'cursor',
+  name: 'Cursor',
+
+  async apply({ repoPath, manifest, opts }) {
+    const written = [];
+    const skipped = [];
+    const dest = join(repoPath, '.cursor', 'rules', 'cofoundr.mdc');
+    const body = renderRule(manifest);
+    const r = await writeIfChanged(dest, body, opts);
+    if (r.wrote) written.push(r.path);
+    else skipped.push({ path: r.path, reason: r.reason });
+    return { written, skipped };
+  },
+};
+
+function renderRule(manifest) {
+  const cmdLines = manifest.commands
+    .map((c) => `- \`/cofoundr:${c.id}\` — ${c.summary}`)
+    .join('\n');
+  return `---
+description: CoFoundr — spec-driven workflow for this project. Source of truth in .cofoundr/.
+globs:
+  - "**/*"
+alwaysApply: true
+---
+
+# CoFoundr workspace
+
+This project uses **CoFoundr** — a tool-agnostic spec-driven workspace. The source of truth lives in \`.cofoundr/\`. The universal context file is \`AGENTS.md\` at the repo root — read it first.
+
+## How to follow CoFoundr commands
+
+When the user types one of:
+
+- \`/cofoundr:<name>\`
+- \`cofoundr <name>\`
+- \`run cofoundr <name>\`
+
+…you must:
+
+1. Read \`.cofoundr/commands/<name>.md\`.
+2. Follow it step-by-step. Do not paraphrase. Do not skip steps.
+3. Honor the rules in \`.cofoundr/constitution.md\`. The \`Never\` section is binding.
+
+## Available commands
+
+${cmdLines}
+
+## Reading order at session start
+
+1. \`AGENTS.md\` — universal context.
+2. \`.cofoundr/constitution.md\` — binding rules.
+3. \`.cofoundr/memory/project.md\` — project facts.
+4. \`.cofoundr/memory/decisions.md\` — append-only decision log.
+5. The active feature doc in \`docs/features/\` if any.
+
+## Refresh
+
+\`npx @cofoundr/init sync\` refreshes this rule and all shims after a CoFoundr upgrade.
+`;
+}

package/src/adapters/gemini.mjs

@@ -0,0 +1,41 @@
+// Gemini CLI adapter.
+// Gemini CLI reads GEMINI.md at the repo root (sibling to AGENTS.md).
+
+import { join } from 'node:path';
+import { writeIfChanged } from '../core/fs.mjs';
+
+export const adapter = {
+  id: 'gemini',
+  name: 'Gemini CLI',
+
+  async apply({ repoPath, manifest, opts }) {
+    const dest = join(repoPath, 'GEMINI.md');
+    const body = render(manifest);
+    const r = await writeIfChanged(dest, body, opts);
+    return r.wrote
+      ? { written: [r.path], skipped: [] }
+      : { written: [], skipped: [{ path: r.path, reason: r.reason }] };
+  },
+};
+
+function render(manifest) {
+  const cmds = manifest.commands.map((c) => `- \`/cofoundr:${c.id}\` — ${c.summary}`).join('\n');
+  return `# Gemini CLI — CoFoundr workspace
+
+The canonical project context is in \`AGENTS.md\` at the repo root. Read that first.
+
+This file exists for tools that prefer \`GEMINI.md\` to \`AGENTS.md\`.
+
+## Quick rules
+
+1. Read \`AGENTS.md\`, \`.cofoundr/constitution.md\`, and \`.cofoundr/memory/project.md\` before any change.
+2. The \`Never\` list in the constitution is binding.
+3. When the user says \`/cofoundr:<name>\` or \`cofoundr <name>\`, read \`.cofoundr/commands/<name>.md\` and follow it step-by-step.
+
+## Commands
+
+${cmds}
+
+Refresh with \`npx @cofoundr/init sync\`.
+`;
+}