@withmata/blueprints 0.2.0

package/.claude/commands/new-project.md

@@ -0,0 +1,230 @@
+# New Project
+
+Take a product from idea to running code. This command walks through the full lifecycle — defining the product, setting up the codebase to support it, and wiring in the capabilities it needs. You're a product partner with deep engineering expertise: the product strategy drives every technical decision.
+
+## Step 1: Read the Blueprints
+
+Load all available blueprints so you understand what's possible:
+
+```
+~/Documents/WithMata/my-blueprints/blueprints/discovery/product-discovery/BLUEPRINT.md
+~/Documents/WithMata/my-blueprints/blueprints/discovery/product-discovery/templates/*
+~/Documents/WithMata/my-blueprints/blueprints/foundation/monorepo-turbo/BLUEPRINT.md
+~/Documents/WithMata/my-blueprints/blueprints/foundation/monorepo-turbo/files/**/*
+```
+
+Also scan for available feature blueprints:
+
+```
+~/Documents/WithMata/my-blueprints/blueprints/features/*/BLUEPRINT.md
+```
+
+Only consider a feature blueprint "available" if its BLUEPRINT.md has `Status: Complete` (not a placeholder). If not found at the paths above, ask the user for the path to their blueprints repo.
+
+## Step 2: Assess Current State
+
+Before doing anything, understand where this project stands.
+
+**Check `.project-context.md`** in the target project root. This file tracks what has already been done:
+
+- **Has a `## Product Discovery` section?** Discovery is complete.
+- **Has a `## Foundation` section?** Foundation is scaffolded.
+- **Has entries under `## Installed Blueprints`?** Some features are already installed.
+
+**Explore the target directory:**
+
+- Empty directory? Fresh start — begin from Stage 1.
+- Has `docs/product/`? Discovery was done (even without a context file).
+- Has `package.json`, `turbo.json`, workspace dirs? Foundation was done.
+- Has auth files, DB packages, etc.? Features were installed.
+
+## Step 3: Determine Starting Point
+
+Based on what you found, tell the user where things stand. Lead with the product, not the tech:
+
+- **Nothing exists**: "This is a blank slate. Let's start by figuring out what you're building and who it's for — then we'll set up the codebase to support it."
+
+- **Discovery done, nothing else**: "You've already defined [product name] — [problem statement in one line]. We've got a clear picture of the product. Let's turn that into something you can ship."
+
+- **Discovery + Foundation done**: "The product is defined and the codebase is ready. Based on what [primary archetype] needs, let's wire in the right capabilities."
+
+- **Everything done**: "This project looks fully set up. Want to add more capabilities, or revisit any of the product decisions?"
+
+If the user wants to start at a specific stage, let them. If they want to redo a completed stage, confirm before proceeding (it may be destructive).
+
+---
+
+## Stage 1: Discovery
+
+> "Before we write any code, let's get clear on what we're building and why it matters."
+
+This is the most important stage. Everything downstream — the architecture, the features, the trade-offs — flows from what we define here. Don't rush it.
+
+Follow the full discovery process from the product-discovery blueprint. This is a rigorous product conversation — challenge assumptions, research the market, and push until the product thesis is sharp. You'll work through:
+
+1. **Initial Framing** — What are you building? Who is it for? Why does it need to exist?
+2. **Problem Deep Dive** — 5 Whys to get past symptoms to root cause
+3. **User Definition** — Vivid archetypes and personas via scenario mapping + JTBD
+4. **Solution Positioning** — Competitive landscape, differentiation, "why now?"
+5. **Synthesis** — Distill everything into a defensible product thesis
+
+Use the templates from the blueprint to generate:
+
+```
+docs/product/
+├── product-thesis.md        # The 2-minute read — pillars, metrics, positioning
+├── product-brief.md         # Supporting research and detail
+└── users/
+    ├── archetype-[name].md  # Vivid portraits of who you're building for
+    └── research-summary.md  # Evidence and sources
+```
+
+Create or update `.project-context.md` with the `## Product Discovery` section.
+
+### Pause Point
+
+After discovery is complete, connect what was defined to what comes next:
+
+"We've defined [product name] around [N] core pillars: [list them]. The primary user is [archetype] — [one-line description of their world]. This gives us a clear foundation to build on. Want to set up the codebase now, or let this sit and come back to it?"
+
+If stopping: "Whenever you're ready, run `/scaffold-foundation` to set up the project, or `/new-project` again to pick up where we left off."
+
+---
+
+## Stage 1.5: Project Type
+
+After discovery is complete, determine the project type:
+
+"Now let's set up the codebase. Are you building a:
+1. **Monorepo** — multiple packages, shared config, Turborepo (recommended for larger products with separate frontend/backend/packages)
+2. **Single-repo** — one application, everything in one package.json (simpler for smaller products or standalone apps)"
+
+Record the choice in `.project-context.md` under `## Foundation`:
+```yaml
+project_type: monorepo  # or single-repo
+```
+
+- If **monorepo**: proceed to Stage 2 (Foundation)
+- If **single-repo**: skip Stage 2 entirely, proceed to Stage 3 (Features). Note in context: "Foundation skipped — single-repo project."
+
+---
+
+## Stage 2: Foundation
+
+> "The product is defined. Let's build the structure to support it."
+
+> **Note:** Skip this stage for single-repo projects — proceed directly to Stage 3.
+
+Read the discovery context from `.project-context.md` to inform technical decisions:
+
+- Derive the npm scope from the product name (e.g., "Acme Dashboard" -> `@acme`)
+- Use the product pillars and archetype needs to inform any trade-offs
+- Apply technical constraints from discovery if any were noted
+
+Follow the foundation blueprint process. Only three questions — skip any already answered by project context:
+
+1. **npm scope** — defaults from product name
+2. **Project name** — human-readable, for metadata and page titles
+3. **Node.js version** — defaults to `>=22`
+
+Scaffold the monorepo skeleton: root configs, TypeScript config package, Tailwind config package, Next.js app shell, and empty workspace directories for future blueprints.
+
+After scaffolding:
+
+1. Run `pnpm install` to verify the workspace is valid
+2. Briefly verify the dev server boots: `pnpm dev`
+3. Append the `## Foundation` section to `.project-context.md`
+
+### Pause Point
+
+After foundation is complete, bridge to features by referencing the product:
+
+"The codebase is ready — [scope] monorepo with Turborepo, Biome, and a Next.js app shell. Now let's think about what [product name] needs to actually work. Want to look at what's available, or stop here for now?"
+
+If stopping: "You can add capabilities anytime. Run `/scaffold-auth` for authentication, or `/new-project` to see all available blueprints."
+
+---
+
+## Stage 3: Features
+
+> "Let's wire in what [product name] needs to deliver on its core pillars."
+
+If discovery was completed, reference the product pillars and archetype needs when presenting features. Connect each blueprint back to the product — don't just list technical capabilities.
+
+List the available feature blueprints. Read each `BLUEPRINT.md` under `blueprints/features/*/` and show only those with `Status: Complete`.
+
+**Present features in dependency order** — blueprints that others depend on should be listed first. Check each blueprint's `## Blueprint Dependencies` section. For example, db should be listed before auth (since auth requires db).
+
+For each available blueprint, show:
+- **Name** — human-readable
+- **What it enables for the product** — tie it to a pillar or user need when possible
+- **Dependencies** — note if it requires another blueprint (e.g., "requires Database")
+- **Command** — the slash command to run it individually
+
+Example:
+
+```
+Based on what [product name] needs:
+
+  1. Authentication (Better Auth + Drizzle) — /scaffold-auth
+     User accounts, login flows, route protection. Required for [relevant pillar].
+     If org plugin: team/workspace management for [archetype need].
+```
+
+Ask: "Which of these does [product name] need? We'll set them up one at a time."
+
+If no discovery context exists, fall back to a straightforward capability list without the product framing.
+
+### For Each Selected Feature
+
+1. Read the feature's BLUEPRINT.md and all its files
+2. Read `.project-context.md` to understand current state
+3. Follow the blueprint's scaffolding process (ask its configuration questions, adapt files, etc.)
+4. Append the feature's entry to `## Installed Blueprints` in .project-context.md
+
+After each feature is installed, ask: "[Feature] is wired in. Want to add another, or is [product name] ready to start building on?"
+
+---
+
+## Step 7: Final Summary
+
+Once the user is done (whether after one stage or all three), provide a summary that connects the product to the technical foundation:
+
+### What We Built
+
+- **The product** (if discovery ran) — what it is, who it's for, the core pillars it delivers on
+- **The codebase** (if foundation ran) — how the project structure supports the product
+- **The capabilities** (if features ran) — what's wired in and how it maps to product needs
+
+### Getting Started
+
+```
+pnpm dev          # Start the development server
+```
+
+### Environment Variables to Set
+
+List any env vars that need values (aggregated from all stages).
+
+### Manual Steps Remaining
+
+List anything that can't be automated (aggregated from all stages).
+
+### What's Next
+
+Suggest next steps in terms of product progress, not just technical tasks. Reference specific commands:
+
+- "The product thesis identified [pillar] as a core pillar — `/scaffold-auth` wires in the user accounts and access control to support that."
+- "Other feature blueprints coming soon: UI components, database, Tailwind theming."
+- "Start building the core product experience — the [archetype]'s primary workflow."
+
+---
+
+## Important Notes
+
+- **Resumable** — this command always checks `.project-context.md` before starting. Run it again anytime to pick up where you left off, or use the individual stage commands (`/discover`, `/scaffold-foundation`, `/scaffold-auth`).
+- **Non-destructive** — never overwrite existing files without asking. If a stage was already completed, confirm before redoing it.
+- **Product-first** — every technical decision should trace back to the product definition. When in doubt, reference the pillars, the archetype, and the problem statement.
+- **Conversational** — this is a guided conversation, not a script. Adapt to the user's pace. If they want to skip ahead, let them. If they want to dig deeper into a stage, follow their lead.
+- **Project context is the source of truth** — every stage reads it, every stage appends to it. This is how stages communicate with each other across sessions.
+- **Maintenance rules accumulate** — each stage injects its maintenance rules into the project's rules file(s). These rules tell the AI coding tool what actions to take after certain types of changes. They accumulate as more blueprints are installed — the monorepo rules from foundation, plus auth rules, plus database rules, etc. The tool reads these at the start of every session.

package/.claude/commands/scaffold-auth.md

@@ -0,0 +1,310 @@
+# Scaffold Auth Blueprint
+
+Scaffold the `auth-better-auth` blueprint into the current project. Read the full blueprint first, then adapt it to this project's stack.
+
+## Step 1: Read the Blueprint
+
+Read the full BLUEPRINT.md and all code files from the auth blueprint:
+
+```
+blueprints/features/auth-better-auth/BLUEPRINT.md
+blueprints/features/auth-better-auth/files/**/*
+```
+
+If these files are not in the current project, look for them at `~/Documents/WithMata/my-blueprints/blueprints/features/auth-better-auth/`. If still not found, ask the user for the path to their blueprints repo.
+
+## Step 1.5: Read Project Context
+
+Check if `.project-context.md` exists in the target project root:
+
+- **If it exists**: read it to understand:
+  - Product name and scope (from Discovery)
+  - npm scope, workspace layout, server framework (from Foundation)
+  - What other blueprints are already installed (from Installed Blueprints)
+  - Use this information to pre-fill configuration questions in Step 3 and adapt file paths in Step 4
+
+- **If it does not exist**: proceed normally — explore the project manually (Step 2) and ask all configuration questions (Step 3)
+
+When project context provides clear answers, skip the corresponding questions in Step 3. For example:
+- Context says `server_framework: hono` -> do not ask about server framework
+- Context says `npm_scope: "@acme"` -> use `@acme` for package references
+- Context has `auth-better-auth` in Installed Blueprints -> warn about existing install
+
+## Step 1.7: Check Blueprint Dependencies
+
+Read the Blueprint Dependencies section from `auth-better-auth/BLUEPRINT.md`.
+
+For `features/db-drizzle-postgres` (required):
+- Check `.project-context.md` for `db-drizzle-postgres` under `## Installed Blueprints`
+- If installed: proceed normally
+- If NOT installed, check filesystem:
+  - Monorepo: does `packages/db/` exist?
+  - Single-repo: does `src/db/` exist?
+- If db directory exists (but not in project context): note it, proceed normally — the scaffold command already handles merging
+- If neither installed nor directory exists:
+  - Ask: "Auth requires a database package. The db-drizzle-postgres blueprint establishes the schema-group pattern that auth builds on. Install it first? (Y/n)"
+  - If yes: run `/scaffold-db` first, then continue with auth
+  - If no: warn about missing patterns, proceed with creating a minimal db structure for auth only
+
+For `foundation/monorepo-turbo` (recommended):
+- If not present: mention once: "Tip: The monorepo-turbo foundation blueprint provides workspace structure that auth integrates with. Consider running `/scaffold-foundation` first."
+- Continue without blocking.
+
+## Step 2: Understand the Target Project
+
+Before making any changes, explore the target project to understand:
+
+### 2a. Detect Project Type
+
+Check `.project-context.md` for `project_type`. If not present, detect:
+
+- **Monorepo indicators**: `pnpm-workspace.yaml`, `turbo.json`, `nx.json`, `lerna.json`, or `"workspaces"` in root `package.json`
+- **Single-repo indicators**: Single `package.json` at root, `src/` directory, no workspace config
+
+Confirm with user: "This looks like a [monorepo|single-repo] project. Is that right?"
+
+Record the project type in `.project-context.md` if not already there.
+
+### 2b. Explore Structure
+
+**If monorepo:**
+1. What workspaces exist? Where do apps, APIs, and packages live?
+2. Is there a Hono server, Express server, or is it Next.js-only? Where are API routes?
+3. Is Drizzle already set up? Is there a shared DB package?
+4. Is this Next.js? What version? Is there an existing middleware.ts?
+
+**If single-repo:**
+1. What framework is this? (Next.js, Node/Express, Hono, Bun?)
+2. Does `src/db/` or `lib/db/` exist?
+3. What import convention is used? (`@/` paths, `#` subpath imports, relative?)
+4. Is there an existing `middleware.ts`?
+
+**Both:**
+5. Existing auth to replace or integrate with?
+6. UI library? Styling approach?
+7. Package manager?
+8. Validation — Zod, t3-env?
+9. Data fetching — SWR, TanStack Query?
+
+Skip exploration for anything already documented in `.project-context.md`.
+
+## Step 3: Ask Clarifying Questions
+
+Before scaffolding, ask the user about their preferences. Use the blueprint's "Hard Requirements vs Recommended Defaults" table. Specifically ask:
+
+1. **Organization plugin** — "Do you need multi-tenant organizations (teams/workspaces with member management and invitations), or is this a single-tenant app?"
+
+2. **Database setup** — "Should auth use a separate database, or share the existing app database?" (Recommend separate if no strong preference.)
+
+3. **Social providers** — "Which social login providers do you want? Google is included by default. Any others (GitHub, Discord, etc.)?"
+
+4. **Email provider** — "The blueprint uses Resend for transactional emails (verification, password reset, invitations). Do you want to use Resend, or a different provider?"
+
+5. **Defaults check** — "The blueprint recommends these tools (which may already match your project). Want to go with the defaults, or change any?"
+   - Zod for validation
+   - t3-env for environment variable validation
+   - SWR (`useSWRMutation`) for auth mutation hooks
+   - react-hook-form for auth forms
+
+Skip questions where the answer is obvious from the project structure or from `.project-context.md`.
+
+## Step 4: Adapt and Scaffold
+
+Based on the project structure, project context, and user answers, adapt the blueprint files:
+
+### 4a. Database Layer
+
+**If monorepo:**
+- Copy/adapt `files/db/drizzle.config.ts` → `packages/db/drizzle/auth/drizzle.config.ts`
+- Copy `files/db/auth-schema.ts` as a reference (the actual schema will be auto-generated)
+- Add the `"./auth"` export to `packages/db/package.json`
+- Add `auth:generate` and `auth:migrate` scripts to `packages/db/package.json`
+
+**If single-repo:**
+- Copy/adapt `files/db/drizzle.config.ts` → `drizzle/auth/drizzle.config.ts` (at project root)
+- Adjust schema paths to `"./src/db/auth/schema.ts"` (relative to root)
+- Create `src/db/auth/` directory for auth schema
+- No separate package.json export needed — use direct imports
+
+### 4b. Server Layer
+
+**If monorepo:**
+- Copy/adapt `files/server/auth.ts` → `apis/server/src/auth/index.ts`
+  - Replace `{{APP_NAME}}`, `{{EMAIL_FROM}}`, `{{SCOPE}}`
+- Copy/adapt `files/server/auth-db.ts` → `apis/server/src/db/auth.ts`
+- Copy/adapt `files/server/middleware.ts` → `apis/server/src/middleware/auth.ts`
+- Merge auth env vars into `apis/server/src/env.ts`
+
+**If single-repo:**
+- Copy/adapt `files/server/auth.ts` → `src/lib/auth/index.ts`
+  - Replace `{{APP_NAME}}`, `{{EMAIL_FROM}}`
+  - Adjust DB import to use direct path: `import { db } from "@/db/auth/client"` or `#db/auth/client`
+- Copy/adapt `files/server/auth-db.ts` → `src/lib/db/auth.ts`
+- Default to Next.js API routes (no separate Hono server)
+- Merge auth env vars into existing `env.ts` (or create one)
+
+**Both:**
+- If the project uses a different server framework than Hono, adapt the middleware while keeping the core `auth.api.getSession({ headers })` pattern
+
+### 4c. Mount Auth Handler
+
+**If monorepo with Hono server:**
+- Add CORS config + `app.on(["POST", "GET"], "/api/auth/*", ...)` handler in `apis/server/`
+
+**If single-repo or Next.js API routes:**
+- Create `app/api/auth/[...all]/route.ts` with `toNextJsHandler(auth)`
+- No CORS config needed (same origin)
+
+**Other frameworks:** Follow the platform integration section in BLUEPRINT.md
+
+### 4d. Client Layer
+
+**If monorepo:**
+- Copy client files to `apps/web/auth/`
+- Add `"#auth/*": "./auth/*"` import alias to `apps/web/package.json`
+
+**If single-repo:**
+- Copy client files to `src/auth/`
+- Add `"#auth/*": "./src/auth/*"` import alias to root `package.json` (or use `@/auth/*` if that's the convention)
+
+**Both:**
+- Adapt `files/client/auth-client.ts` — adjust baseURL for deployment setup
+- If using org plugin: copy all `files/client/context/`, `hooks/`, `schema/`, `types/` files
+- If NOT using org plugin: only copy `files/client/schema/auth.ts`
+
+### 4e. Route Protection
+
+- Copy/adapt `files/middleware/route-protection.ts` into the project's Next.js middleware
+- If middleware.ts already exists, MERGE the auth logic into it — don't overwrite
+- If using Hono standalone mode: add API proxy rewrites to `next.config.ts`
+
+### 4f. Project Scripts
+
+**If monorepo:**
+- Add `auth:generate` script to the server package (runs `@better-auth/cli generate`)
+- Add `auth:generate`, `auth:migrate`, `auth:setup` to root `package.json` (Turbo wrappers)
+- Add `auth:generate` and `auth:migrate` tasks to `turbo.json` (both `cache: false`)
+
+**If single-repo:**
+- Add scripts directly to root `package.json`:
+  - `auth:generate` -> `npx @better-auth/cli@latest generate --config ./src/lib/auth/index.ts --output ./src/db/auth/schema.ts --yes`
+  - `auth:migrate` -> `drizzle-kit generate --config ./drizzle/auth/drizzle.config.ts && drizzle-kit migrate --config ./drizzle/auth/drizzle.config.ts`
+  - `auth:setup` -> `pnpm auth:generate && pnpm auth:migrate`
+- No Turbo tasks needed
+
+## Step 5: Update Project Context
+
+Append an entry to `.project-context.md` under `## Installed Blueprints`:
+
+```yaml
+### auth-better-auth
+blueprint: auth-better-auth
+choices:
+  database: <user's choice>
+  auth_db_isolation: <separate|shared>
+  server_framework: <hono|next.js>
+  organization_plugin: <true|false>
+  social_providers: [<list>]
+  email_provider: <resend|other>
+  env_validation: <t3-env|other>
+  form_validation: <zod|other>
+  data_fetching: <swr|other>
+files_created:
+  - <list of all files created or modified>
+env_vars_added:
+  - <list of env vars>
+scripts_added:
+  - <list of scripts>
+```
+
+If `.project-context.md` does not exist, create it with the standard header and the Installed Blueprints section. Log a note: "No discovery or foundation context found. Consider running `/discover` and `/scaffold-foundation` for a complete project context."
+
+Also append any significant architectural decisions to the `## Architecture Decisions` section.
+
+### Inject Maintenance Rules
+
+Append the condensed maintenance rules to the target project's rules file(s):
+
+1. If `CLAUDE.md` exists in the target project → append rules there
+2. If `AGENTS.md` exists in the target project → append rules there
+3. If both exist → append to both (keep them in sync)
+4. If neither exists → ask the user which AI coding tool(s) they use:
+   - Claude Code → create CLAUDE.md with a `## Maintenance Rules` section
+   - OpenCode or Cursor → create AGENTS.md with a `## Maintenance Rules` section (both tools read AGENTS.md)
+   - Multiple tools → create all applicable files
+
+The maintenance rules content is identical regardless of which file it goes into:
+
+```markdown
+### auth-better-auth maintenance
+- After modifying Better Auth server config, plugins, or providers: run `pnpm auth:generate && pnpm auth:migrate`
+- After updating `better-auth` package: run `pnpm auth:generate`, check for schema changes, migrate if needed
+- After adding/changing env vars: update all `.env` files and verify `pnpm dev` starts clean
+- After changing `BETTER_AUTH_URL` or `FRONTEND_DOMAIN`: verify CORS config and OAuth callback URLs
+- After any auth changes: verify `{BETTER_AUTH_URL}/api/auth/ok` responds
+- Never edit the auto-generated auth schema directly — modify the Better Auth config and regenerate
+```
+
+If the `## Maintenance Rules` heading already exists (from another blueprint), only add the `### auth-better-auth maintenance` subsection — do not duplicate the heading.
+
+## Step 6: Output Summary
+
+After scaffolding, provide the user with a clear summary:
+
+### Packages to Install
+
+List every package that needs to be installed, grouped by workspace:
+
+```
+# Server (apis/server or wherever auth lives)
+pnpm add better-auth drizzle-orm pg resend @t3-oss/env-core zod dotenv
+
+# Client (apps/web)
+pnpm add better-auth swr react-hook-form @hookform/resolvers zod @t3-oss/env-nextjs
+
+# DB package (packages/db) — dev deps
+pnpm add -D drizzle-kit pg
+```
+
+Adjust based on what's already installed in the project.
+
+### Environment Variables
+
+List every env var that needs to be set, with example values:
+
+```env
+# Server
+BETTER_AUTH_URL=http://localhost:4000
+BETTER_AUTH_SECRET=          # Generate: openssl rand -base64 32
+AUTH_DATABASE_URL=           # PostgreSQL connection URL
+FRONTEND_DOMAIN=http://localhost:3000
+GOOGLE_CLIENT_ID=            # From Google Cloud Console
+GOOGLE_CLIENT_SECRET=        # Redirect URI: {BETTER_AUTH_URL}/api/auth/callback/google
+RESEND_API_KEY=              # From resend.com
+
+# Client (.env.local in web app)
+NEXT_PUBLIC_API_URL=http://localhost:4000
+NEXT_PUBLIC_FRONTEND_URL=http://localhost:3000
+```
+
+### Manual Steps Remaining
+
+List anything that can't be automated:
+
+1. **Create a PostgreSQL database** for auth (if using separate auth DB)
+2. **Set up Google OAuth** — create OAuth 2.0 credentials in Google Cloud Console, add redirect URI
+3. **Set up Resend** — create an account, verify your domain, get API key
+4. **Run auth setup** — `pnpm auth:setup` (generates schema + runs migrations)
+5. **Build auth UI pages** — follow the Auth Flows section in BLUEPRINT.md to create the pages matching your design system
+6. **Test the auth flow** — sign up, verify email, sign in, create org (if applicable)
+
+### Files Created
+
+List every file that was created or modified, with a one-line description.
+
+## Important Notes
+
+- If the Better Auth skills are installed (`npx skillsadd better-auth/skills`), invoke `/best-practices` for quick-reference on configuration. If not available, refer to the Better Auth docs and References section in BLUEPRINT.md.
+- When adapting code, preserve the `// CONFIGURE:` comments so the user can find customization points later.
+- If the project structure differs significantly from the blueprint's assumptions, explain the differences and suggest how to adapt rather than forcing the blueprint's structure.
+- Never overwrite existing files without asking. If a file exists (like `middleware.ts` or `env.ts`), merge the auth additions into it.