start-vibing 3.0.8 → 3.0.9

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "start-vibing",
-	"version": "3.0.8",
+	"version": "3.0.9",
 	"description": "Setup Claude Code agents, skills, and hooks in your project. Smart copy that preserves your custom domains and configurations.",
 	"type": "module",
 	"bin": {

package/template/.claude/CLAUDE.md

@@ -9,8 +9,7 @@ This file provides detailed context for the development system. For user-facing
 ```
 .claude/
 ├── agents/          # 6 active subagents (flat structure)
-│   └── _archive/    # 82+ archived agents (unused, kept for reference)
-├── skills/          # 20 skill systems with cache
+├── skills/          # 26 skill systems with cache
 ├── scripts/         # Utility scripts (validate-skills.sh)
 ├── config/          # Project-specific configuration
 └── commands/        # Slash commands (feature, fix, research, validate)
@@ -48,7 +47,7 @@ implement -> quality gates -> domain-updater -> commit-manager -> complete
 
 ---
 
-## Skills (20 Active)
+## Skills (26 Active)
 
 Skills are auto-injected into context when the task matches their description. All use the imperative pattern for 95%+ auto-invocation.
 
@@ -73,6 +72,14 @@ Skills are auto-injected into context when the task matches their description. A
 | **security-scan** | API, auth, user data code | OWASP Top 10, Zod validation (HAS VETO POWER) |
 | **test-coverage** | After implementing features | Creates Vitest unit + Playwright E2E tests |
 | **final-check** | Before completing any task | Validates skills used, docs updated (HAS VETO POWER) |
+| **playwright-testing** | Playwright E2E tests | Page Objects, fixtures, multi-viewport patterns |
+| **test-infrastructure** | Test configs, data factories | Vitest config, MongoMemoryServer, cleanup |
+
+### Database Skills
+
+| Skill | Trigger | Description |
+|-------|---------|-------------|
+| **mongoose-patterns** | Mongoose models, queries, DB ops | Schema template, ESR indexes, aggregation, seeders |
 
 ### Infrastructure & DevOps Skills
 
@@ -91,6 +98,14 @@ Skills are auto-injected into context when the task matches their description. A
 | **docs-tracker** | After implementation | Detects modified files, creates/updates docs |
 | **research-cache** | Before web research | Checks cached findings to avoid redundant searches |
 | **ui-ux-audit** | Before UI features | Competitors, WCAG 2.1, responsiveness |
+| **api-docs** | After API/function changes | API docs, JSDoc, changelog management |
+
+### Meta & SEO Skills
+
+| Skill | Trigger | Description |
+|-------|---------|-------------|
+| **skill-creator** | Creating/editing skills | Interview, draft, test, iterate loop (from anthropics/skills) |
+| **claude-seo** | SEO analysis, audits, sitemaps | Full SEO suite with health scoring (from AgriciDaniel/claude-seo) |
 
 ---
 

package/template/.claude/skills/api-docs/SKILL.md

@@ -0,0 +1,206 @@
+---
+name: api-docs
+description: "ALWAYS invoke after creating or modifying API endpoints, exported functions, or releasing features. Do NOT skip API documentation, JSDoc comments, or changelog entries."
+allowed-tools: Read, Write, Edit, Bash, Grep, Glob
+---
+
+# API Documentation
+
+Patterns for API endpoint docs, JSDoc comments, and changelog management.
+
+## API Documentation Template
+
+````markdown
+## POST /api/users
+
+Create a new user.
+
+### Request
+
+**Headers:**
+| Header | Required | Description |
+|--------|----------|-------------|
+| Authorization | Yes | Bearer token |
+| Content-Type | Yes | application/json |
+
+**Body:**
+```json
+{
+  "email": "user@example.com",
+  "password": "Password123!",
+  "name": "John Doe"
+}
+```
+
+**Validation:**
+- email: Required, valid email format
+- password: Required, min 8 chars, 1 uppercase, 1 number
+- name: Required, 1-100 chars
+
+### Response
+
+**Success (201):**
+```json
+{
+  "id": "abc123",
+  "email": "user@example.com",
+  "name": "John Doe",
+  "createdAt": "2025-01-03T12:00:00Z"
+}
+```
+
+**Error (400):**
+```json
+{
+  "error": "Validation failed",
+  "details": [{ "field": "email", "message": "Invalid email format" }]
+}
+```
+````
+
+### Documentation Location
+
+```
+docs/api/
+├── README.md      # API overview
+├── auth.md        # Auth endpoints
+├── users.md       # User endpoints
+└── openapi.yaml   # OpenAPI spec (optional)
+```
+
+## OpenAPI Quick Reference
+
+```yaml
+openapi: 3.0.3
+info:
+  title: My API
+  version: 1.0.0
+paths:
+  /api/users:
+    post:
+      summary: Create user
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/CreateUser'
+      responses:
+        '201':
+          description: User created
+components:
+  schemas:
+    CreateUser:
+      type: object
+      required: [email, password, name]
+      properties:
+        email:
+          type: string
+          format: email
+        password:
+          type: string
+          minLength: 8
+```
+
+## JSDoc Patterns
+
+```typescript
+/**
+ * Creates a new user in the database.
+ *
+ * @param data - The user creation data
+ * @returns The created user document
+ * @throws {ValidationError} If data is invalid
+ * @throws {ConflictError} If email already exists
+ *
+ * @example
+ * ```typescript
+ * const user = await createUser({
+ *   email: 'user@example.com',
+ *   password: 'Password123!',
+ *   name: 'John Doe'
+ * });
+ * ```
+ */
+async function createUser(data: CreateUserInput): Promise<User> {
+  // Implementation
+}
+
+/** User creation input data. */
+interface CreateUserInput {
+  /** User email address (must be unique) */
+  email: string;
+  /** User password (min 8 chars, 1 uppercase, 1 number) */
+  password: string;
+  /** User display name */
+  name: string;
+}
+```
+
+| Tag | Usage |
+|-----|-------|
+| `@param` | Function parameter |
+| `@returns` | Return value |
+| `@throws` | Possible errors |
+| `@example` | Usage example |
+| `@deprecated` | Deprecated feature |
+| `@see` | Related docs |
+
+### When to Document
+
+- Public API functions
+- Complex algorithms
+- Non-obvious behavior
+- Exported types/interfaces
+
+## Changelog Management
+
+```markdown
+# Changelog
+
+Format: [Keep a Changelog](https://keepachangelog.com/en/1.1.0/)
+
+## [Unreleased]
+
+### Added
+- New feature description
+
+### Changed
+- Changed behavior description
+
+### Fixed
+- Bug fix description
+
+### Security
+- Security improvement
+
+## [1.0.0] - 2025-01-01
+
+### Added
+- Initial release features
+```
+
+| Category | Use When |
+|----------|----------|
+| Added | New features |
+| Changed | Existing functionality changes |
+| Deprecated | Soon-to-be-removed features |
+| Removed | Removed features |
+| Fixed | Bug fixes |
+| Security | Security fixes |
+
+### Versioning
+
+- **MAJOR** (1.0.0): Breaking changes
+- **MINOR** (0.1.0): New features, backwards compatible
+- **PATCH** (0.0.1): Bug fixes
+
+## Critical Rules
+
+1. **Include examples** — Request and response for every endpoint
+2. **List all errors** — Every possible error response code
+3. **Document validation** — Field requirements and constraints
+4. **Keep current** — Update docs when endpoints change
+5. **Explain why** — Not just what, in JSDoc comments
+6. **User perspective** — Write changelog for users, not devs
+7. **Always [Unreleased]** — Keep this section at top of changelog

package/template/.claude/skills/claude-seo/SKILL.md

@@ -0,0 +1,84 @@
+---
+name: claude-seo
+description: "ALWAYS invoke when doing SEO analysis, audits, schema markup, sitemaps, or content optimization. Do NOT skip SEO checks when building public-facing pages or marketing content."
+allowed-tools: Read, Write, Edit, Bash, Grep, Glob
+---
+
+# SEO Analysis
+
+Comprehensive SEO analysis for any website or business type.
+
+> Source: `AgriciDaniel/claude-seo` (adapted for project conventions)
+
+## Commands
+
+| Command | What it does |
+|---------|-------------|
+| `/seo audit <url>` | Full website audit with parallel analysis |
+| `/seo page <url>` | Deep single-page analysis |
+| `/seo sitemap <url>` | Analyze or generate XML sitemaps |
+| `/seo schema <url>` | Detect, validate, and generate Schema.org markup |
+| `/seo images <url>` | Image optimization analysis |
+| `/seo technical <url>` | Technical SEO audit (crawlability, indexability, CWV) |
+| `/seo content <url>` | E-E-A-T and content quality analysis |
+| `/seo geo <url>` | AI Overviews / Generative Engine Optimization |
+| `/seo plan <type>` | Strategic SEO planning by business type |
+
+## SEO Health Score (0-100)
+
+| Category | Weight |
+|----------|--------|
+| Technical SEO | 25% |
+| Content Quality (E-E-A-T) | 25% |
+| On-Page SEO | 20% |
+| Schema / Structured Data | 10% |
+| Performance (Core Web Vitals) | 10% |
+| Images | 5% |
+| AI Search Readiness | 5% |
+
+## Industry Detection
+
+- **SaaS**: pricing page, /features, /docs, "free trial"
+- **Local Service**: phone, address, service area, Google Maps
+- **E-commerce**: /products, /cart, "add to cart", product schema
+- **Publisher**: /blog, /articles, article schema, author pages
+- **Agency**: /case-studies, /portfolio, client logos
+
+## Audit Workflow
+
+1. Detect business type from homepage signals
+2. Run parallel analysis: technical, content, schema, sitemap, performance
+3. Generate unified report with SEO Health Score
+4. Create prioritized action plan (Critical → High → Medium → Low)
+
+## Priority Levels
+
+- **Critical**: Blocks indexing or causes penalties (immediate fix)
+- **High**: Significantly impacts rankings (fix within 1 week)
+- **Medium**: Optimization opportunity (fix within 1 month)
+- **Low**: Nice to have (backlog)
+
+## Quality Gates
+
+- Never recommend HowTo schema (deprecated Sept 2023)
+- FAQ schema only for government and healthcare sites
+- All Core Web Vitals references use INP, never FID
+- Warn at 30+ location pages (enforce 60%+ unique content)
+- Hard stop at 50+ location pages (require user justification)
+
+## AI Search Readiness (GEO)
+
+Check accessibility for AI crawlers:
+- GPTBot, ClaudeBot, PerplexityBot in robots.txt
+- llms.txt compliance
+- Brand mention signals
+- Passage-level citability
+
+## Critical Rules
+
+1. **INP not FID** — FID is deprecated, always use INP for Core Web Vitals
+2. **No HowTo schema** — Deprecated since Sept 2023
+3. **E-E-A-T framework** — Experience, Expertise, Authoritativeness, Trustworthiness
+4. **Parallel analysis** — Run all audit categories simultaneously
+5. **Business-type aware** — Tailor recommendations to industry
+6. **GEO included** — Always check AI search readiness alongside traditional SEO

package/template/.claude/skills/mongoose-patterns/SKILL.md

@@ -0,0 +1,188 @@
+---
+name: mongoose-patterns
+description: "ALWAYS invoke when creating or editing Mongoose models, queries, or database operations. Do NOT write MongoDB code without checking schema, index, and query patterns first."
+allowed-tools: Read, Write, Edit, Bash, Grep, Glob
+---
+
+# Mongoose Patterns
+
+Comprehensive patterns for Mongoose schemas, indexes, queries, aggregations, and seeders.
+
+## Schema Template
+
+```typescript
+// types/[entity].ts — ALL interfaces in types/ folder
+export interface I[Entity] {
+  field1: string;
+  field2: number;
+  createdAt: Date;
+  updatedAt: Date;
+}
+
+export interface I[Entity]Document extends I[Entity], Document {
+  comparePassword(password: string): Promise<boolean>;
+}
+
+export interface I[Entity]Model extends Model<I[Entity]Document> {
+  findByEmail(email: string): Promise<I[Entity]Document | null>;
+}
+```
+
+```typescript
+// src/models/[entity].model.ts
+import type { I[Entity]Document, I[Entity]Model } from '$types/[entity]';
+
+const [Entity]Schema = new Schema<I[Entity]Document, I[Entity]Model>(
+  {
+    field1: {
+      type: String,
+      required: [true, 'Field1 is required'],
+      trim: true,
+      maxlength: [100, 'Max 100 characters'],
+    },
+  },
+  {
+    timestamps: true,
+    collection: '[entities]',
+    toJSON: {
+      transform: (_, ret) => {
+        delete ret.password;
+        delete ret.__v;
+        return ret;
+      },
+    },
+  }
+);
+```
+
+## Index Strategy (ESR Rule)
+
+Order compound indexes by: **Equality → Sort → Range**
+
+```typescript
+// Query: { status: "active", createdAt: { $gt: date } }.sort({ score: -1 })
+// Index: { status: 1, score: -1, createdAt: 1 }
+//        [Equality] [Sort]     [Range]
+
+UserSchema.index({ email: 1 }, { unique: true });
+UserSchema.index({ role: 1, isActive: 1 });  // Compound
+UserSchema.index({ createdAt: 1 }, { expireAfterSeconds: 86400 }); // TTL
+UserSchema.index({ name: 'text', bio: 'text' }); // Text search
+UserSchema.index({ nickname: 1 }, { sparse: true }); // Only non-null
+```
+
+| Type | Syntax | Use Case |
+|------|--------|----------|
+| Single | `{ field: 1 }` | Frequent queries |
+| Compound | `{ a: 1, b: -1 }` | Multi-field queries |
+| Unique | `{ unique: true }` | No duplicates |
+| Text | `{ field: 'text' }` | Full-text search |
+| TTL | `{ expireAfterSeconds: N }` | Auto-expire |
+| Sparse | `{ sparse: true }` | Only index non-null |
+| Partial | `{ partialFilterExpression: {} }` | Conditional index |
+
+## Query Optimization
+
+```typescript
+// Use .lean() for read-only (2-5x faster)
+const users = await User.find({}).select('name email').lean();
+
+// Use .exists() instead of findOne for checks
+const exists = await User.exists({ email });
+
+// Selective population
+await Order.find({}).populate('user', 'name email');
+
+// Cursor for large datasets
+const cursor = User.find({}).cursor();
+for await (const user of cursor) { /* ... */ }
+
+// Batch operations
+await Model.insertMany(items);
+await Model.bulkWrite([
+  { insertOne: { document: { ... } } },
+  { updateOne: { filter: { ... }, update: { ... } } },
+]);
+
+// Use $in over $or
+await User.find({ status: { $in: ['active', 'pending'] } });
+
+// Pagination with count (parallel)
+const [items, total] = await Promise.all([
+  Model.find(query).skip((page - 1) * limit).limit(limit).lean(),
+  Model.countDocuments(query),
+]);
+```
+
+## Aggregation Patterns
+
+```typescript
+// Paginated search with $facet
+const [result] = await Product.aggregate([
+  { $match: { $text: { $search: query } } },
+  {
+    $facet: {
+      data: [
+        { $sort: { score: { $meta: 'textScore' } } },
+        { $skip: (page - 1) * limit },
+        { $limit: limit },
+      ],
+      total: [{ $count: 'count' }],
+    },
+  },
+  {
+    $project: {
+      items: '$data',
+      total: { $arrayElemAt: ['$total.count', 0] },
+    },
+  },
+]);
+
+// Sales report grouped by day
+await Order.aggregate([
+  { $match: { createdAt: { $gte: start, $lte: end }, status: 'completed' } },
+  {
+    $group: {
+      _id: { $dateToString: { format: '%Y-%m-%d', date: '$createdAt' } },
+      totalSales: { $sum: '$total' },
+      orderCount: { $sum: 1 },
+      avgOrderValue: { $avg: '$total' },
+    },
+  },
+  { $sort: { _id: 1 } },
+]);
+```
+
+**Performance**: $match first, use indexes, $project early, $facet for parallel ops, allowDiskUse for large datasets.
+
+## Seeder Pattern
+
+```typescript
+// scripts/seed/index.ts
+async function seed() {
+  await mongoose.connect(process.env['MONGODB_URI']!);
+  // Clear children before parents
+  await Promise.all([
+    mongoose.connection.collection('orders').deleteMany({}),
+    mongoose.connection.collection('products').deleteMany({}),
+    mongoose.connection.collection('users').deleteMany({}),
+  ]);
+  const users = await seedUsers();
+  const products = await seedProducts();
+  await seedOrders(users, products);
+  await mongoose.disconnect();
+}
+```
+
+## Critical Rules
+
+1. **Types in `types/`** — Interfaces separate from schema (I[Entity], I[Entity]Document, I[Entity]Model)
+2. **`select: false`** for passwords — Hide sensitive fields by default
+3. **`toJSON.transform`** — Remove password, __v from API responses
+4. **`Bun.password.hash`** — Use Bun's native hashing (not bcrypt)
+5. **ESR ordering** — Equality, Sort, Range for compound indexes
+6. **`.lean()`** — Always for read-only queries
+7. **`$facet`** — For paginated search (data + count in one query)
+8. **Explain first** — Always analyze with `.explain('executionStats')` before optimizing
+9. **COLLSCAN = bad** — Every frequent query needs an IXSCAN
+10. **Clear children first** — Delete dependent collections before parents in seeders