Execute Task

Step 1 — Determine input type:

• If $ARGUMENTS looks like a file path (ends in .md, or starts with /, ./, docs/, or contains a directory separator): read the file.
• Otherwise: treat it as a free-form task description — skip to Step 3.

Step 2 — Validate the task document: A task document is ready for execution when it contains ALL of:

• ## Scope — Files with at least one file entry
• ## Success Criteria with at least one testable criterion
• ## Verification Plan with baseline and post-change checks

If all required sections are present → proceed to phase 1.

Step 3 — Generate the task document: If the document is missing any required section, OR the input was a free-form description:

1. Inform the user:

   Task document incomplete. Generating a structured task document via /generate-tasks before proceeding.

2. Call Skill(skill: "generate-tasks") passing the original input as context.
3. After generation, note the path of the saved TASK_N.md file.
4. Read the generated file and confirm all required sections are present.
5. Resume execution using the generated document — continue to phase 1.

1. Read the resolved task document fully (path determined in phase 0).
2. Read the project CLAUDE.md and root package.json — understand project structure, available commands, and dependency graph.
3. Search the codebase for existing patterns — use Grep/Glob to find related files, similar implementations, and reusable code relevant to the task's file scope.
4. Identify the affected packages/directories from the task's "Scope — Files" section.

Backend

Frontend

Shared packages — typescript-pro or general-purpose (shared types, schemas, utilities)

Cross-cutting specialists (use alongside any domain)

A single task may require agents from multiple sub-areas. For example, "add a new resource endpoint with list UI" needs database-expert (schema) + api-builder (route) + react-specialist (component).

Discover the actual technologies and versions from package.json. Describe the project based on CLAUDE.md or README.

Identify the required skills from the domain area, then call each one:

Skill(skill: "fastify-best-practices")
Skill(skill: "drizzle-pg")
Skill(skill: "postgresql")

Backend sub-areas:

• Database → /drizzle-pg, /postgresql
• Endpoints → /fastify-best-practices
• Queues → /bullmq, /ioredis
• Security → /owasp-security-review

Frontend sub-areas:

• Components → /react-best-practices, /composition-patterns
• Pages/routing → /nextjs-best-practices
• UI/UX → /ui-ux-guidelines
• Performance → /react-best-practices

Cross-cutting → combine skills from each sub-area involved.

In ALL execution modes: include explicit Skill() call instructions in each subagent prompt (see references/agent-dispatch.md). The orchestrator does not need to load skills itself — agents load them 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, 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.

Do not decompose if:

1. The task is small and contained within a single package.
2. The cross-package changes are trivial (e.g., adding one type to shared and importing it).

Selecting the agent type:

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:

• Role persona: who the agent is and what it specializes in.
• Domain expertise: specific technologies, frameworks, and versions.
• Project context: how this sub-area fits into the project (discover from CLAUDE.md and package.json).
• Constraints: patterns to follow, files to reference, conventions to match.
• Skills to load: explicit Skill(skill: "...") calls for domain-specific rules.

Your expertise: Redis-backed job queues, workers, flow producers, retry strategies, rate limiting, and graceful shutdown.

Before writing any code

1. Read CLAUDE.md and relevant package.json files to understand the project structure and conventions.
2. Call the Skill tool to load these domain skills:
   • Skill(skill: "bullmq")
   • Skill(skill: "ioredis")

Your task

[task details...]

Project context

Discover from the codebase:

• Redis connection configuration (search for Redis imports)
• Existing queue/worker patterns (search for queue or worker files)
• Import conventions (check existing code for named vs default imports) [...] """ )

Each agent prompt must follow the template in references/agent-dispatch.md. The agent must be able to complete its work independently.

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).

Set the model parameter on the Task tool call accordingly.

Constraints:

1. Subagents cannot spawn other subagents. All dispatch happens from the main session.
2. Each agent prompt must be fully self-contained — do not assume agents have conversation history.
3. Review each agent's output before dispatching dependents.

EXECUTION MODE: SINGLE-ROLE — Single domain. I will dispatch 1-2 focused agents for implementation.

OR

EXECUTION MODE: MULTI-ROLE — Multiple domains. I will dispatch specialized agents across domains via the Task tool.

OR

EXECUTION MODE: PLAN — The task is highly complex. I will enter plan mode to design a structured implementation plan before executing.

CRITICAL: In ALL execution modes, the orchestrator (main session) NEVER writes application code directly. All implementation — components, hooks, pages, routes, services, tests — is delegated to agents via the Task tool. The orchestrator's role is: context gathering, agent dispatch, output review, integration glue (under 15 lines), and quality gates.

The difference between SINGLE-ROLE and MULTI-ROLE is decomposition complexity, NOT whether agents are used:

• SINGLE-ROLE: simpler decomposition (1-2 agents, same domain). Use when the task is contained within one package or domain.
• MULTI-ROLE: complex decomposition (3+ agents, multiple domains). Use when the task spans packages or skill sets.

Use PLAN mode when:

• The task has 4+ distinct roles or implementation phases.
• The scope is large enough that context window management becomes a concern.
• The task benefits from upfront architectural planning before any code is written.

In PLAN mode: use EnterPlanMode to design the full plan. Once the user approves it, exit plan mode and execute phases sequentially as orchestrator, with context cleanup between major phases when needed.

1. Extract from the task document:

   • Success criteria — exact conditions for task completion
   • Baseline checks — what to run/capture BEFORE changes
   • Post-change checks — what to verify AFTER changes
   • Performance benchmarks — specific metrics with targets
   • Non-functional requirements — scoped to this task's domain
   • Scope — Files — the exact list of files to create or modify

   State them to the user:

   Task loaded: [task title]

   • Dependencies: [list or "none"]
   • Files in scope: N files
   • Success criteria: [count] criteria
   • Baseline checks: [list]
   • Post-change checks: [list]
   • Performance targets: [list or "none defined"]

2. For questions about project libraries, use Context7 (mcp__context7__resolve-library-id → mcp__context7__query-docs) to query up-to-date documentation. If anything is ambiguous, ask the user before proceeding.

3. Check MCP availability — use ToolSearch to detect which browser MCPs are available (playwright, chrome-devtools, or neither), then confirm against the task's "MCP Checks" section.

4. Plan the implementation order from the task's file scope — build dependencies before dependents: shared types → database schema → API layer → UI components → pages → tests.

5. Confirm the verification plan with the user:

   Verification plan:

   • Baseline checks: [from task doc]
   • MCPs available: [detected list or "none — shell-only"]
   • Post-change checks: [from task doc]

Step 1: Standard quality gates — run and record results (pass/fail, counts, bundle sizes). Discover the exact commands from package.json scripts for each affected package.

Step 2: MCP-based checks — follow this decision tree in order:

1. Use ToolSearch to confirm which browser MCPs are available (playwright, chrome-devtools, or neither).
2. If browser MCPs are available AND the task touches frontend pages: a. Check if the dev server is running (attempt to navigate to localhost or the configured URL). b. If dev server is accessible: navigate to each affected page, capture screenshots of key states, and measure performance (LCP, load time). Use Chrome DevTools traces or Playwright screenshots as appropriate. c. If dev server is NOT accessible: ask the user whether to start it or skip visual checks. Do NOT silently skip — the user must confirm.
3. If no browser MCPs are available: note it explicitly and proceed with shell-only checks (build output, bundle sizes).
4. Backend tasks: execute requests to affected endpoints (via curl or available API MCPs) and record response status, payload shape, and timing.
5. Database tasks: record current schema state for affected tables.

Step 3: Store baseline — all values captured here are compared against post-change results in phase 5b.

When visual/performance checks are skipped, state the reason:

Baseline captured. MCP-based visual checks skipped — [reason: no browser MCPs available | dev server not running (user confirmed skip) | no frontend pages affected].

The orchestrator ALWAYS runs baseline capture before dispatching any agents, regardless of execution mode.

Before dispatching, check the execution mode decision from phase 2 to determine decomposition complexity.

As orchestrator, your responsibilities are: context gathering, agent dispatch, output review, integration glue, and quality gates. You do NOT write application code (components, hooks, pages, routes, services, tests).

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 — 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. 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.

Self-check: If you find yourself creating application files (routes, components, services, hooks, tests, pages), STOP and delegate to an agent instead.

Decision tree (include in agent prompts when relevant):

• Is this code used by multiple modules? YES → Create in the shared/common package.
• Is this code used by multiple modules? NO → Is this component multi-file? YES → Create folder with index.tsx + related files. NO → Single file, co-located with usage.

Discover the available commands from package.json scripts for each affected package. Common gates:

1. Type checking — run the project's typecheck command (e.g., tsc, typecheck)
2. Linting — run the project's lint command (e.g., lint, eslint)
3. Tests (if available) — run the project's test command (e.g., test, vitest)
4. Build — run the project's build command (e.g., build)
5. Self-check — review your changes against the success criteria from the task document.

For monorepos, run these for each affected workspace/package. Discover the workspace command pattern from CLAUDE.md or the root package.json (e.g., yarn workspace <name> <script>, pnpm --filter <name> <script>, npm -w <name> <script>, turbo run <script> --filter=<name>).

If a gate fails:

• Read the error output carefully.
• 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.

1. Re-run every check from phase 3b with identical parameters.
2. Compare each result against baseline:
   • Quality gates: must remain passing. New failures = regression.
   • Visual checks (if MCPs available): compare screenshots for unintended changes.
   • Performance (if MCPs available): compare metrics against task-defined benchmarks. Regressions > 10% must be investigated.
   • API responses: compare status codes and payload shapes. Breaking changes = regression.
3. Build the comparison table (see template.md for format).

If any regression is found, fix it, re-run phase 5 quality gates, then re-run this phase. Repeat until clean.

• CLAUDE.md — new commands, architecture changes, dependency graph updates, new conventions.
• Existing docs — new environment variables, setup steps, API contract changes.

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.

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.

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.

Do not add explanations, caveats, or follow-up suggestions unless the user explicitly asks. The report is the final output.