feat: add @tanstack/db-playbook package for AI agent documentation

.changeset/add-db-skills-package.md

@@ -0,0 +1,5 @@
+---
+'@tanstack/db-playbook': patch
+---
+
+Add @tanstack/db-playbook package with AI-agent-optimized skills for TanStack DB. Includes skills for live queries, mutations, collections, schemas, and all collection types (Query, Electric, PowerSync, RxDB, TrailBase) with a CLI (`list` and `show` commands) for skill discovery.

packages/playbook/README.md

@@ -0,0 +1,64 @@
+# @tanstack/db-playbook
+
+A playbook of skills for AI agents building with [TanStack DB](https://tanstack.com/db).
+
+## What is a Playbook?
+
+A **playbook** is the collection of skills, patterns, and tools someone uses in a vibe-coding context — analogous to "stack" but for the less deliberate, more aesthetic-driven way people assemble their setup now.
+
+This package provides structured documentation designed for AI coding assistants (Claude Code, Cursor, Copilot, etc.) to help them build TanStack DB applications effectively.
+
+Skills are distilled, task-focused patterns that agents can quickly consume and apply — unlike large documentation that often exceeds context limits.
+
+## Installation
+
+```bash
+npm install @tanstack/db-playbook
+```
+
+## CLI Usage
+
+```bash
+# List all available skills
+npx @tanstack/db-playbook list
+
+# Show a specific skill
+npx @tanstack/db-playbook show tanstack-db
+npx @tanstack/db-playbook show tanstack-db/live-queries
+npx @tanstack/db-playbook show tanstack-db/mutations
+```
+
+## Skills Structure
+
+| Skill                      | Purpose                                           |
+| -------------------------- | ------------------------------------------------- |
+| `tanstack-db`              | Router/entry point with routing table             |
+| `tanstack-db/live-queries` | Reactive queries, joins, aggregations             |
+| `tanstack-db/mutations`    | Optimistic updates, transactions, paced mutations |
+| `tanstack-db/collections`  | QueryCollection, ElectricCollection, sync modes   |
+| `tanstack-db/schemas`      | Validation, transformations, TInput/TOutput       |
+| `tanstack-db/electric`     | ElectricSQL integration, txid matching            |
+
+Each skill includes:
+
+- **SKILL.md** - Common patterns and routing table
+- **references/** - Deep-dive documentation for specialized topics
+
+## For AI Agents
+
+Point your agent to the skills directory or use the CLI to fetch specific skills:
+
+```bash
+# Get the main routing skill
+npx @tanstack/db-playbook show tanstack-db
+
+# Get specific domain skills
+npx @tanstack/db-playbook show tanstack-db/live-queries
+```
+
+The router skill (`tanstack-db`) contains a routing table that helps agents find the right sub-skill for any task.
+
+## Learn More
+
+- [TanStack DB Documentation](https://tanstack.com/db)
+- [TanStack DB GitHub](https://github.com/TanStack/db)

packages/playbook/bin/cli.js

@@ -0,0 +1,114 @@
+#!/usr/bin/env node
+
+import { readFileSync, readdirSync, statSync } from 'node:fs'
+import { join, dirname } from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+const __dirname = dirname(fileURLToPath(import.meta.url))
+const skillsDir = join(__dirname, '..', 'skills')
+
+function listSkills(dir, prefix = '') {
+  const items = readdirSync(dir)
+
+  for (const item of items) {
+    const itemPath = join(dir, item)
+    const stat = statSync(itemPath)
+
+    if (!stat.isDirectory()) continue
+
+    const skillPath = join(itemPath, 'SKILL.md')
+    try {
+      const content = readFileSync(skillPath, 'utf-8')
+      const nameMatch = content.match(/^name:\s*(.+)$/m)
+      const descMatch = content.match(/description:\s*\|?\s*\n?\s*(.+)/m)
+
+      const name = nameMatch?.[1] || item
+      const desc = descMatch?.[1]?.trim() || 'No description'
+
+      console.log(`${prefix}${name}`)
+      console.log(`${prefix}  ${desc}`)
+      console.log()
+    } catch (err) {
+      if (err.code !== 'ENOENT') {
+        throw err
+      }
+      // No SKILL.md, check subdirectories
+    }
+
+    listSkills(itemPath, prefix + '  ')
+  }
+}
+
+function showSkill(skillName) {
+  const parts = skillName.split('/')
+  let searchDir = skillsDir
+
+  for (const part of parts) {
+    const items = readdirSync(searchDir)
+    const match = items.find(
+      (item) =>
+        item.toLowerCase() === part.toLowerCase() ||
+        item.toLowerCase().replace(/-/g, '') ===
+          part.toLowerCase().replace(/-/g, ''),
+    )
+
+    if (match) {
+      searchDir = join(searchDir, match)
+    } else {
+      console.error(`Skill not found: ${skillName}`)
+      process.exit(1)
+    }
+  }
+
+  const skillPath = join(searchDir, 'SKILL.md')
+  try {
+    const content = readFileSync(skillPath, 'utf-8')
+    console.log(content)
+  } catch {
+    console.error(`SKILL.md not found in: ${searchDir}`)
+    process.exit(1)
+  }
+}
+
+const args = process.argv.slice(2)
+const command = args[0]
+
+switch (command) {
+  case 'list':
+    console.log('TanStack Playbook\n')
+    listSkills(skillsDir)
+    break
+
+  case 'show':
+    if (!args[1]) {
+      console.error('Usage: db-playbook show <skill-name>')
+      console.error('Example: db-playbook show tanstack-db/live-queries')
+      process.exit(1)
+    }
+    showSkill(args[1])
+    break
+
+  case 'help':
+  case '--help':
+  case '-h':
+  case undefined:
+    console.log(`TanStack Playbook CLI
+
+Usage:
+  db-playbook list              List all available skills
+  db-playbook show <skill>      Show a specific skill
+  db-playbook help              Show this help message
+
+Examples:
+  db-playbook list
+  db-playbook show tanstack-db
+  db-playbook show tanstack-db/live-queries
+  db-playbook show tanstack-db/mutations
+`)
+    break
+
+  default:
+    console.error(`Unknown command: ${command}`)
+    console.log(`Run 'db-playbook help' for usage information.`)
+    process.exit(1)
+}

packages/playbook/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "@tanstack/db-playbook",
+  "version": "0.0.1",
+  "description": "TanStack DB Playbook - skills for AI agents building with TanStack DB",
+  "author": "TanStack",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/TanStack/db.git",
+    "directory": "packages/playbook"
+  },
+  "homepage": "https://tanstack.com/db",
+  "keywords": [
+    "tanstack",
+    "db",
+    "playbook",
+    "skills",
+    "ai",
+    "llm",
+    "documentation",
+    "reactive",
+    "live-queries",
+    "optimistic-updates"
+  ],
+  "bin": {
+    "db-playbook": "./bin/cli.js"
+  },
+  "type": "module",
+  "sideEffects": false,
+  "files": [
+    "bin",
+    "skills",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "lint": "true"
+  }
+}