| name | nbl.parallel-subagent-driven-development |
| description | Use when executing implementation plans with parallelizable tasks - analyzes dependencies, groups by level, executes independent tasks concurrently |
Parallel Subagent-Driven Development
Execute plan by dispatching fresh subagent per task. Each implementer performs built-in two-stage self-review (spec compliance + code quality) before reporting done. After all tasks complete in all levels, perform global two-stage review on all merged code.
Why subagents: You delegate tasks to specialized agents with isolated context. By precisely crafting their instructions and context, you ensure they stay focused and succeed at their task. They should never inherit your session's context or history — you construct exactly what they need. This also preserves your own context for coordination work.
Core principle: Fresh subagent per task with built-in two-stage self-review + global review after all tasks = high quality, fast iteration
Core design: Parallel mode creates a top-level merge worktree at startup from the development branch. All tasks in each level fork from this merge worktree and merge back to it after completion. After all tasks complete, only the merge worktree remains with all accumulated changes, and nbl.finishing-a-development-branch can be used directly.
NON-NEGOTIABLE Requirements (Read BEFORE Starting)
| Check | Requirement |
|---|
| Worktree Isolation | MUST create isolated merge worktree via nbl.using-git-worktrees Skill tool (NOT the built-in EnterWorktree tool) before any dispatching. If in primary worktree (.git is a directory), invoke nbl.using-git-worktrees first. NEVER implement directly in primary worktree. NEVER use built-in EnterWorktree. |
| TDD Required | Every implementation task MUST invoke nbl.test-driven-development skill FIRST. Never write implementation before tests. |
| Two-Stage Self-Review | Each implementer MUST complete: Stage 1 (spec compliance, line-by-line check) → Stage 2 (code quality, naming, conventions). Fix issues immediately in each stage. Never report DONE until both stages pass with NO issues. |
| Merge Lifecycle | One merge worktree created at startup, ALL task merges go here. MUST NOT delete before all levels complete. After all levels, finishing-a-development-branch handles final cleanup. |
| Directory Safety | Always cd back to project root between Bash commands. Prefer sub-to-sub-merge script for merge + cleanup in one step. Never leave CWD inside a nested worktree. |
Worktree Setup (MANDATORY)
Full Check Process (execute step-by-step):
STEP 1: Pre-check - Is this a Git repository?
Execute: git rev-parse --is-inside-work-tree
If NO → STOP, prompt user to initialize Git
If YES → continue to STEP 2
STEP 2: Check if already inside an added worktree:
If .git is a file → INSIDE_ADDED_WORKTREE = YES
If .git is a directory → INSIDE_ADDED_WORKTREE = NO
STEP 3: If INSIDE_ADDED_WORKTREE = YES:
→ Proceed directly to create merge worktree from current branch
STEP 4: If INSIDE_ADDED_WORKTREE = NO (in primary working tree):
Get current branch: CURRENT_BRANCH=$(git rev-parse --abbrev-ref HEAD)
If CURRENT_BRANCH is "main" or "master":
1. Auto-create development branch from plan name
2. Checkout new development branch in primary working tree
// CRITICAL: This step executes for BOTH main/master AND development branches!
INVOKE via **Skill tool** (NOT built-in EnterWorktree): `/nbl.using-git-worktrees create <base-name>-merge --parent feature/<base-name>`
// After invocation, you will be inside the newly created merge worktree
→ Setup complete, proceed to read plan and analyze dependencies
Result after setup:
- Base name: `<name>-merge`
- Branch: `feature/{name}-merge`
- Path: `.worktrees/{name}-merge/`
- All subsequent task worktrees will be created from this merge worktree
Level-Based Execution
Dependency Graph Analysis
def analyze_plan(plan):
for task in plan.tasks:
if task.dependencies == None:
task.level = 0
else:
task.level = max(dep.level for dep in task.dependencies) + 1
levels = group_by_level(tasks)
return levels
Level Semantics
Level 0: Task 1, Task 3 # No dependencies
↓
Level 1: Task 2, Task 4 # Depends on Level 0
↓
Level 2: ... # Depends on Level 1
Key insight: Level describes dependency constraints. All tasks in a level must complete before Level+1 starts.
Pipeline Execution Pattern
For each level:
├── Create worktrees for tasks in this level (max 2 per batch)
│ For each task, invoke **nbl.using-git-worktrees** skill via **Skill tool** (NOT built-in EnterWorktree) with:
│ - Base name: `<base_name>`
│ - Parent branch: `feature/<base_name>-merge`
│ - Task id: `<task_id>`
│ Skill handles correct path calculation automatically: `.worktrees/{base}-task{id}`
├── Dispatch agents in parallel
├── Wait all tasks complete (implementer does built-in two-stage self-review)
├── Rebase each task branch to merge branch
├── Merge all task branches to merge branch
├── Mark all completed tasks as done in TodoWrite and plan file
└── Proceed to next level
Per-Task Rebase + Merge + Cleanup
For each completed agent:
- Implementer completes: implement → spec self-check → fix → quality self-check → fix → DONE
- Rebase + Merge + Cleanup - Invoke
nbl.using-git-worktrees skill:
/nbl.using-git-worktrees merge-sub <base_name> <task_id>
⚠️ The merge must happen inside the merge worktree. Do NOT attempt git checkout $merge_branch in the main workspace (Git forbids checking out the same branch in two worktrees simultaneously).
Level Completion Criteria
| Step | Description | Must Pass? |
|---|
| 1 | Implementer reports DONE (with built-in self-review passed) | ✅ |
| 2 | Rebase to merge branch | ✅ |
| 3 | Merge to merge branch | ✅ |
| 4 | Mark task statuses complete in plan file | ✅ |
Key rule: Level completion = ALL tasks passed ALL steps.
Failure Handling
If any task fails at any step:
- Level is blocked — do NOT proceed to next level
- Fix the failing task — implementer fixes, re-review if needed
- Resume once all tasks pass — then proceed to next level
| Scenario | Action |
|---|
| Implementer BLOCKED/NEEDS_CONTEXT | Main agent provides context or re-dispatch |
| Rebase conflict | Follow "Rebase Conflict Resolution" below |
| Merge fails | Rollback, fix, retry |
| Any task in level fails | Whole level blocked |
Rule: One agent failure does not block other parallel agents from executing, but blocks that agent's subsequent merges until fixed.
Rebase Conflict Resolution
When git rebase $merge_branch encounters conflicts:
Why LLM for Conflicts?
LLMs excel at resolving Git conflicts because they understand semantics: can analyze changes in base vs subagent, merge non-conflicting parts, and resolve most simple conflicts automatically (70-80%). Only complex semantic conflicts require human judgment.
Resolution Flow
1. git rebase $base_branch
2. If conflict:
a. Get conflict status: git status
b. Get conflict details: git diff (shows base vs subagent changes)
c. **Read the full content of all conflicted files** to understand context
d. LLM analyzes → generates merged code
e. Write merged files
f. git add <conflict-files>
g. git rebase --continue
3. If auto-resolution succeeds → continue normal flow
Escalation
If the conflict is too complex for automatic resolution:
git rebase --abort — rollback- Present conflict details to user
- Explain why automatic resolution failed
- User makes decision: manually resolve, provide context for retry, or other approach
Principle: Main agent coordinates; user decides on complex conflicts; LLM executes.
| Conflict Type | Action |
|---|
| Simple (localized, obvious merge) | LLM auto-resolve |
| Complex (semantic ambiguity) | Escalate to user |
The Process (WITH NON-NEGOTIABLE GATES)
digraph process {
rankdir=TB;
subgraph cluster_setup {
label="Setup Phase";
style=filled fillcolor=lightyellow;
"Pre-Check: Is git repository?" [shape=diamond style=filled fillcolor=yellow];
"STOP: Not a git repository" [shape=box style=filled fillcolor=red];
"STEP 2: .git is file or directory?" [shape=diamond style=filled fillcolor=yellow];
"On main/master?" [shape=diamond style=filled fillcolor=yellow];
"Auto-create dev branch from plan name" [shape=box];
"INVOKE nbl.using-git-worktrees (create merge worktree)" [shape=box style=filled fillcolor=lightblue];
"Merge worktree created ✓" [shape=box style=filled fillcolor=lightgreen];
"Read plan, extract all tasks with full text, note context, create TodoWrite" [shape=box];
"Analyze dependencies → Build levels" [shape=box];
}
subgraph cluster_level_loop {
label="For Each Level (Sequential)";
style=filled fillcolor=lightyellow;
"Create worktrees for tasks in this level (max 2)" [shape=box style=filled fillcolor=lightpink];
"Dispatch N implementers (each with built-in two-stage review)" [shape=box style=filled fillcolor=lightblue];
}
// Pre-execution flow
"Pre-Check: Is git repository?" -> "STOP: Not a git repository" [label="no"];
"Pre-Check: Is git repository?" -> "STEP 2: .git is file or directory?" [label="yes"];
"STEP 2: .git is file or directory?" -> "Merge worktree created ✓" [label=".git is FILE (already in worktree)"];
"STEP 2: .git is file or directory?" -> "On main/master?" [label=".git is DIR (in primary worktree)"];
"On main/master?" -> "Auto-create dev branch from plan name" [label="yes"];
"On main/master?" -> "INVOKE nbl.using-git-worktrees (create merge worktree)" [label="no - on dev branch"];
"Auto-create dev branch from plan name" -> "INVOKE nbl.using-git-worktrees (create merge worktree)";
"INVOKE nbl.using-git-worktrees (create merge worktree)" -> "Merge worktree created ✓";
"Merge worktree created ✓" -> "Read plan, extract all tasks with full text, note context, create TodoWrite";
subgraph cluster_pipeline {
label="Pipeline Processing";
style=filled fillcolor=lightblue;
"Wait for ANY completion" [shape=diamond];
"Implementer reports DONE (built-in self-review passed)" [shape=box];
"Rebase to merge" [shape=box];
"Merge to merge" [shape=box];
"Cleanup worktree" [shape=box];
"More agents pending?" [shape=diamond];
"Level complete" [shape=box];
}
subgraph cluster_cleanup {
label="After Level Complete";
"Mark level tasks complete (TodoWrite + Plan file)" [shape=box];
"More levels?" [shape=diamond];
}
subgraph cluster_finish {
label="All Levels Complete";
"Global Stage 1: Spec review (all changes)" [shape=box];
"Global Stage 2: Code quality review (all changes)" [shape=box];
"Fix any issues found" [shape=box];
"Use nbl.finishing-a-development-branch" [shape=doublecircle style=filled fillcolor=lightgreen];
}
// Setup flow
"Read plan, extract all tasks with full text, note context, create TodoWrite" -> "Analyze dependencies → Build levels";
"Analyze dependencies → Build levels" -> "Create worktrees for tasks in this level (max 2)";
"Create worktrees for tasks in this level (max 5)" -> "Dispatch N implementers (each with built-in two-stage review)";
// Pipeline processing
"Dispatch N implementers (each with built-in two-stage review)" -> "Wait for ANY completion";
"Wait for ANY completion" -> "Implementer reports DONE (built-in self-review passed)";
"Implementer reports DONE (built-in self-review passed)" -> "Rebase to merge";
"Rebase to merge" -> "Merge to merge";
"Merge to merge" -> "Cleanup worktree";
"Cleanup worktree" -> "More agents pending?";
"More agents pending?" -> "Wait for ANY completion" [label="yes - continue"];
"More agents pending?" -> "Level complete" [label="no"];
// Cleanup flow
"Level complete" -> "Mark level tasks complete (TodoWrite + Plan file)";
"Mark level tasks complete (TodoWrite + Plan file)" -> "More levels?";
"More levels?" -> "Create worktrees for tasks in this level (max 5)" [label="yes - next level"];
"More levels?" -> "Global Stage 1: Spec review (all changes)" [label="no"];
"Global Stage 1: Spec review (all changes)" -> "Global Stage 2: Code quality review (all changes)" [label="passed"];
"Global Stage 2: Code quality review (all changes)" -> "Fix any issues found" [label="issues found"];
"Fix any issues found" -> "Global Stage 1: Spec review (all changes)";
"Global Stage 2: Code quality review (all changes)" -> "Use nbl.finishing-a-development-branch" [label="passed"];
}
Batch Handling for 3+ Tasks
| Tasks in Level | Approach |
|---|
| 2 tasks | Single batch, all agents in parallel |
| 3+ tasks | Split into batches of 2, process batch by batch |
Process Gates Summary
| Gate | Location | Requirement |
|---|
| GATE 1: Branch Check + Merge Worktree | BEFORE starting levels | If on main/master → auto-create dev branch. Create merge worktree from dev branch. |
| GATE 2: TDD | Implementer phase | MUST invoke nbl.test-driven-development skill |
| GATE 3: Built-In Self-Review | Implementer phase | Two-stage self-review before reporting DONE |
| GATE 4: Global Spec Review | After all levels | MUST invoke spec reviewer on all merged changes |
| GATE 5: Global Quality Review | After global spec review | MUST invoke code quality reviewer on all merged changes |
Model Selection
Use the least powerful model that can handle each role:
- Mechanical tasks (1-2 files, clear specs) → fast, cheap model
- Integration tasks (multi-file, pattern matching) → standard model
- Architecture/review tasks → most capable model
Handling Implementer Status
- DONE: Completed + passed two-stage self-review. Mark complete, proceed to rebase/merge.
- DONE_WITH_CONCERNS: Completed but flagged doubts. Read concerns; address correctness/scope issues before merging.
- NEEDS_CONTEXT: Missing information. Provide context and re-dispatch.
- BLOCKED: Cannot complete. Assess: provide context → upgrade model → break into smaller tasks → escalate to human.
Never ignore an escalation or force the same model to retry without changes.
Prompt Templates
Prompt templates are shared with serial subagent-driven-development:
../nbl.subagent-driven-development/implementer-prompt.md - Dispatch implementer subagent../nbl.subagent-driven-development/spec-reviewer-prompt.md - Dispatch spec compliance reviewer subagent../nbl.subagent-driven-development/code-quality-reviewer-prompt.md - Dispatch code quality reviewer subagent
Red Flags (Never Do This)
- Execute on main/master without user consent
- Dispatch implementer without worktree isolation
- Use built-in
EnterWorktree tool - MUST invoke nbl.using-git-worktrees via Skill tool instead
- Accept DONE before two-stage review completes
- Skip TDD
- Proceed with unfixed self-review issues
- Make subagent read plan file (provide full text instead)
- Skip scene-setting context for subagent
- Ignore subagent questions
- Dispatch more than 2 agents simultaneously
- Merge without rebasing first
- Proceed to next level with failed agents
- Skip the final global two-stage review
If global reviewer finds issues: dispatch fix subagent with specific instructions → re-review after fixes. Don't fix manually (context pollution).
Integration
Required workflow skills:
- nbl.using-git-worktrees - REQUIRED: Set up isolated worktrees before each level
- nbl.writing-plans - Creates the plan this skill executes (with task dependencies)
- nbl.requesting-code-review - Code review template for reviewer subagents
- nbl.finishing-a-development-branch - Complete development after all tasks are merged
Subagents should use:
- nbl.test-driven-development - Subagents follow TDD for each task
