create-baton 1.0.0 → 1.1.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-baton",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "description": "Set up Baton AI orchestration protocol in any project",
   "bin": {
     "create-baton": "./bin/create-baton.js"

package/src/constants.js

@@ -11,9 +11,9 @@ const IDE_MAP = {
 
 // Stack → which skill directories to copy into stacks/
 const STACK_MAP = {
-  'Next.js + Supabase': ['nextjs', 'supabase'],
-  'Next.js + other': ['nextjs'],
-  'React + Node': [],
+  'Next.js + Supabase': ['nextjs', 'supabase', 'tailwind', 'shadcn', 'typescript', 'vercel'],
+  'Next.js + other': ['nextjs', 'tailwind', 'shadcn', 'typescript', 'vercel'],
+  'React + Node': ['tailwind', 'typescript', 'prisma'],
   'Python': [],
   'Other': [],
 };

package/templates/BATON_v3.1.md

@@ -92,23 +92,29 @@ Based on chosen tech stack, read relevant skill files:
 - Next.js → `skills/stacks/nextjs/SKILL.md`
 - Supabase → `skills/stacks/supabase/SKILL.md`
 - Tailwind → `skills/stacks/tailwind/SKILL.md`
-- etc.
+- shadcn/ui → `skills/stacks/shadcn/SKILL.md`
+- TypeScript → `skills/stacks/typescript/SKILL.md`
+- Prisma → `skills/stacks/prisma/SKILL.md`
+- Vercel → `skills/stacks/vercel/SKILL.md`
 
 ### Step 3: Load Pattern Skills (Based on Features)
 
 If project needs specific patterns:
 - Authentication → `skills/patterns/authentication/SKILL.md`
+- Database design → `skills/patterns/database-design/SKILL.md`
 - File uploads → `skills/patterns/file-uploads/SKILL.md`
-- Background jobs → `skills/patterns/background-jobs/SKILL.md`
-- etc.
+- Payments → `skills/patterns/payments/SKILL.md`
+- Email → `skills/patterns/email/SKILL.md`
+- SEO → `skills/patterns/seo/SKILL.md`
+- API integration → `skills/patterns/api-integration/SKILL.md`
 
 ### Step 4: Load Domain Skills (If Applicable)
 
 If project is in a specialized domain:
-- Fintech → `skills/domains/fintech/SKILL.md`
+- SaaS → `skills/domains/saas/SKILL.md`
 - E-commerce → `skills/domains/ecommerce/SKILL.md`
-- Healthcare → `skills/domains/healthcare/SKILL.md`
-- etc.
+- Portfolio → `skills/domains/portfolio/SKILL.md`
+- API service → `skills/domains/api/SKILL.md`
 
 ### Step 5: Verify Current Documentation
 
@@ -129,6 +135,25 @@ Tell the user:
 
 After research, summarize findings in 3-5 bullet points before proceeding.
 
+### Step 7: Condense Skills into Tech Stack
+
+After reading all relevant skills (Steps 1-4), extract only the rules, patterns, and gotchas that apply to THIS project. Write them into `.ai-rules/tech-stack.md` during file generation (Phase 3).
+
+**What to extract:**
+- Stack-specific patterns the project will actually use
+- Security rules relevant to chosen stack
+- Common pitfalls for this exact combination of tools
+- Key commands and workflows
+
+**What to leave out:**
+- Rules for tools/patterns the project doesn't use
+- Generic advice already covered in core skills
+- Setup instructions (only needed once)
+
+**After Session 0:** Do NOT re-read `skills/` every session. Read `.ai-rules/tech-stack.md` instead — it contains everything this project needs, condensed. Only go back to `skills/` if you encounter a new problem area not covered by existing context (e.g., project adds payments mid-build → read `skills/patterns/payments/SKILL.md`, then update tech-stack.md).
+
+**The skills/ folder stays** as a reference library. Disk is free, tokens aren't.
+
 ---
 
 ## Phase 3: Generate Files
@@ -225,8 +250,11 @@ See "IDE Config Templates" section below for exact templates.
 ```
 
 ### .ai-rules/tech-stack.md
+
+This file is the **condensed single source of technical truth** for this project. During Session 0, read all relevant skills and distill project-specific rules here. After Session 0, this replaces re-reading skills/.
+
 ```markdown
-# Tech Stack Best Practices
+# Tech Stack — [Project Name]
 
 ## Stack
 [Chosen stack from Q4]
@@ -235,15 +263,17 @@ See "IDE Config Templates" section below for exact templates.
 [From research - typical folder structure for this stack]
 
 ## Key Patterns
-[From research - 5-10 bullet points of best practices]
+[Condensed from skills — only rules that apply to THIS project's stack + features]
+[Example: if using Next.js + Supabase + Stripe, include patterns from all three]
 
 ## Common Commands
 [Build, dev, test commands for this stack]
 
 ## Pitfalls to Avoid
-[From research - 3-5 common mistakes]
+[Condensed from skills — mistakes specific to this project's tool combination]
 
-## Security Hardening (MANDATORY)
+## Security Rules
+[Condensed from skills/core/security + stack-specific security patterns]
 - RLS (Row Level Security) on ALL database tables
 - Zod validation on ALL form inputs and API routes
 - Environment variables for ALL secrets (never in code)
@@ -256,6 +286,12 @@ See "IDE Config Templates" section below for exact templates.
 1. Create SQL/migration file with descriptive name
 2. Ask user to run migration
 3. Wait for confirmation before building UI that depends on it
+
+## Skills Loaded
+[List which skills were condensed into this file, so future sessions know what's covered]
+- skills/core/security, skills/core/testing, ...
+- skills/stacks/nextjs, skills/stacks/supabase, ...
+- skills/patterns/authentication, ...
 ```
 
 ### .ai-rules/structure.md
@@ -626,12 +662,14 @@ Same content as .cursorrules — Windsurf uses similar format.
 1. Read context files in order:
    - `handoff/SESSION_N.md` (current session)
    - `.ai-rules/project.md`
-   - `.ai-rules/tech-stack.md`
+   - `.ai-rules/tech-stack.md` (condensed skills — this is your technical reference)
    - `.ai-rules/patterns.md`
    - `.ai-rules/structure.md`
    - `PROGRESS.md`
    - `BACKLOG.md`
 
+   **Do NOT re-read `skills/` every session.** Tech-stack.md already contains what you need. Only go back to skills/ when encountering a new problem area — then update tech-stack.md with what you learn.
+
 2. Run health check (after Session 2):
    - Run build command
    - Verify no errors from previous session
@@ -706,10 +744,10 @@ After creating the handoff, ask:
 
 When working on any task:
 
-1. **Check `.ai-rules/patterns.md` FIRST** — Project-specific discoveries
-2. **Check `skills/core/`** — Universal security, testing, production rules
-3. **Check `skills/stacks/`** — Tech stack patterns
-4. **Check `skills/patterns/`** — Implementation patterns
+1. **Check `.ai-rules/tech-stack.md` FIRST** — Condensed skills for this project
+2. **Check `.ai-rules/patterns.md`** — Project-specific discoveries
+3. **Check `skills/` ONLY if needed** — For new problem areas not yet in tech-stack.md
+4. **Update tech-stack.md** — If you loaded a new skill, condense relevant parts into tech-stack.md
 5. **Only then web search** — If nothing found above
 6. **Document new findings** — Add to patterns.md or propose skill update
 

package/templates/skills/domains/api/SKILL.md

@@ -0,0 +1,318 @@
+---
+name: api
+description: >-
+  API service patterns — RESTful design, endpoint versioning, authentication,
+  rate limiting, documentation, and error handling. Load at Session 0 when
+  building a backend API, webhook service, or microservice. Stays loaded
+  entire lifecycle.
+---
+
+# API Service Domain Skill
+
+> An API is a contract. Breaking it breaks everyone who depends on you.
+
+---
+
+## Load This Skill When
+
+- User says they're building an API, backend service, or webhook handler
+- Project serves data to other apps (mobile, frontend, third-party)
+- No user-facing UI — the API IS the product
+
+---
+
+## API Design (Session 0-1)
+
+### URL Structure
+
+```
+GET    /api/v1/items          — List items
+GET    /api/v1/items/:id      — Get single item
+POST   /api/v1/items          — Create item
+PATCH  /api/v1/items/:id      — Update item
+DELETE /api/v1/items/:id      — Delete item
+```
+
+**Rules:**
+- Plural nouns (`/items` not `/item`)
+- No verbs in URLs (`/items` not `/getItems`)
+- Nest for relationships (`/items/:id/comments`)
+- Maximum 2 levels of nesting
+- Version in URL (`/api/v1/`) from day one
+
+### Response Format
+
+Always return consistent JSON:
+
+```json
+// Success
+{
+  "data": { ... },
+  "meta": { "page": 1, "total": 42 }
+}
+
+// Error
+{
+  "error": {
+    "code": "VALIDATION_ERROR",
+    "message": "Name is required",
+    "details": [
+      { "field": "name", "message": "Cannot be empty" }
+    ]
+  }
+}
+```
+
+**Never return:**
+- Raw database errors
+- Stack traces
+- Inconsistent formats (sometimes array, sometimes object)
+
+### HTTP Status Codes (Use These, Not Others)
+
+| Code | When |
+|------|------|
+| 200 | Success (GET, PATCH) |
+| 201 | Created (POST) |
+| 204 | Deleted (DELETE, no body) |
+| 400 | Bad request (validation failed) |
+| 401 | Not authenticated |
+| 403 | Authenticated but not authorized |
+| 404 | Resource not found |
+| 409 | Conflict (duplicate, version mismatch) |
+| 429 | Rate limited |
+| 500 | Server error (your fault) |
+
+Don't use obscure status codes. These 10 cover everything.
+
+---
+
+## Authentication (Session 1-2)
+
+### API Key Authentication (Simplest)
+
+```typescript
+// Middleware
+const apiKey = req.headers['x-api-key'];
+if (!apiKey || !isValidApiKey(apiKey)) {
+  return Response.json(
+    { error: { code: 'UNAUTHORIZED', message: 'Invalid API key' } },
+    { status: 401 }
+  );
+}
+```
+
+**API key rules:**
+- Prefix keys for identification (`baton_live_...`, `baton_test_...`)
+- Store hashed, not plaintext
+- Support key rotation (multiple active keys per user)
+- Different keys for test vs production
+
+### When to Use What
+
+| Method | Use For |
+|--------|---------|
+| API keys | Server-to-server, simple integrations |
+| JWT tokens | User-facing apps, short-lived sessions |
+| OAuth 2.0 | Third-party integrations, "Login with X" |
+
+**Default:** API keys for most backend services. Only add OAuth when third parties need access.
+
+---
+
+## Rate Limiting (Session 2-3)
+
+### Implement From Day One
+
+```typescript
+// Simple in-memory rate limiter (replace with Redis for production)
+const rateLimit = {
+  windowMs: 60 * 1000,     // 1 minute
+  maxRequests: 100,          // per window
+};
+```
+
+### Rate Limit Headers
+
+Always return these:
+```
+X-RateLimit-Limit: 100
+X-RateLimit-Remaining: 87
+X-RateLimit-Reset: 1708300800
+```
+
+### Tiered Limits
+
+| Tier | Requests/min | Use Case |
+|------|-------------|----------|
+| Free | 60 | Testing, hobby |
+| Pro | 600 | Production apps |
+| Enterprise | 6000 | High-volume |
+
+---
+
+## Pagination (Session 1-2)
+
+### Cursor-Based (Recommended)
+
+```
+GET /api/v1/items?limit=20&cursor=abc123
+```
+
+Response:
+```json
+{
+  "data": [...],
+  "meta": {
+    "has_more": true,
+    "next_cursor": "def456"
+  }
+}
+```
+
+**Why cursor over offset:** Offset pagination breaks when data changes between pages. Cursor doesn't.
+
+### If Offset is Simpler
+
+```
+GET /api/v1/items?page=1&per_page=20
+```
+
+Response includes `total`, `page`, `per_page`, `total_pages`.
+
+Fine for admin dashboards. Not for public APIs with frequent writes.
+
+---
+
+## Validation (Session 1-2)
+
+### Validate Everything at the Boundary
+
+```typescript
+import { z } from 'zod';
+
+const createItemSchema = z.object({
+  name: z.string().min(1).max(255),
+  description: z.string().optional(),
+  price_cents: z.number().int().positive(),
+});
+
+// In route handler
+const parsed = createItemSchema.safeParse(body);
+if (!parsed.success) {
+  return Response.json({
+    error: {
+      code: 'VALIDATION_ERROR',
+      message: 'Invalid input',
+      details: parsed.error.issues,
+    }
+  }, { status: 400 });
+}
+```
+
+---
+
+## Versioning (Session 0)
+
+### URL Versioning (Default)
+
+```
+/api/v1/items
+/api/v2/items
+```
+
+**Rules:**
+- Start at v1, not v0
+- Only bump version for breaking changes
+- Keep old version running for at least 6 months
+- Announce deprecation in response headers
+
+```
+Deprecation: true
+Sunset: Sat, 01 Jan 2027 00:00:00 GMT
+Link: <https://docs.example.com/migration>; rel="deprecation"
+```
+
+---
+
+## Documentation (Session 4+)
+
+### Minimum Viable Docs
+
+Every endpoint needs:
+- URL and method
+- Request body (with example)
+- Response body (with example)
+- Error responses
+- Authentication required (yes/no)
+
+### OpenAPI/Swagger
+
+Generate from code if possible. Don't maintain a separate spec file.
+
+```typescript
+// If using Next.js API routes, consider next-swagger-doc
+// If standalone, use tsoa or express-openapi-validator
+```
+
+### README Quick Start
+
+```markdown
+## Quick Start
+
+1. Get an API key at https://example.com/dashboard
+2. Make your first request:
+
+curl -X GET https://api.example.com/v1/items \
+  -H "X-API-Key: your_key_here"
+```
+
+Every API needs a "get started in 30 seconds" section.
+
+---
+
+## Webhooks (If Your API Sends Events)
+
+### Webhook Design
+
+```json
+{
+  "id": "evt_abc123",
+  "type": "item.created",
+  "created_at": "2026-02-14T10:00:00Z",
+  "data": { ... }
+}
+```
+
+**Rules:**
+- Sign every webhook (HMAC-SHA256)
+- Include event type and timestamp
+- Retry on failure (3 attempts, exponential backoff)
+- Let users configure webhook URLs
+- Log all deliveries (success and failure)
+
+---
+
+## Session Checkpoints
+
+### Session 2: Foundation Check
+- [ ] Core CRUD endpoints work
+- [ ] Authentication enforced
+- [ ] Consistent error format
+- [ ] Validation on all inputs
+
+### Session 4: Production Check
+- [ ] Rate limiting active
+- [ ] Pagination on list endpoints
+- [ ] API documentation exists
+- [ ] Error responses don't leak internals
+
+### Session 7: Launch Check
+- [ ] All endpoints documented with examples
+- [ ] Rate limits tested under load
+- [ ] API keys can be rotated
+- [ ] Monitoring/logging on all routes
+
+---
+
+*Last updated: Baton Protocol v3.1*