@withmata/blueprints 0.2.0

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

@@ -0,0 +1,158 @@
+# 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/audit.md

@@ -0,0 +1,183 @@
+---
+description: Run a project health check against available blueprints
+---
+
+# Project Audit
+
+Run a health check against available blueprints. Analyze this project's current state and recommend improvements, missing best practices, or blueprints that could replace hand-rolled infrastructure. This command is read-only — it does not modify any files.
+
+## Step 1: Read Available Blueprints
+
+Load all available blueprint specs to understand what is possible:
+
+```
+~/Documents/WithMata/my-blueprints/blueprints/discovery/product-discovery/BLUEPRINT.md
+~/Documents/WithMata/my-blueprints/blueprints/foundation/monorepo-turbo/BLUEPRINT.md
+~/Documents/WithMata/my-blueprints/blueprints/features/auth-better-auth/BLUEPRINT.md
+```
+
+Also scan for any additional feature blueprints:
+
+```
+~/Documents/WithMata/my-blueprints/blueprints/features/*/BLUEPRINT.md
+```
+
+Only consider a blueprint "available" if its BLUEPRINT.md has `Status: Complete`. If not found at these paths, ask the user for the path to their blueprints repo.
+
+## Step 2: Read Project Context
+
+Check if `.project-context.md` exists in this project root.
+
+- **If it exists**: read it fully. Note which stages are complete (Discovery, Foundation, Installed Blueprints) and what choices were made.
+- **If it does not exist**: note this — it means either no blueprints have been used, or the project predates the blueprint system.
+
+## Step 3: Explore the Project
+
+Regardless of whether project context exists, explore the actual project to understand its true state. If `.project-context.md` contradicts what you find in the actual files, trust the files and note the discrepancy.
+
+### 3a. Product & Planning
+
+- Does `docs/product/` exist? Are there product briefs, user stories, or discovery artifacts?
+- Is there any structured product documentation, or just a README?
+
+### 3b. Project Structure & Type
+
+- **Detect project type:**
+  - **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
+  - Record as `monorepo` or `single-repo` in the report
+- What package manager? Check for `pnpm-lock.yaml`, `yarn.lock`, `package-lock.json`, `bun.lock`
+- If monorepo: What workspaces exist? List `apps/`, `packages/`, `apis/`, `config/` or equivalent
+- Is there a `biome.json`? ESLint config? Prettier config?
+- Is TypeScript strict? Check `tsconfig.json` for `strict: true` and `noUncheckedIndexedAccess`
+- Are there shared config packages? Or is config duplicated?
+
+### 3c. Authentication
+
+- Is there an auth system? Search for:
+  - Better Auth config files (`better-auth`, `createAuthClient`)
+  - NextAuth/Auth.js files (`auth.ts`, `[...nextauth]`, `authOptions`)
+  - Hand-rolled auth (JWT imports, `bcrypt`, `jsonwebtoken`, session handling in middleware)
+  - Third-party services (Clerk, Auth0, Supabase auth, Firebase auth)
+- Are there login/signup pages? Route protection middleware?
+- Are there organization/team/workspace features?
+
+### 3d. Database
+
+- Is Drizzle set up? Check for `drizzle.config.ts`, `drizzle-kit`
+- Other ORMs? Check for Prisma (`schema.prisma`), TypeORM, Knex
+- Is there a shared DB package, or is database access scattered?
+
+### 3e. Styling & UI
+
+- Tailwind version? Check `tailwindcss` version in package.json — v3 (JS config) vs v4 (CSS config)
+- Is there a shared UI package, or are components duplicated?
+- Component library? shadcn/ui, Radix, MUI, Chakra?
+
+### 3f. Environment & Validation
+
+- How are env vars handled? t3-env, raw `process.env`, dotenv only?
+- Is there input validation? Zod, Valibot, Yup, Joi?
+
+### 3g. Code Quality
+
+- Are there patterns that diverge from best practices?
+  - Default exports where named exports are preferred
+  - Missing barrel exports (`index.ts`) in packages
+  - File-type organization instead of feature-based
+  - Missing or inconsistent error handling
+
+### 3h. Blueprint Dependency Check
+
+For each blueprint listed under `## Installed Blueprints` in `.project-context.md`:
+- Read its `## Blueprint Dependencies` section from the BLUEPRINT.md
+- Check if each `required` dependency is also listed in Installed Blueprints
+- If a required dependency is missing, include it in the report as a recommendation
+
+Example finding: "auth-better-auth is installed but its required dependency db-drizzle-postgres is not. Auth created a minimal db structure that lacks the full schema-group patterns. Run `/scaffold-db` to add the complete db patterns — it will merge without overwriting auth files."
+
+## Step 4: Generate the Audit Report
+
+Present findings as a structured report. Be concrete and specific — reference actual files and patterns found.
+
+### Report Format
+
+---
+
+**Project Audit: [project name or directory name]**
+
+### Current State
+
+| Area | Status | Details |
+|------|--------|---------|
+| Product Discovery | [done / not found / partial] | [Brief note] |
+| Foundation / Structure | [done / partial / needs work] | [Brief note] |
+| Authentication | [blueprint / hand-rolled / third-party / none] | [Brief note] |
+| Database | [Drizzle / Prisma / other / none] | [Brief note] |
+| Styling | [Tailwind v4 / v3 / other] | [Brief note] |
+| Code Quality | [good / needs attention] | [Brief note] |
+
+### Recommendations
+
+For each recommendation:
+
+1. **[Priority: High/Medium/Low] [Category] — [One-line summary]**
+   - **What we found:** [Specific observation referencing actual files]
+   - **Why it matters:** [Impact on the project — explain for non-technical users too]
+   - **Action:** [Exact command or step to fix it]
+
+---
+
+### Recommendation Priority Guidelines
+
+**High priority** — things that block progress or create real risk:
+- No auth system and the product needs user accounts
+- No monorepo structure in a multi-workspace project
+- Hand-rolled auth with security gaps (plain text passwords, no CSRF, no rate limiting)
+- Missing environment variable validation
+
+**Medium priority** — things that improve quality and maintainability:
+- A blueprint could replace hand-rolled infrastructure
+- Missing product documentation for a project still figuring out its direction
+- Inconsistent patterns across workspaces
+- Tailwind v3 when v4 is available
+- ESLint + Prettier when Biome could replace both
+
+**Low priority** — nice-to-haves:
+- Blueprints in development that are not yet available (mention them as "coming soon")
+- Style preferences that do not affect functionality
+- Optimizations for mature projects
+
+## Step 5: Provide Actionable Next Steps
+
+End the report with a clear list of what to do, in recommended order:
+
+### Next Steps
+
+```
+# Run these in order — each one is independent, stop whenever you want
+
+1. [command]    # [what it does and why]
+2. [command]    # [what it does and why]
+...
+```
+
+For blueprint commands, use the slash command format: `/discover`, `/scaffold-foundation`, `/scaffold-auth`
+
+For non-blueprint improvements, include the actual shell commands or instructions.
+
+## Tone Guidelines
+
+- **Be honest.** If the project is in great shape, say so. Do not manufacture recommendations.
+- **Be warm and accessible.** The user may be non-technical. Explain WHY something matters, not just what to do.
+- **Be specific.** "Your auth looks hand-rolled" is not helpful. "I found JWT signing in `lib/auth.ts` without CSRF protection — the auth blueprint handles this with Better Auth's built-in security" is helpful.
+- **Separate facts from opinions.** "You are using ESLint + Prettier" is a fact. "Biome could replace both with simpler config" is a recommendation — label it as such.
+- **Do not overwhelm.** Lead with the 3-5 most impactful recommendations. If there are many findings, prioritize.
+- **Celebrate what is done well.** If something follows best practices, acknowledge it briefly.
+
+## Important Notes
+
+- This command is **read-only**. It does not modify any files — it only reads and reports.
+- Only recommend blueprints with `Status: Complete`. Mention planned blueprints (tailwind-v4, ui-shared-components) as "coming soon" if relevant, but do not suggest running commands for them.
+- If the project is empty or brand new, keep the report short: "This is a fresh project. Here is where to start." and suggest `/discover` or `/scaffold-foundation`.
+- If everything looks good, say so: "This project is in great shape. No immediate recommendations."

package/.opencode/commands/discover.md

@@ -0,0 +1,96 @@
+---
+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."