@withmata/blueprints 0.2.0 → 0.3.1

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

@@ -1,310 +0,0 @@
-# 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.

package/.cursor/commands/scaffold-foundation.md

@@ -1,158 +0,0 @@
-# Scaffold Foundation
-
-Set up the monorepo project skeleton using the foundation blueprint. **For single-repo applications** (standalone Next.js, Node, or Bun apps), skip this command and go directly to feature blueprints (`/scaffold-db`, `/scaffold-auth`) — they detect single-repo projects and adapt automatically.
-
-## Step 1: Read the Blueprint
-
-Read the full foundation blueprint and all template files:
-
-```
-~/Documents/WithMata/my-blueprints/blueprints/foundation/monorepo-turbo/BLUEPRINT.md
-~/Documents/WithMata/my-blueprints/blueprints/foundation/monorepo-turbo/files/**/*
-```
-
-If not found at that path, ask the user for the path to their blueprints repo.
-
-The BLUEPRINT.md contains the full architecture documentation, naming conventions, folder conventions, and file manifest. Follow it precisely.
-
-## Step 2: Read Project Context
-
-Check if `.project-context.md` exists in the target project root:
-
-- **If it has a Discovery section**: use the product name to derive the npm scope (e.g., "Acme Dashboard" -> `@acme`). Use technical constraints to inform any decisions.
-
-- **If it has a Foundation section already**: warn the user. Ask: "Foundation was already set up. Do you want to re-scaffold (destructive — replaces existing structure) or skip?"
-
-- **If no context file exists**: that is fine. Ask the user directly for the product name and npm scope.
-
-## Step 3: Understand Current State
-
-Explore the target project directory:
-
-- Is it empty? Fresh start — scaffold everything.
-- Does it already have files? Ask before overwriting anything.
-- Is there an existing `package.json`? Read it for context.
-
-## Step 4: Ask Configuration Questions
-
-Only three questions — skip any already answered by project context:
-
-1. **npm scope** — "What npm scope should internal packages use? (e.g., @acme)" Default: derive from product name.
-2. **Project name** — "What is the human-readable project name?" (for metadata, page titles). Default: from discovery context.
-3. **Node.js version** — "Target Node.js version?" Default: `>=22`.
-
-## Step 5: Scaffold
-
-Create the monorepo skeleton by adapting all files from the blueprint. Replace placeholders:
-
-- `{{SCOPE}}` -> the npm scope (e.g., `@acme`)
-- `{{APP_NAME}}` -> the human-readable name (e.g., `Acme Dashboard`)
-
-### 5a. Root Configuration
-
-From `files/root/`, create at project root:
-- `package.json` — root monorepo config
-- `turbo.json` — task orchestration
-- `pnpm-workspace.yaml` — workspace patterns
-- `biome.json` — linting + formatting
-- `.gitignore` — from `files/root/gitignore`
-
-### 5b. Config Packages
-
-From `files/config/`, create:
-- `config/typescript-config/` — base.json, nextjs.json, react-library.json, package.json
-- `config/tailwind-config/` — shared-styles.css, postcss.config.js, package.json
-
-### 5c. Next.js App Shell
-
-From `files/apps/web/`, create:
-- `apps/web/package.json`
-- `apps/web/tsconfig.json`
-- `apps/web/next.config.ts`
-- `apps/web/env.ts`
-- `apps/web/postcss.config.mjs`
-- `apps/web/app/layout.tsx`
-- `apps/web/app/page.tsx`
-- `apps/web/app/globals.css`
-
-### 5d. Empty Workspace Directories
-
-Create empty directories for feature blueprints:
-- `apis/` — backend feature blueprint will add servers here
-- `packages/` — feature blueprints will add shared packages here
-
-### 5e. Initialize
-
-After creating all files:
-1. Initialize git if not already a repo: `git init`
-2. Run `pnpm install` to verify the workspace configuration is valid
-3. Verify the dev server starts: `pnpm dev` (briefly — just check it boots)
-
-## Step 6: Update Project Context
-
-Append the `## Foundation` section to `.project-context.md`:
-
-```yaml
-## Foundation
-monorepo_tool: turborepo
-package_manager: pnpm
-npm_scope: "<scope>"
-node_version: ">=22"
-workspaces:
-  apps: ["web"]
-  apis: []
-  packages: []
-  config: ["typescript-config", "tailwind-config"]
-framework: next.js (app router)
-typescript: strict
-linter: biome
-styling: tailwind-v4
-env_validation: t3-env + zod
-module_resolution: node subpath imports (#prefix)
-foundation_completed: <date>
-```
-
-If `.project-context.md` does not exist, create it with the standard header and the Foundation 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
-## Maintenance Rules
-
-### Monorepo maintenance
-- After every code change: format with Biome (`pnpm biome check --write .`) before considering work complete
-- After adding new workspace packages: verify `pnpm-workspace.yaml` patterns match, run `pnpm install`
-- After modifying shared configs (`config/typescript-config/`, `config/tailwind-config/`): verify all consumers still build
-- After changing `turbo.json`: verify task ordering with `pnpm turbo run <task> --dry`
-- After adding workspace dependencies: run `pnpm install` to create workspace links
-- Keep `turbo.json` tasks with `cache: false` for any task with side effects (migrations, code generation)
-```
-
-## Step 7: Summarize
-
-Tell the user:
-
-- Project structure overview (directory tree)
-- What was configured (scope, Node version, tooling)
-- How to start development: `pnpm dev`
-- Available feature blueprints to install next
-- Suggest: "Run `/scaffold-auth` to add authentication. Other feature blueprints: ui-shared-components, tailwind-v4, db-drizzle-postgres."
-
-## Important Notes
-
-- Never overwrite existing files without asking.
-- Preserve all `// CONFIGURE:` comments in generated files so the user can find customization points.
-- The Tailwind config is intentionally minimal — the UI feature blueprint extends it with shadcn, animations, and component-specific styles.
-- Feature blueprints will add scripts to root `package.json` and tasks to `turbo.json` — the foundation provides the base that they extend.

package/.opencode/commands/discover.md

@@ -1,96 +0,0 @@
----
-description: Run a structured product discovery session — outputs docs, no code
----
-
-# Run Product Discovery
-
-Run a rigorous product discovery session. This produces product documentation — no code is generated. The session is a structured 60-minute deep dive that transforms a raw idea into a defensible product strategy.
-
-## Step 1: Read the Blueprint
-
-Read the full discovery blueprint and all templates:
-
-```
-~/Documents/WithMata/my-blueprints/blueprints/discovery/product-discovery/BLUEPRINT.md
-~/Documents/WithMata/my-blueprints/blueprints/discovery/product-discovery/templates/*
-```
-
-If not found at that path, ask the user for the path to their blueprints repo.
-
-The BLUEPRINT.md contains the full methodology: phased session structure, frameworks, operating principles, research strategy, challenge patterns, and quality checkpoints. Follow it precisely.
-
-## Step 2: Check for Existing Discovery
-
-Check if `.project-context.md` exists and already contains a `## Product Discovery` section. If it does:
-
-- Show the user what was previously discovered
-- Ask: "Product discovery was already completed. Would you like to redo it (replaces existing), refine it (update specific sections), or skip?"
-
-## Step 3: Run the Discovery Session
-
-Follow the full 5-phase discovery process documented in BLUEPRINT.md. The blueprint contains the complete methodology: phase structure, frameworks, operating principles, research strategy, challenge patterns, and quality gates. Follow it precisely. Do not abbreviate or skip phases.
-
-This is conversational — you are guiding the user through structured discovery, not filling in a form.
-
-Quick reference for the phases:
-1. **Phase 1: Initial Framing** — what and who
-2. **Phase 2: Problem Deep Dive** — root cause via 5 Whys
-3. **Phase 3: User Definition** — archetypes and persona variations
-4. **Phase 4: Solution Positioning** — competitive landscape and differentiation
-5. **Phase 5: Synthesis** — distill findings for documentation
-
-## Step 4: Verify Quality Checkpoints
-
-Before generating documentation, verify ALL quality checkpoints listed in BLUEPRINT.md pass. If any fail, continue probing — do not rush to documentation.
-
-## Step 5: Generate Documentation
-
-Create the `docs/product/` directory structure in the target project. Use the templates from the blueprint as the structural guide — fill them with the session's findings.
-
-```
-docs/
-└── product/
-    ├── product-thesis.md
-    ├── product-brief.md
-    └── users/
-        ├── archetype-[name].md     # One per archetype identified
-        └── research-summary.md
-```
-
-See BLUEPRINT.md for document quality standards and writing guidelines for each document type. Do not create files beyond what's specified. Do not rename the structure.
-
-## Step 6: Update Project Context
-
-Create or update `.project-context.md` in the target project root:
-
-- If the file does not exist, create it with a header and the `## Product Discovery` section
-- If the file exists but has no discovery section, add the discovery section after the header
-- If the file exists with a discovery section (user chose to redo), replace that section only
-
-Append this structured YAML block:
-
-```yaml
-## Product Discovery
-product_name: "<name>"
-problem_statement: "<one sentence>"
-core_pillars:
-  - "<pillar 1>"
-  - "<pillar 2>"
-  - "<pillar 3>"
-primary_archetype: "<archetype name>"
-discovery_completed: <date>
-artifacts:
-  - docs/product/product-thesis.md
-  - docs/product/product-brief.md
-  - docs/product/users/archetype-<name>.md
-  - docs/product/users/research-summary.md
-```
-
-## Step 7: Summary
-
-Tell the user:
-
-- What documents were generated (list each with a one-line description)
-- Key findings: core pillars, primary archetype, main competitive gap
-- Critical assumptions that need validation
-- Suggest next step: "Run `/scaffold-foundation` to set up the project skeleton, or `/new-project` to continue the full workflow."