@withmata/blueprints 0.3.3 → 0.3.5

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

@@ -36,19 +36,53 @@ If not found, run `npx @withmata/blueprints` to install.
 
 The BLUEPRINT.md files contain the full architecture documentation, naming conventions, folder conventions, and file manifests. Follow them precisely.
 
-## Step 2: Read Project Context
+## Step 1.5: 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**: **switch to upgrade mode** (see Step 2b below).
+- **If it has a Foundation section already**: switch to upgrade mode (Step 1.6).
 
 - **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
+## Step 1.6: Upgrade Mode
 
-When foundation is already installed, compare what's currently in the project against what the blueprints now offer. Check for:
+When foundation is already installed, run migrations first, then check for template updates and missing features.
+
+### 1.6a: System Migrations
+
+Check for legacy patterns from older blueprint versions and offer to migrate them. Run these checks in order:
+
+**Migration: Separate maintenance skills → consolidated `project-maintenance/`**
+
+Scan `.claude/skills/` in the project for individual maintenance skill directories:
+- `auth-maintenance/`
+- `db-maintenance/`
+- `env-maintenance/`
+- `tailwind-maintenance/`
+- `ui-maintenance/`
+- `monorepo-maintenance/`
+
+If any are found:
+1. Read each `SKILL.md` to extract the maintenance rules (the `### {name} maintenance` sections)
+2. Create (or update) `.claude/skills/project-maintenance/SKILL.md` with the consolidated frontmatter and all extracted sections
+3. Remove the old individual directories
+4. Report: "Migrated {n} separate maintenance skills into one `project-maintenance/SKILL.md`"
+
+**Migration: `foundation_completed` → `installed_at`**
+
+Check `.project-context.md` for `foundation_completed:` under `## Foundation`. If found, rename the field to `installed_at:`.
+
+**Future migrations go here.** Each migration should:
+- Check for the legacy pattern
+- Only run if the legacy pattern is detected (idempotent)
+- Report what was changed
+- Be safe to run multiple times (no-op if already migrated)
+
+### 1.6b: Template Updates and Missing Features
+
+After migrations, compare what's currently in the project against what the blueprints now offer:
 
 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`).
 
@@ -61,6 +95,10 @@ When foundation is already installed, compare what's currently in the project ag
    ```
    Foundation was installed on <date>. Here's what's available:
 
+   Migrations applied:
+     ✓ Consolidated 4 maintenance skills into project-maintenance/SKILL.md
+     ✓ Renamed foundation_completed → installed_at in project context
+
    Updates to existing files:
      ☐ turbo.json — new task caching strategy
      ☐ apps/web/next.config.ts — updated config pattern
@@ -76,11 +114,11 @@ When foundation is already installed, compare what's currently in the project ag
 
 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.
+5. Update `.project-context.md` with the newly installed features and update `installed_at` date.
 
 After upgrade mode completes, skip to Step 7 (Summarize).
 
-## Step 3: Understand Current State
+## Step 2: Understand Current State
 
 *(Install mode only — skipped in upgrade mode)*
 
@@ -239,7 +277,7 @@ linter: biome
 styling: tailwind-v4
 env_validation: t3-env + zod
 module_resolution: node subpath imports (#prefix)
-foundation_completed: <date>
+installed_at: <date>
 ```
 
 Then append `## Installed Blueprints` with entries for every feature that was applied:
@@ -253,19 +291,25 @@ Then append `## Installed Blueprints` with entries for every feature that was ap
 
 **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 Skills
+### Create Maintenance Skill
+
+All blueprints share a single project-level maintenance skill. Create or append to:
 
-Create the foundation maintenance skill:
+**File:** `<project>/.claude/skills/project-maintenance/SKILL.md`
 
-**File:** `<project>/.claude/skills/monorepo-maintenance/SKILL.md`
+If the file does not exist, create it with the frontmatter header:
 
 ```yaml
 ---
-name: monorepo-maintenance
-description: Maintenance rules for the Turborepo monorepo foundation. Invoke when modifying workspace configs, shared packages, or Turbo tasks.
+name: project-maintenance
+description: Maintenance rules for all installed blueprints. Invoke when modifying schemas, env vars, auth config, workspace configs, UI components, or Tailwind tokens.
 user-invocable: false
 ---
+```
 
+Then append sections for each blueprint applied in this run. Foundation always adds:
+
+```markdown
 ### 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`
@@ -273,11 +317,32 @@ user-invocable: false
 - 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)
+
+### env-t3 maintenance
+- After adding a new env var: add it to the env schema file (client.ts or server.ts), `.env.example`, and `.env.local`
+- NEXT_PUBLIC_* vars go in env/client.ts with explicit runtimeEnv mapping; server vars go in env/server.ts
+- After removing an env var: remove from schema, .env.example, and .env.local
+- Never access process.env directly — always use the typed env objects (clientEnv, serverEnv, or env)
+- Keep .env.example documented with section headers and local/production hints
 ```
 
-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)
+If frontend UI was applied, also append:
+
+```markdown
+### tailwind-v4 maintenance
+- After adding a new color: add CSS variable to both :root and .dark selectors in shared-styles.css, then map in @theme inline
+- After adding a new app: import the tailwind-config package in the app's globals.css
+- After upgrading Tailwind: check for @import, @theme, or @custom-variant breaking changes
+- Never use tailwind.config.js — all configuration is CSS-based in shared-styles.css
+- Colors use OKLCH color space — do not use hex or RGB
+
+### ui-shared-components maintenance
+- Add shadcn components via `pnpm dlx shadcn@latest add <name>` from packages/ui/
+- Use cn() for all className composition — never concatenate class strings manually
+- Internal imports use #prefix (#components/ui/button); cross-package imports use @scope/ui/components/ui/button
+- After adding a new export directory: add to both exports and imports in packages/ui/package.json
+- After adding a new consuming app: add @import and @source directive to the app's globals.css
+```
 
 ## Step 7: Summarize
 

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

@@ -29,6 +29,29 @@ Check if `.project-context.md` exists in the target project root:
   - Use this to determine if `config/tailwind-config/` exists
 
 - **If it does not exist**: proceed normally — explore the project manually
+- **If `tailwind-v4` is in Installed Blueprints**: switch to upgrade mode (Step 1.6)
+
+## Step 1.6: Upgrade Mode
+
+If `tailwind-v4` is found in `.project-context.md` under `## Installed Blueprints`, switch to upgrade mode.
+
+1. **Read installed state** — from project context, get `files_modified`, `choices`, and `installed_at`
+2. **Compare templates against installed files:**
+   - `config/tailwind-config/shared-styles.css` — compare against current blueprint template. Look for new imports (`@import`), new tokens in `@theme inline`, new CSS variables in `:root` and `.dark`, new base layer rules.
+   - `config/tailwind-config/package.json` — compare dependencies. Look for new or updated packages.
+3. **Present findings:**
+   ```
+   tailwind-v4 was installed on <date>. Checking for updates...
+
+   Updated files:
+     ☐ shared-styles.css — new tokens added (e.g., new sidebar variants, chart colors)
+     ☐ package.json — new dependency: <package>
+
+   Apply updates?
+   ```
+4. **Apply selectively** — `shared-styles.css` is a blueprint-owned file (users customize colors but the structure is ours). For color value changes, ask before overwriting. For new token additions (new `--color-*` vars), safe to append.
+5. **Update project context** — update `installed_at` date
+6. **Skip to Step 6 (Output Summary)**
 
 ## Step 2: Understand the Target Project
 
@@ -111,6 +134,7 @@ Append an entry to `.project-context.md` under `## Installed Blueprints`:
 ```yaml
 ### tailwind-v4
 blueprint: tailwind-v4
+installed_at: <date>
 choices:
   include_sidebar_tokens: <true|false>
   include_chart_tokens: <true|false>
@@ -127,17 +151,21 @@ packages_added:
 
 ### Create Maintenance Skill
 
-Create a project-level maintenance skill:
+Append to the shared project-level maintenance skill at `<project>/.claude/skills/project-maintenance/SKILL.md`.
 
-**File:** `<project>/.claude/skills/tailwind-maintenance/SKILL.md`
+If the file does not exist, create it with frontmatter:
 
 ```yaml
 ---
-name: tailwind-maintenance
-description: Maintenance rules for Tailwind v4 design system. Invoke when modifying theme tokens, colors, or adding new apps.
+name: project-maintenance
+description: Maintenance rules for all installed blueprints. Invoke when modifying schemas, env vars, auth config, workspace configs, UI components, or Tailwind tokens.
 user-invocable: false
 ---
+```
 
+Then append:
+
+```markdown
 ### tailwind-v4 maintenance
 - After adding a new color: add CSS variable to both :root and .dark selectors in shared-styles.css, then map in @theme inline
 - After adding a new app: import the tailwind-config package in the app's globals.css
@@ -146,6 +174,8 @@ user-invocable: false
 - Colors use OKLCH color space — do not use hex or RGB
 ```
 
+If a `### tailwind-v4 maintenance` section already exists in the file, skip — do not duplicate.
+
 ## Step 6: Output Summary
 
 ### Packages Added

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

@@ -32,6 +32,41 @@ Check if `.project-context.md` exists in the target project root:
 
 When project context provides clear answers, skip the corresponding questions in Step 3.
 
+If `ui-shared-components` is in Installed Blueprints, switch to upgrade mode (Step 1.6).
+
+## Step 1.6: Upgrade Mode
+
+If `ui-shared-components` is found in `.project-context.md` under `## Installed Blueprints`, switch to upgrade mode.
+
+1. **Read installed state** — from project context, get `files_created`, `choices`, and `installed_at`
+2. **Compare templates against installed files:**
+   - `packages/ui/package.json` — compare exports, imports, dependencies. Look for new export patterns, updated deps.
+   - `packages/ui/components.json` — compare shadcn config. Look for updated aliases or style changes.
+   - `packages/ui/utils/cn.ts` — compare utility implementation.
+   - `packages/ui/utils/cva.ts` — compare CVA re-export.
+   - `packages/ui/styles/globals.css` — compare style imports.
+   - `packages/ui/tsconfig.json` — compare TypeScript config.
+   - Check consuming app `globals.css` — verify `@import` and `@source` directives are present and correct.
+3. **Present findings:**
+   ```
+   ui-shared-components was installed on <date>. Checking for updates...
+
+   Updated files:
+     ☐ packages/ui/package.json — new export patterns or dependencies
+     ☐ packages/ui/components.json — updated shadcn configuration
+
+   New files:
+     ☐ packages/ui/utils/cva.ts — new utility (didn't exist in previous version)
+
+   Unchanged:
+     ✓ packages/ui/utils/cn.ts — no changes
+
+   Apply updates?
+   ```
+4. **Apply selectively** — `package.json` exports and `components.json` are blueprint-owned. `components/ui/` files are user-owned (shadcn-generated) — never touch those.
+5. **Update project context** — update `installed_at` date
+6. **Skip to Step 6 (Output Summary)**
+
 ## Step 2: Understand the Target Project
 
 ### 2a. Detect Project Type
@@ -128,6 +163,7 @@ Append an entry to `.project-context.md` under `## Installed Blueprints`:
 ```yaml
 ### ui-shared-components
 blueprint: ui-shared-components
+installed_at: <date>
 choices:
   shadcn_style: <style>
   icon_library: <library>
@@ -142,17 +178,21 @@ packages_added:
 
 ### Create Maintenance Skill
 
-Create a project-level maintenance skill:
+Append to the shared project-level maintenance skill at `<project>/.claude/skills/project-maintenance/SKILL.md`.
 
-**File:** `<project>/.claude/skills/ui-maintenance/SKILL.md`
+If the file does not exist, create it with frontmatter:
 
 ```yaml
 ---
-name: ui-maintenance
-description: Maintenance rules for shared UI component library. Invoke when adding components, icons, or modifying the UI package.
+name: project-maintenance
+description: Maintenance rules for all installed blueprints. Invoke when modifying schemas, env vars, auth config, workspace configs, UI components, or Tailwind tokens.
 user-invocable: false
 ---
+```
 
+Then append:
+
+```markdown
 ### ui-shared-components maintenance
 - Add shadcn components via `pnpm dlx shadcn@latest add <name>` from packages/ui/
 - Use cn() for all className composition — never concatenate class strings manually
@@ -161,6 +201,8 @@ user-invocable: false
 - After adding a new consuming app: add @import and @source directive to the app's globals.css
 ```
 
+If a `### ui-shared-components maintenance` section already exists in the file, skip — do not duplicate.
+
 ## Step 6: Output Summary
 
 ### Packages to Install

package/ENGINEERING.md

@@ -43,5 +43,5 @@ These preferences apply to ALL blueprints in this repo and to any project scaffo
 - **Project context:** Every blueprint appends to `.project-context.md` in the target project root — tool-agnostic location readable by any AI coding tool
 - **Skills live in `.claude/skills/<name>/SKILL.md`** — single source of truth. Installed globally to `~/.claude/skills/`, `~/.config/opencode/skills/`, `~/.cursor/skills/` via the CLI. OpenCode and Cursor also read `~/.claude/skills/` as a cross-tool fallback.
 - **Rules/preferences are in `ENGINEERING.md`** — tool-specific files (`CLAUDE.md`, `AGENTS.md`, `.cursor/rules/engineering.mdc`) point to it
-- **Available skills:** `/new-project`, `/discover`, `/scaffold-foundation`, `/scaffold-auth`, `/scaffold-db`, `/audit`, plus `blueprint-catalog` (background, auto-invoked)
+- **Available skills:** `/new-project`, `/discover`, `/scaffold-foundation`, `/scaffold-env`, `/scaffold-tailwind`, `/scaffold-ui`, `/scaffold-auth`, `/scaffold-db`, `/audit`, plus `blueprint-catalog` (background, auto-invoked)
 - **BLUEPRINT.md required** in every blueprint directory. Placeholder blueprints must still have a BLUEPRINT.md documenting intended scope.

package/blueprints/features/auth-better-auth/BLUEPRINT.md

@@ -1,5 +1,9 @@
 # Auth Blueprint — Better Auth + Drizzle
 
+## Tier
+
+Feature
+
 ## Problem
 
 Full authentication and authorization for a TypeScript monorepo: multi-provider social login, email/password with verification, password reset, organization-based multi-tenancy with role-based permissions (owner/admin/member), invitation system, and session management with cookie-based route protection.

package/blueprints/features/db-drizzle-postgres/BLUEPRINT.md

@@ -551,6 +551,7 @@ Appends to `.project-context.md` under `## Installed Blueprints`:
 ```yaml
 ### db-drizzle-postgres
 blueprint: db-drizzle-postgres
+installed_at: <date>
 choices:
   schema_group: {{GROUP}}
   include_example: true|false

package/blueprints/features/env-t3/BLUEPRINT.md

@@ -297,6 +297,7 @@ Appends to `.project-context.md` under `## Installed Blueprints`:
 ```yaml
 ### env-t3
 blueprint: env-t3
+installed_at: <date>
 choices:
   nextjs_env_location: src/env/
   backend_env_location: src/env.ts

package/blueprints/features/tailwind-v4/BLUEPRINT.md

@@ -252,6 +252,7 @@ Appends to `.project-context.md` under `## Installed Blueprints`:
 ```yaml
 ### tailwind-v4
 blueprint: tailwind-v4
+installed_at: <date>
 choices:
   include_sidebar_tokens: true
   include_chart_tokens: true

package/blueprints/features/ui-shared-components/BLUEPRINT.md

@@ -338,6 +338,7 @@ Appends to `.project-context.md` under `## Installed Blueprints`:
 ```yaml
 ### ui-shared-components
 blueprint: ui-shared-components
+installed_at: <date>
 choices:
   shadcn_style: new-york
   icon_library: lucide

package/blueprints/foundation/monorepo-turbo/BLUEPRINT.md

@@ -372,7 +372,7 @@ linter: biome
 styling: tailwind-v4
 env_validation: t3-env + zod
 module_resolution: node subpath imports (#prefix)
-foundation_completed: <date>
+installed_at: <date>
 ```