Task Builder

Execute ONE task from the task system. Spawn multiple task-builders in parallel for independent tasks.

ORCHESTRATOR: READ THIS FIRST

You are the orchestrator. You do not implement. You spawn workers.

# YOUR JOB
1. Create task DAG (TaskCreate + TaskUpdate for dependencies)
2. Find unblocked tasks (TaskList)
3. Spawn task-builder for EACH unblocked task IN PARALLEL
4. Monitor TaskList for completion
5. Review, test, merge
6. Repeat until done

# WRONG
spawn task-builder #1 → wait → spawn #2 → wait → spawn #3

# RIGHT
spawn task-builder #1, #2, #3 IN THE SAME MESSAGE

If 5 tasks are unblocked, you spawn 5 task-builders simultaneously. Period.

When to Use

• •You've created a task DAG via TaskCreate/TaskUpdate
• •Tasks are unblocked (no incomplete dependencies)
• •Tasks have clear file ownership (no conflicts)
• •You want SPEED — parallel execution is the default

Required Inputs

task_id: "3"                         # System ID from TaskCreate
worktree_path: "../project-task-3"   # Isolated worktree for this task

Each task-builder needs its own worktree. Create them first:

git worktree add ../wt-task-1 -b task-1
git worktree add ../wt-task-2 -b task-2
git worktree add ../wt-task-3 -b task-3

What the Agent Does

1. •TaskGet(task_id) — Retrieves subject, description, blockedBy
2. •Verify not blocked — All blockedBy tasks must be completed; STOP if blocked
3. •Load relevant skills (see Skill Auto-Loading below)
4. •TaskUpdate(owner="session-<id>") — Claims task ownership
5. •TaskGet(task_id) — Re-read and verify ownership before proceeding
6. •TaskUpdate(status="in_progress") — Starts execution
7. •Implements in the worktree (isolated, focused)
8. •Run quality gates (.claude-quality-gates commands first; otherwise relevant project checks)
9. •TaskUpdate(status="completed") — Marks done
10. •Returns summary to orchestrator

The agent does NOT commit, merge, or push. You review and integrate.

Skill Auto-Loading (Supercharges the Agent)

Task-builders automatically load domain-specific skills before implementing:

Priority (Exclusive, Not Merged):

1. •skills= in spawn prompt — If specified, load ONLY those (skip keyword detection)
2. •Keyword detection — ONLY if no explicit skills, scan description for keywords
3. •No matches — Proceed without skills, report "Skills Loaded: none"

Orchestrator can specify skills explicitly when spawning:

/task-builder task_id=1 worktree_path=../wt-1 skills=threejs,react-three-fiber

Or let the agent auto-detect — keywords like "Three.js", "3D", "scene" trigger automatic skill loading.

Skill routing (agent auto-detects):

Use bare skill names (no / prefix) in skills= parameter and Skill() calls. See agents/task-builder.md for the canonical routing table.

Parallel Execution Pattern

# Step 1: Create DAG
TaskCreate("Create user model") → #1
TaskCreate("Create auth middleware") → #2
TaskCreate("Create login endpoint") → #3
TaskUpdate(#3, addBlockedBy=[#1, #2])

# Step 2: Create worktrees for unblocked tasks
git worktree add ../wt-1 -b task-1
git worktree add ../wt-2 -b task-2

# Step 3: SPAWN IN PARALLEL (same message!)
/task-builder task_id=1 worktree_path=../wt-1
/task-builder task_id=2 worktree_path=../wt-2

# Step 4: Monitor
TaskList → #1 in_progress, #2 in_progress

# Step 5: When complete, #3 unblocks
git worktree add ../wt-3 -b task-3
/task-builder task_id=3 worktree_path=../wt-3

# Step 6: Review and merge each
cd ../wt-1 && git diff --stat && npm test
/requesting-code-review
git checkout main && git merge task-1

Review Gate (Mandatory)

All changes require orchestrator review:

1. •Agent returns summary with files changed
2. •Orchestrator runs tests in worktree
3. •Orchestrator runs /requesting-code-review
4. •Only merge after approval

Race-Safe Ownership

Before any implementation begins:

1. •Claim with owner="session-<id>"
2. •Re-read task and verify ownership
3. •Only then set status="in_progress"

If ownership does not match, stop and pick another task.

Before marking complete:

1. •Run quality gates from .claude-quality-gates if the file exists
2. •Otherwise run the relevant project checks for touched code

Output Expectations

Task: #3
Status: complete
Subject: Create login endpoint

Skills Loaded:
- frontend-design (keyword: "form")

Files Changed:
- src/routes/auth/login.ts
- src/routes/auth/index.ts

Tests to Run:
- npm test -- src/routes/auth

Next Steps for Orchestrator:
1. cd ../wt-3 && git diff --stat
2. npm test -- src/routes/auth
3. /requesting-code-review
4. Merge if approved

Note: If no skills match, output shows "Skills Loaded: none"

Cleanup

After merging:

git worktree remove ../wt-1
git worktree remove ../wt-2
git worktree remove ../wt-3

Remember

You are the orchestrator. Your speed comes from parallelism, not from doing work yourself. Spawn task-builders. Monitor. Review. Merge. Repeat.