@ruaruababa/vibe-kit 1.0.0

package/skills/turborepo-caching/SKILL.md

@@ -0,0 +1,419 @@
+---
+name: turborepo-caching
+description: Configure Turborepo for efficient monorepo builds with local and remote caching. Use when setting up Turborepo, optimizing build pipelines, or implementing distributed caching.
+---
+
+# Turborepo Caching
+
+Production patterns for Turborepo build optimization.
+
+## Do not use this skill when
+
+- The task is unrelated to turborepo caching
+- You need a different domain or tool outside this scope
+
+## Instructions
+
+- Clarify goals, constraints, and required inputs.
+- Apply relevant best practices and validate outcomes.
+- Provide actionable steps and verification.
+- If detailed examples are required, open `resources/implementation-playbook.md`.
+
+## Use this skill when
+
+- Setting up new Turborepo projects
+- Configuring build pipelines
+- Implementing remote caching
+- Optimizing CI/CD performance
+- Migrating from other monorepo tools
+- Debugging cache misses
+
+## Core Concepts
+
+### 1. Turborepo Architecture
+
+```
+Workspace Root/
+├── apps/
+│   ├── web/
+│   │   └── package.json
+│   └── docs/
+│       └── package.json
+├── packages/
+│   ├── ui/
+│   │   └── package.json
+│   └── config/
+│       └── package.json
+├── turbo.json
+└── package.json
+```
+
+### 2. Pipeline Concepts
+
+| Concept | Description |
+|---------|-------------|
+| **dependsOn** | Tasks that must complete first |
+| **cache** | Whether to cache outputs |
+| **outputs** | Files to cache |
+| **inputs** | Files that affect cache key |
+| **persistent** | Long-running tasks (dev servers) |
+
+## Templates
+
+### Template 1: turbo.json Configuration
+
+```json
+{
+  "$schema": "https://turbo.build/schema.json",
+  "globalDependencies": [
+    ".env",
+    ".env.local"
+  ],
+  "globalEnv": [
+    "NODE_ENV",
+    "VERCEL_URL"
+  ],
+  "pipeline": {
+    "build": {
+      "dependsOn": ["^build"],
+      "outputs": [
+        "dist/**",
+        ".next/**",
+        "!.next/cache/**"
+      ],
+      "env": [
+        "API_URL",
+        "NEXT_PUBLIC_*"
+      ]
+    },
+    "test": {
+      "dependsOn": ["build"],
+      "outputs": ["coverage/**"],
+      "inputs": [
+        "src/**/*.tsx",
+        "src/**/*.ts",
+        "test/**/*.ts"
+      ]
+    },
+    "lint": {
+      "outputs": [],
+      "cache": true
+    },
+    "typecheck": {
+      "dependsOn": ["^build"],
+      "outputs": []
+    },
+    "dev": {
+      "cache": false,
+      "persistent": true
+    },
+    "clean": {
+      "cache": false
+    }
+  }
+}
+```
+
+### Template 2: Package-Specific Pipeline
+
+```json
+// apps/web/turbo.json
+{
+  "$schema": "https://turbo.build/schema.json",
+  "extends": ["//"],
+  "pipeline": {
+    "build": {
+      "outputs": [".next/**", "!.next/cache/**"],
+      "env": [
+        "NEXT_PUBLIC_API_URL",
+        "NEXT_PUBLIC_ANALYTICS_ID"
+      ]
+    },
+    "test": {
+      "outputs": ["coverage/**"],
+      "inputs": [
+        "src/**",
+        "tests/**",
+        "jest.config.js"
+      ]
+    }
+  }
+}
+```
+
+### Template 3: Remote Caching with Vercel
+
+```bash
+# Login to Vercel
+npx turbo login
+
+# Link to Vercel project
+npx turbo link
+
+# Run with remote cache
+turbo build --remote-only
+
+# CI environment variables
+TURBO_TOKEN=your-token
+TURBO_TEAM=your-team
+```
+
+```yaml
+# .github/workflows/ci.yml
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+env:
+  TURBO_TOKEN: ${{ secrets.TURBO_TOKEN }}
+  TURBO_TEAM: ${{ vars.TURBO_TEAM }}
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 20
+          cache: 'npm'
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Build
+        run: npx turbo build --filter='...[origin/main]'
+
+      - name: Test
+        run: npx turbo test --filter='...[origin/main]'
+```
+
+### Template 4: Self-Hosted Remote Cache
+
+```typescript
+// Custom remote cache server (Express)
+import express from 'express';
+import { createReadStream, createWriteStream } from 'fs';
+import { mkdir } from 'fs/promises';
+import { join } from 'path';
+
+const app = express();
+const CACHE_DIR = './cache';
+
+// Get artifact
+app.get('/v8/artifacts/:hash', async (req, res) => {
+  const { hash } = req.params;
+  const team = req.query.teamId || 'default';
+  const filePath = join(CACHE_DIR, team, hash);
+
+  try {
+    const stream = createReadStream(filePath);
+    stream.pipe(res);
+  } catch {
+    res.status(404).send('Not found');
+  }
+});
+
+// Put artifact
+app.put('/v8/artifacts/:hash', async (req, res) => {
+  const { hash } = req.params;
+  const team = req.query.teamId || 'default';
+  const dir = join(CACHE_DIR, team);
+  const filePath = join(dir, hash);
+
+  await mkdir(dir, { recursive: true });
+
+  const stream = createWriteStream(filePath);
+  req.pipe(stream);
+
+  stream.on('finish', () => {
+    res.json({ urls: [`${req.protocol}://${req.get('host')}/v8/artifacts/${hash}`] });
+  });
+});
+
+// Check artifact exists
+app.head('/v8/artifacts/:hash', async (req, res) => {
+  const { hash } = req.params;
+  const team = req.query.teamId || 'default';
+  const filePath = join(CACHE_DIR, team, hash);
+
+  try {
+    await fs.access(filePath);
+    res.status(200).end();
+  } catch {
+    res.status(404).end();
+  }
+});
+
+app.listen(3000);
+```
+
+```json
+// turbo.json for self-hosted cache
+{
+  "remoteCache": {
+    "signature": false
+  }
+}
+```
+
+```bash
+# Use self-hosted cache
+turbo build --api="http://localhost:3000" --token="my-token" --team="my-team"
+```
+
+### Template 5: Filtering and Scoping
+
+```bash
+# Build specific package
+turbo build --filter=@myorg/web
+
+# Build package and its dependencies
+turbo build --filter=@myorg/web...
+
+# Build package and its dependents
+turbo build --filter=...@myorg/ui
+
+# Build changed packages since main
+turbo build --filter='...[origin/main]'
+
+# Build packages in directory
+turbo build --filter='./apps/*'
+
+# Combine filters
+turbo build --filter=@myorg/web --filter=@myorg/docs
+
+# Exclude package
+turbo build --filter='!@myorg/docs'
+
+# Include dependencies of changed
+turbo build --filter='...[HEAD^1]...'
+```
+
+### Template 6: Advanced Pipeline Configuration
+
+```json
+{
+  "$schema": "https://turbo.build/schema.json",
+  "pipeline": {
+    "build": {
+      "dependsOn": ["^build"],
+      "outputs": ["dist/**"],
+      "inputs": [
+        "$TURBO_DEFAULT$",
+        "!**/*.md",
+        "!**/*.test.*"
+      ]
+    },
+    "test": {
+      "dependsOn": ["^build"],
+      "outputs": ["coverage/**"],
+      "inputs": [
+        "src/**",
+        "tests/**",
+        "*.config.*"
+      ],
+      "env": ["CI", "NODE_ENV"]
+    },
+    "test:e2e": {
+      "dependsOn": ["build"],
+      "outputs": [],
+      "cache": false
+    },
+    "deploy": {
+      "dependsOn": ["build", "test", "lint"],
+      "outputs": [],
+      "cache": false
+    },
+    "db:generate": {
+      "cache": false
+    },
+    "db:push": {
+      "cache": false,
+      "dependsOn": ["db:generate"]
+    },
+    "@myorg/web#build": {
+      "dependsOn": ["^build", "@myorg/db#db:generate"],
+      "outputs": [".next/**"],
+      "env": ["NEXT_PUBLIC_*"]
+    }
+  }
+}
+```
+
+### Template 7: Root package.json Setup
+
+```json
+{
+  "name": "my-turborepo",
+  "private": true,
+  "workspaces": [
+    "apps/*",
+    "packages/*"
+  ],
+  "scripts": {
+    "build": "turbo build",
+    "dev": "turbo dev",
+    "lint": "turbo lint",
+    "test": "turbo test",
+    "clean": "turbo clean && rm -rf node_modules",
+    "format": "prettier --write \"**/*.{ts,tsx,md}\"",
+    "changeset": "changeset",
+    "version-packages": "changeset version",
+    "release": "turbo build --filter=./packages/* && changeset publish"
+  },
+  "devDependencies": {
+    "turbo": "^1.10.0",
+    "prettier": "^3.0.0",
+    "@changesets/cli": "^2.26.0"
+  },
+  "packageManager": "npm@10.0.0"
+}
+```
+
+## Debugging Cache
+
+```bash
+# Dry run to see what would run
+turbo build --dry-run
+
+# Verbose output with hashes
+turbo build --verbosity=2
+
+# Show task graph
+turbo build --graph
+
+# Force no cache
+turbo build --force
+
+# Show cache status
+turbo build --summarize
+
+# Debug specific task
+TURBO_LOG_VERBOSITY=debug turbo build --filter=@myorg/web
+```
+
+## Best Practices
+
+### Do's
+- **Define explicit inputs** - Avoid cache invalidation
+- **Use workspace protocol** - `"@myorg/ui": "workspace:*"`
+- **Enable remote caching** - Share across CI and local
+- **Filter in CI** - Build only affected packages
+- **Cache build outputs** - Not source files
+
+### Don'ts
+- **Don't cache dev servers** - Use `persistent: true`
+- **Don't include secrets in env** - Use runtime env vars
+- **Don't ignore dependsOn** - Causes race conditions
+- **Don't over-filter** - May miss dependencies
+
+## Resources
+
+- [Turborepo Documentation](https://turbo.build/repo/docs)
+- [Caching Guide](https://turbo.build/repo/docs/core-concepts/caching)
+- [Remote Caching](https://turbo.build/repo/docs/core-concepts/remote-caching)

package/skills/tutorial-engineer/SKILL.md

@@ -0,0 +1,139 @@
+---
+name: tutorial-engineer
+description: Creates step-by-step tutorials and educational content from code.
+  Transforms complex concepts into progressive learning experiences with
+  hands-on examples. Use PROACTIVELY for onboarding guides, feature tutorials,
+  or concept explanations.
+metadata:
+  model: sonnet
+---
+
+## Use this skill when
+
+- Working on tutorial engineer tasks or workflows
+- Needing guidance, best practices, or checklists for tutorial engineer
+
+## Do not use this skill when
+
+- The task is unrelated to tutorial engineer
+- You need a different domain or tool outside this scope
+
+## Instructions
+
+- Clarify goals, constraints, and required inputs.
+- Apply relevant best practices and validate outcomes.
+- Provide actionable steps and verification.
+- If detailed examples are required, open `resources/implementation-playbook.md`.
+
+You are a tutorial engineering specialist who transforms complex technical concepts into engaging, hands-on learning experiences. Your expertise lies in pedagogical design and progressive skill building.
+
+## Core Expertise
+
+1. **Pedagogical Design**: Understanding how developers learn and retain information
+2. **Progressive Disclosure**: Breaking complex topics into digestible, sequential steps
+3. **Hands-On Learning**: Creating practical exercises that reinforce concepts
+4. **Error Anticipation**: Predicting and addressing common mistakes
+5. **Multiple Learning Styles**: Supporting visual, textual, and kinesthetic learners
+
+## Tutorial Development Process
+
+1. **Learning Objective Definition**
+   - Identify what readers will be able to do after the tutorial
+   - Define prerequisites and assumed knowledge
+   - Create measurable learning outcomes
+
+2. **Concept Decomposition**
+   - Break complex topics into atomic concepts
+   - Arrange in logical learning sequence
+   - Identify dependencies between concepts
+
+3. **Exercise Design**
+   - Create hands-on coding exercises
+   - Build from simple to complex
+   - Include checkpoints for self-assessment
+
+## Tutorial Structure
+
+### Opening Section
+- **What You'll Learn**: Clear learning objectives
+- **Prerequisites**: Required knowledge and setup
+- **Time Estimate**: Realistic completion time
+- **Final Result**: Preview of what they'll build
+
+### Progressive Sections
+1. **Concept Introduction**: Theory with real-world analogies
+2. **Minimal Example**: Simplest working implementation
+3. **Guided Practice**: Step-by-step walkthrough
+4. **Variations**: Exploring different approaches
+5. **Challenges**: Self-directed exercises
+6. **Troubleshooting**: Common errors and solutions
+
+### Closing Section
+- **Summary**: Key concepts reinforced
+- **Next Steps**: Where to go from here
+- **Additional Resources**: Deeper learning paths
+
+## Writing Principles
+
+- **Show, Don't Tell**: Demonstrate with code, then explain
+- **Fail Forward**: Include intentional errors to teach debugging
+- **Incremental Complexity**: Each step builds on the previous
+- **Frequent Validation**: Readers should run code often
+- **Multiple Perspectives**: Explain the same concept different ways
+
+## Content Elements
+
+### Code Examples
+- Start with complete, runnable examples
+- Use meaningful variable and function names
+- Include inline comments for clarity
+- Show both correct and incorrect approaches
+
+### Explanations
+- Use analogies to familiar concepts
+- Provide the "why" behind each step
+- Connect to real-world use cases
+- Anticipate and answer questions
+
+### Visual Aids
+- Diagrams showing data flow
+- Before/after comparisons
+- Decision trees for choosing approaches
+- Progress indicators for multi-step processes
+
+## Exercise Types
+
+1. **Fill-in-the-Blank**: Complete partially written code
+2. **Debug Challenges**: Fix intentionally broken code
+3. **Extension Tasks**: Add features to working code
+4. **From Scratch**: Build based on requirements
+5. **Refactoring**: Improve existing implementations
+
+## Common Tutorial Formats
+
+- **Quick Start**: 5-minute introduction to get running
+- **Deep Dive**: 30-60 minute comprehensive exploration
+- **Workshop Series**: Multi-part progressive learning
+- **Cookbook Style**: Problem-solution pairs
+- **Interactive Labs**: Hands-on coding environments
+
+## Quality Checklist
+
+- Can a beginner follow without getting stuck?
+- Are concepts introduced before they're used?
+- Is each code example complete and runnable?
+- Are common errors addressed proactively?
+- Does difficulty increase gradually?
+- Are there enough practice opportunities?
+
+## Output Format
+
+Generate tutorials in Markdown with:
+- Clear section numbering
+- Code blocks with expected output
+- Info boxes for tips and warnings
+- Progress checkpoints
+- Collapsible sections for solutions
+- Links to working code repositories
+
+Remember: Your goal is to create tutorials that transform learners from confused to confident, ensuring they not only understand the code but can apply concepts independently.

package/skills/typescript-advanced-types/SKILL.md

@@ -0,0 +1,35 @@
+---
+name: typescript-advanced-types
+description: Master TypeScript's advanced type system including generics, conditional types, mapped types, template literals, and utility types for building type-safe applications. Use when implementing complex type logic, creating reusable type utilities, or ensuring compile-time type safety in TypeScript projects.
+---
+
+# TypeScript Advanced Types
+
+Comprehensive guidance for mastering TypeScript's advanced type system including generics, conditional types, mapped types, template literal types, and utility types for building robust, type-safe applications.
+
+## Use this skill when
+
+- Building type-safe libraries or frameworks
+- Creating reusable generic components
+- Implementing complex type inference logic
+- Designing type-safe API clients
+- Building form validation systems
+- Creating strongly-typed configuration objects
+- Implementing type-safe state management
+- Migrating JavaScript codebases to TypeScript
+
+## Do not use this skill when
+
+- The task is unrelated to typescript advanced types
+- You need a different domain or tool outside this scope
+
+## Instructions
+
+- Clarify goals, constraints, and required inputs.
+- Apply relevant best practices and validate outcomes.
+- Provide actionable steps and verification.
+- If detailed examples are required, open `resources/implementation-playbook.md`.
+
+## Resources
+
+- `resources/implementation-playbook.md` for detailed patterns and examples.