subagent-driven-development

Files (1)

• SKILL.md

SKILL.md (first lines)

# Subagent-Driven Development

## Quick Reference

When a plan has independent steps, delegate them to subagents. You orchestrate — subagents implement. Merge their work, verify the whole, then proceed.

## When to Use

- An approved plan has steps that are genuinely independent
- Multiple files need similar changes (migrations, refactors)
- Implementation can be parallelized without shared state conflicts
- During `executing-plans` when you identify parallel opportunities

## When NOT to Use

- Steps have dependencies (step 2 needs step 1's output)
- Changes touch the same files (merge conflicts)
- The task is small enough to do sequentially in less time than orchestrating agents
- You're unsure if steps are truly independent (sequential is safer)

## Core Process

### Step 1: Identify Parallel Work

From the plan, find steps that:
- Touch different files
- Have no shared state
- Can be verified independently
- Don't need each other's output

### Step 2: Define Agent Tasks

For each parallel task, create a clear brief:

```
Task: [What to implement]
Files: [Which files to create/modify]
Acceptance: [How to verify success]
Context: [Relevant code patterns, types, APIs to follow]
Constraints: [What NOT to do]
```

Each brief must be self-contained. The agent has no context from your conversation.

### Step 3: Dispatch Agents

Use the Agent tool to launch subagents:
- Use `subagent_type: "general-purpose"` for implementation tasks
- Launch independent agents in a **single message** (parallel execution)
- Set `isolation: "worktree"` when agents modify overlapping areas (rare — prefer non-overlapping splits)

### Step 4: Merge and Verify

After all agents complete:
1. Review each agent's output for quality
2. If agents worked in worktrees, merge their branches
3. Run the full test suite — agents may have introduced conflicts
4. Fix any integration issues yourself

### Step 5: Integration Check

After merging:
- Do the pieces work together?
- Are there naming inconsistencies between agents' work?
- Does the combined output match the plan?

Chain to `verification-before-completion`.

## Splitting Strategies

| Pattern | How to Split |
|---------|-------------|
| Multiple independent components | One agent per component |
| Same change across many files | One agent per file group |
| Feature + tests | Same agent (tests verify the feature) |
| Frontend + backend | One agent each IF the API contract is defined |

## Anti-Patterns

| Anti-Pattern | Why It's Wrong |
|--------------|----------------|
| Parallelizing dependent work | Agents will produce inconsistent code |
| Agents editing the same file | Merge conflicts, lost work |
| Vague agent briefs | Garbage in, garbage out |
| No verification after merge | Agents don't know about each other's changes |
| Over-splitting simple work | Orchestration overhead exceeds time saved |
| Trusting agent output blindly | Review before merging. Agents make mistakes. |

## When to Use Worktrees

Use `isolation: "worktree"` when:
- You want to protect the main branch from partial work
- Multiple agents might touch adjacent (not same) files
- The task is large enough that isolation is worth the merge cost

For most subagent work, direct execution without worktrees is simpler.

## Chaining

REQUIRED: syntaxninja-dojo:verification-before-completion (after all agents complete and work is merged)
REQUIRED: syntaxninja-dojo:self-review (after verification passes)

From thesyntaxninja/syntaxninja-dojo, MIT.

More from thesyntaxninja/syntaxninja-dojo