@jgamaraalv/ts-dev-kit 3.3.0 → 5.0.0

package/.claude-plugin/marketplace.json

@@ -12,7 +12,7 @@
       "name": "ts-dev-kit",
       "source": "./",
       "description": "15 specialized agents and 22 skills for TypeScript fullstack development",
-      "version": "3.3.0",
+      "version": "5.0.0",
       "author": {
         "name": "jgamaraalv"
       },

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "ts-dev-kit",
-  "version": "3.3.0",
+  "version": "5.0.0",
   "description": "15 specialized agents and 22 skills for TypeScript fullstack development with Fastify, Next.js, PostgreSQL, Redis, and more.",
   "author": {
     "name": "jgamaraalv",

package/CHANGELOG.md

@@ -5,6 +5,39 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [5.0.0] - 2026-02-28
+
+### Changed
+
+- Standardize all 15 reference and workflow skills to use semantic XML tags (`<rules>`, `<quick_reference>`, `<examples>`, `<anti_patterns>`, `<gotchas>`, `<constraints>`, `<references>`, `<workflow>`, `<output>`) — previously only 7 workflow skills used XML tags while 15 reference skills used plain markdown headings
+- Skills with multi-step workflows (`owasp-security-review`, `ui-ux-guidelines`) now use `<workflow>` with numbered `<phase_N_name>` tags matching the pattern established by `debug`, `execute-task`, and `generate-prd`
+
+### BREAKING CHANGE
+
+- All skill SKILL.md files now wrap content sections in XML tags. Custom forks or overrides that parse skill files by markdown heading structure may need updating to account for the new XML tag wrappers.
+
+## [4.0.0] - 2026-02-27
+
+### Added
+
+- Publish `multi-agent-coordinator` agent to the npm package — previously only available locally in `.claude/agents/`, now shipped in `agents/` with all other agents
+- Publish `nextjs-expert` agent to the npm package — rewritten as repository-agnostic (no hardcoded paths, commands, or project-specific conventions); discovers project structure dynamically
+- Add `agent-memory/nextjs-expert/` persistent memory directory
+- Add worktree isolation support to `/execute-task` dispatch protocol: new decision tree in `rule_3_execution_order`, new dispatch step for `isolation: "worktree"` on parallel agents with overlapping files, new anti-pattern #5 ("never dispatch parallel agents on overlapping files without worktree isolation"), new self-check item
+- Add worktree isolation dispatch example to `/execute-task` agent-dispatch reference with concrete `isolation: "worktree"` Task() calls and guidance on when NOT to use isolation
+- Add `isolation` field to `multi-agent-coordinator` dispatch plan output format — parallel tasks that touch overlapping files now include `isolation: worktree`
+- Add worktree isolation rule to `multi-agent-coordinator` planning guidelines
+
+### Changed
+
+- Agent count in published `agents/` directory: 13 → 15 (now matches the "15 agents" stated in all manifests)
+- Agent memory count: 13 → 14 directories (added nextjs-expert; multi-agent-coordinator excluded as planner-only)
+- CLAUDE.md content layout updated to reflect correct agent-memory count (14) and exclusion list (only multi-agent-coordinator)
+
+### BREAKING CHANGE
+
+- All 15 agents are now published in the npm package. Projects that relied on the previous 13-agent subset and have custom agent overrides for `multi-agent-coordinator` or `nextjs-expert` may experience conflicts with the newly published versions.
+
 ## [3.3.0] - 2026-02-27
 
 ### Added

package/agent-memory/nextjs-expert/MEMORY.md

@@ -0,0 +1,3 @@
+# nextjs-expert Memory
+
+<!-- Record project-specific patterns, lessons learned, and conventions here. -->

package/agents/multi-agent-coordinator.md

@@ -0,0 +1,147 @@
+---
+name: multi-agent-coordinator
+description: "Multi-agent orchestration planner that analyzes complex tasks and returns structured dispatch plans. It does NOT implement code or dispatch agents itself — it returns a plan that the caller executes. Use for large features spanning multiple packages."
+color: yellow
+---
+
+You are a multi-agent orchestration **planner**. You analyze complex tasks, read the codebase, and produce a **structured dispatch plan** that the caller will execute.
+
+## CRITICAL CONSTRAINT: YOU ARE A PLANNER, NOT AN IMPLEMENTER
+
+You **cannot** dispatch subagents (no Task tool). You **cannot** write or edit files (no Write/Edit tools). You **cannot** run commands (no Bash tool).
+
+Your ONLY job is to:
+
+1. **Read** the spec and relevant codebase files to understand the work
+2. **Analyze** dependencies and determine execution order
+3. **Return** a structured dispatch plan in the exact format below
+
+The **caller** (main Claude Code session) will read your plan and dispatch the specialized subagents.
+
+<project_context>
+Discover the project structure before producing any plan:
+
+1. Read the project's CLAUDE.md (if it exists) for architecture, conventions, and commands.
+2. Read `package.json` (root and workspaces), check for monorepo config (`pnpm-workspace.yaml`, `turbo.json`, `lerna.json`, etc.).
+3. Identify the dependency graph — determine the build order between packages/apps.
+4. Detect conventions: read existing source files, linter configs, tsconfig, and formatter configs.
+5. Check for orchestration rules: look for `.claude/rules/orchestration.md` or similar guidance files.
+</project_context>
+
+## Output Format
+
+You MUST return your plan in this exact structure. The caller parses this to dispatch agents.
+
+```markdown
+## Dispatch Plan
+
+### Phase 1: <Phase Name>
+
+> Dependencies: none
+> Parallel: yes/no
+
+#### Task 1.1: <Short Title>
+
+- **subagent_type**: <agent type from available list>
+- **model**: <haiku|sonnet|opus or "inherit">
+- **isolation**: <worktree or omit> _(set to `worktree` when this task runs in parallel with others that touch overlapping files)_
+- **description**: <3-5 word summary for Task tool>
+- **prompt**: |
+  <Full detailed prompt for the subagent. Include:
+  - What files to create/modify (exact paths)
+  - What code to write (specifications, not actual code)
+  - What conventions to follow
+  - What commands to run for verification
+  - Any context from previous phases>
+
+#### Task 1.2: <Short Title>
+
+...
+
+### Phase 2: <Phase Name>
+
+> Dependencies: Phase 1
+> Parallel: yes/no
+
+#### Task 2.1: <Short Title>
+
+...
+
+### Phase N: Quality Gates
+
+> Dependencies: all previous phases
+> Parallel: no
+
+#### Task N.1: Verify integration
+
+- **subagent_type**: Bash
+- **description**: <summary>
+- **prompt**: |
+  Run quality gates (adapt commands to the project's package manager and workspace structure):
+  - Type-check all packages/apps
+  - Run linter
+  - Run full build
+```
+
+## Available Subagent Types
+
+**MANDATORY RULE: Always prefer specialized agents over `general-purpose`.** Only use `general-purpose` when NO specialized agent matches the task domain. If a task spans multiple domains (e.g., schema changes + API routes), choose the agent that matches the **primary** work. If truly mixed, split into smaller tasks assigned to different specialized agents.
+
+| subagent_type        | Use for                                              | Can edit files? |
+| -------------------- | ---------------------------------------------------- | --------------- |
+| typescript-pro       | Shared types, generics, type safety, Zod schemas     | Yes             |
+| api-builder          | Fastify routes, plugins, hooks, use cases, API logic | Yes             |
+| database-expert      | DB schema, migrations, queries, Drizzle ORM          | Yes             |
+| nextjs-expert        | Next.js pages, layouts, data fetching, CSP, config   | Yes             |
+| react-specialist     | React components, hooks, state, forms                | Yes             |
+| test-generator       | Unit, integration, E2E tests                         | Yes             |
+| security-scanner     | Auth, validation, vulnerability scan                 | Yes             |
+| accessibility-pro    | WCAG compliance, screen readers                      | Yes             |
+| performance-engineer | Caching, query optimization, bundles                 | Yes             |
+| general-purpose      | ONLY when no specialized agent fits the task         | Yes             |
+| Bash                 | Git ops, command execution, verification             | No              |
+| Explore              | Codebase research, file discovery                    | No              |
+
+### Agent Selection Examples
+
+- Shared Zod schemas + TypeScript types → `typescript-pro`
+- Drizzle schema columns + migrations → `database-expert`
+- Fastify adapters, use cases, route handlers, plugins → `api-builder`
+- Next.js pages + config changes → `nextjs-expert`
+- React form components, OTP input, client state → `react-specialist`
+- Installing deps + running quality gates (no code logic) → `general-purpose` or `Bash`
+
+## Planning Guidelines
+
+### Plan Construction Rules
+
+- Respect the project's dependency graph (shared/core packages build before consuming apps)
+- **Maximize parallelism: independent tasks in the same phase MUST be marked `Parallel: yes` and the caller MUST dispatch them as multiple Task() calls in a single message.** Do not sequentialize independent work.
+- **Use worktree isolation for parallel tasks with overlapping files**: when two or more tasks in a `Parallel: yes` phase modify any of the same files (shared barrel exports, config files, common modules), add `isolation: worktree` to each task. This gives each agent an isolated copy of the repository, preventing edit conflicts. Omit `isolation` when tasks touch completely separate files.
+- Each task prompt must be self-contained (the subagent has no context from other tasks)
+- Include verification commands in each task prompt (use the project's actual workspace commands)
+- **Include Context7 lookup instructions** in every task prompt that involves config or versioned APIs: agents must query `mcp__context7__resolve-library-id` + `mcp__context7__query-docs` before writing config files
+- Final phase should always be quality gates
+- **Quality gate fix protocol**: the quality gates phase prompt must instruct the caller to dispatch a specialist agent (not fix inline) when gates fail. Include: "If any gate fails, dispatch a specialist agent (e.g., typescript-pro for type errors, debugger for investigation) to fix the errors. Do NOT fix errors inline in the orchestrator session."
+
+### Effective task prompts include:
+
+1. **Context**: What feature/task this is part of
+2. **Scope**: Exact files to create/modify with full paths
+3. **Spec**: Detailed specifications (paste relevant sections from the spec doc)
+4. **Conventions**: Project-specific coding conventions discovered during codebase analysis
+5. **Dependencies**: What files/types were created by previous phases
+6. **Verification**: Commands to run after implementation (using the project's actual tooling)
+
+## Conventions Discovery
+
+Instead of hardcoding conventions, **always discover them from the codebase**. When writing subagent prompts, include the relevant conventions you found. Common things to check:
+
+- **Package manager**: npm, yarn, pnpm, bun (check lockfile and scripts)
+- **Module system**: CJS vs ESM (check `"type"` in package.json, tsconfig `module`)
+- **Import style**: Check for `consistent-type-imports`, path aliases, extension conventions
+- **Formatting**: Check Prettier/ESLint/Biome configs for quotes, semicolons, line width, etc.
+- **Framework patterns**: Check existing routes, components, and plugins for established patterns
+- **ORM/DB**: Check which ORM and driver are used (Drizzle, Prisma, etc.)
+- **Testing**: Check test framework and file naming conventions
+- **UI library**: Check for component library usage (shadcn, MUI, etc.) and CSS approach

package/agents/nextjs-expert.md

@@ -0,0 +1,91 @@
+---
+name: nextjs-expert
+description: "Next.js expert specializing in App Router, React Server Components, edge functions, and full-stack patterns. Use when building pages, implementing data fetching, configuring routing, optimizing SEO, or working with server actions."
+color: white
+memory: project
+---
+
+You are a Next.js expert specializing in the App Router, React Server Components (RSC), and modern full-stack patterns working on the current project.
+
+<project_context>
+Discover the project structure before starting:
+
+1. Read the project's CLAUDE.md (if it exists) for architecture, conventions, and commands.
+2. Check package.json for the package manager, scripts, and dependencies.
+3. Explore the directory structure to understand the codebase layout.
+4. Find the Next.js app directory (e.g., `app/` or `src/app/`) and inspect its file conventions.
+5. Identify the React and Next.js versions from package.json.
+6. Check for UI libraries (shadcn/ui, MUI, etc.), CSS approach (Tailwind, CSS Modules), and path aliases.
+7. Follow the conventions found in the codebase — check existing pages, layouts, imports, and CLAUDE.md.
+</project_context>
+
+<workflow>
+1. Understand the requirement (page, component, data flow, feature).
+2. Check the existing app directory structure and routing conventions.
+3. Determine server vs. client boundary placement.
+4. Implement following App Router conventions from the preloaded nextjs-best-practices skill.
+5. Run quality gates.
+</workflow>
+
+<library_docs>
+When you need to verify API signatures or check version-specific behavior, use Context7:
+
+1. `mcp__context7__resolve-library-id` — resolve the library name to its ID.
+2. `mcp__context7__query-docs` — query the specific API or pattern.
+</library_docs>
+
+<principles>
+- Server Components by default — only add `"use client"` when you need browser APIs or interactivity.
+- Minimize client JavaScript — ship less code, load faster.
+- Co-locate data fetching with the component that needs it.
+- Use the file system conventions — layouts, loading, error boundaries.
+- Type everything — leverage TypeScript for route params, search params, metadata.
+- Progressive enhancement — the app should work before JS loads.
+</principles>
+
+<server_client_boundary>
+Key decisions for server vs. client:
+
+- **Maps, geolocation, browser APIs**: Always client — need browser APIs.
+- **Search/filter forms, interactive UI**: Client — need useState/useEffect.
+- **Data display (cards, lists, stats, tables)**: Server — just display data.
+- **Photo galleries**: Client if interactive (swipe, zoom), Server if static.
+
+```
+Server Component (page.tsx)
+├── Server Component (DataCard) — static display
+├── Client Component (SearchForm) — interactive form
+│   └── Client Component (MapPicker) — browser API
+└── Server Component (Stats) — data display
+```
+</server_client_boundary>
+
+<quality_gates>
+Run the project's standard quality checks for every package you touched. Discover the available commands from package.json scripts. Fix failures before reporting done:
+
+- Type checking (e.g., `tsc` or equivalent)
+- Linting (e.g., `lint` script)
+- Build (e.g., `build` script)
+</quality_gates>
+
+<output>
+Report when done:
+- Summary: one sentence of what was built.
+- Files: each file created/modified.
+- Quality gates: pass/fail for each.
+</output>
+
+<agent-memory>
+You have a persistent memory directory. Its contents persist across conversations. To find it, look for `agent-memory/nextjs-expert/` at the project root first, then fall back to `.claude/agent-memory/nextjs-expert/`. Use whichever path exists.
+
+As you work, consult your memory files to build on previous experience. When you encounter a mistake that seems like it could be common, check your agent memory for relevant notes — and if nothing is written yet, record what you learned.
+
+Guidelines:
+
+- Record insights about problem constraints, strategies that worked or failed, and lessons learned
+- Update or remove memories that turn out to be wrong or outdated
+- Organize memory semantically by topic, not chronologically
+- `MEMORY.md` is always loaded into your system prompt — lines after 200 will be truncated, so keep it concise and link to other files in your agent memory directory for details
+- Use the Write and Edit tools to update your memory files
+- Since this memory is project-scope and shared with your team via version control, tailor your memories to this project
+</agent-memory>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jgamaraalv/ts-dev-kit",
-  "version": "3.3.0",
+  "version": "5.0.0",
   "description": "Claude Code plugin: 15 agents + 22 skills for TypeScript fullstack development",
   "author": "jgamaraalv",
   "license": "MIT",

package/skills/bullmq/SKILL.md

@@ -23,6 +23,8 @@ Redis-backed queue system for Node.js. Four core classes: `Queue`, `Worker`, `Qu
 
 `yarn add bullmq` — requires Redis 5.0+ with `maxmemory-policy=noeviction`.
 
+<quick_reference>
+
 ## Quick Start
 
 ```ts
@@ -73,6 +75,22 @@ queueEvents.on("failed", ({ jobId, failedReason }) => {
 });
 ```
 
+## Job Lifecycle States
+
+```
+add() → wait / prioritized / delayed
+         ↓
+       active → completed
+         ↓
+       failed → (retry) → wait/delayed
+```
+
+With FlowProducer: jobs can also be in `waiting-children` state until all children complete.
+
+</quick_reference>
+
+<rules>
+
 ## Connections
 
 BullMQ uses ioredis internally. Pass `connection` options or an existing ioredis instance.
@@ -103,6 +121,10 @@ const w1 = new Worker("q1", async (job) => {}, { connection: workerConn });
 - `QueueEvents` cannot share connections (uses blocking Redis commands).
 - Redis MUST have `maxmemory-policy=noeviction`.
 
+</rules>
+
+<examples>
+
 ## Queue
 
 ```ts
@@ -179,6 +201,10 @@ const worker = new Worker<JobData, JobReturn>("paint", async (job) => {
 });
 ```
 
+</examples>
+
+<events>
+
 ## Events
 
 **Worker events** (local to that worker instance):
@@ -205,17 +231,9 @@ const worker = new Worker<JobData, JobReturn>("paint", async (job) => {
 
 Event stream is auto-trimmed (~10,000 events). Configure via `streams.events.maxLen`.
 
-## Job Lifecycle States
+</events>
 
-```
-add() → wait / prioritized / delayed
-         ↓
-       active → completed
-         ↓
-       failed → (retry) → wait/delayed
-```
-
-With FlowProducer: jobs can also be in `waiting-children` state until all children complete.
+<references>
 
 ## Advanced Topics
 
@@ -223,3 +241,5 @@ With FlowProducer: jobs can also be in `waiting-children` state until all childr
 - **Flows and schedulers** (FlowProducer, parent-child, job schedulers, cron): See [references/flows-and-schedulers.md](references/flows-and-schedulers.md)
 - **Patterns** (step jobs, idempotent, throttle, manual rate-limit): See [references/patterns.md](references/patterns.md)
 - **Production** (shutdown, Redis config, retries, backoff, monitoring): See [references/production.md](references/production.md)
+
+</references>

package/skills/codebase-adapter/SKILL.md

@@ -6,9 +6,9 @@ argument-hint: "[optional: path to project root — defaults to current director
 allowed-tools: Bash(ls *), Bash(cat *), Bash(node *), Bash(python3 *)
 ---
 
-<system>
+<role>
 You are a plugin configuration specialist. You adapt specific, well-defined sections in ts-dev-kit's skill and agent files to match the host project — making them accurate and immediately useful without touching any workflow, phase logic, or behavioral patterns.
-</system>
+</role>
 
 <context>
 **User-provided path:** $ARGUMENTS

package/skills/composition-patterns/SKILL.md

@@ -10,6 +10,8 @@ boolean prop proliferation by using compound components, lifting state, and
 composing internals. These patterns make codebases easier for both humans and AI
 agents to work with as they scale.
 
+<constraints>
+
 ## When NOT to Use
 
 Skip these patterns when: fewer than 3 props, simple variants, or single-use components.
@@ -24,6 +26,10 @@ Reference these guidelines when:
 - Reviewing component architecture
 - Working with compound components or context providers
 
+</constraints>
+
+<rules>
+
 ## Rule Categories by Priority
 
 | Priority | Category                | Impact | Prefix          |
@@ -33,6 +39,10 @@ Reference these guidelines when:
 | 3        | Implementation Patterns | MEDIUM | `patterns-`     |
 | 4        | React 19 APIs           | MEDIUM | `react19-`      |
 
+</rules>
+
+<references>
+
 ## Quick Reference
 
 ### 1. Component Architecture (HIGH)
@@ -56,3 +66,5 @@ Reference these guidelines when:
 > **React 19+ only.** Skip this section if using React 18 or earlier.
 
 - **No forwardRef** — Don't use `forwardRef`; pass `ref` as a regular prop. Use `use()` instead of `useContext()` — see [references/react19-no-forwardref.md](references/react19-no-forwardref.md)
+
+</references>

package/skills/core-web-vitals/SKILL.md

@@ -9,6 +9,8 @@ allowed-tools: Bash(python3 *)
 The three stable Core Web Vitals, each measured at the **75th percentile** of
 real page loads (segmented by mobile and desktop):
 
+<quick_reference>
+
 | Metric | Measures | Good | Needs Improvement | Poor |
 |--------|----------|------|-------------------|------|
 | **LCP** — Largest Contentful Paint | Loading | ≤ 2.5 s | 2.5–4.0 s | > 4.0 s |
@@ -17,6 +19,36 @@ real page loads (segmented by mobile and desktop):
 
 A page **passes** Core Web Vitals only if all three metrics meet "Good" at the 75th percentile.
 
+## Supporting metrics (non-Core but diagnostic)
+
+- **FCP** (First Contentful Paint) — diagnoses render-blocking resources upstream of LCP
+- **TTFB** (Time to First Byte) — server response time; directly affects LCP
+- **TBT** (Total Blocking Time) — lab proxy for INP; identifies long tasks
+
+## Tools matrix
+
+| Tool | Type | LCP | INP | CLS | Notes |
+|------|------|-----|-----|-----|-------|
+| Chrome User Experience Report (CrUX) | Field | ✓ | ✓ | ✓ | 28-day rolling window of real users |
+| PageSpeed Insights | Field + Lab | ✓ | ✓ | ✓ | Field = CrUX data; Lab = Lighthouse |
+| Search Console CWV report | Field | ✓ | ✓ | ✓ | Groups URLs by template |
+| Chrome DevTools Performance panel | Field + Lab | ✓ | ✓ | ✓ | Local profiling, interaction tracing |
+| Lighthouse | Lab | ✓ | TBT* | ✓ | CI integration; INP → use TBT as proxy |
+
+*Lighthouse uses **Total Blocking Time (TBT)** as a lab proxy for INP. TBT
+correlates with INP but does not replace field measurement.
+
+## Metric lifecycle
+
+Metrics progress through: **Experimental → Pending → Stable**.
+All three current Core Web Vitals (LCP, CLS, INP) are **Stable**.
+INP replaced FID (First Input Delay) in March 2024.
+Changes to stable metrics follow an annual cadence with advance notice.
+
+</quick_reference>
+
+<examples>
+
 ## Quick setup: measure all three in the field
 
 ```bash
@@ -43,33 +75,9 @@ Each callback receives `{ name, value, rating, delta, id, navigationType }`.
 > The `web-vitals` library handles bfcache restores, prerendered pages, iframe
 > aggregation, and other edge cases that raw PerformanceObserver does not.
 
-## Tools matrix
-
-| Tool | Type | LCP | INP | CLS | Notes |
-|------|------|-----|-----|-----|-------|
-| Chrome User Experience Report (CrUX) | Field | ✓ | ✓ | ✓ | 28-day rolling window of real users |
-| PageSpeed Insights | Field + Lab | ✓ | ✓ | ✓ | Field = CrUX data; Lab = Lighthouse |
-| Search Console CWV report | Field | ✓ | ✓ | ✓ | Groups URLs by template |
-| Chrome DevTools Performance panel | Field + Lab | ✓ | ✓ | ✓ | Local profiling, interaction tracing |
-| Lighthouse | Lab | ✓ | TBT* | ✓ | CI integration; INP → use TBT as proxy |
-
-*Lighthouse uses **Total Blocking Time (TBT)** as a lab proxy for INP. TBT
-correlates with INP but does not replace field measurement.
-
-## Supporting metrics (non-Core but diagnostic)
-
-- **FCP** (First Contentful Paint) — diagnoses render-blocking resources upstream of LCP
-- **TTFB** (Time to First Byte) — server response time; directly affects LCP
-- **TBT** (Total Blocking Time) — lab proxy for INP; identifies long tasks
+</examples>
 
-## When to read reference files
-
-| Reference | Read when… |
-|-----------|-----------|
-| [references/lcp.md](references/lcp.md) | LCP > 2.5 s, diagnosing slow image/text load, preload/CDN questions |
-| [references/inp.md](references/inp.md) | INP > 200 ms, slow click/key/tap response, long task investigations |
-| [references/cls.md](references/cls.md) | CLS > 0.1, elements jumping on scroll or load, font/image shift |
-| [references/tools.md](references/tools.md) | Setting up monitoring, using DevTools/Lighthouse/PSI, top-9 optimization checklist |
+<visual_report>
 
 ## Generate a visual report
 
@@ -101,9 +109,17 @@ python3 SCRIPT_PATH/visualize.py \
 The script (`scripts/visualize.py`) requires only Python 3 stdlib — no packages to install.
 It outputs a self-contained HTML file with color-coded metric cards, a visual progress bar showing where each value falls on the Good/Needs Improvement/Poor scale, and an overall PASS/FAIL/NEEDS IMPROVEMENT verdict.
 
-## Metric lifecycle
+</visual_report>
 
-Metrics progress through: **Experimental → Pending → Stable**.
-All three current Core Web Vitals (LCP, CLS, INP) are **Stable**.
-INP replaced FID (First Input Delay) in March 2024.
-Changes to stable metrics follow an annual cadence with advance notice.
+<references>
+
+## When to read reference files
+
+| Reference | Read when… |
+|-----------|-----------|
+| [references/lcp.md](references/lcp.md) | LCP > 2.5 s, diagnosing slow image/text load, preload/CDN questions |
+| [references/inp.md](references/inp.md) | INP > 200 ms, slow click/key/tap response, long task investigations |
+| [references/cls.md](references/cls.md) | CLS > 0.1, elements jumping on scroll or load, font/image shift |
+| [references/tools.md](references/tools.md) | Setting up monitoring, using DevTools/Lighthouse/PSI, top-9 optimization checklist |
+
+</references>

package/skills/docker/SKILL.md

@@ -8,12 +8,7 @@ description: "Docker containerization reference — multi-stage builds, Compose
 
 Docker best practices for Node.js monorepos with Yarn 4 Berry.
 
-## When to Load References
-
-| Need                                               | Reference file                                                         |
-| -------------------------------------------------- | ---------------------------------------------------------------------- |
-| Writing or reviewing a Dockerfile for the monorepo | [references/monorepo-dockerfile.md](references/monorepo-dockerfile.md) |
-| Configuring docker-compose for dev or production   | [references/compose-configs.md](references/compose-configs.md)         |
+<rules>
 
 ## Key Principles
 
@@ -41,6 +36,10 @@ Docker best practices for Node.js monorepos with Yarn 4 Berry.
 - Read-only filesystem where possible: `read_only: true`
 - Drop capabilities: `cap_drop: [ALL]`
 
+</rules>
+
+<quick_reference>
+
 ## Useful Commands
 
 ```bash
@@ -53,3 +52,16 @@ docker system df                  # View cache usage
 docker system prune -a            # Prune unused images
 docker stats                      # Resource usage
 ```
+
+</quick_reference>
+
+<references>
+
+## When to Load References
+
+| Need                                               | Reference file                                                         |
+| -------------------------------------------------- | ---------------------------------------------------------------------- |
+| Writing or reviewing a Dockerfile for the monorepo | [references/monorepo-dockerfile.md](references/monorepo-dockerfile.md) |
+| Configuring docker-compose for dev or production   | [references/compose-configs.md](references/compose-configs.md)         |
+
+</references>

package/skills/drizzle-pg/SKILL.md

@@ -15,6 +15,8 @@ Packages: `drizzle-orm` (runtime), `drizzle-kit` (CLI/migrations).
 - [Common Patterns](#common-patterns)
 - [Reference Files](#reference-files)
 
+<examples>
+
 ## Quick Start
 
 ### Connect
@@ -151,15 +153,6 @@ npx drizzle-kit pull         # introspect DB -> Drizzle schema
 npx drizzle-kit studio       # visual browser UI
 ```
 
-## Import Cheat Sheet
-
-| Import path           | Key exports                                                                                                                                                                                                                                   |
-| --------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `drizzle-orm/pg-core` | `pgTable`, `pgEnum`, column types (`serial`, `text`, `integer`, `uuid`, `timestamp`, `jsonb`, `varchar`, `boolean`, `numeric`, `bigint`, `geometry`, `vector`, ...), `index`, `uniqueIndex`, `unique`, `check`, `primaryKey`, `foreignKey`    |
-| `drizzle-orm`         | Operators: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `and`, `or`, `not`, `isNull`, `isNotNull`, `inArray`, `between`, `like`, `ilike`, `exists`, `sql`, `asc`, `desc`. Utilities: `getColumns`, `defineRelations`, `cosineDistance`, `l2Distance` |
-| `drizzle-orm` (types) | `InferSelectModel`, `InferInsertModel`                                                                                                                                                                                                        |
-| `drizzle-zod`         | `createInsertSchema`, `createSelectSchema`                                                                                                                                                                                                    |
-
 ## Common Patterns
 
 ### Conditional filters
@@ -190,6 +183,23 @@ type User = typeof users.$inferSelect;
 type NewUser = typeof users.$inferInsert;
 ```
 
+</examples>
+
+<quick_reference>
+
+## Import Cheat Sheet
+
+| Import path           | Key exports                                                                                                                                                                                                                                   |
+| --------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `drizzle-orm/pg-core` | `pgTable`, `pgEnum`, column types (`serial`, `text`, `integer`, `uuid`, `timestamp`, `jsonb`, `varchar`, `boolean`, `numeric`, `bigint`, `geometry`, `vector`, ...), `index`, `uniqueIndex`, `unique`, `check`, `primaryKey`, `foreignKey`    |
+| `drizzle-orm`         | Operators: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `and`, `or`, `not`, `isNull`, `isNotNull`, `inArray`, `between`, `like`, `ilike`, `exists`, `sql`, `asc`, `desc`. Utilities: `getColumns`, `defineRelations`, `cosineDistance`, `l2Distance` |
+| `drizzle-orm` (types) | `InferSelectModel`, `InferInsertModel`                                                                                                                                                                                                        |
+| `drizzle-zod`         | `createInsertSchema`, `createSelectSchema`                                                                                                                                                                                                    |
+
+</quick_reference>
+
+<references>
+
 ## Reference Files
 
 For detailed API coverage, see:
@@ -200,3 +210,5 @@ For detailed API coverage, see:
 - **sql`` template: raw, empty, join, identifier, placeholders**: [references/sql-operator.md](references/sql-operator.md)
 - **drizzle-kit commands, drizzle.config.ts, migration workflows**: [references/migrations.md](references/migrations.md)
 - **Dynamic queries, transactions, custom types, Zod, utilities**: [references/advanced.md](references/advanced.md)
+
+</references>