devskill 2.0.2

package/skills/turborepo/references/filtering/RULE.md

@@ -0,0 +1,148 @@
+# Turborepo Filter Syntax Reference
+
+## Running Only Changed Packages: `--affected`
+
+**The primary way to run only changed packages is `--affected`:**
+
+```bash
+# Run build/test/lint only in changed packages and their dependents
+turbo run build test lint --affected
+```
+
+This compares your current branch to the default branch (usually `main` or `master`) and runs tasks in:
+
+1. Packages with file changes
+2. Packages that depend on changed packages (dependents)
+
+### Why Include Dependents?
+
+If you change `@repo/ui`, packages that import `@repo/ui` (like `apps/web`) need to re-run their tasks to verify they still work with the changes.
+
+### Customizing --affected
+
+```bash
+# Use a different base branch
+turbo run build --affected --affected-base=origin/develop
+
+# Use a different head (current state)
+turbo run build --affected --affected-head=HEAD~5
+```
+
+### Common CI Pattern
+
+```yaml
+# .github/workflows/ci.yml
+- run: turbo run build test lint --affected
+```
+
+This is the most efficient CI setup - only run tasks for what actually changed.
+
+---
+
+## Manual Git Comparison with --filter
+
+For more control, use `--filter` with git comparison syntax:
+
+```bash
+# Changed packages + dependents (same as --affected)
+turbo run build --filter=...[origin/main]
+
+# Only changed packages (no dependents)
+turbo run build --filter=[origin/main]
+
+# Changed packages + dependencies (packages they import)
+turbo run build --filter=[origin/main]...
+
+# Changed since last commit
+turbo run build --filter=...[HEAD^1]
+
+# Changed between two commits
+turbo run build --filter=[a1b2c3d...e4f5g6h]
+```
+
+### Comparison Syntax
+
+| Syntax        | Meaning                               |
+| ------------- | ------------------------------------- |
+| `[ref]`       | Packages changed since `ref`          |
+| `...[ref]`    | Changed packages + their dependents   |
+| `[ref]...`    | Changed packages + their dependencies |
+| `...[ref]...` | Dependencies, changed, AND dependents |
+
+---
+
+## Other Filter Types
+
+Filters select which packages to include in a `turbo run` invocation.
+
+### Basic Syntax
+
+```bash
+turbo run build --filter=<package-name>
+turbo run build -F <package-name>
+```
+
+Multiple filters combine as a union (packages matching ANY filter run).
+
+### By Package Name
+
+```bash
+--filter=web          # exact match
+--filter=@acme/*      # scope glob
+--filter=*-app        # name glob
+```
+
+### By Directory
+
+```bash
+--filter=./apps/*           # all packages in apps/
+--filter=./packages/ui      # specific directory
+```
+
+### By Dependencies/Dependents
+
+| Syntax      | Meaning                                |
+| ----------- | -------------------------------------- |
+| `pkg...`    | Package AND all its dependencies       |
+| `...pkg`    | Package AND all its dependents         |
+| `...pkg...` | Dependencies, package, AND dependents  |
+| `^pkg...`   | Only dependencies (exclude pkg itself) |
+| `...^pkg`   | Only dependents (exclude pkg itself)   |
+
+### Negation
+
+Exclude packages with `!`:
+
+```bash
+--filter=!web              # exclude web
+--filter=./apps/* --filter=!admin   # apps except admin
+```
+
+### Task Identifiers
+
+Run a specific task in a specific package:
+
+```bash
+turbo run web#build        # only web's build task
+turbo run web#build api#test   # web build + api test
+```
+
+### Combining Filters
+
+Multiple `--filter` flags create a union:
+
+```bash
+turbo run build --filter=web --filter=api   # runs in both
+```
+
+---
+
+## Quick Reference: Changed Packages
+
+| Goal                               | Command                                                     |
+| ---------------------------------- | ----------------------------------------------------------- |
+| Changed + dependents (recommended) | `turbo run build --affected`                                |
+| Custom base branch                 | `turbo run build --affected --affected-base=origin/develop` |
+| Only changed (no dependents)       | `turbo run build --filter=[origin/main]`                    |
+| Changed + dependencies             | `turbo run build --filter=[origin/main]...`                 |
+| Since last commit                  | `turbo run build --filter=...[HEAD^1]`                      |

package/skills/turborepo/references/filtering/patterns.md

@@ -0,0 +1,152 @@
+# Common Filter Patterns
+
+Practical examples for typical monorepo scenarios.
+
+## Single Package
+
+Run task in one package:
+
+```bash
+turbo run build --filter=web
+turbo run test --filter=@acme/api
+```
+
+## Package with Dependencies
+
+Build a package and everything it depends on:
+
+```bash
+turbo run build --filter=web...
+```
+
+Useful for: ensuring all dependencies are built before the target.
+
+## Package Dependents
+
+Run in all packages that depend on a library:
+
+```bash
+turbo run test --filter=...ui
+```
+
+Useful for: testing consumers after changing a shared package.
+
+## Dependents Only (Exclude Target)
+
+Test packages that depend on ui, but not ui itself:
+
+```bash
+turbo run test --filter=...^ui
+```
+
+## Changed Packages
+
+Run only in packages with file changes since last commit:
+
+```bash
+turbo run lint --filter=[HEAD^1]
+```
+
+Since a specific branch point:
+
+```bash
+turbo run lint --filter=[main...HEAD]
+```
+
+## Changed + Dependents (PR Builds)
+
+Run in changed packages AND packages that depend on them:
+
+```bash
+turbo run build test --filter=...[HEAD^1]
+```
+
+Or use the shortcut:
+
+```bash
+turbo run build test --affected
+```
+
+## Directory-Based
+
+Run in all apps:
+
+```bash
+turbo run build --filter=./apps/*
+```
+
+Run in specific directories:
+
+```bash
+turbo run build --filter=./apps/web --filter=./apps/api
+```
+
+## Scope-Based
+
+Run in all packages under a scope:
+
+```bash
+turbo run build --filter=@acme/*
+```
+
+## Exclusions
+
+Run in all apps except admin:
+
+```bash
+turbo run build --filter=./apps/* --filter=!admin
+```
+
+Run everywhere except specific packages:
+
+```bash
+turbo run lint --filter=!legacy-app --filter=!deprecated-pkg
+```
+
+## Complex Combinations
+
+Apps that changed, plus their dependents:
+
+```bash
+turbo run build --filter=...[HEAD^1] --filter=./apps/*
+```
+
+All packages except docs, but only if changed:
+
+```bash
+turbo run build --filter=[main...HEAD] --filter=!docs
+```
+
+## Debugging Filters
+
+Use `--dry` to see what would run without executing:
+
+```bash
+turbo run build --filter=web... --dry
+```
+
+Use `--dry=json` for machine-readable output:
+
+```bash
+turbo run build --filter=...[HEAD^1] --dry=json
+```
+
+## CI/CD Patterns
+
+PR validation (most common):
+
+```bash
+turbo run build test lint --affected
+```
+
+Deploy only changed apps:
+
+```bash
+turbo run deploy --filter=./apps/* --filter=[main...HEAD]
+```
+
+Full rebuild of specific app and deps:
+
+```bash
+turbo run build --filter=production-app...
+```

package/skills/turborepo/references/watch/RULE.md

@@ -0,0 +1,99 @@
+# turbo watch
+
+Full docs: https://turborepo.dev/docs/reference/watch
+
+Re-run tasks automatically when code changes. Dependency-aware.
+
+```bash
+turbo watch [tasks]
+```
+
+## Basic Usage
+
+```bash
+# Watch and re-run build task when code changes
+turbo watch build
+
+# Watch multiple tasks
+turbo watch build test lint
+```
+
+Tasks re-run in order configured in `turbo.json` when source files change.
+
+## With Persistent Tasks
+
+Persistent tasks (`"persistent": true`) won't exit, so they can't be depended on. They work the same in `turbo watch` as `turbo run`.
+
+### Dependency-Aware Persistent Tasks
+
+If your tool has built-in watching (like `next dev`), use its watcher:
+
+```json
+{
+  "tasks": {
+    "dev": {
+      "persistent": true,
+      "cache": false
+    }
+  }
+}
+```
+
+### Non-Dependency-Aware Tools
+
+For tools that don't detect dependency changes, use `interruptible`:
+
+```json
+{
+  "tasks": {
+    "dev": {
+      "persistent": true,
+      "interruptible": true,
+      "cache": false
+    }
+  }
+}
+```
+
+`turbo watch` will restart interruptible tasks when dependencies change.
+
+## Limitations
+
+### Caching
+
+Caching is experimental with watch mode:
+
+```bash
+turbo watch your-tasks --experimental-write-cache
+```
+
+### Task Outputs in Source Control
+
+If tasks write files tracked by git, watch mode may loop infinitely. Watch mode uses file hashes to prevent this but it's not foolproof.
+
+**Recommendation**: Remove task outputs from git.
+
+## vs turbo run
+
+| Feature           | `turbo run` | `turbo watch` |
+| ----------------- | ----------- | ------------- |
+| Runs once         | Yes         | No            |
+| Re-runs on change | No          | Yes           |
+| Caching           | Full        | Experimental  |
+| Use case          | CI, one-off | Development   |
+
+## Common Patterns
+
+### Development Workflow
+
+```bash
+# Run dev servers and watch for build changes
+turbo watch dev build
+```
+
+### Type Checking During Development
+
+```bash
+# Watch and re-run type checks
+turbo watch check-types
+```

package/skills/vercel-cli-with-tokens/SKILL.md

@@ -0,0 +1,328 @@
+---
+name: vercel-cli-with-tokens
+description: Deploy and manage projects on Vercel using token-based authentication. Use when working with Vercel CLI using access tokens rather than interactive login — e.g. "deploy to vercel", "set up vercel", "add environment variables to vercel".
+metadata:
+  author: vercel
+  version: "1.0.0"
+---
+
+# Vercel CLI with Tokens
+
+Deploy and manage projects on Vercel using the CLI with token-based authentication, without relying on `vercel login`.
+
+## Step 1: Locate the Vercel Token
+
+Before running any Vercel CLI commands, identify where the token is coming from. Work through these scenarios in order:
+
+### A) `VERCEL_TOKEN` is already set in the environment
+
+```bash
+printenv VERCEL_TOKEN
+```
+
+If this returns a value, you're ready. Skip to Step 2.
+
+### B) Token is in a `.env` file under `VERCEL_TOKEN`
+
+```bash
+grep '^VERCEL_TOKEN=' .env 2>/dev/null
+```
+
+If found, export it:
+
+```bash
+export VERCEL_TOKEN=$(grep '^VERCEL_TOKEN=' .env | cut -d= -f2-)
+```
+
+### C) Token is in a `.env` file under a different name
+
+Look for any variable that looks like a Vercel token (Vercel tokens typically start with `vca_`):
+
+```bash
+grep -i 'vercel' .env 2>/dev/null
+```
+
+Inspect the output to identify which variable holds the token, then export it as `VERCEL_TOKEN`:
+
+```bash
+export VERCEL_TOKEN=$(grep '^<VARIABLE_NAME>=' .env | cut -d= -f2-)
+```
+
+### D) No token found — ask the user
+
+If none of the above yield a token, ask the user to provide one. They can create a Vercel access token at vercel.com/account/tokens.
+
+---
+
+**Important:** Once `VERCEL_TOKEN` is exported as an environment variable, the Vercel CLI reads it natively — **do not pass it as a `--token` flag**. Putting secrets in command-line arguments exposes them in shell history and process listings.
+
+```bash
+# Bad — token visible in shell history and process listings
+vercel deploy --token "vca_abc123"
+
+# Good — CLI reads VERCEL_TOKEN from the environment
+export VERCEL_TOKEN="vca_abc123"
+vercel deploy
+```
+
+## Step 2: Locate the Project and Team
+
+Similarly, check for the project ID and team scope. These let the CLI target the right project without needing `vercel link`.
+
+```bash
+# Check environment
+printenv VERCEL_PROJECT_ID
+printenv VERCEL_ORG_ID
+
+# Or check .env
+grep -i 'vercel' .env 2>/dev/null
+```
+
+**If you have a project URL** (e.g. `https://vercel.com/my-team/my-project`), extract the team slug:
+
+```bash
+# e.g. "my-team" from "https://vercel.com/my-team/my-project"
+echo "$PROJECT_URL" | sed 's|https://vercel.com/||' | cut -d/ -f1
+```
+
+**If you have both `VERCEL_ORG_ID` and `VERCEL_PROJECT_ID` in your environment**, export them — the CLI will use these automatically and skip any `.vercel/` directory:
+
+```bash
+export VERCEL_ORG_ID="<org-id>"
+export VERCEL_PROJECT_ID="<project-id>"
+```
+
+Note: `VERCEL_ORG_ID` and `VERCEL_PROJECT_ID` must be set together — setting only one causes an error.
+
+## CLI Setup
+
+Ensure the Vercel CLI is installed:
+
+```bash
+npm install -g vercel
+vercel --version
+```
+
+## Deploying a Project
+
+Always deploy as **preview** unless the user explicitly requests production. Choose a method based on what you have available.
+
+### Quick Deploy (have project ID — no linking needed)
+
+When `VERCEL_TOKEN` and `VERCEL_PROJECT_ID` are set in the environment, deploy directly:
+
+```bash
+vercel deploy -y --no-wait
+```
+
+With a team scope (either via `VERCEL_ORG_ID` or `--scope`):
+
+```bash
+vercel deploy --scope <team-slug> -y --no-wait
+```
+
+Production (only when explicitly requested):
+
+```bash
+vercel deploy --prod --scope <team-slug> -y --no-wait
+```
+
+Check status:
+
+```bash
+vercel inspect <deployment-url>
+```
+
+### Full Deploy Flow (no project ID — need to link)
+
+Use this when you have a token and team but no pre-existing project ID.
+
+#### Check project state first
+
+```bash
+# Does the project have a git remote?
+git remote get-url origin 2>/dev/null
+
+# Is it already linked to a Vercel project?
+cat .vercel/project.json 2>/dev/null || cat .vercel/repo.json 2>/dev/null
+```
+
+#### Link the project
+
+**With git remote (preferred):**
+
+```bash
+vercel link --repo --scope <team-slug> -y
+```
+
+Reads the git remote and connects to the matching Vercel project. Creates `.vercel/repo.json`. More reliable than plain `vercel link`, which matches by directory name.
+
+**Without git remote:**
+
+```bash
+vercel link --scope <team-slug> -y
+```
+
+Creates `.vercel/project.json`.
+
+**Link to a specific project by name:**
+
+```bash
+vercel link --project <project-name> --scope <team-slug> -y
+```
+
+If the project is already linked, check `orgId` in `.vercel/project.json` or `.vercel/repo.json` to verify it matches the intended team.
+
+#### Deploy after linking
+
+**A) Git Push Deploy — has git remote (preferred)**
+
+Git pushes trigger automatic Vercel deployments.
+
+1. **Ask the user before pushing.** Never push without explicit approval.
+2. Commit and push:
+   ```bash
+   git add .
+   git commit -m "deploy: <description of changes>"
+   git push
+   ```
+3. Vercel builds automatically. Non-production branches get preview deployments.
+4. Retrieve the deployment URL:
+   ```bash
+   sleep 5
+   vercel ls --format json --scope <team-slug>
+   ```
+   Find the latest entry in the `deployments` array.
+
+**B) CLI Deploy — no git remote**
+
+```bash
+vercel deploy --scope <team-slug> -y --no-wait
+```
+
+Check status:
+
+```bash
+vercel inspect <deployment-url>
+```
+
+### Deploying from a Remote Repository (code not cloned locally)
+
+1. Clone the repository:
+   ```bash
+   git clone <repo-url>
+   cd <repo-name>
+   ```
+2. Link to Vercel:
+   ```bash
+   vercel link --repo --scope <team-slug> -y
+   ```
+3. Deploy via git push (if you have push access) or CLI deploy.
+
+### About `.vercel/` Directory
+
+A linked project has either:
+- `.vercel/project.json` — from `vercel link`. Contains `projectId` and `orgId`.
+- `.vercel/repo.json` — from `vercel link --repo`. Contains `orgId`, `remoteName`, and a `projects` map.
+
+Not needed when `VERCEL_ORG_ID` + `VERCEL_PROJECT_ID` are both set in the environment.
+
+**Do NOT** run `vercel ls`, `vercel project inspect`, or `vercel link` in an unlinked directory to detect state — they will interactively prompt or silently link as a side-effect. Only `vercel whoami` is safe to run anywhere.
+
+## Managing Environment Variables
+
+```bash
+# Set for all environments
+echo "value" | vercel env add VAR_NAME --scope <team-slug>
+
+# Set for a specific environment (production, preview, development)
+echo "value" | vercel env add VAR_NAME production --scope <team-slug>
+
+# List environment variables
+vercel env ls --scope <team-slug>
+
+# Pull env vars to local .env file
+vercel env pull --scope <team-slug>
+
+# Remove a variable
+vercel env rm VAR_NAME --scope <team-slug> -y
+```
+
+## Inspecting Deployments
+
+```bash
+# List recent deployments
+vercel ls --format json --scope <team-slug>
+
+# Inspect a specific deployment
+vercel inspect <deployment-url>
+
+# View build logs
+vercel logs <deployment-url>
+```
+
+## Managing Domains
+
+```bash
+# List domains
+vercel domains ls --scope <team-slug>
+
+# Add a domain to the project
+vercel domains add <domain> --scope <team-slug>
+```
+
+## Working Agreement
+
+- **Never pass `VERCEL_TOKEN` as a `--token` flag.** Export it as an environment variable and let the CLI read it natively.
+- **Check the environment for tokens before asking the user.** Look in the current env and `.env` files first.
+- **Default to preview deployments.** Only deploy to production when explicitly asked.
+- **Ask before pushing to git.** Never push commits without the user's approval.
+- **Do not read or modify `.vercel/` files directly.** The CLI manages this directory.
+- **Do not curl/fetch deployed URLs to verify.** Just return the link to the user.
+- **Use `--format json`** when structured output will help with follow-up steps.
+- **Use `-y`** on commands that prompt for confirmation to avoid interactive blocking.
+
+## Troubleshooting
+
+### Token not found
+
+Check the environment and any `.env` files present:
+
+```bash
+printenv | grep -i vercel
+grep -i vercel .env 2>/dev/null
+```
+
+### Authentication error
+
+If the CLI fails with `Authentication required`:
+- The token may be expired or invalid.
+- Verify: `vercel whoami` (uses `VERCEL_TOKEN` from environment).
+- Ask the user for a fresh token.
+
+### Wrong team
+
+Verify the scope is correct:
+
+```bash
+vercel whoami --scope <team-slug>
+```
+
+### Build failure
+
+Check the build logs:
+
+```bash
+vercel logs <deployment-url>
+```
+
+Common causes:
+- Missing dependencies — ensure `package.json` is complete and committed.
+- Missing environment variables — add with `vercel env add`.
+- Framework misconfiguration — check `vercel.json`. Vercel auto-detects frameworks (Next.js, Remix, Vite, etc.) from `package.json`; override with `vercel.json` if detection is wrong.
+
+### CLI not installed
+
+```bash
+npm install -g vercel
+```