@withmata/blueprints 0.2.0

package/.cursor/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/.cursor/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.

package/.cursor/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.