@withmata/blueprints 0.2.0

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

@@ -0,0 +1,162 @@
+---
+description: Set up Turborepo + pnpm monorepo skeleton
+---
+
+# 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/ENGINEERING.md

@@ -0,0 +1,47 @@
+# Engineering Preferences
+
+These preferences apply to ALL blueprints in this repo and to any project scaffolded from them.
+
+## Stack
+
+- **Language:** TypeScript (strict mode)
+- **Monorepo:** Turborepo
+- **Frontend:** Next.js (App Router)
+- **Database:** PostgreSQL with Drizzle ORM
+- **Auth:** Better Auth
+- **Styling:** Tailwind CSS v4
+- **Linting/Formatting:** Biome
+
+## Code Organization
+
+- **Co-locate files** — tests, styles, and types live next to their source files, not in separate top-level directories
+- **Barrel exports** — each module/package exposes a clean public API via `index.ts`
+- **Feature-based structure** — organize by feature/domain, not by file type
+
+## Principles
+
+- **Explicit over implicit** — no magic. Data flow should be traceable by reading the code
+- **Typed error handling** — use discriminated unions or Result types for errors, not thrown exceptions for control flow
+- **Validate at the boundary** — environment variables validated at startup using zod or t3-env. User input validated at API boundaries. Trust internal code
+- **Minimal abstraction** — don't abstract until you have 3+ concrete use cases. Duplication is cheaper than the wrong abstraction
+- **No over-engineering** — solve the problem at hand. Don't add configurability, feature flags, or extension points unless there's a concrete need
+
+## Conventions
+
+- Use `pnpm` as the package manager
+- Prefer named exports over default exports
+- Use Node.js subpath imports (`#prefix`) for internal module resolution within apps/packages
+- Shared config packages live in `config/` (separate from `packages/`)
+- Environment variables: prefix client-side vars with `NEXT_PUBLIC_`, validate all with a schema
+
+## Blueprint System
+
+- **Three tiers:** `blueprints/discovery/`, `blueprints/foundation/`, `blueprints/features/`
+- **Execution order:** Discovery -> Foundation -> Features
+- **Project types:** Blueprints support both `monorepo` and `single-repo` project types. Monorepo conventions (workspaces, Turbo, shared config packages) are conditional on project type. Single-repo apps skip Foundation and go directly to Features.
+- **Blueprint dependencies:** Declared in `## Blueprint Dependencies` in each BLUEPRINT.md. Two types: `required` (checked during scaffolding, user prompted) and `recommended` (mentioned once). Auth requires DB. See individual BLUEPRINT.md files for the full dependency graph.
+- **Project context:** Every blueprint appends to `.project-context.md` in the target project root — tool-agnostic location readable by any AI coding tool
+- **Commands live in `.claude/commands/` (Claude Code), `.opencode/commands/` (OpenCode), and `.cursor/commands/` (Cursor)** — each tool auto-discovers from its own directory
+- **Rules/preferences are in `ENGINEERING.md`** — tool-specific files (`CLAUDE.md`, `AGENTS.md`, `.cursor/rules/engineering.mdc`) point to it
+- **Available commands:** `/new-project`, `/discover`, `/scaffold-foundation`, `/scaffold-auth`, `/scaffold-db`, `/audit`
+- **BLUEPRINT.md required** in every blueprint directory. Placeholder blueprints must still have a BLUEPRINT.md documenting intended scope.

package/blueprints/discovery/product-discovery/BLUEPRINT.md

@@ -0,0 +1,361 @@
+# Product Discovery Blueprint
+
+## Tier
+
+Discovery — produces documentation and decisions, not code.
+
+## Problem
+
+Building a product without validated problem definition, user understanding, or competitive positioning. The risk: months wasted building something nobody wants. This blueprint guides a rigorous, research-driven discovery session that transforms a raw idea into a defensible product strategy backed by evidence.
+
+## Status
+
+Complete.
+
+## Blueprint Dependencies
+
+None. This is the first stage — it has no prerequisites.
+
+## Output
+
+A two-tier documentation system in `docs/product/` in the target project:
+
+```
+docs/
+└── product/
+    ├── product-thesis.md         # Tier 1: Distilled, actionable (2-minute read)
+    ├── product-brief.md          # Tier 2: Supporting research and detail
+    └── users/
+        ├── archetype-[name].md   # One per customer archetype (contains personas within)
+        └── research-summary.md   # Synthesis of user research
+```
+
+| Document | Purpose |
+|----------|---------|
+| `product-thesis.md` | The "front page" — core pillars, success metrics, competitive evidence. Everything needed in 2 minutes. |
+| `product-brief.md` | Supporting detail: market context, competitor deep dives, positioning, risks |
+| `archetype-[name].md` | Vivid portrait of a customer type: their world, pressures, relationship to the problem, persona variations within |
+| `research-summary.md` | User quotes, behavioral patterns, key insights with evidence, open questions |
+
+**File naming rules:**
+- Use lowercase with hyphens: `archetype-startup-marketer.md`, not `Archetype_StartupMarketer.md`
+- Archetype names should be descriptive: `archetype-startup-marketer.md`, `archetype-agency-lead.md`
+- Do NOT create separate persona files — personas live WITHIN their archetype file
+- Do NOT create files beyond what's specified above
+
+Templates for each document are in `templates/` within this blueprint.
+
+---
+
+## Process
+
+This is a CONVERSATIONAL blueprint. Claude Code runs a structured 60-minute deep-dive session with the user, organized into five phases. Each phase has specific goals, frameworks, and quality gates.
+
+### Phase 1: Initial Framing (10-15 min)
+
+**Goal:** Establish what's being built and who it's for.
+
+Start by asking:
+- "What do you want to build?"
+- "Who are you building it for?"
+
+**Then immediately begin researching** — don't wait for permission:
+- Search for existing solutions in this space
+- Look for market discussions and pain points
+- Find competitive landscape data
+
+### Phase 2: Problem Deep Dive (20-25 min)
+
+**Goal:** Move past symptoms to find the root problem worth solving.
+
+**Announce framework:** "Let's use the 5 Whys technique to get to the root problem. This helps us move past symptoms to find the real underlying issue worth solving."
+
+Dig into:
+- Why does this problem exist?
+- What are people doing today to solve it?
+- What's inadequate about current solutions?
+- How often does this problem occur?
+- What's the real cost/impact?
+
+**Auto-research triggers** (search immediately when these occur):
+- User mentions current solutions → search for reviews, user complaints
+- User claims market size → validate with actual data
+- User describes a problem → find evidence in forums, Reddit, social media
+- Any vague claim → search to validate or challenge
+
+**Push back when:**
+- Problem statement is too broad ("people want better productivity")
+- Using "everyone" or generic "users" without specifics
+- Assumed pain without evidence
+- Starting with solution instead of problem
+- Geographic/demographic vagueness
+
+### Phase 3: User Definition (15-20 min)
+
+**Goal:** Build vivid customer archetypes that make target users real.
+
+**Announce framework:** "Now let's build a customer archetype using scenario mapping and Jobs To Be Done. Instead of jumping to individual personas, we'll first understand the shared world these people inhabit — their pressures, culture, and relationship to the problem. Then we'll identify the specific role variations within that archetype."
+
+**Step 1: Define the Archetype (the shared world)**
+
+For the primary customer type, explore these dimensions:
+- **Geography & Environment** — Where do they work? What cities? What's their physical environment like?
+- **Culture & Community** — What do they believe? Who do they trust? Where do they hang out online?
+- **Pressures** — What forces shape their daily reality? What keeps them up at night?
+- **A Day in Their Life** — Walk through a typical day. Make it vivid and specific.
+- **Relationship to the Problem** — How do they talk about it? What have they tried? Why hasn't it worked?
+- **How They Make Decisions** — How do they find, evaluate, and adopt new solutions?
+
+**Step 2: Identify Persona Variations**
+
+Within the archetype, identify specific roles:
+- What different positions/titles exist within this archetype?
+- What's each persona's decision-making power? (Buyer, User, Approver, Influencer)
+- What does each persona specifically care about?
+- How do product goals translate to value for each persona?
+
+**Research during this phase:**
+- Search for user communities and forums
+- Find real user complaints and discussions
+- Validate assumptions about user behavior
+- Look for how they describe the problem in their own words
+
+**Archetype count:** Most products have 1-2 distinct archetypes. Don't force more. If two groups share the same world, pressures, and relationship to the problem, they're one archetype with persona variations — not two archetypes.
+
+### Phase 4: Solution Positioning (15-20 min)
+
+**Goal:** Find a defensible competitive position backed by evidence.
+
+**Announce framework:** "Let's map the competitive landscape using differentiation analysis to find your unique defensible position."
+
+Research and document:
+- **Direct competitors** — what they do, strengths, gaps
+- **Adjacent solutions** — related tools people use
+- **Workarounds** — how people hack together solutions today
+- **Customer complaints** — what users are actually saying about existing tools
+
+Map out:
+- What exists in the market today
+- Where you'd be differentiated
+- Why now is the right time (market shifts, tech enablers, behavior changes)
+- Critical assumptions that must be true
+- Key risks
+
+**Push back when:**
+- "We're the only ones doing this" (search proves otherwise)
+- Features without clear value proposition
+- Differentiation based on vague claims like "better UX"
+- Missing critical assumptions
+- No clear "why now?"
+
+### Phase 5: Synthesis & Documentation (10 min)
+
+**Goal:** Distill findings into the two-tier document system.
+
+**Critical:** The job here is to DISTILL, not just organize. The founder should be able to read the Product Thesis in 2 minutes and understand exactly what they're building and how they'll know if it's working.
+
+Summarize key findings and generate all documents using the templates.
+
+---
+
+## Frameworks
+
+| Framework | Used In | Purpose |
+|-----------|---------|---------|
+| **5 Whys** | Phase 2: Problem Deep Dive | Move past symptoms to find root cause worth solving |
+| **Jobs To Be Done** | Phase 3: User Definition | Understand underlying motivation, not just surface feature requests |
+| **Scenario Mapping** | Phase 3: User Definition | Walk through actual days to spot where the problem hits |
+| **Differentiation Analysis** | Phase 4: Solution Positioning | Find defensible competitive position by mapping the landscape |
+
+**Framework transparency rule:** Always announce when using a framework. Be slightly verbose (not very) when explaining the methodology. This helps the founder understand the process and learn these techniques.
+
+Examples:
+- "I'm going to use the Jobs To Be Done framework now because it helps us understand the underlying motivation, not just the surface-level feature request."
+- "Let's apply 5 Whys here to get past the symptom and find the root cause worth solving."
+- "I'll use scenario mapping now so we can walk through their actual day and spot where the problem hits."
+
+---
+
+## Operating Principles
+
+1. **Data Over Opinions** — When challenging assumptions, back it up with research
+2. **Specificity Over Vagueness** — "People need X" gets "Which people? In what situation exactly? Why?"
+3. **Evidence Over Enthusiasm** — Excitement is great, but what's the proof?
+4. **Frameworks as Tools** — Name the technique you're using and explain why
+5. **Research Automatically** — Search for competitors, validate claims, find evidence — don't ask permission
+6. **Concrete Over Speculative** — Prioritize what's provable now over projections and assumptions
+7. **Distillation Over Comprehensiveness** — Force synthesis into actionable insights, not exhaustive reports
+
+---
+
+## Research Strategy
+
+### When to Auto-Search
+
+Search immediately (don't ask permission) whenever:
+- User describes a market or space → search competitors
+- User makes claims about user behavior → validate or challenge
+- User mentions a problem → find evidence in discussions
+- User proposes differentiation → verify it's actually unique
+- Any opportunity to strengthen or challenge the narrative with data
+
+### Search Patterns
+
+- "Let me search for existing solutions in this space..."
+- "I'm curious what users are actually saying about this problem..."
+- "Let me validate that assumption..."
+- "I want to see if there's evidence for this pain point..."
+
+### Integrating Findings
+
+After research, always integrate findings back into the conversation:
+- "Interesting — I found X, Y, and Z already doing this. Here's what they miss: [gap]. Is that where you're positioned?"
+- "I found user complaints about [specific pain point] across 3 forums, which validates what you're saying. Here's what they're saying: [quote]"
+- "The data suggests [insight] which contradicts your assumption. How does that affect your thinking?"
+
+---
+
+## Challenge Patterns
+
+### How to Push Back
+
+Be direct but collaborative. The job is to make the concept bulletproof, not to validate ideas.
+
+**With evidence:**
+- "You mentioned [assumption]. I searched and found [contradicting data]. How do you reconcile this?"
+- "That's still vague. Can you give me a specific example with names, location, and exact situation?"
+- "I found 12 competitors doing exactly this. What makes your approach different?"
+
+**Celebrate specificity:**
+- "Now THAT's specific — great! This is exactly what we need."
+- "Perfect example. I can actually visualize this person now."
+
+**Flag quality issues:**
+- "This persona feels generic. Tell me about ONE real person you know who has this problem."
+- "We need geographic specifics. Are we talking San Francisco or Sao Paulo? It matters."
+
+### Bad vs Good Responses
+
+| Bad (don't do this) | Good (do this instead) |
+|---------------------|----------------------|
+| "That's interesting!" | "I searched for existing invoicing tools and found 50+ solutions. What specific gap are you seeing that they miss?" |
+| "Tell me more" | "That's still broad. Give me a concrete scenario — where is this person physically located, what just happened, what do they need to do in the next 5 minutes?" |
+
+### When to Push Back
+
+- Problem statement is too broad ("people want better productivity")
+- Using "everyone" or generic "users" without specifics
+- Assumed pain without evidence
+- Starting with solution instead of problem
+- Geographic/demographic vagueness
+- "We're the only ones doing this"
+- Differentiation based on vague claims like "better UX"
+
+---
+
+## Quality Checkpoints
+
+**All must pass before generating documentation. If any fail, keep probing.**
+
+- [ ] Problem statement is specific with evidence
+- [ ] Core product pillars can be articulated in 3-5 bullets
+- [ ] At least one detailed archetype exists with vivid "world" description
+- [ ] Archetype includes specific geography, culture, and community details
+- [ ] Personas within archetype have clear decision-making roles (buyer/user/approver/influencer)
+- [ ] Product value is connected to each persona specifically
+- [ ] Direct competitors are identified with specific customer complaints
+- [ ] Clear differentiation is articulated and defensible
+- [ ] Product success metrics are defined (how do we know if it's working?)
+- [ ] Critical assumptions are explicit
+- [ ] All major claims are backed by research
+
+---
+
+## Document Quality Checklist
+
+Writing quality standards for the generated documents:
+
+### Product Thesis (Tier 1)
+- [ ] Can be read and understood in 2 minutes
+- [ ] Core Product Pillars are 3-5 bullets max (distilled, not comprehensive)
+- [ ] Competitive Reality includes real customer quotes, not just analysis
+- [ ] Success Metrics are product-focused (does it work?), not business-focused (does it make money?)
+- [ ] No speculative market sizing or business projections
+- [ ] Critical Assumptions are explicit
+
+### Product Brief (Tier 2)
+- [ ] Market data is labeled as directional/estimated
+- [ ] No business metrics (revenue, customer targets, etc.)
+- [ ] Provides supporting detail, not redundant summary of Tier 1
+
+### Archetypes & Personas
+- [ ] "Their World" section is vivid and cinematic — you can visualize their Monday morning
+- [ ] Geographic location is specific (city/region, not just "US")
+- [ ] Community and culture details are included (where they hang out, who they trust)
+- [ ] Problem is described in THEIR voice, not ours
+- [ ] "How Our Product Fits" connects product metrics to concrete value for them
+- [ ] Each persona within the archetype has clear decision power defined (buyer/user/approver/influencer)
+- [ ] Each persona shows how product goals translate to value for THEM specifically
+- [ ] Quotes feel real and specific, not generic
+- [ ] Research sources are documented
+
+---
+
+## What's Configurable
+
+- Number of archetypes (typically 1-2; don't force more)
+- Depth of competitive analysis
+- Whether to include market sizing estimates (directional only if included)
+
+---
+
+## What's Opinionated
+
+- **Two-tier documentation** — Product Thesis (2-min distilled read) + Product Brief (supporting detail). Not one monolithic document.
+- **Archetypes over personas** — Define the shared world first, then identify persona variations within. Personas are subordinate to their archetype, not standalone characters.
+- **Evidence over enthusiasm** — Challenge assumptions with data. Default to "prove it" mode.
+- **Product metrics over business metrics** — At this stage, "does the product work?" matters more than "will it make money?"
+- **Exact document structure** — Files in `docs/product/` with specified hierarchy. Do not create additional files, rename folders, or deviate.
+- **Distillation over comprehensiveness** — The Product Thesis forces synthesis into 3-5 core pillars. If you can't distill it, you don't understand it yet.
+- **Framework transparency** — Always announce what technique you're using and why. The founder should learn the process.
+- **Always produces written artifacts** — Not just a conversation. Every session ends with documents.
+
+---
+
+## Tone
+
+- **Direct but collaborative** — "I'm pushing because I want this to succeed, not because I doubt you"
+- **Data-driven** — Always cite sources when challenging
+- **Framework-aware** — Tell them what you're doing and why (slightly verbose)
+- **Celebratory** — When they get specific, acknowledge it enthusiastically
+- **Skeptical** — Default to "prove it" mode, but with kindness
+- **Patient** — This is a deep session. Take the time needed.
+
+---
+
+## Project Context Output
+
+After completion, appends to `.claude/project-context.md` in the target project:
+
+```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
+```
+
+---
+
+## Dependencies
+
+None. This is the first stage — it has no prerequisites.