task-decomposition

name	task-decomposition
description	Decomposes feature requests into concrete, parallelizable tasks for the agent team. Identifies file domains, defines API contracts via Apidog MCP, creates dependency-aware task lists, and determines optimal spawn order. Automatically loaded by the team-lead agent during planning.
user-invokable	false

Task Decomposition Protocol

When the team-lead receives a feature request, follow this protocol to break it into parallel-safe tasks before spawning any workers.

Step 1: Identify File Domains Touched

Scan the feature requirements and map every piece of work to a domain:

Domain	Owner	Directories
Backend	backend-dev	src/app/api/, src/services/, src/lib/server/, prisma/
Web Frontend	web-dev	src/app/ (non-api), src/components/, src/hooks/, src/lib/client/, src/styles/
Mobile	mobile-dev	lib/, android/, ios/, test/, integration_test/, pubspec.yaml
Tests	test-worker	tests/, __tests__/, **/*.test.*, **/*.spec.*
Shared	team-lead	src/types/, package.json, tsconfig.json, next.config.*, pubspec.yaml (coordinated)

If a feature only touches ONE domain, consider using a single worker instead of a full team deployment.

Auto-Detect Project Stack

Before spawning workers, detect which domains are relevant:

# Check for web project
test -f tsconfig.json && echo "WEB"

# Check for mobile project
test -f pubspec.yaml && echo "MOBILE"

# Check for backend project (implied by web or standalone)
test -d src/app/api/ && echo "BACKEND"

• Web only (tsconfig.json, no pubspec.yaml): spawn backend-dev + web-dev
• Mobile only (pubspec.yaml, no tsconfig.json): spawn mobile-dev
• Fullstack + Mobile (both): spawn backend-dev + web-dev + mobile-dev
• Neither: Ask project-owner for clarification

Only spawn workers for domains that the feature actually touches.

Step 2: Define API Contracts First

Before spawning ANY workers, if both backend and frontend are involved:

1. Query Apidog MCP for existing endpoint specifications

2. If endpoints don't exist yet, define them in Apidog first

3. Create shared types/models appropriate to the detected stack:

   Web/TypeScript Projects (tsconfig.json exists):

   • Create shared TypeScript interfaces in src/types/ for request/response shapes, entity types, shared enums and constants

   Flutter/Dart Projects (pubspec.yaml exists):

   • Define shared Dart models in lib/core/models/ for entity types, DTOs, enums and constants

   Other Projects:

   • Define shared types/models appropriate to the detected stack in a central location

This ensures backend and frontend code against the SAME contract.

Step 2.5: Extract Design Specs (if applicable)

If design artifacts exist (docs/designs/DES-<NNN>/), read the design README to extract the Screen → Node ID Mapping:

1. Read docs/designs/DES-<NNN>/README.md — find the "Screen → Node ID Mapping" table
2. Also check docs/requirements/REQ-<NNN>.md section 8 "Design References" (if exists)
3. For each UI task you create, attach the relevant Pencil node ID so workers can call batch_get(nodeIds: ["<id>"]) to read exact design specs

If the project-owner included the mapping in the spawn template, use that directly.

Step 3: Create Task List

For each task, specify ALL of these fields:

Task ID:      TASK-001
Title:        [Clear one-line description]
Assignee:     [backend-dev | web-dev | mobile-dev | test-worker | team-lead]
Domain:       [Exact directory paths this task touches]
Design:       [Pencil node ID, e.g., "F2P7Z" — for UI tasks only, or "N/A"]
Dependencies: [List of task IDs this is blocked by, or "none"]
Done when:    [Specific, verifiable acceptance criteria]

Step 4: Size Tasks Appropriately

• Right-sized: Self-contained, clear deliverable, one logical unit of work
• Too big: Split by sub-feature or sub-domain
• Too small: Combine with related work into a single task
• Target: 2-4 tasks per worker for good throughput

Step 5: Determine Spawn Order

Batch 1 — Independent tasks (Dependencies: none)

• Shared types (team-lead implements directly)
• Database schema changes (backend-dev)
• Independent UI components (web-dev) → Spawn all Batch 1 workers in parallel

Batch 2 — Dependent tasks (blocked by Batch 1)

• API endpoints (depends on DB schema + types)
• Pages that consume APIs (depends on types) → Spawn after Batch 1 workers complete

Batch 3 — Tests (depends on implementation)

• Unit tests, integration tests, E2E tests → Spawn test-worker after Batch 2

Batch 4 — Review (depends on everything)

• Code review across all branches → Spawn reviewer after all implementation + tests

Example: User Comments Feature (Web/TypeScript)

#	Task	Assignee	Domain	Depends On
1	Add Comment model to Prisma schema	backend-dev	prisma/	none
2	Create shared types: Comment, CreateCommentInput, CommentListResponse	team-lead	src/types/	none
3	Implement GET/POST /api/items/[id]/comments	backend-dev	src/app/api/, src/services/	1, 2
4	Create CommentCard, CommentList, CommentForm components	web-dev	src/components/	2
5	Add comments section to item detail page	web-dev	src/app/items/	4
6	Write API endpoint tests	test-worker	tests/	3
7	Write component + E2E tests	test-worker	tests/	4, 5
8	Review all branches	reviewer	(all, read-only)	3, 5, 6, 7

Spawn order: Batch 1: tasks 1, 2 → Batch 2: tasks 3, 4, 5 → Batch 3: tasks 6, 7 → Batch 4: task 8