expand-tasks

Expand Tasks with Research v1.0

Expands TaskMaster tasks with research before coding begins. Deterministic operations handled by script.py; AI handles judgment.

Script location: skills/expand-tasks/script.py (relative to plugin root) Part of: prd-taskmaster plugin Depends on: research-expander agent (parallel research worker), any research provider configured via task-master models --set-research or registered as an MCP research tool.

When to Use

Activate when user says: expand tasks, research tasks, research before coding for all, expand subtasks. Do NOT activate for: single task research (use /research-before-coding), PRD generation (use /prd:go).

Native-parallel first (token economy)

Before launching agent waves, check the cheaper path: the native engine expands tasks in parallel for free. Prefer python3 script.py expand — backend op expand (native api) — or the expand_tasks MCP tool: it runs structured expand across pending tasks concurrently (inheriting the engine's ThreadPoolExecutor) on economy-tier models / keyless host CLIs and merges atomically. Use THIS skill's agent waves when: no provider/CLI is available, native expand reports failures for specific tasks (rerun just those here), or the research must be repo-grounded (agents can read the codebase; native expand cannot).

Prerequisites

• TaskMaster tasks.json must exist (run /prd:go first)
• A research provider is configured — either (a) task-master models --set-research <model> --<provider> for any task-master provider family, or (b) an MCP research tool registered in ~/.claude.json that Claude Code can call directly (for example mcp__plugin_prd_go__* tools or an external search/reason MCP)
• At least 1 task in tasks.json

---

Workflow (5 Steps)

Step 1: Preflight

python3 skills/expand-tasks/script.py read-tasks

Returns JSON: total, expanded, pending_expansion, tasks[].

If pending_expansion is 0: Report all tasks already expanded. Exit skill.

If research provider is not configured: Check via task-master models and verify a research role is set. If none, tell the user to configure one (task-master models --set-research <model> --<provider>) and exit. The skill does not assume any specific research backend — it uses whatever is configured.

---

Step 2: Choose Scope

Use AskUserQuestion:

• All tasks (default): Expand every task that hasn't been researched yet
• Specific tasks: User provides task IDs (comma-separated)
• By dependency level: Expand tasks with no dependencies first, then next wave

AI judgment: Recommend "All tasks" for initial expansion, "By dependency level" for incremental work.

---

Step 3: Generate Research Prompts

For each task to expand:

python3 skills/expand-tasks/script.py gen-prompt --task-id <ID>

Returns JSON with prompt field containing the full research agent prompt.

AI judgment: Review the auto-generated prompt. Customize research questions if the task needs domain-specific queries. Add project context from the PRD or session-context files if relevant.

---

Step 4: Launch Parallel Research Agents

Launch research agents in parallel waves. Each wave = up to 5 concurrent agents.

For each task, spawn a Task agent using the dedicated research-expander subagent type (defined in agents/research-expander.md):

Task(
  subagent_type: "research-expander",
  description: "Research Task <ID>: <title>",
  run_in_background: true,
  prompt: <prompt from Step 3>
)

Wave strategy:

• Wave 1: Tasks with no dependencies (they inform downstream tasks) — run in parallel
• Wave 2: Tasks depending on Wave 1 — run in parallel
• Wave 3+: Continue until all tasks covered — run in parallel per wave
• Max 5 agents per wave to avoid overwhelming the configured research backend

Wait for each wave to complete before launching the next. Parallel dispatch only happens WITHIN a wave; waves themselves are serial.

---

Step 5: Collect and Write Results

As each research-expander agent completes, save its research output:

1. Write agent output to a temp file:

   cat > /tmp/research-task-<ID>.md <<'EOF'
   <agent output>
   EOF
   

2. Write research back to tasks.json:

   python3 skills/expand-tasks/script.py write-research --task-id <ID> --research /tmp/research-task-<ID>.md
   

3. After all tasks are written, verify:

   python3 skills/expand-tasks/script.py status
   

AI judgment: Review each research result for quality. If a result is too thin (< 5 lines of useful content) or clearly failed, re-run that specific task's research through a fresh research-expander invocation.

---

Research Agent Prompt Pattern

The gen-prompt command generates prompts that follow the research-before-coding pattern:

1. Agent receives task context (title, description, dependencies, subtasks)
2. Agent runs 3-5 targeted queries against the user's configured research provider. The research-expander agent is tool-agnostic: it picks up whichever research tools are available in the current Claude Code session. This may be task-master research, an MCP search/reason tool from ~/.claude.json (including any mcp__plugin_prd_go__* tools registered by this plugin), WebSearch as a last resort, or whatever the user has bound. The skill does not hard-code any specific research MCP.
3. Agent distills results into structured summary
4. Summary returns to main context (~25-40 lines per task)

Critical: prefer structured research tools (task-master research, MCP search/reason tools) over raw WebSearch/WebFetch when available — they produce cleaner outputs with citations.

---

Error Handling

Error	Action
Research provider unreachable or rate-limited	Exit skill, tell user to verify task-master models research role is set and reachable
research-expander agent returns empty/failed	Re-run that specific task with different queries
tasks.json not found	Exit skill, tell user to run /prd:go first
Task already expanded	Skip silently unless user forces re-expansion
Agent timeout	Mark task as failed, continue with others

---

Output

After all tasks are expanded, the skill reports:

• Total tasks expanded
• Any failures that need retry
• Next recommended action (usually: begin implementation)

---

Integration with prd-taskmaster

This skill fits between Step 8 (Parse & Expand Tasks) and Step 11 (Choose Next Action) of the prd-taskmaster workflow. After PRD is parsed into tasks but before execution begins.

/prd:go → generates PRD → parses into tasks
    ↓
/expand-tasks   → research-expander agents run in Parallel waves → writes findings back to tasks.json
    ↓
Implementation begins (with research context in each task)

---

Tips

• Run after PRD generation but before any implementation
• Research results are stored in research_notes field of each task in tasks.json
• Re-running on already-expanded tasks is safe (will skip unless forced)
• For very large task lists (20+), consider expanding in dependency order to save context
• Each research-expander agent typically completes in ~30s depending on research backend and query depth; 15 tasks ≈ 3 waves ≈ 2-3 minutes total