@claude-code-mastery/starter-kit 1.2.0 → 1.2.1

package/.claude/skills/mongodb-rules/SKILL.md

@@ -59,4 +59,7 @@ Non-negotiable for this codebase. From production, not preference.
 
 ## Schema
 
-- **Collections enforce no structure by default.** Add a `$jsonSchema` validator as a collection stabilizes and more code depends on its shape. Roll out safely: `validationAction: "warn"` to observe first, then `error`; `validationLevel: "moderate"` to spare existing nonconforming documents.
+Collections enforce no structure by default, so validate in two layers.
+
+- **Parse before every write.** Validate each document against its Zod schema right before it hits the database, so a malformed shape never lands. The schema itself isn't Mongo-specific, it's the same contract the API and frontend use, see the `schema-source-of-truth` skill for defining it once and deriving every layer from one base.
+- **Keep a `$jsonSchema` collection validator as the floor.** Zod only guards writes that go through your app, so the DB validator is the last line that also catches mongosh, scripts, and other services. Add it as a collection stabilizes and more code depends on its shape. Roll out safely: `validationAction: "warn"` to observe first, then `error`; `validationLevel: "moderate"` to spare existing nonconforming documents.

package/.claude/skills/schema-source-of-truth/SKILL.md

@@ -0,0 +1,50 @@
+---
+name: schema-source-of-truth
+description: One canonical Zod schema per entity, reused across the stack instead of redeclared at each layer. Use whenever defining or changing a data shape, a TypeScript type or interface for an entity, an API request/response validator, an Express body/query/params check, a frontend form validator, or a DB document shape. Catches the same-entity-defined-four-times drift. TypeScript-first, derive types and per-layer variants from one base instead of hand-writing parallel copies.
+when_to_use: |
+  - Defining or editing an entity's shape (a User, Order, etc.) in types, an API, a form, or the DB
+  - Writing API request/response validation or Express middleware that checks req.body / query / params
+  - Writing a frontend form validator, or a TypeScript interface/type for data that also lives on the backend
+  - Any moment you're about to write a second definition of a shape that already exists somewhere
+  - Do NOT use for one-off internal types with no cross-layer counterpart
+---
+
+# Schema as a Single Source of Truth
+
+A data entity should be defined once, as a Zod schema, and everything else derived from it. The failure pattern to kill: declaring the same entity separately at each layer, a frontend `interface User`, a backend `interface User`, a hand-written API validator, and a manual Mongo `$jsonSchema`. Four shapes for one entity, kept in sync by hand, guaranteed to drift the first time a field is added or renamed.
+
+## One schema per entity, derive the rest
+
+Define the canonical schema once and generate every other representation from it:
+
+- **TypeScript type:** `type User = z.infer<typeof UserSchema>`. Never hand-write an `interface` that parallels a schema, infer it so it can't fall out of sync.
+- **API validation:** parse `req.body` / `req.query` / `req.params` through the schema in middleware. `safeParse` and return 400 on failure, no field-by-field `if` checks.
+- **Frontend forms:** the same schema drives form validation (`zodResolver` with react-hook-form), so client and server reject the same inputs by the same rules.
+- **Pre-write guard:** parse before writing to the DB. See the `mongodb-rules` skill for the Mongo-specific parse-before-write and `$jsonSchema` floor.
+- **OpenAPI and `$jsonSchema`:** generate them from the schema (`zod-to-openapi`, `zod-to-json-schema`) rather than maintaining them by hand.
+
+Zod is TypeScript-first with zero runtime dependencies, so this costs one small library and removes every duplicated definition.
+
+## One base, many variants (they are not identical)
+
+"Same schema everywhere" is the goal, but a create payload is not the stored document and a response is not the request, so don't pretend they're one object. Model it honestly: one base schema, with per-layer variants derived from it, sharing a single origin while differing where they genuinely must.
+
+```typescript
+const UserSchema = z.object({
+  _id: z.string(),
+  email: z.string().email(),
+  name: z.string().min(1),
+  createdAt: z.date(),
+});
+
+const CreateUser   = UserSchema.omit({ _id: true, createdAt: true }); // POST body
+const UpdateUser   = CreateUser.partial();                            // PATCH body
+const UserResponse = UserSchema.extend({ displayName: z.string() });  // adds computed field
+type User = z.infer<typeof UserSchema>;
+```
+
+Derive variants with `.omit()`, `.partial()`, `.pick()`, `.extend()`. When the base gains a field, every variant inherits it automatically, which is the entire point. A hand-copied variant is just the drift problem at smaller scale.
+
+## Make it physically shared
+
+Single source of truth only holds if there is literally one file. Put entity schemas in a shared module both sides import, a `packages/schemas` workspace, or a shared `src/schemas/` reachable by frontend and backend. If each side keeps its own copy, they diverge no matter how disciplined the intent. The shared import is the enforcement, not the convention.

package/README.md

@@ -1,6 +1,6 @@
 # @claude-code-mastery/starter-kit
 
-A Claude Code toolkit that installs 27 commands, 10 skills, 10 hooks, and scaffolding templates into Claude Code globally - so every project you open already has them available.
+A Claude Code toolkit that installs 27 commands, 11 skills, 10 hooks, and scaffolding templates into Claude Code globally - so every project you open already has them available.
 
 **Requires:** Node.js 20+ and [Claude Code](https://claude.ai/code)
 
@@ -25,7 +25,7 @@ After `init`, your `~/.claude/` directory looks like this:
 ├── starter-kit/                  <- package files live here (single source of truth)
 │   ├── commands/                 <- 27 slash commands
 │   ├── hooks/                    <- 10 lifecycle hooks
-│   ├── skills/                   <- 10 skill files
+│   ├── skills/                   <- 11 skill files
 │   └── .starter-kit/             <- scaffolding templates for /new-project
 ├── commands/
 │   ├── new-project.md  -> (symlink to starter-kit/commands/new-project.md)
@@ -84,6 +84,7 @@ Skills are expertise files Claude loads when relevant. These install automatical
 - `create-service` - scaffolding patterns for new services
 - `mcp-builder` - MCP server development patterns
 - `terminal-tui` - Ink + React TUI patterns, resize handling
+- `schema-source-of-truth` - one canonical Zod schema per entity, derived across all layers; catches the same shape defined four times drift
 
 ---
 

package/README.npm.md

@@ -1,6 +1,6 @@
 # @claude-code-mastery/starter-kit
 
-A Claude Code toolkit that installs 27 commands, 10 skills, 10 hooks, and scaffolding templates into Claude Code globally - so every project you open already has them available.
+A Claude Code toolkit that installs 27 commands, 11 skills, 10 hooks, and scaffolding templates into Claude Code globally - so every project you open already has them available.
 
 **Requires:** Node.js 20+ and [Claude Code](https://claude.ai/code)
 
@@ -25,7 +25,7 @@ After `init`, your `~/.claude/` directory looks like this:
 ├── starter-kit/                  <- package files live here (single source of truth)
 │   ├── commands/                 <- 27 slash commands
 │   ├── hooks/                    <- 10 lifecycle hooks
-│   ├── skills/                   <- 10 skill files
+│   ├── skills/                   <- 11 skill files
 │   └── .starter-kit/             <- scaffolding templates for /new-project
 ├── commands/
 │   ├── new-project.md  -> (symlink to starter-kit/commands/new-project.md)
@@ -84,6 +84,7 @@ Skills are expertise files Claude loads when relevant. These install automatical
 - `create-service` - scaffolding patterns for new services
 - `mcp-builder` - MCP server development patterns
 - `terminal-tui` - Ink + React TUI patterns, resize handling
+- `schema-source-of-truth` - one canonical Zod schema per entity, derived across all layers; catches the same shape defined four times drift
 
 ---
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@claude-code-mastery/starter-kit",
-  "version": "1.2.0",
+  "version": "1.2.1",
   "description": "Production-ready Claude Code starter kit — commands, hooks, skills, and agents for AI-assisted development",
   "type": "module",
   "publishConfig": {