@withmata/blueprints 0.3.5 → 0.4.0

package/.claude/skills/audit/SKILL.md

@@ -13,7 +13,7 @@ Run a health check against available blueprints. Analyze this project's current
 Load all available blueprint specs to understand what is possible:
 
 ```
-~/.withmata/blueprints/blueprints/discovery/product-discovery/BLUEPRINT.md
+~/.withmata/blueprints/blueprints/discovery/*/BLUEPRINT.md
 ~/.withmata/blueprints/blueprints/foundation/monorepo-turbo/BLUEPRINT.md
 ~/.withmata/blueprints/blueprints/features/*/BLUEPRINT.md
 ```
@@ -41,10 +41,10 @@ Regardless of whether project context exists, explore the actual project to unde
 ### 3b. Project Structure & Type
 
 - **Detect project type:**
-  - **Monorepo indicators**: `pnpm-workspace.yaml`, `turbo.json`, `nx.json`, `lerna.json`, or `"workspaces"` in root `package.json`
+  - **Monorepo indicators**: `turbo.json`, `"workspaces"` in root `package.json`, `pnpm-workspace.yaml`, `nx.json`, or `lerna.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`
+- What package manager? Check for `bun.lock`, `pnpm-lock.yaml`, `yarn.lock`, `package-lock.json`
 - 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`
@@ -323,7 +323,7 @@ Blueprint upgrades:
 Skipped:
   ○ ui-shared-components — not selected
 
-Next: run pnpm install to pick up new dependencies.
+Next: run bun install to pick up new dependencies.
 ──────────────────────────────────────────────
 ```
 

package/.claude/skills/blueprint-catalog/SKILL.md

@@ -13,12 +13,14 @@ user-invocable: false
 | Blueprint | Tier | What it does | Dependencies | Skill |
 |-----------|------|-------------|--------------|-------|
 | Product Discovery | Discovery | Structured session producing product thesis, user archetypes, and competitive analysis. No code. | None | `/discover` |
-| Monorepo Foundation | Foundation | Turborepo + pnpm monorepo with Next.js, Biome, TypeScript strict, Tailwind v4. | None | `/scaffold-foundation` |
+| Marketing Copywriting | Discovery | Conversion-focused page copy (landing, pricing, about, features) with psychology frameworks, variations, and educational annotations. | product-discovery (recommended) | `/copywrite`, `/copywrite-landing` |
+| Design System | Discovery | Visual identity definition: colors, typography, spacing, shadows, component guidelines. Outputs actual Tailwind v4 CSS tokens. | product-discovery (recommended) | `/design-system` |
+| Monorepo Foundation | Foundation | Turborepo + bun monorepo with Next.js, Biome, TypeScript strict, Tailwind v4. | None | `/scaffold-foundation` |
 | Database | Feature | Drizzle ORM + PostgreSQL: schema groups, per-group migrations, seed scripts. | None | `/scaffold-db` |
 | Authentication | Feature | Better Auth + Drizzle + PostgreSQL: social login, email/password, organizations, role-based permissions. | Database | `/scaffold-auth` |
 | Environment Variables | Feature | T3 Env + Zod: validated, type-safe env vars for Next.js (client/server split) and backend apps. | None | `/scaffold-env` |
-| Tailwind v4 Design System | Feature | Full design system: shadcn tokens, animations, typography, sidebar/chart tokens, dark mode. | Foundation (recommended) | `/scaffold-tailwind` |
-| UI Shared Components | Feature | Shared UI package: shadcn/ui, path-based exports, cn utility, component generation. | Tailwind v4 | `/scaffold-ui` |
+| Tailwind v4 Design System | Feature | Full Tailwind v4 upgrade: shadcn tokens, shadows, easing, animations, sidebar/chart tokens, dark mode. Auto-detects `/design-system` output. | Foundation (recommended) | `/scaffold-tailwind` |
+| UI Shared Components | Feature | 31 base components (Base UI + Phosphor): compound patterns, form system, app shell, data display. Auto-installs Tailwind. | Tailwind v4 (auto-installed) | `/scaffold-ui` |
 
 ## Project Context
 
@@ -30,7 +32,13 @@ Suggest a blueprint when you observe these signals. Be helpful, not pushy — me
 
 **`/discover`** — User describes a new product idea, asks "what should I build", is unsure about scope or target users, is non-technical or building their first product, or project has no product documentation.
 
-**`/scaffold-foundation`** — User wants to set up a monorepo, mentions Turborepo or project structure, or project has no `turbo.json` / `pnpm-workspace.yaml`. Best after discovery. Skip for single-repo apps.
+**`/copywrite`** — User mentions landing page copy, marketing page, pricing page copy, about page copy, or wants help writing page content. For landing pages specifically, suggest `/copywrite-landing` instead (deeper CRO frameworks).
+
+**`/copywrite-landing`** — User mentions landing page, homepage copy, conversion optimization, or wants to write a high-converting landing page. Reads from product discovery automatically when available.
+
+**`/design-system`** — User mentions visual identity, brand colors, design tokens, font choices, custom theme, "make it look unique", or wants to move beyond the default shadcn aesthetic. Best after discovery. Output is consumed by `/scaffold-tailwind` automatically.
+
+**`/scaffold-foundation`** — User wants to set up a monorepo, mentions Turborepo or project structure, or project has no `turbo.json` / `"workspaces"` in root `package.json`. Best after discovery. Skip for single-repo apps.
 
 **`/scaffold-db`** — User mentions database, Drizzle, PostgreSQL, schemas, migrations, or needs a structured db layer. Or is writing raw SQL or using an ORM without organized schemas.
 
@@ -48,12 +56,14 @@ Suggest a blueprint when you observe these signals. Be helpful, not pushy — me
 
 Discovery → Foundation → Features is the recommended flow, but blueprints can be applied at any stage.
 
-- **New project, no code:** Start with `/discover` (especially for non-technical users) or `/scaffold-foundation` (for monorepos)
+- **New project, no code:** Start with `/discover` (product definition), then optionally `/copywrite-landing` (marketing copy) and `/design-system` (visual identity), then `/scaffold-foundation` (monorepo) or go straight to features (single-repo)
 - **Single-repo project:** Skip foundation — go directly to feature blueprints (`/scaffold-db`, `/scaffold-auth`)
 - **Has monorepo, missing features:** Suggest specific feature blueprints
 - **Existing project:** Feature blueprints adapt to existing structures — no foundation required
-- **Dependencies:** `/scaffold-auth` works best after `/scaffold-db` (auth builds on db patterns). `/scaffold-ui` requires `/scaffold-tailwind`. Install dependencies first.
-- **Environment setup:** `/scaffold-env` is recommended for all projects — it's standalone and works with any combination of other blueprints
+- **Want unique visual identity:** Run `/design-system` — it outputs Tailwind tokens that `/scaffold-tailwind` auto-detects
+- **Need marketing pages:** Run `/copywrite-landing` for landing pages, `/copywrite` for other pages (pricing, about, features)
+- **Dependencies:** `/scaffold-auth` works best after `/scaffold-db` (auth builds on db patterns). `/scaffold-ui` auto-installs `/scaffold-tailwind`. `/scaffold-tailwind` auto-detects design system tokens.
+- **Environment setup:** `/scaffold-env` is recommended for all projects — it's standalone
 
 ## Important
 

package/.claude/skills/copywrite/SKILL.md

@@ -0,0 +1,187 @@
+---
+name: copywrite
+description: Write conversion-focused marketing page copy with psychology-backed frameworks and educational annotations
+---
+
+# Write Marketing Page Copy
+
+Write structured, conversion-focused marketing copy for any page type: pricing, about, features, team, careers, changelog, and more. Every section is annotated with the psychology and framework behind it so the user learns marketing through the output.
+
+This skill covers general marketing pages. For landing pages and homepages, redirect to `/copywrite-landing`.
+
+## Step 1: Read the Blueprint
+
+Read the full copywriting blueprint:
+
+```
+~/.withmata/blueprints/blueprints/discovery/marketing-copywriting/BLUEPRINT.md
+```
+
+If not found, run `npx @withmata/blueprints` to install.
+
+The BLUEPRINT.md contains the complete methodology: page-type section sequences, copywriting frameworks, psychology principles, and the Seven Sweeps editing process. Follow it precisely.
+
+## Step 2: Read Context
+
+Check if `.project-context.md` exists in the target project root. If it contains a `## Product Discovery` section, read the product docs:
+
+- `docs/product/product-thesis.md` — for pillars, positioning, value prop
+- `docs/product/product-brief.md` — for competitive landscape, differentiation
+- `docs/product/users/archetype-*.md` — for customer language, pain points, desires, "In Their Voice" quotes
+
+Map discovery findings to copywriting context:
+
+- Product thesis pillars become the key benefits to emphasize
+- Archetype "Their World" + "The Problem in Their Words" become problem/pain section content
+- Archetype "What They Care About Most" drives benefit prioritization
+- Competitive landscape informs differentiation claims and objection handling
+- "In Their Voice" quotes supply customer language to weave into copy
+
+If no product docs exist, note what context is missing. Gather it conversationally in Step 3.
+
+## Step 3: Understand the Page
+
+Ask these questions. Skip any already answered by product docs:
+
+1. **"What page are you writing?"** — pricing, about, features, team, careers, changelog, or describe it
+2. **"What's the primary goal?"** — what action should visitors take? (sign up, book demo, learn about team, explore features, etc.)
+3. **"Who's the audience for THIS specific page?"** — pre-fill from archetypes if available, confirm or refine
+4. **"What tone fits?"** — casual/conversational, professional but friendly, technical/precise, playful/bold. Derive from product docs if brand voice is defined.
+5. **"Any specific content that MUST be included?"** — e.g., specific features for a feature page, specific team members for a team page, specific plans for pricing
+
+If product docs exist, present a summary of what you pulled and ask: "Here's what I'm working from — [summarize context]. Anything to adjust or add?"
+
+## Step 4: Generate Page Structure
+
+Based on the page type, select the appropriate section sequence from the blueprint. Present a structure sketch for approval before writing:
+
+```
+Here's the structure I recommend for your [page type]:
+
+1. **Hero** — [what this section will accomplish]
+   *Why first: [psychology reasoning]*
+
+2. **[Section 2]** — [purpose]
+   *Why here: [reasoning]*
+
+... etc
+
+Does this structure feel right, or should we adjust before I write the copy?
+```
+
+Wait for confirmation. Do not proceed to writing until the user approves or adjusts the structure.
+
+## Step 5: Write Copy Section by Section
+
+For each section, generate:
+
+- The actual copy text
+- An annotation explaining the framework/psychology behind the choices
+- For key elements (headlines, CTAs, hero text): 2-3 variations with rationale
+
+**Annotation format for every section:**
+
+```
+*Why this works: [Name the specific framework or psychology principle]. [Explain in 1-2 sentences why this technique is effective for this audience/product]. [Note any product-specific reasoning from the discovery docs].*
+```
+
+**Variation format for key elements:**
+
+```
+**Primary (recommended):**
+> [copy text]
+*Why: [reasoning]*
+
+**Alternative A** — [angle description]:
+> [copy text]
+*Best when: [context]*
+
+**Alternative B** — [angle description]:
+> [copy text]
+*Best when: [context]*
+```
+
+Generate 2-3 meaningfully different angles, not slight word swaps. Each variation should represent a different strategic choice.
+
+Use customer language from archetypes when available. Bridge every feature to a benefit with "which means..."
+
+## Step 6: Quality Pass — Seven Sweeps
+
+Run the Seven Sweeps copy editing framework against the generated copy:
+
+1. **Clarity** — flag anything not immediately understandable
+2. **Voice & Tone** — flag any inconsistencies with the chosen tone
+3. **"So What?"** — flag features presented without benefits
+4. **"Prove It"** — flag unsupported claims (suggest where to add testimonials or stats; never fabricate them)
+5. **Specificity** — flag vague language, suggest concrete alternatives
+6. **Heightened Emotion** — flag purely informational sections near decision points
+7. **Zero Risk** — flag missing risk reversals near CTAs
+
+Include the sweep results in the output document under "## Copy Editing Notes". Fix what can be fixed inline; call out what needs user input (e.g., real testimonials, actual stats).
+
+## Step 7: Output
+
+Create `docs/pages/` in the target project if it does not exist. Write the page copy to `docs/pages/{page-name}.md` using this structure:
+
+```markdown
+# {Page Name} — {Page Type} Copy
+
+## Context
+- **Page type:** [type]
+- **Primary goal:** [conversion action]
+- **Target audience:** [from product docs or conversation]
+- **Tone:** [chosen tone]
+- **Product discovery:** [Yes — linked to docs/product/ | No — context gathered conversationally]
+
+## Page Structure Sketch
+[Section-by-section layout with spacing/hierarchy notes.
+Not pixel-perfect, but sketch-level: what goes where, relative sizing, visual weight.
+Describe the visual flow a developer would need to build this page.]
+
+## Copy by Section
+
+### 1. Hero
+[Headlines with variations, subheadline, primary CTA, supporting micro-copy.
+Each with full annotations.]
+
+### 2. [Section 2]
+[Copy + annotations]
+
+... [all sections]
+
+## Copy Editing Notes
+[Results of Seven Sweeps — what was flagged, what was improved, what needs user input (e.g., real testimonials to add)]
+
+## Meta Content
+- **Page title:** [SEO-optimized, 60 chars max]
+- **Meta description:** [155 chars max, includes CTA]
+- **OG title:** [for social sharing]
+- **OG description:** [for social sharing]
+```
+
+Update `.project-context.md` under `## Installed Blueprints`. If a `### marketing-copywriting` entry already exists, update `pages_created` to include the new page. Otherwise append:
+
+```yaml
+### marketing-copywriting
+blueprint: marketing-copywriting
+pages_created:
+  - docs/pages/{page-name}.md
+```
+
+## Step 8: Summary
+
+Tell the user:
+
+- What page was created and where the file lives
+- Key copywriting decisions and the reasoning behind them
+- Top 3 things the user should customize with real data (e.g., "Replace the placeholder testimonial with a real customer quote")
+- Suggested next steps ("Run `/copywrite-landing` for your homepage", "Add real testimonials to strengthen the social proof section")
+
+## Important Rules
+
+- **Never fabricate testimonials, stats, or customer quotes.** Use placeholder format: `[Testimonial: Customer name, role — what they'd say about {specific benefit}]`. The user fills these in with real data.
+- **Always explain WHY.** Every section, every headline choice, every CTA — annotate with the framework and psychology behind it. The user is learning marketing through these outputs.
+- **Use customer language when available.** If archetypes have "In Their Voice" quotes, weave that language into the copy. It converts because it feels like the visitor wrote it themselves.
+- **Don't over-sell.** Honest, specific claims convert better than sensational ones. If the product can't back a claim, don't make it.
+- **Variations are for comparison, not volume.** Each variation should represent a different strategic choice, not a slight word swap.
+- **For landing pages, redirect to `/copywrite-landing`.** If the user asks for a landing page or homepage, suggest: "Landing pages benefit from deeper frameworks. Want to use `/copywrite-landing` instead? It includes CRO analysis and traffic source matching."