@jgamaraalv/ts-dev-kit 3.3.0 → 5.0.0

package/skills/execute-task/SKILL.md

@@ -240,7 +240,12 @@ Each agent prompt must follow the template in references/agent-dispatch.md. The
 Decide the execution order based on file conflicts and dependencies:
 - **Parallel**: roles touch independent files with no data dependency → launch multiple Task calls in one message. **CRITICAL: "parallel" means sending ALL independent Task() calls in a SINGLE assistant message. If you announce "dispatching 3 agents in parallel" you MUST include exactly 3 Task() tool calls in that same message. Announcing parallel dispatch and then sending only 1 Task() is a violation of this protocol.**
 - **Sequential**: one role's output is another's input → await the blocker first.
-- **Worktree isolation**: roles touch overlapping files but are otherwise independent → set `isolation: "worktree"` on the Task tool.
+- **Worktree isolation**: roles touch overlapping files but are otherwise independent → set `isolation: "worktree"` on the Task tool. Each agent gets an isolated copy of the repository; the worktree is auto-cleaned if the agent makes no changes.
+
+**Decision tree for overlapping files:**
+1. Do the agents have a data dependency (one needs the other's output)? → **Sequential**.
+2. Are the agents logically independent but touch some of the same files (e.g., both modify a shared barrel export, or both edit the same config)? → **Worktree isolation** — dispatch in parallel with `isolation: "worktree"` on each Task() call, then merge results.
+3. Do the agents touch completely separate files? → **Parallel** (no isolation needed).
 </rule_3_execution_order>
 
 <rule_4_model_selection>
@@ -369,8 +374,9 @@ As orchestrator, your responsibilities are: context gathering, agent dispatch, o
 1. Create TaskCreate entries for each role to track progress.
 2. For each role, dispatch a specialized agent via the Task tool with a self-contained prompt. Set the `model` parameter according to rule_4_model_selection.
 3. **Launch independent agents in parallel — this means multiple Task() calls in a SINGLE message.** Do NOT sequentialize independent agents. If you have 3 independent tasks, your message must contain 3 Task() tool calls. Launch dependent agents sequentially (wait for blockers to complete first).
-4. Each agent runs its own quality gates before reporting completion. Review the agent's output and gate results before dispatching dependents.
-5. After all agents complete, proceed to phase 5 for the final cross-package quality gates.
+4. **For parallel agents that touch overlapping files**, add `isolation: "worktree"` to each Task() call. This gives each agent an isolated copy of the repository, preventing edit conflicts. Worktrees are auto-cleaned when the agent makes no changes.
+5. Each agent runs its own quality gates before reporting completion. Review the agent's output and gate results before dispatching dependents.
+6. After all agents complete, proceed to phase 5 for the final cross-package quality gates.
 
 For the agent prompt template and dispatch details, see references/agent-dispatch.md.
 
@@ -450,11 +456,15 @@ If you announce "dispatching 3 agents in parallel", your message MUST contain ex
 ### 4. Never write application code as orchestrator
 The orchestrator reads, analyzes, dispatches, reviews, and runs quality gates. It does NOT write components, hooks, routes, services, migrations, tests, or any application logic. The only code the orchestrator may write is trivial integration glue (under 15 lines): barrel exports, small wiring imports, or config one-liners.
 
+### 5. Never dispatch parallel agents on overlapping files without worktree isolation
+When two or more agents run in parallel and touch any of the same files (shared barrel exports, config files, common modules), they will produce edit conflicts. Always set `isolation: "worktree"` on each Task() call so each agent works on an isolated copy of the repository. Skip isolation only when agents touch completely separate files.
+
 ### Self-check before sending each message
 Before sending any message during execution, verify:
 - [ ] Am I about to write application code? → STOP, dispatch an agent instead.
 - [ ] Am I about to modify a config without querying docs? → STOP, use Context7 first.
 - [ ] Did I announce N parallel agents? → Count my Task() calls. Are there N? If not, add the missing ones.
+- [ ] Am I dispatching parallel agents that touch the same files? → Add `isolation: "worktree"` to each Task() call.
 - [ ] Did a quality gate fail? → STOP, dispatch a specialist agent to fix it.
 </orchestrator_anti_patterns>
 </workflow>

package/skills/execute-task/references/agent-dispatch.md

@@ -97,6 +97,49 @@ Discover from the codebase:
 )
 ```
 
+## Dispatch with worktree isolation
+
+When parallel agents touch overlapping files (e.g., both modify a shared barrel export or the same config), add `isolation: "worktree"` to each Task() call. Each agent gets an isolated copy of the repository, preventing edit conflicts.
+
+```
+// Two agents that both touch shared/src/index.ts — dispatch in parallel with worktree isolation
+Task(
+  description: "Add user schema and migration",
+  subagent_type: "database-expert",
+  model: "sonnet",
+  isolation: "worktree",
+  prompt: """
+## Your task
+Create the users table schema and migration...
+
+## Success criteria
+- Schema exported from shared package
+- Migration runs cleanly
+"""
+)
+
+Task(
+  description: "Add notification schema and migration",
+  subagent_type: "database-expert",
+  model: "sonnet",
+  isolation: "worktree",
+  prompt: """
+## Your task
+Create the notifications table schema and migration...
+
+## Success criteria
+- Schema exported from shared package
+- Migration runs cleanly
+"""
+)
+```
+
+After both agents complete, review the worktree results. If both modified the same file (e.g., a barrel export), manually merge the additions into the main working directory.
+
+**When NOT to use worktree isolation:**
+- Agents touch completely separate files → plain parallel dispatch (no isolation overhead).
+- One agent depends on the other's output → sequential dispatch (await the blocker first).
+
 ## Agent type resolution
 
 Before dispatching, resolve the agent type for each role:

package/skills/fastify-best-practices/SKILL.md

@@ -10,12 +10,10 @@ description: "Fastify 5 best practices, API reference, and patterns for routes,
 - [Request lifecycle](#request-lifecycle-exact-order)
 - [Top anti-patterns](#top-anti-patterns)
 - [Quick patterns](#quick-patterns)
-  - [Plugin with fastify-plugin (FastifyPluginCallback)](#plugin-with-fastify-plugin-fastifyplugincallback)
-  - [Route with validation](#route-with-validation)
-  - [Hook (application-level)](#hook-application-level)
-  - [Error handler](#error-handler)
 - [Reference files](#reference-files)
 
+<quick_reference>
+
 ## Request lifecycle (exact order)
 
 ```
@@ -36,6 +34,10 @@ Incoming Request
 
 Error at any stage → `onError` hooks → error handler → `onSend` → response → `onResponse`.
 
+</quick_reference>
+
+<anti_patterns>
+
 ## Top anti-patterns
 
 1. **Mixing async/callback in handlers** — Use `async` OR callbacks, never both. With async, `return` the value; don't call `reply.send()` AND return.
@@ -58,6 +60,10 @@ Error at any stage → `onError` hooks → error handler → `onSend` → respon
 
 10. **Missing response schema** — Without `response` schema, Fastify serializes with `JSON.stringify()` (slow) and may leak sensitive fields. Use `fast-json-stringify` via response schemas.
 
+</anti_patterns>
+
+<examples>
+
 ## Quick patterns
 
 ### Plugin with fastify-plugin (FastifyPluginCallback)
@@ -130,6 +136,10 @@ fastify.setErrorHandler((error, request, reply) => {
 });
 ```
 
+</examples>
+
+<references>
+
 ## Reference files
 
 Load the relevant file when you need detailed API information:
@@ -141,3 +151,5 @@ Load the relevant file when you need detailed API information:
 - **Validation & serialization** — JSON Schema, Ajv, response schemas, custom validators: [references/validation-and-serialization.md](references/validation-and-serialization.md)
 - **Request, Reply & errors** — request/reply API, error handling, FST_ERR codes: [references/request-reply-errors.md](references/request-reply-errors.md)
 - **TypeScript & logging** — route generics, type providers, Pino config, decorators: [references/typescript-and-logging.md](references/typescript-and-logging.md)
+
+</references>

package/skills/generate-prd/SKILL.md

@@ -4,9 +4,9 @@ description: "Generates a complete, structured, and implementation-ready Product
 argument-hint: "[product-idea | feature-description | business-context | prd-md-file-path]"
 ---
 
-<system>
+<role>
 You are a Senior Product Manager and Product Strategist. Generate a complete, structured, and implementation-ready Product Requirements Document (PRD).
-</system>
+</role>
 
 <spec>
 $ARGUMENTS

package/skills/ioredis/SKILL.md

@@ -7,6 +7,8 @@ description: "ioredis v5 reference for Node.js Redis client — connection setup
 
 ioredis v5.x. Requires Node.js >= 12, Redis >= 2.6.12. 100% TypeScript.
 
+<quick_reference>
+
 ## Critical: Import Style
 
 ```ts
@@ -17,15 +19,6 @@ import { Redis } from "ioredis";
 import { Redis, Cluster } from "ioredis";
 ```
 
-## When to Load References
-
-| Need                                                                           | Reference file                                                       |
-| ------------------------------------------------------------------------------ | -------------------------------------------------------------------- |
-| Connection setup, RedisOptions, TLS, retryStrategy, lifecycle                  | [references/connection-options.md](references/connection-options.md) |
-| Core API: pipelines, transactions, Pub/Sub, Lua scripting, scanning, events    | [references/core-api.md](references/core-api.md)                     |
-| Streams, auto-pipelining, transformers, binary data, error handling, debugging | [references/advanced-patterns.md](references/advanced-patterns.md)   |
-| Redis Cluster setup, ClusterOptions, Sentinel config, failover                 | [references/cluster-sentinel.md](references/cluster-sentinel.md)     |
-
 ## Quick Reference
 
 | Operation      | Code                                                                       |
@@ -40,6 +33,10 @@ import { Redis, Cluster } from "ioredis";
 | Graceful close | `await redis.quit()`                                                       |
 | Force close    | `redis.disconnect()`                                                       |
 
+</quick_reference>
+
+<gotchas>
+
 ## Common Gotchas
 
 1. **Named import**: Always `import { Redis } from "ioredis"` with NodeNext resolution
@@ -49,3 +46,18 @@ import { Redis, Cluster } from "ioredis";
 5. **`showFriendlyErrorStack`**: Performance cost — never enable in production
 6. **Cluster pipelines**: All keys in a pipeline must hash to slots served by the same node
 7. **`enableAutoPipelining`**: 35-50% throughput improvement, safe to enable globally
+
+</gotchas>
+
+<references>
+
+## When to Load References
+
+| Need                                                                           | Reference file                                                       |
+| ------------------------------------------------------------------------------ | -------------------------------------------------------------------- |
+| Connection setup, RedisOptions, TLS, retryStrategy, lifecycle                  | [references/connection-options.md](references/connection-options.md) |
+| Core API: pipelines, transactions, Pub/Sub, Lua scripting, scanning, events    | [references/core-api.md](references/core-api.md)                     |
+| Streams, auto-pipelining, transformers, binary data, error handling, debugging | [references/advanced-patterns.md](references/advanced-patterns.md)   |
+| Redis Cluster setup, ClusterOptions, Sentinel config, failover                 | [references/cluster-sentinel.md](references/cluster-sentinel.md)     |
+
+</references>

package/skills/nextjs-best-practices/SKILL.md

@@ -9,27 +9,7 @@ Apply these rules when writing or reviewing Next.js code.
 
 > **Note:** Next.js 16 renamed `middleware.ts` to `proxy.ts`. Verify `proxy.ts` support in your version; `middleware.ts` remains the stable API.
 
-## Table of Contents
-
-- [File Conventions](#file-conventions)
-- [RSC Boundaries](#rsc-boundaries)
-- [Async Patterns](#async-patterns)
-- [Runtime Selection](#runtime-selection)
-- [Directives](#directives)
-- [Functions](#functions)
-- [Error Handling](#error-handling)
-- [Data Patterns](#data-patterns)
-- [Route Handlers](#route-handlers)
-- [Metadata & OG Images](#metadata--og-images)
-- [Image Optimization](#image-optimization)
-- [Font Optimization](#font-optimization)
-- [Bundling](#bundling)
-- [Scripts](#scripts)
-- [Hydration Errors](#hydration-errors)
-- [Suspense Boundaries](#suspense-boundaries)
-- [Parallel & Intercepting Routes](#parallel--intercepting-routes)
-- [Self-Hosting](#self-hosting)
-- [Debug Tricks](#debug-tricks)
+<references>
 
 ## File Conventions
 
@@ -192,3 +172,5 @@ See [debug-tricks.md](references/debug-tricks.md) for:
 
 - MCP endpoint for AI-assisted debugging
 - Rebuild specific routes with `--debug-build-paths`
+
+</references>

package/skills/owasp-security-review/SKILL.md

@@ -5,6 +5,8 @@ description: "Review code and architectures against the OWASP Top 10:2025 — th
 
 # OWASP Top 10:2025 Security Review
 
+<quick_reference>
+
 ## Quick reference
 
 | #   | Category                              | Key risk                                                               | Avg incidence |
@@ -20,9 +22,23 @@ description: "Review code and architectures against the OWASP Top 10:2025 — th
 | A09 | Security Logging & Alerting Failures  | Missing audit logs, no alerting, log injection, sensitive data in logs | 3.91%         |
 | A10 | Mishandling of Exceptional Conditions | Failing open, info leakage via errors, unchecked return values         | 2.95%         |
 
+## Severity classification
+
+Use these severity levels when reporting findings:
+
+- **Critical**: Directly exploitable, leads to full system compromise or mass data breach (e.g., SQLi with no parameterization, hardcoded admin credentials, missing auth on admin endpoints).
+- **High**: Exploitable with moderate effort, significant data exposure or privilege escalation (e.g., IDOR, weak password hashing, SSRF, deserialization of untrusted data).
+- **Medium**: Exploitable under specific conditions, limited impact (e.g., missing CSRF protection, verbose error messages, missing security headers).
+- **Low**: Defense-in-depth issue, minimal direct impact (e.g., missing rate limiting, incomplete logging, suboptimal crypto configuration).
+
+</quick_reference>
+
+<workflow>
+
 ## Workflows
 
-### 1. Code review for security
+<phase_1_code_review>
+### Code review for security
 
 Systematically check the code against each relevant category:
 
@@ -41,8 +57,10 @@ Priority order for review (highest impact first):
 - `[MEDIUM]` Error handling → A10 (Exceptional Conditions), A09 (Logging)
 - `[MEDIUM]` Architecture/design → A06 (Insecure Design)
 - `[MEDIUM]` Data integrity → A08 (Integrity Failures)
+</phase_1_code_review>
 
-### 2. Security audit checklist
+<phase_2_audit_checklist>
+### Security audit checklist
 
 Generate a checklist for a feature or codebase:
 
@@ -50,8 +68,10 @@ Generate a checklist for a feature or codebase:
 2. For each of the 10 categories, determine if it applies.
 3. For applicable categories, load the reference file and produce a checklist of items to verify.
 4. Output a markdown checklist grouped by category.
+</phase_2_audit_checklist>
 
-### 3. Remediation guidance
+<phase_3_remediation>
+### Remediation guidance
 
 When a vulnerability is identified:
 
@@ -59,6 +79,11 @@ When a vulnerability is identified:
 2. Load the corresponding reference file.
 3. Apply the prevention checklist to produce a specific, actionable fix.
 4. Provide a code example of the fix when possible.
+</phase_3_remediation>
+
+</workflow>
+
+<references>
 
 ## Reference files
 
@@ -75,15 +100,8 @@ Load the relevant file when you need detailed guidance for a specific category:
 - **A09 Logging & Alerting** — audit trails, log injection, alerting, sensitive data in logs: [references/a09-logging-alerting-failures.md](references/a09-logging-alerting-failures.md)
 - **A10 Exceptional Conditions** — error handling, fail-closed, resource cleanup, info leakage: [references/a10-exceptional-conditions.md](references/a10-exceptional-conditions.md)
 
-## Severity classification
-
-Use these severity levels when reporting findings:
-
-- **Critical**: Directly exploitable, leads to full system compromise or mass data breach (e.g., SQLi with no parameterization, hardcoded admin credentials, missing auth on admin endpoints).
-- **High**: Exploitable with moderate effort, significant data exposure or privilege escalation (e.g., IDOR, weak password hashing, SSRF, deserialization of untrusted data).
-- **Medium**: Exploitable under specific conditions, limited impact (e.g., missing CSRF protection, verbose error messages, missing security headers).
-- **Low**: Defense-in-depth issue, minimal direct impact (e.g., missing rate limiting, incomplete logging, suboptimal crypto configuration).
-
-## Output format
+</references>
 
+<output>
 When reporting security findings, use the template in [template.md](template.md) for each finding.
+</output>

package/skills/postgresql/SKILL.md

@@ -7,6 +7,8 @@ description: "PostgreSQL 16+ reference for writing queries, designing schemas, m
 
 Version: **16+**. All syntax is standard; most features apply to PostgreSQL 13+.
 
+<quick_reference>
+
 ## Quick patterns
 
 ```sql
@@ -24,6 +26,25 @@ WHERE relkind = 'r' ORDER BY pg_total_relation_size(oid) DESC;
 SELECT pg_terminate_backend(pid) FROM pg_stat_activity WHERE pid = <pid>;
 ```
 
+</quick_reference>
+
+<rules>
+
+## Key non-obvious facts
+
+- Every statement runs in a transaction. Without `BEGIN`, each statement auto-commits.
+- `jsonb` stores parsed binary (faster queries); `json` stores raw text (exact input preserved). Prefer `jsonb`.
+- `LIKE 'foo%'` can use B-tree; `LIKE '%foo'` cannot — use `pg_trgm` GIN for suffix search.
+- `CREATE INDEX CONCURRENTLY` avoids table lock but cannot run inside a transaction block.
+- `EXPLAIN` without `ANALYZE` shows the planner's _estimate_. Always use `EXPLAIN (ANALYZE, BUFFERS)` for real data.
+- Null values are stored in indexes by B-tree (unlike some other databases). `IS NULL` can use an index.
+- `SERIAL`/`BIGSERIAL` are shorthand for sequence + default; prefer `GENERATED ALWAYS AS IDENTITY` (SQL standard).
+- Default isolation level is **Read Committed**. `SERIALIZABLE` prevents all anomalies but may abort transactions.
+
+</rules>
+
+<references>
+
 ## Reference files
 
 Load the relevant file when working on a specific topic:
@@ -38,13 +59,4 @@ Load the relevant file when working on a specific topic:
 | EXPLAIN output, VACUUM, stats          | [references/performance.md](references/performance.md)   | Query tuning or performance analysis   |
 | psql meta-commands                     | [references/psql-cli.md](references/psql-cli.md)         | Working interactively in psql          |
 
-## Key non-obvious facts
-
-- Every statement runs in a transaction. Without `BEGIN`, each statement auto-commits.
-- `jsonb` stores parsed binary (faster queries); `json` stores raw text (exact input preserved). Prefer `jsonb`.
-- `LIKE 'foo%'` can use B-tree; `LIKE '%foo'` cannot — use `pg_trgm` GIN for suffix search.
-- `CREATE INDEX CONCURRENTLY` avoids table lock but cannot run inside a transaction block.
-- `EXPLAIN` without `ANALYZE` shows the planner's _estimate_. Always use `EXPLAIN (ANALYZE, BUFFERS)` for real data.
-- Null values are stored in indexes by B-tree (unlike some other databases). `IS NULL` can use an index.
-- `SERIAL`/`BIGSERIAL` are shorthand for sequence + default; prefer `GENERATED ALWAYS AS IDENTITY` (SQL standard).
-- Default isolation level is **Read Committed**. `SERIALIZABLE` prevents all anomalies but may abort transactions.
+</references>

package/skills/react-best-practices/SKILL.md

@@ -7,18 +7,7 @@ description: "React and Next.js performance patterns. Use when writing, reviewin
 
 Performance optimization guide for React and Next.js applications, based on Vercel Engineering practices. 8 categories organized by impact.
 
-## Table of Contents
-
-- [When to Apply](#when-to-apply)
-- [Quick Reference](#quick-reference)
-  - [Async Patterns (CRITICAL)](#1-async-patterns-critical)
-  - [Bundle Optimization (CRITICAL)](#2-bundle-optimization-critical)
-  - [Server-Side Performance (HIGH)](#3-server-side-performance-high)
-  - [Client-Side Patterns (MEDIUM-HIGH)](#4-client-side-patterns-medium-high)
-  - [Re-render Optimization (MEDIUM)](#5-re-render-optimization-medium)
-  - [Rendering Performance (MEDIUM)](#6-rendering-performance-medium)
-  - [JavaScript Performance (LOW-MEDIUM)](#7-javascript-performance-low-medium)
-  - [Advanced Patterns (LOW)](#8-advanced-patterns-low)
+<constraints>
 
 ## When to Apply
 
@@ -27,6 +16,10 @@ Performance optimization guide for React and Next.js applications, based on Verc
 - Reviewing code for performance issues
 - Optimizing bundle size or load times
 
+</constraints>
+
+<references>
+
 ## Quick Reference
 
 ### 1. Async Patterns (CRITICAL)
@@ -108,3 +101,5 @@ Performance optimization guide for React and Next.js applications, based on Verc
 
 - Store event handlers in refs -- stable effect subscriptions
 - Initialize app once per load -- module-level guard
+
+</references>

package/skills/service-worker/SKILL.md

@@ -10,17 +10,12 @@ description: "Service Worker API implementation guide — registration, lifecycl
 - [Constraints](#constraints)
 - [Lifecycle](#lifecycle)
 - [Registration](#registration)
-- [Install Event — Pre-cache Assets](#install-event--pre-cache-assets)
-- [Activate Event — Clean Up Old Caches](#activate-event--clean-up-old-caches)
-- [Fetch Event — Intercept Requests](#fetch-event--intercept-requests)
-- [Navigation Preload](#navigation-preload)
-- [Updating a Service Worker](#updating-a-service-worker)
-- [Communicating with Pages](#communicating-with-pages)
+- [Install / Activate / Fetch Events](#install-event--pre-cache-assets)
 - [Common Pitfalls](#common-pitfalls)
-- [Push Notifications & Background Sync](#push-notifications--background-sync)
-- [API Quick Reference](#api-quick-reference)
 - [Next.js Integration](#nextjs-integration)
-- [DevTools](#devtools)
+- [Reference files](#reference-files)
+
+<constraints>
 
 ## Constraints
 
@@ -31,6 +26,10 @@ description: "Service Worker API implementation guide — registration, lifecycl
 - Scope defaults to the directory containing the SW file
 - `self` refers to `ServiceWorkerGlobalScope`
 
+</constraints>
+
+<quick_reference>
+
 ## Lifecycle
 
 ```
@@ -45,6 +44,27 @@ register() → Download → Install → [Wait] → Activate → Fetch control
 
 A document must reload to be controlled (or call `clients.claim()` during activate).
 
+## Updating a Service Worker
+
+- Browser byte-compares the SW file on each navigation (or every 24h)
+- New version installs in background while old version still serves
+- Increment the cache name (e.g., `v1` → `v2`) in the new version
+- Delete old caches in the `activate` handler
+- Call `self.skipWaiting()` in `install` to activate immediately
+- Call `self.clients.claim()` in `activate` to take control of open pages
+
+## DevTools
+
+- **Chrome**: `chrome://inspect/#service-workers` or Application > Service Workers
+- **Firefox**: `about:debugging#/runtime/this-firefox` or Application > Service Workers
+- **Edge**: `edge://inspect/#service-workers` or Application > Service Workers
+
+Unregister, update, and inspect caches from the Application panel. Use "Update on reload" checkbox during development.
+
+</quick_reference>
+
+<examples>
+
 ## Registration
 
 ```js
@@ -125,15 +145,6 @@ self.addEventListener("fetch", (event) => {
 });
 ```
 
-## Updating a Service Worker
-
-- Browser byte-compares the SW file on each navigation (or every 24h)
-- New version installs in background while old version still serves
-- Increment the cache name (e.g., `v1` → `v2`) in the new version
-- Delete old caches in the `activate` handler
-- Call `self.skipWaiting()` in `install` to activate immediately
-- Call `self.clients.claim()` in `activate` to take control of open pages
-
 ## Communicating with Pages
 
 ```js
@@ -150,22 +161,6 @@ self.addEventListener("message", (event) => {
 });
 ```
 
-## Common Pitfalls
-
-1. **Response cloning** — `response.clone()` before both caching and returning, since body streams can only be read once
-2. **Opaque responses** — cross-origin fetches without CORS return opaque responses (status 0). `cache.add()` will refuse them. Use `cache.put()` but you can't inspect the response
-3. **waitUntil timing** — call `event.waitUntil()` synchronously within the event handler, not inside an async callback
-4. **Scope ceiling** — a SW cannot control URLs above its own directory unless `Service-Worker-Allowed` header is set
-5. **No state persistence** — the SW may terminate at any time when idle. Don't store state in global variables — use Cache API or IndexedDB
-
-## Push Notifications & Background Sync
-
-For push subscription, handling push events, and background sync implementation, see [references/push-and-sync.md](references/push-and-sync.md).
-
-## API Quick Reference
-
-For detailed interfaces (`Cache`, `CacheStorage`, `FetchEvent`, `Clients`, `ServiceWorkerRegistration`, `ServiceWorkerGlobalScope`), see [references/api-reference.md](references/api-reference.md).
-
 ## Next.js Integration
 
 In Next.js, place the service worker file in `public/sw.js`. `public/sw.js` is intentionally plain JS (not processed by Next.js build pipeline). Register it from a client component:
@@ -186,10 +181,26 @@ export function ServiceWorkerRegistrar() {
 
 Add to root layout. Next.js serves `public/` files at the root, so `/sw.js` scope covers `/`.
 
-## DevTools
+</examples>
 
-- **Chrome**: `chrome://inspect/#service-workers` or Application > Service Workers
-- **Firefox**: `about:debugging#/runtime/this-firefox` or Application > Service Workers
-- **Edge**: `edge://inspect/#service-workers` or Application > Service Workers
+<gotchas>
 
-Unregister, update, and inspect caches from the Application panel. Use "Update on reload" checkbox during development.
+## Common Pitfalls
+
+1. **Response cloning** — `response.clone()` before both caching and returning, since body streams can only be read once
+2. **Opaque responses** — cross-origin fetches without CORS return opaque responses (status 0). `cache.add()` will refuse them. Use `cache.put()` but you can't inspect the response
+3. **waitUntil timing** — call `event.waitUntil()` synchronously within the event handler, not inside an async callback
+4. **Scope ceiling** — a SW cannot control URLs above its own directory unless `Service-Worker-Allowed` header is set
+5. **No state persistence** — the SW may terminate at any time when idle. Don't store state in global variables — use Cache API or IndexedDB
+
+</gotchas>
+
+<references>
+
+## Reference files
+
+- **Caching strategies** (cache-first, network-first, stale-while-revalidate): [references/caching-strategies.md](references/caching-strategies.md)
+- **Push notifications & background sync** (push subscription, push events, background sync): [references/push-and-sync.md](references/push-and-sync.md)
+- **API quick reference** (`Cache`, `CacheStorage`, `FetchEvent`, `Clients`, `ServiceWorkerRegistration`, `ServiceWorkerGlobalScope`): [references/api-reference.md](references/api-reference.md)
+
+</references>

package/skills/tanstack-query/SKILL.md

@@ -13,6 +13,8 @@ description: |
 
 # TanStack Query v5 (React)
 
+<quick_reference>
+
 ## Setup
 
 ```tsx
@@ -52,6 +54,10 @@ function App() {
 
 **Key recommendation:** Set `staleTime` above 0 to control refetch frequency rather than disabling individual refetch triggers.
 
+</quick_reference>
+
+<examples>
+
 ## queryOptions — co-locate key + fn
 
 Always use `queryOptions` to define query configurations. It enables type inference across `useQuery`, `prefetchQuery`, `getQueryData`, and `setQueryData`.
@@ -325,6 +331,10 @@ const { data } = useQuery({
 
 `skipToken` prevents `refetch()` from working — use `enabled: false` if you need manual refetch.
 
+</examples>
+
+<gotchas>
+
 ## setQueryData — immutability
 
 ```tsx
@@ -340,9 +350,15 @@ queryClient.setQueryData(['todo', id], (old) =>
 )
 ```
 
+</gotchas>
+
+<references>
+
 ## Further Reference
 
 - **Full API signatures** (useQuery, useMutation, useInfiniteQuery, QueryClient): See [references/api-reference.md](references/api-reference.md)
 - **SSR & Next.js** (hydration, App Router, streaming): See [references/ssr-nextjs.md](references/ssr-nextjs.md)
 - **Testing** (renderHook, mocking, setup): See [references/testing.md](references/testing.md)
 - **Advanced patterns** (TypeScript, Suspense, waterfalls, network modes): See [references/advanced-patterns.md](references/advanced-patterns.md)
+
+</references>

package/skills/typescript-conventions/SKILL.md

@@ -7,6 +7,8 @@ description: "TypeScript coding conventions for strict, type-safe projects. Use
 
 Project-wide TypeScript standards that complement agent-specific instructions.
 
+<rules>
+
 ## Type Safety
 
 - **No `any`**: Use `unknown` if the type is truly dynamic, then narrow.
@@ -43,9 +45,15 @@ import { Redis } from "ioredis";
 - **Query** (returns data): `get`, `find`, `list`, `fetch`
 - **Command** (changes state): `create`, `update`, `delete`, `add`, `remove`
 
+</rules>
+
+<anti_patterns>
+
 ## Anti-Patterns
 
 - **Primitive obsession**: Use branded types or Zod enums, not raw strings for IDs and statuses.
 - **Magic numbers/strings**: Use constants from a shared package (e.g., `RATE_LIMITS`, `PAGINATION`, `CACHE`).
 - **Long parameter lists**: Use an options object or a Zod schema.
 - **Premature abstraction**: Three similar lines > one premature helper. Abstract on the third repetition.
+
+</anti_patterns>