@withmata/blueprints 0.2.0

package/.claude/commands/audit.md

@@ -0,0 +1,179 @@
+# 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/.claude/commands/discover.md

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

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

@@ -0,0 +1,265 @@
+# Add a New Blueprint
+
+Guide the user through adding a new blueprint to this repo. This command ensures every blueprint follows the established conventions and is fully wired up.
+
+## Step 1: Understand the Conventions
+
+Read these files to understand the system you're adding to:
+
+```
+ENGINEERING.md                # Engineering preferences
+README.md                    # System overview and blueprint anatomy
+CHANGELOG.md                 # To update when done
+```
+
+Also scan existing complete blueprints to understand the quality bar:
+
+```
+blueprints/features/auth-better-auth/BLUEPRINT.md    # Best example of a feature blueprint
+blueprints/foundation/monorepo-turbo/BLUEPRINT.md    # Best example of a foundation blueprint
+blueprints/discovery/product-discovery/BLUEPRINT.md  # Best example of a discovery blueprint
+```
+
+## Step 2: Gather Information
+
+Ask the user:
+
+1. **"What pattern are you extracting?"** — What does it do? (e.g., "shared database layer with Drizzle", "Stripe billing integration", "email service with Resend")
+
+2. **"Which tier?"** — Discovery (produces docs), Foundation (project skeleton), or Feature (plugs into existing project)? Most new blueprints are Features.
+
+3. **"Is there an existing project to extract from?"** — If yes, get the path. If no, we're building from scratch — which is fine but harder.
+
+4. **"What should it be called?"** — Suggest a name following the convention: `{domain}-{tool}` for features (e.g., `auth-better-auth`, `db-drizzle-postgres`, `billing-stripe`, `email-resend`). Foundation and discovery blueprints use `{purpose}-{tool}` (e.g., `monorepo-turbo`, `product-discovery`).
+
+## Step 3: Extract or Build
+
+### If extracting from an existing project:
+
+Read the relevant code in the source project. Understand:
+- What files are involved
+- How they connect to each other
+- What's project-specific vs what's the reusable pattern
+- What dependencies are needed
+- What environment variables are required
+- How it integrates with the monorepo (workspace deps, turbo tasks, root scripts)
+
+Then create the blueprint:
+
+1. Create the directory: `blueprints/{tier}/{name}/`
+2. Create `files/` with the extracted code — generalize project-specific values:
+   - Replace npm scopes with `{{SCOPE}}`
+   - Replace app names with `{{APP_NAME}}`
+   - Replace project-specific emails, URLs, etc. with `{{PLACEHOLDER}}` and `// CONFIGURE:` comments
+   - Remove any business logic that's not part of the pattern
+3. Create `BLUEPRINT.md` following the structure below
+
+### If building from scratch:
+
+1. Create the directory: `blueprints/{tier}/{name}/`
+2. Build the code files in `files/`, following the conventions in ENGINEERING.md
+3. Create `BLUEPRINT.md` following the structure below
+
+## Step 4: Write the BLUEPRINT.md
+
+This is the most important file. It's what makes AI-assisted scaffolding intelligent rather than mechanical. Follow this structure:
+
+### Required sections (all tiers):
+
+```markdown
+# [Name] Blueprint — [Short Description]
+
+## Tier
+[Discovery | Foundation | Feature]
+
+## Status
+[Complete | In Progress | Planned]
+
+## Problem
+[What problem does this blueprint solve? Be specific about the pain point.]
+```
+
+### Additional sections for Feature blueprints:
+
+```markdown
+## Blueprint Dependencies
+
+[Does this blueprint require or recommend other blueprints be installed first?
+List them in a table with columns: Blueprint, Type (required/recommended), Why.
+If required, include a subsection explaining fallback behavior if the dependency is absent.
+If no dependencies, write "None."]
+
+## Single-Repo Adaptation
+
+[How does file placement, imports, and scripts differ for standalone (non-monorepo) apps?
+Include a path mapping table (monorepo vs single-repo) and a single-repo scripts example.
+Document what core patterns stay the same regardless of project type.]
+
+## Architecture
+
+### Core Pattern
+[How does this work at a high level?]
+
+### Key Decisions
+[For each major decision, document WHAT you chose and WHY. This is what lets the AI coding tool adapt intelligently.]
+
+- **[Decision 1]** (recommended/required) — [Explanation of what and why. Include alternatives if relevant.]
+- **[Decision 2]** (optional) — [Explanation]
+
+## Hard Requirements vs Recommended Defaults
+
+**Hard requirements:**
+- [Things that can't change]
+
+**Recommended defaults — ask during scaffolding:**
+
+| Choice | Recommended | Alternatives |
+|---|---|---|
+| [Choice 1] | [Default] | [Options] |
+
+## Dependencies
+
+### npm packages
+
+**Server:**
+| Package | Version | Purpose |
+|---|---|---|
+| [pkg] | [version] | [why] |
+
+**Client:**
+| Package | Version | Purpose |
+|---|---|---|
+
+### Environment Variables
+
+| Variable | Where | Description |
+|---|---|---|
+| [VAR] | [Server/Client] | [What it's for] |
+
+## Monorepo Wiring
+
+[How does this integrate across workspaces? Package exports, workspace deps, turbo tasks, root scripts. This section is critical — it's the hardest part to figure out from scratch.]
+
+## File Manifest
+
+| File | Purpose | Target Location |
+|---|---|---|
+| [file path in files/] | [what it does] | [where it goes in target project] |
+
+## Integration Steps
+
+[Ordered phases for scaffolding. Group related steps.]
+
+### Phase 1: [Name]
+1. [Step]
+2. [Step]
+
+### Phase 2: [Name]
+...
+
+## Maintenance Hooks
+
+[What needs to happen after changes to keep this working?]
+
+### Condensed Rules for project rules file
+
+```markdown
+### [name] maintenance
+- [rule 1]
+- [rule 2]
+```
+
+## References
+
+- [Links to docs, repos, etc.]
+```
+
+### Additional sections for Discovery blueprints:
+
+```markdown
+## Output
+[What documents are generated and where]
+
+## Process
+[The conversational flow — phases, frameworks, quality gates]
+```
+
+### Additional sections for Foundation blueprints:
+
+```markdown
+## Output
+[What project structure is generated — show the directory tree]
+
+## Architecture
+[Key structural decisions: why this tool, why this config, why this convention]
+
+## Expects from Discovery
+[What info it reads from the discovery context, if anything]
+```
+
+### Quality checklist for BLUEPRINT.md:
+
+Before considering the BLUEPRINT.md done, verify:
+
+- [ ] Every architectural decision explains WHY, not just WHAT
+- [ ] Configurable vs opinionated choices are clearly separated
+- [ ] Blueprint Dependencies section is present (even if "None")
+- [ ] Single-Repo Adaptation section documents path mapping and script differences
+- [ ] File manifest covers every file in files/ with both monorepo and single-repo target locations
+- [ ] Integration steps are ordered and phased, with conditional monorepo/single-repo phases
+- [ ] Dependencies list specific versions
+- [ ] Environment variables are documented with descriptions
+- [ ] Monorepo wiring is documented (this is always the hardest part)
+- [ ] Maintenance hooks define trigger-action pairs
+- [ ] Code files use `{{SCOPE}}`, `{{APP_NAME}}`, and `// CONFIGURE:` markers
+- [ ] References link to official docs
+
+## Step 5: Create the Scaffold Command
+
+Create the command in all three tool directories: `.claude/commands/scaffold-{name}.md`, `.opencode/commands/scaffold-{name}.md`, and `.cursor/commands/scaffold-{name}.md`. The OpenCode version should include YAML frontmatter with a `description` field. The Claude Code and Cursor versions use plain markdown (no frontmatter). The command body is the same across all three.
+
+Follow the pattern from existing commands (read `.claude/commands/scaffold-auth.md` as the model). Every scaffold command must:
+
+1. **Read the blueprint** — BLUEPRINT.md and all files
+2. **Read project context** — `.project-context.md` for existing state
+3. **Explore the target project** — understand current structure
+4. **Ask clarifying questions** — based on the blueprint's configurable options
+5. **Adapt and scaffold** — replace placeholders, adapt to project structure
+6. **Update project context** — append to `.project-context.md`
+7. **Inject maintenance rules** — detect and append to the target project's rules file(s): CLAUDE.md, AGENTS.md, or both (see the multi-tool injection pattern in existing scaffold commands)
+8. **Summarize** — packages to install, env vars to set, manual steps remaining
+
+The command should reference the BLUEPRINT.md as the source of truth for methodology and not duplicate its content.
+
+## Step 6: Update the Repo
+
+After the blueprint and command are created:
+
+1. **Update README.md** — Add the new blueprint to the appropriate table (Complete or Planned) in the "Available blueprints" section. Add a scaffold command entry to the "Available commands" table.
+
+2. **Update CHANGELOG.md** — Add an entry under [Unreleased] → Added describing the new blueprint.
+
+3. **Update the directory structure** in README.md if it's shown there.
+
+4. **Check for a planned blueprint placeholder** — If `blueprints/features/{name}/BLUEPRINT.md` already existed as a planned placeholder, replace it entirely with the full BLUEPRINT.md. Don't try to preserve the placeholder content.
+
+5. **Ensure all three directories have the new scaffold command:** `.claude/commands/`, `.opencode/commands/`, and `.cursor/commands/`.
+
+## Step 7: Verify
+
+Before considering the blueprint done:
+
+1. Read back the BLUEPRINT.md and verify it meets the quality checklist from Step 4
+2. Read the scaffold command and verify it follows the pattern from Step 5
+3. Verify all files in files/ use proper placeholders (no hardcoded scopes or app names)
+4. Verify README.md and CHANGELOG.md are updated
+5. Show the user a summary of everything that was created
+
+## Tips for Good Blueprints
+
+- **Extract from real projects** — Blueprints that come from battle-tested code are always better than theoretical ones.
+- **Document the WHY** — The code is the easy part. The decisions and reasoning are what make AI-assisted scaffolding intelligent.
+- **Keep it focused** — One blueprint, one problem. If you're tempted to add "and also X", that's probably a separate blueprint.
+- **Include the monorepo wiring** — Package exports, workspace dependencies, turbo tasks, root scripts. This is always the part people get wrong, and it's where the blueprint adds the most value.
+- **Think about maintenance** — What breaks silently if you forget to run something? Those are your maintenance hooks.
+- **Use existing blueprints as your quality bar** — Read auth-better-auth before writing yours. Match that level of detail.