@jgamaraalv/ts-dev-kit 3.1.3 → 3.3.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.1.3",
+      "version": "3.3.0",
       "author": {
         "name": "jgamaraalv"
       },

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "ts-dev-kit",
-  "version": "3.1.3",
+  "version": "3.3.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,32 @@ 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).
 
+## [3.3.0] - 2026-02-27
+
+### Added
+
+- `/execute-task` orchestrator anti-patterns section: 4 explicit rules (never fix errors inline, never guess-loop configs, never announce parallel without delivering it, never write application code as orchestrator) with a pre-send self-check checklist
+- `/execute-task` agent-dispatch rules 5–6: parallel dispatch enforcement ("parallel means parallel") and mandatory Context7-before-config policy
+
+### Changed
+
+- `/execute-task` Context7 guidance upgraded from optional recommendation to **mandatory** for all config and versioned API files — must query docs before writing any configuration
+- `/execute-task` parallel dispatch rule now includes CRITICAL annotation: announcing N parallel agents requires exactly N Task() calls in the same message
+- `/execute-task` quality gate failure handling: orchestrator must dispatch a specialist agent to fix errors instead of fixing inline (prevents context exhaustion and mid-task compaction)
+
+## [3.2.0] - 2026-02-27
+
+### Added
+
+- Cross-scope agent name resolution: `/execute-task` and `/debug` dispatch protocols now detect whether agents are registered with a plugin prefix (`ts-dev-kit:agent-name`) and use the correct `subagent_type` automatically
+- `/yolo` Phase 1.5 — Ensure plugin availability: when ts-dev-kit is installed as a plugin, copies agents, skills, and agent-memory into the project before mounting the devcontainer so they're accessible inside the container
+- `/codebase-adapter` scope-aware discovery: phase 2 now searches agents and skills across project scope (`.claude/`), plugin scope (`node_modules/`), and personal scope (`~/.claude/`)
+
+### Fixed
+
+- Agent memory paths in all 13 agents now use dynamic resolution (`agent-memory/<name>/` at project root first, fallback to `.claude/agent-memory/<name>/`) instead of a hardcoded `.claude/` prefix
+- `/core-web-vitals` visualize script path no longer hardcoded to `~/.claude/skills/` — now discovers the correct path across all installation scopes
+
 ## [3.1.3] - 2026-02-27
 
 ### Fixed

package/agents/accessibility-pro.md

@@ -88,7 +88,7 @@ Report when done:
 </output>
 
 <agent-memory>
-You have a persistent memory directory at `.claude/agent-memory/accessibility-pro/`. Its contents persist across conversations.
+You have a persistent memory directory. Its contents persist across conversations. To find it, look for `agent-memory/accessibility-pro/` at the project root first, then fall back to `.claude/agent-memory/accessibility-pro/`. 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.
 

package/agents/api-builder.md

@@ -58,7 +58,7 @@ Report when done:
 </output>
 
 <agent-memory>
-You have a persistent memory directory at `.claude/agent-memory/api-builder/`. Its contents persist across conversations.
+You have a persistent memory directory. Its contents persist across conversations. To find it, look for `agent-memory/api-builder/` at the project root first, then fall back to `.claude/agent-memory/api-builder/`. 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.
 

package/agents/code-reviewer.md

@@ -70,7 +70,7 @@ APPROVE / REQUEST CHANGES / NEEDS DISCUSSION
 </output_format>
 
 <agent-memory>
-You have a persistent memory directory at `.claude/agent-memory/code-reviewer/`. Its contents persist across conversations.
+You have a persistent memory directory. Its contents persist across conversations. To find it, look for `agent-memory/code-reviewer/` at the project root first, then fall back to `.claude/agent-memory/code-reviewer/`. 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.
 

package/agents/database-expert.md

@@ -69,7 +69,7 @@ Report when done:
 </output>
 
 <agent-memory>
-You have a persistent memory directory at `.claude/agent-memory/database-expert/`. Its contents persist across conversations.
+You have a persistent memory directory. Its contents persist across conversations. To find it, look for `agent-memory/database-expert/` at the project root first, then fall back to `.claude/agent-memory/database-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.
 

package/agents/debugger.md

@@ -119,7 +119,7 @@ Report when done:
 </output>
 
 <agent-memory>
-You have a persistent memory directory at `.claude/agent-memory/debugger/`. Its contents persist across conversations.
+You have a persistent memory directory. Its contents persist across conversations. To find it, look for `agent-memory/debugger/` at the project root first, then fall back to `.claude/agent-memory/debugger/`. 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.
 

package/agents/docker-expert.md

@@ -43,7 +43,7 @@ Report when done:
 </output>
 
 <agent-memory>
-You have a persistent memory directory at `.claude/agent-memory/docker-expert/`. Its contents persist across conversations.
+You have a persistent memory directory. Its contents persist across conversations. To find it, look for `agent-memory/docker-expert/` at the project root first, then fall back to `.claude/agent-memory/docker-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.
 

package/agents/performance-engineer.md

@@ -101,7 +101,7 @@ Report when done:
 </output>
 
 <agent-memory>
-You have a persistent memory directory at `.claude/agent-memory/performance-engineer/`. Its contents persist across conversations.
+You have a persistent memory directory. Its contents persist across conversations. To find it, look for `agent-memory/performance-engineer/` at the project root first, then fall back to `.claude/agent-memory/performance-engineer/`. 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.
 

package/agents/playwright-expert.md

@@ -90,7 +90,7 @@ Report when done:
 </output>
 
 <agent-memory>
-You have a persistent memory directory at `.claude/agent-memory/playwright-expert/`. Its contents persist across conversations.
+You have a persistent memory directory. Its contents persist across conversations. To find it, look for `agent-memory/playwright-expert/` at the project root first, then fall back to `.claude/agent-memory/playwright-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.
 

package/agents/react-specialist.md

@@ -69,7 +69,7 @@ Report when done:
 </output>
 
 <agent-memory>
-You have a persistent memory directory at `.claude/agent-memory/react-specialist/`. Its contents persist across conversations.
+You have a persistent memory directory. Its contents persist across conversations. To find it, look for `agent-memory/react-specialist/` at the project root first, then fall back to `.claude/agent-memory/react-specialist/`. 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.
 

package/agents/security-scanner.md

@@ -71,7 +71,7 @@ If implementing fixes, run the project's standard quality checks for every packa
   </quality_gates>
 
 <agent-memory>
-You have a persistent memory directory at `.claude/agent-memory/security-scanner/`. Its contents persist across conversations.
+You have a persistent memory directory. Its contents persist across conversations. To find it, look for `agent-memory/security-scanner/` at the project root first, then fall back to `.claude/agent-memory/security-scanner/`. 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.
 

package/agents/test-generator.md

@@ -115,7 +115,7 @@ Report when done:
 </output>
 
 <agent-memory>
-You have a persistent memory directory at `.claude/agent-memory/test-generator/`. Its contents persist across conversations.
+You have a persistent memory directory. Its contents persist across conversations. To find it, look for `agent-memory/test-generator/` at the project root first, then fall back to `.claude/agent-memory/test-generator/`. 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.
 

package/agents/typescript-pro.md

@@ -110,7 +110,7 @@ Report when done:
 </output>
 
 <agent-memory>
-You have a persistent memory directory at `.claude/agent-memory/typescript-pro/`. Its contents persist across conversations.
+You have a persistent memory directory. Its contents persist across conversations. To find it, look for `agent-memory/typescript-pro/` at the project root first, then fall back to `.claude/agent-memory/typescript-pro/`. 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.
 

package/agents/ux-optimizer.md

@@ -66,7 +66,7 @@ Report when done:
 </output>
 
 <agent-memory>
-You have a persistent memory directory at `.claude/agent-memory/ux-optimizer/`. Its contents persist across conversations.
+You have a persistent memory directory. Its contents persist across conversations. To find it, look for `agent-memory/ux-optimizer/` at the project root first, then fall back to `.claude/agent-memory/ux-optimizer/`. 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.
 

package/package.json

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

package/skills/codebase-adapter/SKILL.md

@@ -19,7 +19,7 @@ Working directory: !`pwd`
 
 Lockfile detected: !`ls bun.lock pnpm-lock.yaml yarn.lock package-lock.json 2>/dev/null | head -1 || echo "none"`
 
-Agents installed: !`ls .claude/agents/ 2>/dev/null | tr '\n' ' ' || echo "(not found)"`
+Agents installed: !`ls .claude/agents/ 2>/dev/null | tr '\n' ' ' || ls agents/ 2>/dev/null | tr '\n' ' ' || echo "(not found)"`
 
 MCP servers configured: !`python3 -c "import json; s=json.load(open('.claude/settings.json')); print(', '.join(s.get('mcpServers',{}).keys()) or '(none)')" 2>/dev/null || echo "(not found)"`
 
@@ -91,9 +91,17 @@ Discover with Read, Glob, Grep — verify everything, assume nothing.
 - typecheck, lint, test, build command names
 - Compose the full run command per workspace (e.g., `pnpm --filter @acme/api typecheck`)
 
-**Available skills** — list directories in `[plugin-root]/skills/`
-
-**Available agents** — list files in `[plugin-root]/.claude/agents/`
+**Available skills** — search across all scopes in order:
+1. `[plugin-root]/skills/` (plugin or project-local)
+2. `.claude/skills/` in the project root (project scope)
+3. `~/.claude/skills/` (personal scope)
+Merge and deduplicate — plugin-root takes priority.
+
+**Available agents** — search across all scopes in order:
+1. `[plugin-root]/agents/` and `[plugin-root]/.claude/agents/` (plugin or project-local)
+2. `.claude/agents/` in the project root (project scope)
+3. `~/.claude/agents/` (personal scope)
+Merge and deduplicate — plugin-root takes priority.
 
 **Available MCPs** — read `.claude/settings.json` in project root (and `~/.claude/settings.json` as fallback). Extract `mcpServers` keys.
 </phase_2_project_discovery>

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

@@ -75,18 +75,25 @@ correlates with INP but does not replace field measurement.
 
 When the user provides metric values or a Lighthouse JSON file, generate an interactive HTML report and open it in the browser:
 
+To locate the script, find `scripts/visualize.py` relative to this skill's directory. The path depends on how ts-dev-kit is installed:
+- **Project scope**: `skills/core-web-vitals/scripts/visualize.py` or `.claude/skills/core-web-vitals/scripts/visualize.py`
+- **Personal scope**: `~/.claude/skills/core-web-vitals/scripts/visualize.py`
+- **Plugin scope**: resolve via `node_modules/@jgamaraalv/ts-dev-kit/skills/core-web-vitals/scripts/visualize.py`
+
+Use `find` or `ls` to discover the actual path, then run:
+
 ```bash
-# From manual values
-python3 ~/.claude/skills/core-web-vitals/scripts/visualize.py \
+# From manual values (replace SCRIPT_PATH with the discovered path)
+python3 SCRIPT_PATH/visualize.py \
   --lcp 2.1 --inp 180 --cls 0.05 \
   --url https://example.com
 
 # From a Lighthouse JSON output
-python3 ~/.claude/skills/core-web-vitals/scripts/visualize.py \
+python3 SCRIPT_PATH/visualize.py \
   --lighthouse lighthouse-report.json
 
 # Custom output path, no auto-open
-python3 ~/.claude/skills/core-web-vitals/scripts/visualize.py \
+python3 SCRIPT_PATH/visualize.py \
   --lcp 3.8 --inp 420 --cls 0.12 \
   --output cwv-report.html --no-open
 ```

package/skills/debug/references/debug-dispatch.md

@@ -72,7 +72,7 @@ After investigation, dispatch the appropriate **specialist agent** (not necessar
 [Specific changes needed — be precise about expected behavior]
 ```
 
-Use the agent type that matches the fix domain:
+Use the agent type that matches the fix domain. If ts-dev-kit is installed as a plugin, use the prefixed name (e.g., `ts-dev-kit:api-builder`). Check which agents are available in your context and use the exact registered name:
 - API route fix -> `api-builder` (preloads fastify-best-practices)
 - Database/query fix -> `database-expert` (preloads drizzle-pg, postgresql)
 - Component fix -> `react-specialist` (preloads react-best-practices, composition-patterns)
@@ -84,6 +84,8 @@ Use the agent type that matches the fix domain:
 
 ## Role-specific prompts
 
+> **Note:** All agent types below may be prefixed with `ts-dev-kit:` when the plugin is installed in plugin scope (e.g., `ts-dev-kit:debugger`). Check the available agents in your context and use the exact registered name.
+
 ### Backend debugger
 
 **Agent type**: `debugger`
@@ -166,9 +168,10 @@ Verification focus:
 # Dispatch: MULTI-LAYER
 
 # Wave 1: Parallel investigation
+# Use "debugger" or "ts-dev-kit:debugger" depending on scope
 Task(
   description: "Debug resource creation API endpoint",
-  subagent_type: "debugger",
+  subagent_type: "debugger",  // or "ts-dev-kit:debugger" if plugin-scoped
   model: "sonnet",
   prompt: """
 ## Bug description
@@ -195,7 +198,7 @@ Returns 200, but GET /api/<resource> returns empty array.
 
 Task(
   description: "Debug resource list page",
-  subagent_type: "debugger",
+  subagent_type: "debugger",  // or "ts-dev-kit:debugger" if plugin-scoped
   model: "sonnet",
   prompt: """
 ## Bug description
@@ -219,12 +222,12 @@ stale data.
 )
 
 # Wave 2: Dispatch fixes using specialist agents matching the fix domain
-# e.g., api-builder for API fix, react-specialist for frontend fix
+# e.g., api-builder (or ts-dev-kit:api-builder) for API fix
 
 # Wave 3: E2E verification
 Task(
   description: "Verify resource creation flow",
-  subagent_type: "playwright-expert",
+  subagent_type: "playwright-expert",  // or "ts-dev-kit:playwright-expert"
   model: "haiku",
   prompt: """
 ## Your task

package/skills/execute-task/SKILL.md

@@ -150,10 +150,12 @@ Identify MCPs that can assist execution:
 - chrome-devtools — inspect pages, debug network requests, check console
 - firecrawl — fetch external documentation or references from the web
 
-**Context7 usage**: When the task involves library APIs, version-specific patterns, or unfamiliar method signatures, use Context7 to query current documentation before writing code:
+**Context7 usage — MANDATORY for config and versioned APIs**: Many tools have breaking config changes across minor versions. **Before writing or modifying ANY configuration file** for versioned tools (OTel collector, Prometheus, Grafana, Loki, Tempo, Docker Compose, Drizzle, Fastify, Next.js, Redis, BullMQ, Nginx, etc.), you MUST query Context7 first to verify the correct syntax for the installed version. Do NOT try variations blindly — guess-looping config fixes wastes context and compounds errors.
+
 1. `mcp__context7__resolve-library-id` — resolve the library name (e.g., "fastify", "drizzle-orm", "next", "react", "bullmq") to its Context7 ID.
-2. `mcp__context7__query-docs` — query with the specific API, pattern, or feature you need.
-Check the project's package.json for installed versions first. In MULTI-ROLE mode, include these instructions in each agent prompt so agents can query docs themselves.
+2. `mcp__context7__query-docs` — query with the specific API, config key, or pattern you need.
+
+This applies to ALL roles: orchestrator, dispatched agents, and ad-hoc specialists. Check the project's package.json for installed versions first. In MULTI-ROLE mode, include these Context7 instructions in each agent prompt so agents query docs themselves before writing config.
 </available_mcps>
 </phase_2_role_assignment>
 
@@ -176,11 +178,11 @@ Do not decompose if:
 Each role gets its own persona, skill set, context files, and success criteria.
 
 <example>
-Role A: Database specialist (sub-area: Database). Agent: database-expert. Task: design schema + migration for the new feature. Skills: drizzle-pg, postgresql.
-Role B: API endpoint developer (sub-area: Endpoints). Agent: api-builder. Task: build REST routes consuming the new schema. Skills: fastify-best-practices.
-Role C: Component architect (sub-area: Components). Agent: react-specialist. Task: build the result card and list components. Skills: react-best-practices, composition-patterns.
+Role A: Database specialist (sub-area: Database). Agent: database-expert (or ts-dev-kit:database-expert if plugin-scoped). Task: design schema + migration for the new feature. Skills: drizzle-pg, postgresql.
+Role B: API endpoint developer (sub-area: Endpoints). Agent: api-builder (or ts-dev-kit:api-builder). Task: build REST routes consuming the new schema. Skills: fastify-best-practices.
+Role C: Component architect (sub-area: Components). Agent: react-specialist (or ts-dev-kit:react-specialist). Task: build the result card and list components. Skills: react-best-practices, composition-patterns.
 Role D: Page builder (sub-area: Pages/routing). Agent: general-purpose (ad-hoc). Task: wire components into the search results page with data fetching. Skills: nextjs-best-practices.
-Role E: TypeScript library developer. Agent: typescript-pro. Task: add shared schemas and types. Skills: none extra.
+Role E: TypeScript library developer. Agent: typescript-pro (or ts-dev-kit:typescript-pro). Task: add shared schemas and types. Skills: none extra.
 </example>
 </rule_1_define_roles_independently>
 
@@ -188,8 +190,11 @@ Role E: TypeScript library developer. Agent: typescript-pro. Task: add shared sc
 For each role, spawn a specialized subagent via the Task tool.
 
 **Selecting the agent type:**
-1. Check if a project agent exists in `.claude/agents/` that matches the sub-area (see domain_areas table above for the mapping).
-2. If a matching agent exists, use its name as `subagent_type` (e.g., `database-expert`, `api-builder`, `react-specialist`).
+1. **Resolve the agent name for the current scope.** Agents may be registered under different names depending on how ts-dev-kit is installed:
+   - **Project scope** (`.claude/agents/`): short name — e.g., `database-expert`
+   - **Plugin scope**: prefixed with the plugin namespace — e.g., `ts-dev-kit:database-expert`
+   Before dispatching, check which agents are available in your context. If you see agents with a `ts-dev-kit:` prefix, use the prefixed name as `subagent_type`. If agents are available by short name, use the short name.
+2. If a matching agent exists (in any scope), use its resolved name as `subagent_type`.
 3. If no matching agent exists, use `general-purpose` as `subagent_type` and embed the full role definition directly in the prompt — this creates an ad-hoc specialist without needing a .md file.
 
 **Ad-hoc agent creation** — when `subagent_type: "general-purpose"` is used as a specialist surrogate, the prompt must include:
@@ -233,7 +238,7 @@ Each agent prompt must follow the template in references/agent-dispatch.md. The
 
 <rule_3_execution_order>
 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.
+- **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.
 </rule_3_execution_order>
@@ -363,7 +368,7 @@ As orchestrator, your responsibilities are: context gathering, agent dispatch, o
 **Dispatch steps:**
 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. Launch dependent agents sequentially.
+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.
 
@@ -400,7 +405,7 @@ For monorepos, run these for each affected workspace/package. Discover the works
 
 If a gate fails:
 - Read the error output carefully.
-- Fix the root cause (do not suppress or ignore errors).
+- **CRITICAL: Dispatch an agent to fix the errors — do NOT fix them inline in the orchestrator session.** Fixing errors inline exhausts the context window and triggers compaction mid-task. Dispatch a `debugger` agent (for investigation) or the appropriate specialist agent (e.g., `typescript-pro` for type errors, `api-builder` for route errors) to fix the issues. The orchestrator's role is to read the error, decide which agent can fix it, and dispatch — never to edit application code itself.
 - Re-run all gates from step 1, since a fix may introduce new issues.
 - Repeat until all gates pass cleanly.
 </phase_5_quality_gates>
@@ -427,6 +432,31 @@ After all quality gates pass, review whether the changes require documentation u
 
 Only update documentation directly affected by the changes. Do not create new documentation files unless the changes introduce a new package or major feature with no existing docs.
 </phase_6_documentation>
+
+<orchestrator_anti_patterns>
+## Orchestrator Anti-Patterns — NEVER do these
+
+These are recurring mistakes. Violating any of these rules degrades execution quality and wastes context.
+
+### 1. Never fix errors in the main thread
+When quality gates (tsc/lint/test/build) fail during execution, **dispatch an isolated agent** to fix them. Do NOT attempt fixes in the main orchestrator session. Fixing inline exhausts the context window and triggers compaction mid-task, losing critical execution state.
+
+### 2. Never guess-loop config fixes
+When a tool or config isn't working (e.g., OTel collector pipeline, Prometheus scraping, Docker networking, Drizzle config, Fastify plugin options), use **Context7 immediately** to query the library docs for the installed version. Do NOT try variations blindly. Query with `mcp__context7__resolve-library-id` + `mcp__context7__query-docs` **before** touching any config file.
+
+### 3. Never announce parallel dispatch without delivering it
+If you announce "dispatching 3 agents in parallel", your message MUST contain exactly 3 Task() tool calls. Announcing parallel dispatch and then only sending 1 Task() is a protocol violation. Count your Task() calls before sending. If agents are independent, they go in the SAME message.
+
+### 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.
+
+### 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.
+- [ ] Did a quality gate fail? → STOP, dispatch a specialist agent to fix it.
+</orchestrator_anti_patterns>
 </workflow>
 
 <output>

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

@@ -44,6 +44,8 @@ Agents with preloaded skills (via `skills` frontmatter) do NOT need Skill() call
 | typescript-pro | (none) | — |
 | playwright-expert | (none) | — |
 
+> **Note:** When ts-dev-kit is installed as a plugin, agent names are prefixed with the plugin namespace (e.g., `ts-dev-kit:api-builder` instead of `api-builder`). Always check the available agents in your context and use the full registered name as `subagent_type`.
+
 ### Agent tool restrictions
 
 | Agent | Restriction |
@@ -68,9 +70,11 @@ All agents default to `sonnet`. Override with the Task tool's `model` parameter
 ## Dispatch example
 
 ```
+// Use the agent name as registered in your context.
+// Project-scoped: "api-builder". Plugin-scoped: "ts-dev-kit:api-builder".
 Task(
   description: "Build resource API routes",
-  subagent_type: "api-builder",
+  subagent_type: "api-builder",  // or "ts-dev-kit:api-builder" if plugin-scoped
   model: "sonnet",
   prompt: """
 ## Your task
@@ -97,7 +101,10 @@ Discover from the codebase:
 
 Before dispatching, resolve the agent type for each role:
 
-1. **Check `.claude/agents/`** — if a project agent matches the sub-area from the domain mapping (e.g., `database-expert` for DB work, `api-builder` for endpoints, `react-specialist` for components), use it as `subagent_type`.
+1. **Resolve the agent name for the current scope.** Agents may be registered with a plugin prefix depending on how ts-dev-kit is installed:
+   - **Project scope** (`.claude/agents/`): short name — e.g., `api-builder`
+   - **Plugin scope**: prefixed — e.g., `ts-dev-kit:api-builder`
+   Check which agents are available in your context and use the exact registered name as `subagent_type`.
 2. **Use a built-in agent type** — if the Task tool has a matching built-in type (e.g., `typescript-pro`, `performance-engineer`, `security-scanner`), use it directly.
 3. **Create an ad-hoc specialist** — if no existing agent matches, use `subagent_type: "general-purpose"` and embed the full specialist definition in the prompt.
 
@@ -153,4 +160,6 @@ Report when done:
 1. **Subagents cannot spawn other subagents.** All dispatch happens from the main session.
 2. **Agent prompts should be concise and task-specific.** Project agents already include project context, conventions, principles, and quality gates in their system prompt. Only include information the agent doesn't already have.
 3. **Ad-hoc prompts must be fully self-contained.** The `general-purpose` agent has no project context, so the prompt must include everything: role, project context, conventions, skills to load, quality gates, and output format.
-4. **Review each agent's output before dispatching dependents.** If an agent failed or produced unexpected results, fix the issue before continuing.
+4. **Review each agent's output before dispatching dependents.** If an agent failed or produced unexpected results, dispatch a fix agent — do NOT fix inline in the orchestrator.
+5. **Parallel means parallel.** When dispatching independent agents, include ALL Task() calls in a single message. If you announce "dispatching 3 agents in parallel", there must be exactly 3 Task() tool calls in that message. Never sequentialize independent work.
+6. **Context7 before config.** Before writing or modifying ANY configuration file for a versioned tool, query Context7 to verify the correct syntax for the installed version. Do not guess-loop config variations.

package/skills/yolo/SKILL.md

@@ -48,8 +48,11 @@ Follow this decision tree strictly. Each phase gates the next.
 START
   │
   ├─ Phase 1: Detect devcontainer
-  │    ├─ EXISTS → Phase 2
-  │    └─ MISSING → Phase 5 (install) → Phase 2
+  │    ├─ EXISTS → Phase 1.5
+  │    └─ MISSING → Phase 5 (install) → Phase 1.5
+  │
+  ├─ Phase 1.5: Ensure plugin availability
+  │    └─ Copy agents/skills/agent-memory into project if missing → Phase 2
   │
   ├─ Phase 2: Check Docker
   │    ├─ RUNNING → Phase 3
@@ -62,7 +65,7 @@ START
   │    └─ Start Docker Desktop/daemon → Phase 3
   │
   └─ Phase 5: Install devcontainer
-       └─ Scaffold .devcontainer/ → Phase 2
+       └─ Scaffold .devcontainer/ → Phase 1.5
 ```
 
 <phase_1_detect>
@@ -72,9 +75,9 @@ START
 Check whether `.devcontainer/devcontainer.json` exists in the project root.
 
 1. Read the `<live_context>` above for the pre-injected detection result.
-2. If **YES** — announce to the user and proceed to Phase 2:
+2. If **YES** — announce to the user and proceed to Phase 1.5:
 
-> **DEVCONTAINER DETECTED** — `.devcontainer/` found. Checking Docker status...
+> **DEVCONTAINER DETECTED** — `.devcontainer/` found. Checking plugin availability...
 
 3. If **NO** — announce and proceed to Phase 5:
 
@@ -82,6 +85,89 @@ Check whether `.devcontainer/devcontainer.json` exists in the project root.
 
 </phase_1_detect>
 
+<phase_1_5_ensure_plugin>
+
+## Phase 1.5 — Ensure plugin availability
+
+The devcontainer mounts only the project directory at `/workspace`. If ts-dev-kit is installed as a plugin (outside the project), its agents, skills, and agent-memory won't be available inside the container. This phase copies them into the project so they're accessible.
+
+### Step 1 — Check if agents and skills already exist in the project
+
+```bash
+ls .claude/agents/*.md 2>/dev/null && echo "AGENTS_PRESENT" || echo "AGENTS_MISSING"
+ls .claude/skills/*/SKILL.md 2>/dev/null && echo "SKILLS_PRESENT" || echo "SKILLS_MISSING"
+```
+
+If both are present, skip to Phase 2:
+
+> **PLUGIN FILES PRESENT** — agents and skills found in project. Checking Docker status...
+
+### Step 2 — Locate the plugin source
+
+If agents or skills are missing, search for the plugin in these locations (in order):
+
+1. `node_modules/@jgamaraalv/ts-dev-kit/` (npm-installed plugin)
+2. The directory containing this skill file (if invoked from a known path)
+
+```bash
+# Try npm location
+PLUGIN_SRC="node_modules/@jgamaraalv/ts-dev-kit"
+if [ ! -d "$PLUGIN_SRC/agents" ]; then
+  echo "Plugin not found in node_modules"
+  PLUGIN_SRC=""
+fi
+```
+
+If the plugin source cannot be found, inform the user and proceed to Phase 2 (the devcontainer will work but without ts-dev-kit agents):
+
+> **PLUGIN NOT FOUND** — Could not locate ts-dev-kit plugin files. The devcontainer will work but agents and skills won't be available. Install the plugin with `npm install -D @jgamaraalv/ts-dev-kit` to fix this.
+
+### Step 3 — Copy plugin files into the project
+
+```bash
+# Copy agents
+mkdir -p .claude/agents
+cp "$PLUGIN_SRC"/agents/*.md .claude/agents/
+
+# Copy skills (symlink directories to save space)
+mkdir -p .claude/skills
+for skill_dir in "$PLUGIN_SRC"/skills/*/; do
+  skill_name=$(basename "$skill_dir")
+  if [ ! -e ".claude/skills/$skill_name" ]; then
+    cp -r "$skill_dir" ".claude/skills/$skill_name"
+  fi
+done
+
+# Copy agent-memory scaffolds (don't overwrite existing memories)
+if [ -d "$PLUGIN_SRC/agent-memory" ]; then
+  for mem_dir in "$PLUGIN_SRC"/agent-memory/*/; do
+    mem_name=$(basename "$mem_dir")
+    if [ ! -d "agent-memory/$mem_name" ]; then
+      mkdir -p "agent-memory/$mem_name"
+      cp -n "$mem_dir"* "agent-memory/$mem_name/" 2>/dev/null || true
+    fi
+  done
+fi
+```
+
+### Step 4 — Suggest .gitignore update
+
+Check if these copied directories are already in `.gitignore`. If not, inform the user:
+
+> **PLUGIN FILES COPIED** — Agents, skills, and agent-memory copied into the project for devcontainer access.
+>
+> Consider adding these to `.gitignore` if you don't want to commit them:
+> ```
+> # ts-dev-kit plugin files (copied for devcontainer)
+> .claude/agents/
+> .claude/skills/
+> agent-memory/
+> ```
+
+Proceed to Phase 2.
+
+</phase_1_5_ensure_plugin>
+
 <phase_2_check_docker>
 
 ## Phase 2 — Check Docker
@@ -288,9 +374,9 @@ cat .devcontainer/devcontainer.json | head -5
 
 Announce completion:
 
-> **DEVCONTAINER INSTALLED** — `.devcontainer/` is ready with Dockerfile, firewall script, and configuration. Proceeding to check Docker...
+> **DEVCONTAINER INSTALLED** — `.devcontainer/` is ready with Dockerfile, firewall script, and configuration. Checking plugin availability...
 
-Return to Phase 2.
+Return to Phase 1.5.
 
 </phase_5_install_devcontainer>