Execute Task

• "Execute TASK_02"
• "Implement docs/features/search/TASK_01.md"
• "Run this task"
• "Execute the task"
• "Implement the search feature"
• "Build the user creation flow end-to-end"
• "Add the notifications endpoint to the API"

$ARGUMENTS

Follow each phase in order. Each one feeds the next.

Resolve the input and ensure the task document is complete before executing.

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.

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

Before writing any code, build a mental model of the task scope.

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.

Determine the full execution context: role persona, domain area, domain technologies, project context, required skills, and available MCPs.

Map the task to one or more domain areas AND sub-areas. Sub-areas determine the specialist agent type and skill set.

Backend | Sub-area | Agent type | When | Key skills | |----------|-----------|------|------------| | Database | database-expert | Schema design, migrations, complex queries, indexes | drizzle-pg, postgresql | | Endpoints | api-builder | Routes, validation, handlers, API contracts | fastify-best-practices | | Queues | general-purpose | Job processing, workers, schedulers | bullmq, ioredis | | Security | security-scanner | Auth flows, RBAC, input sanitization | owasp-security-review |

Frontend | Sub-area | Agent type | When | Key skills | |----------|-----------|------|------------| | Components | react-specialist | Component architecture, hooks, state management, composition | react-best-practices, composition-patterns | | Pages/routing | general-purpose | Pages, layouts, data fetching, RSC boundaries | nextjs-best-practices | | UI/UX | ux-optimizer | User flows, form UX, friction reduction | ui-ux-guidelines | | Accessibility | accessibility-pro | WCAG compliance, keyboard nav, screen readers | — | | Performance | performance-engineer | Core Web Vitals, bundle size, re-renders | react-best-practices |

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

Cross-cutting specialists (use alongside any domain) | Agent type | When | |-----------|------| | test-generator | Writing test suites, improving coverage | | debugger | Investigating errors, stack traces | | docker-expert | Dockerfiles, compose, container config | | code-reviewer | Post-implementation review | | playwright-expert | E2E browser tests |

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

Read the relevant package.json to identify installed packages and their versions. Use the actual versions found — do not assume.

Compose a role persona that combines the domain sub-area, project context, technologies, and task nature.

• "You are a database specialist working with [ORM] and [database] on schema design for [brief project description from CLAUDE.md]"
• "You are a React component architect specialized in composition patterns, hooks, and state management with [React version] and [UI library]"
• "You are a [framework] API developer building REST endpoints with validation and type-safe request/response contracts"
• "You are a frontend performance engineer optimizing Core Web Vitals and bundle size for a [framework] application"
• "You are a queue specialist designing job flows with [queue library] and retry strategies"

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

Call the Skill tool for each relevant skill before writing any code or dispatching agents. Skills inject domain-specific rules and best practices.

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

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

Match skills to the sub-area identified in domain_areas:

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.

Identify MCPs that can assist execution:

• context7 — query up-to-date library documentation (see below)
• playwright — test frontend in the browser, take screenshots, verify UI
• chrome-devtools — inspect pages, debug network requests, check console
• firecrawl — fetch external documentation or references from the web

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.

When a task spans multiple domains, decompose it into separate roles with isolated execution contexts.

Decompose into multiple roles when ANY of these apply:

1. The task touches 2+ packages or major directories (e.g., shared code + backend + frontend).
2. The task involves distinct skill sets (e.g., database schema design + frontend UI).
3. The changes in one domain are large enough to benefit from a focused agent.

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

Each role gets its own persona, skill set, context files, and success criteria.

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 (or ts-dev-kit:typescript-pro). Task: add shared schemas and types. Skills: none extra.

For each role, spawn a specialized subagent via the Task tool.

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.

1. If a matching agent exists (in any scope), use its resolved name as subagent_type.
2. 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.

Task( description: "Implement notification worker", subagent_type: "general-purpose", model: "sonnet", prompt: """ You are a queue specialist working on this project.

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.

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

Choose the model for each dispatched agent based on task complexity:

• haiku: simple, well-defined tasks — adding a type, writing a small utility, updating config, barrel file exports.
• sonnet: moderate tasks — implementing a feature within a single domain, writing tests, building a component.
• opus: complex tasks — cross-cutting concerns, architectural decisions, novel implementations requiring deep reasoning.

Set the model parameter on the Task tool call accordingly.

The main session acts as the orchestrator:

1. Analyze the task and define roles (this phase).
2. Create TaskCreate entries for each role to track progress.
3. Dispatch the first wave of agents (those with no blockers).
4. When a blocking agent completes, dispatch the next wave.
5. After all agents complete, run the final quality gates.
6. Produce the completion report (see template.md).

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.

At the end of phase 2, make an explicit execution mode decision and state it to the user:

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

Read the task document and load the criteria defined there. These are binding requirements for this execution.

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 requirement

…

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: jgamaraalv
• Source: jgamaraalv/ts-dev-kit
• License: MIT

Install and usage instructions live in the source repository linked above.