@withmata/blueprints 0.3.2 → 0.3.3

package/.claude/skills/scaffold-auth/SKILL.md

@@ -138,7 +138,7 @@ Based on the project structure, project context, and user answers, adapt the blu
   - Replace `{{APP_NAME}}`, `{{EMAIL_FROM}}`, `{{SCOPE}}`
 - Copy/adapt `files/server/auth-db.ts` -> `apis/server/src/db/auth.ts`
 - Copy/adapt `files/server/middleware.ts` -> `apis/server/src/middleware/auth.ts`
-- Merge auth env vars into `apis/server/src/env.ts`
+- Merge auth env vars into `apis/server/src/env.ts` (if env-t3 is installed, this uses `@t3-oss/env-core` with Zod schemas — add vars to the `server` schema object)
 
 **If single-repo:**
 - Copy/adapt `files/server/auth.ts` -> `src/lib/auth/index.ts`
@@ -146,7 +146,7 @@ Based on the project structure, project context, and user answers, adapt the blu
   - Adjust DB import to use direct path: `import { db } from "@/db/auth/client"` or `#db/auth/client`
 - Copy/adapt `files/server/auth-db.ts` -> `src/lib/db/auth.ts`
 - Default to Next.js API routes (no separate Hono server)
-- Merge auth env vars into existing `env.ts` (or create one)
+- Merge auth env vars into existing env files. If env-t3 is installed (check for `src/env/server.ts`), add server vars to `src/env/server.ts` and client vars to `src/env/client.ts`. Otherwise merge into `env.ts` (or create one).
 
 **Both:**
 - If the project uses a different server framework than Hono, adapt the middleware while keeping the core `auth.api.getSession({ headers })` pattern

package/.claude/skills/scaffold-foundation/SKILL.md

@@ -7,18 +7,34 @@ description: Set up a Turborepo + pnpm monorepo skeleton (skip for single-repo a
 
 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
+This skill operates in two modes:
 
-Read the full foundation blueprint and all template files:
+- **Install mode** (default) — fresh scaffold of the full monorepo skeleton
+- **Upgrade mode** — detects an existing foundation install and offers to apply updates (new features added to blueprints since the original install)
+
+## Step 1: Read the Blueprints
+
+Read the foundation blueprint and all template files:
 
 ```
 ~/.withmata/blueprints/blueprints/foundation/monorepo-turbo/BLUEPRINT.md
 ~/.withmata/blueprints/blueprints/foundation/monorepo-turbo/files/**/*
 ```
 
+Also read the feature blueprints that foundation can optionally include:
+
+```
+~/.withmata/blueprints/blueprints/features/env-t3/BLUEPRINT.md
+~/.withmata/blueprints/blueprints/features/env-t3/files/**/*
+~/.withmata/blueprints/blueprints/features/tailwind-v4/BLUEPRINT.md
+~/.withmata/blueprints/blueprints/features/tailwind-v4/files/**/*
+~/.withmata/blueprints/blueprints/features/ui-shared-components/BLUEPRINT.md
+~/.withmata/blueprints/blueprints/features/ui-shared-components/files/**/*
+```
+
 If not found, run `npx @withmata/blueprints` to install.
 
-The BLUEPRINT.md contains the full architecture documentation, naming conventions, folder conventions, and file manifest. Follow it precisely.
+The BLUEPRINT.md files contain the full architecture documentation, naming conventions, folder conventions, and file manifests. Follow them precisely.
 
 ## Step 2: Read Project Context
 
@@ -26,12 +42,48 @@ 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 it has a Foundation section already**: **switch to upgrade mode** (see Step 2b below).
+
+- **If no context file exists**: that is fine. Ask the user directly for the product name and npm scope. Proceed with install mode.
+
+### Step 2b: Upgrade Mode Detection
+
+When foundation is already installed, compare what's currently in the project against what the blueprints now offer. Check for:
+
+1. **Foundation file updates** — Compare each foundation template file against the installed version. Flag files where the blueprint template has changed (e.g., updated `turbo.json` task structure, new fields in `package.json`).
+
+2. **Missing features** — Check `.project-context.md` Installed Blueprints for:
+   - `env-t3` — Is it installed? If not, apply it automatically (env validation is not optional).
+   - `tailwind-v4` + `ui-shared-components` — Are they installed? If not, flag as available (frontend UI is optional).
+
+3. **Present findings to the user:**
+
+   ```
+   Foundation was installed on <date>. Here's what's available:
 
-- **If no context file exists**: that is fine. Ask the user directly for the product name and npm scope.
+   Updates to existing files:
+     ☐ turbo.json — new task caching strategy
+     ☐ apps/web/next.config.ts — updated config pattern
+
+   Auto-applying:
+     ✓ Validated environment variables (env-t3) — type-safe env with client/server split
+
+   New features (not yet installed):
+     ☐ Frontend UI setup (tailwind-v4 + ui-shared-components) — full design system and shared component library
+
+   Which would you like to apply?
+   ```
+
+4. Apply only what the user selects. For each selected feature, follow its blueprint's integration steps (adapted to the existing project). Skip configuration questions where the answer is already in `.project-context.md`.
+
+5. Update `.project-context.md` with the newly installed features and update `foundation_completed` date.
+
+After upgrade mode completes, skip to Step 7 (Summarize).
 
 ## Step 3: Understand Current State
 
+*(Install mode only — skipped in upgrade mode)*
+
 Explore the target project directory:
 
 - Is it empty? Fresh start — scaffold everything.
@@ -40,12 +92,20 @@ Explore the target project directory:
 
 ## Step 4: Ask Configuration Questions
 
-Only three questions — skip any already answered by project context:
+*(Install mode only — skipped in upgrade mode)*
+
+Core 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`.
 
+Optional feature question — ask after the core questions:
+
+4. **Frontend UI** — "Will this project have frontend work? If yes, I'll set up the full Tailwind design system and a shared UI component library (`packages/ui/`) with shadcn/ui. (Y/n)" Default: yes. If yes, applies both tailwind-v4 and ui-shared-components together.
+
+**Note:** Validated environment variables (env-t3) are always set up — not optional. Every app gets type-safe env validation.
+
 ## Step 5: Scaffold
 
 Create the monorepo skeleton by adapting all files from the blueprint. Replace placeholders:
@@ -66,7 +126,7 @@ From `files/root/`, create at project root:
 
 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
+- `config/tailwind-config/` — shared-styles.css, postcss.config.mjs, package.json
 
 ### 5c. Next.js App Shell
 
@@ -93,9 +153,73 @@ After creating all files:
 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 5.5: Optional Features
+
+Apply the optional features the user said yes to in Step 4. Each feature follows its own blueprint's integration steps but within the same session — no need to run separate scaffold commands.
+
+### 5.5a. Environment Variables (always applied)
+
+Follow the `env-t3` blueprint's integration steps:
+
+1. Create `apps/web/src/env/client.ts` and `apps/web/src/env/server.ts` from env-t3 templates
+2. Replace the foundation's `apps/web/env.ts` with the split pattern
+3. Update `apps/web/next.config.ts` — replace `import "./env"` with:
+   ```typescript
+   import "./src/env/server";
+   import "./src/env/client";
+   ```
+4. Create `apps/web/.env.example` from env-t3 template — replace `{{APP_NAME}}`
+5. Create `apps/web/.env.local` (empty)
+6. Ensure `@t3-oss/env-nextjs` and `zod` are in `apps/web/package.json` dependencies
+
+### 5.5b. Frontend UI Setup (if opted in)
+
+When the user opts in to frontend work, apply both tailwind-v4 and ui-shared-components together as a single step.
+
+**Tailwind design system** — follow the `tailwind-v4` blueprint's integration steps:
+
+1. Replace `config/tailwind-config/shared-styles.css` with the full version from the tailwind-v4 blueprint (includes `tw-animate-css`, `shadcn/tailwind.css`, `tailwind-scrollbar-hide`, sidebar tokens, chart tokens)
+2. Merge tailwind-v4 dependencies into `config/tailwind-config/package.json`:
+   - Add `@tailwindcss/typography`, `shadcn`, `tailwind-scrollbar-hide`, `tw-animate-css` to `dependencies`
+
+**Shared UI package** — follow the `ui-shared-components` blueprint's integration steps:
+
+1. Create `packages/ui/` with all files from the ui blueprint:
+   - `package.json` — replace `{{SCOPE}}`
+   - `tsconfig.json` — replace `{{SCOPE}}`
+   - `components.json`
+   - `styles/globals.css` — replace `{{SCOPE}}`
+   - `utils/cn.ts`
+   - `utils/cva.ts`
+2. Create empty directories: `packages/ui/components/ui/`, `packages/ui/icons/`, `packages/ui/icons/logos/`
+3. Update `apps/web/app/globals.css` to import UI styles:
+   ```css
+   @import "tailwindcss";
+   @import "{{SCOPE}}/tailwind-config";
+   @import "{{SCOPE}}/ui/styles";
+   @plugin "@tailwindcss/typography";
+
+   @source "../../packages/ui";
+   ```
+   Compute the `@source` relative path based on the actual directory structure.
+
+### 5.5d. Re-install
+
+If any optional features were applied:
+1. Run `pnpm install` again to wire new workspace dependencies
+2. Verify `pnpm dev` still boots cleanly
+
 ## Step 6: Update Project Context
 
-Append the `## Foundation` section to `.project-context.md`:
+**This step is mandatory.** The `.project-context.md` file is how other blueprints and future runs of `/scaffold-foundation` (upgrade mode) know what's been set up. Without it, every subsequent blueprint runs blind.
+
+If `.project-context.md` does not exist, create it now:
+
+```markdown
+# Project Context
+```
+
+Then append the `## Foundation` section:
 
 ```yaml
 ## Foundation
@@ -103,10 +227,11 @@ monorepo_tool: turborepo
 package_manager: pnpm
 npm_scope: "<scope>"
 node_version: ">=22"
+project_type: monorepo
 workspaces:
   apps: ["web"]
   apis: []
-  packages: []
+  packages: ["ui"]  # if frontend UI was applied, otherwise []
   config: ["typescript-config", "tailwind-config"]
 framework: next.js (app router)
 typescript: strict
@@ -117,11 +242,20 @@ 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.
+Then append `## Installed Blueprints` with entries for every feature that was applied:
+
+```markdown
+## Installed Blueprints
+```
+
+- Always add the `env-t3` project context block (see env-t3 BLUEPRINT.md)
+- If frontend UI was applied: add both the `tailwind-v4` and `ui-shared-components` project context blocks (see their BLUEPRINT.md files)
+
+**Verify the file exists and is well-formed before proceeding to Step 7.** If it's missing or empty, that is a bug — fix it before summarizing.
 
-### Create Maintenance Skill
+### Create Maintenance Skills
 
-Create a project-level maintenance skill for the monorepo foundation:
+Create the foundation maintenance skill:
 
 **File:** `<project>/.claude/skills/monorepo-maintenance/SKILL.md`
 
@@ -141,19 +275,35 @@ user-invocable: false
 - Keep `turbo.json` tasks with `cache: false` for any task with side effects (migrations, code generation)
 ```
 
+Also create maintenance skills:
+- Always create `env-maintenance/SKILL.md` (see scaffold-env skill for template)
+- If frontend UI: create both `tailwind-maintenance/SKILL.md` and `ui-maintenance/SKILL.md` (see scaffold-tailwind and scaffold-ui skills for templates)
+
 ## Step 7: Summarize
 
 Tell the user:
 
-- Project structure overview (directory tree)
+### Install Mode Summary
+
+- Project structure overview (directory tree — include optional features that were applied)
 - What was configured (scope, Node version, tooling)
+- Which optional features were included
 - 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."
+- If frontend UI was set up: how to add shadcn components (`cd packages/ui && pnpm dlx shadcn@latest add button`)
+- Available feature blueprints to install next: `/scaffold-db`, `/scaffold-auth`
+
+### Upgrade Mode Summary
+
+- What was updated (list files that changed)
+- What new features were added (env, tailwind, UI)
+- Any manual steps remaining
+- Suggest next steps based on what's still not installed
 
 ## 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.
+- In upgrade mode, be conservative — only modify files that the blueprints own. Don't touch user-customized files (check for differences from the template before replacing).
+- If the user has customized colors in `shared-styles.css` or added variables to `env.ts`, ask before replacing. Offer to merge their customizations into the new version.
 - Feature blueprints will add scripts to root `package.json` and tasks to `turbo.json` — the foundation provides the base that they extend.
+- The individual `/scaffold-env`, `/scaffold-tailwind`, and `/scaffold-ui` skills still exist for projects that didn't use foundation or want to add features later. The foundation's optional feature steps follow the same blueprints — no duplication.

package/dist/index.js

@@ -6,7 +6,7 @@ import pc3 from "picocolors";
 
 // src/constants.ts
 var API_URL = process.env["WITHMATA_API_URL"] || "https://blueprints.withmata.dev";
-var VERSION = "0.3.2";
+var VERSION = "0.3.3";
 
 // src/steps/auth.ts
 import { log } from "@clack/prompts";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@withmata/blueprints",
-  "version": "0.3.2",
+  "version": "0.3.3",
   "description": "Set up AI-powered project blueprints for Claude Code, OpenCode, and Cursor",
   "type": "module",
   "bin": {