Skip to content

Commit 4670e72

Browse files
dhaneshclaude
dhanesh
and
claude
committed
feat(parallel-agents): add parallel task execution with git worktrees
Implement /parallel command for executing independent tasks concurrently using isolated git worktrees. The framework automatically identifies parallelization opportunities and handles merging. Key features: - Task dependency analysis and file overlap detection - Automatic worktree creation/cleanup - Resource monitoring (disk, memory, CPU) - Progress reporting and merge orchestration - Auto-suggestion hook for parallelization opportunities Distribution: - install.sh now installs parallel library to ~/.claude/lib/parallel/ - Auto-suggester hook installed to ~/.claude/hooks/ - /parallel skill file for Claude Code integration Also adds Artifact Placement Rules to m4-generate.md to prevent architectural mismatches between implementation and skill files. Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
1 parent a9d9c4a commit 4670e72

40 files changed

Lines changed: 11770 additions & 7 deletions

‎.manifold/parallel-agents.anchor.yaml‎

Lines changed: 229 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,229 @@
1+
# parallel-agents.anchor.yaml
2+
# Outcome Anchoring Document
3+
# Generated: 2026-01-16
4+
5+
feature: "parallel-agents"
6+
anchor_type: "backward_reasoning"
7+
8+
outcome:
9+
original: "Parallelise tasks that can be completed simultaneously using agents and git worktrees, let the framework identify and decide when and how"
10+
anchored: "Framework automatically detects parallelization opportunities, executes independent tasks in isolated git worktrees, and merges results without conflicts"
11+
12+
required_truths:
13+
- id: RT-1
14+
statement: "Task graph can be analyzed for parallelization opportunities"
15+
requires:
16+
- "Task decomposition into discrete units"
17+
- "Dependency detection between tasks"
18+
maps_to_constraints: [B3, T4]
19+
current_state: "No task analysis capability exists"
20+
status: NOT_SATISFIED
21+
priority: 1
22+
23+
- id: RT-2
24+
statement: "Independent tasks can be identified (no file overlap)"
25+
requires:
26+
- "File-level change prediction for each task"
27+
- "Overlap detection between predicted file sets"
28+
maps_to_constraints: [T3, B1]
29+
current_state: "No file prediction or overlap detection"
30+
status: NOT_SATISFIED
31+
priority: 1
32+
33+
- id: RT-3
34+
statement: "Isolated execution environments can be created"
35+
requires:
36+
- "Git worktree creation from clean state"
37+
- "Per-agent worktree management"
38+
maps_to_constraints: [T1, T2, T7]
39+
current_state: "Git worktrees available but not integrated"
40+
status: PARTIAL
41+
priority: 1
42+
43+
- id: RT-4
44+
statement: "Results from parallel agents can be merged automatically"
45+
requires:
46+
- "Conflict-free changes guaranteed by RT-2"
47+
- "Git merge orchestration"
48+
maps_to_constraints: [U3, B1]
49+
current_state: "Git merge exists, no orchestration layer"
50+
status: PARTIAL
51+
priority: 2
52+
53+
- id: RT-5
54+
statement: "Resource limits are monitored and respected"
55+
requires:
56+
- "Disk/memory/CPU monitoring"
57+
- "Dynamic concurrency adjustment"
58+
maps_to_constraints: [O1, O2, O4]
59+
current_state: "No resource monitoring for parallelization"
60+
status: NOT_SATISFIED
61+
priority: 2
62+
63+
- id: RT-6
64+
statement: "User has visibility and control over parallelization"
65+
requires:
66+
- "Parallelization suggestions shown to user"
67+
- "Opt-in confirmation or auto mode"
68+
maps_to_constraints: [B4, U1, U2, U4]
69+
current_state: "No parallel UI exists"
70+
status: NOT_SATISFIED
71+
priority: 2
72+
73+
dependency_chain:
74+
parallel_tracks:
75+
analysis: ["RT-1", "RT-2"]
76+
infrastructure: ["RT-3", "RT-5"]
77+
user_facing: ["RT-6"]
78+
sequential:
79+
- "RT-1 + RT-2 must complete before RT-4"
80+
- "RT-3 must complete before agents can run"
81+
blocking:
82+
- "RT-2 blocks RT-4 (cannot merge without conflict guarantee)"
83+
84+
options:
85+
- id: A
86+
name: "Hook-based Integration"
87+
description: "Integrate into existing Task tool - when multiple sub-tasks detected, analyze and parallelize behind the scenes"
88+
tech_stack: "Claude Code Task tool extension"
89+
commands:
90+
- "Task tool automatically parallelizes when possible"
91+
satisfies: [RT-3, RT-4]
92+
gaps: [RT-1, RT-2, RT-5, RT-6]
93+
effort: "Low"
94+
risk: "Medium - limited analysis capability"
95+
96+
- id: B
97+
name: "Dedicated Parallel Command"
98+
description: "New /parallel command that takes explicit task list and runs them in parallel worktrees"
99+
tech_stack: "New slash command + worktree manager"
100+
commands:
101+
- "/parallel \"task1\" \"task2\" \"task3\""
102+
- "/parallel --file tasks.yaml"
103+
satisfies: [RT-3, RT-4, RT-6]
104+
gaps: [RT-1, RT-2, RT-5]
105+
effort: "Medium"
106+
risk: "Low - explicit user control"
107+
108+
- id: C
109+
name: "Framework Auto-detection"
110+
description: "Analyze all incoming work for parallelization, suggest opportunities, user confirms"
111+
tech_stack: "Task analyzer + worktree orchestrator + UI"
112+
commands:
113+
- "Automatic detection and suggestion"
114+
- "--auto-parallel for hands-free mode"
115+
satisfies: [RT-1, RT-2, RT-3, RT-4, RT-6]
116+
gaps: [RT-5]
117+
effort: "High"
118+
risk: "Medium - complex analysis"
119+
120+
- id: D
121+
name: "Hybrid Orchestrator"
122+
description: "Combine auto-detection with explicit commands. Framework suggests parallelization, provides /parallel command for explicit use, handles resources dynamically"
123+
tech_stack: "Task analyzer + worktree manager + resource monitor + parallel command"
124+
commands:
125+
- "Auto-suggestion with confirmation"
126+
- "/parallel for explicit parallel execution"
127+
- "--auto-parallel flag for automatic mode"
128+
- "--max-parallel N for resource control"
129+
satisfies: [RT-1, RT-2, RT-3, RT-4, RT-5, RT-6]
130+
gaps: []
131+
effort: "High"
132+
risk: "Low - comprehensive solution"
133+
134+
recommendation:
135+
selected_option: "D"
136+
name: "Hybrid Orchestrator"
137+
rationale:
138+
- "Only option that satisfies all 6 Required Truths"
139+
- "Provides both automatic and explicit parallelization"
140+
- "Resource monitoring prevents system overload"
141+
- "User control via confirmation and --auto-parallel"
142+
- "Higher effort justified by comprehensive solution"
143+
implementation_structure:
144+
phase_1:
145+
name: "Foundation"
146+
components:
147+
- "Worktree Manager: create, track, cleanup worktrees"
148+
- "Resource Monitor: disk/memory/CPU checks"
149+
deliverables: ["worktree-manager.ts", "resource-monitor.ts"]
150+
phase_2:
151+
name: "Analysis"
152+
components:
153+
- "Task Analyzer: break tasks into units"
154+
- "File Predictor: predict files each task will modify"
155+
- "Overlap Detector: identify conflicts"
156+
deliverables: ["task-analyzer.ts", "file-predictor.ts", "overlap-detector.ts"]
157+
phase_3:
158+
name: "Orchestration"
159+
components:
160+
- "Parallel Executor: spawn agents in worktrees"
161+
- "Merge Orchestrator: collect and merge results"
162+
- "Progress Reporter: show parallel progress"
163+
deliverables: ["parallel-executor.ts", "merge-orchestrator.ts", "progress-reporter.ts"]
164+
phase_4:
165+
name: "Integration"
166+
components:
167+
- "/parallel command implementation"
168+
- "Auto-suggestion hooks"
169+
- "Configuration and flags"
170+
deliverables: ["parallel-command.ts", "auto-suggester.ts", "parallel-config.ts"]
171+
build_artifacts:
172+
- "lib/parallel/worktree-manager.ts"
173+
- "lib/parallel/resource-monitor.ts"
174+
- "lib/parallel/task-analyzer.ts"
175+
- "lib/parallel/file-predictor.ts"
176+
- "lib/parallel/overlap-detector.ts"
177+
- "lib/parallel/parallel-executor.ts"
178+
- "lib/parallel/merge-orchestrator.ts"
179+
- "lib/parallel/progress-reporter.ts"
180+
- "commands/parallel.ts"
181+
- "hooks/auto-suggester.ts"
182+
- "tests/parallel/*.test.ts"
183+
- "docs/parallel-agents/README.md"
184+
185+
critical_path:
186+
phase_1:
187+
name: "Foundation"
188+
tasks:
189+
- "Implement worktree create/remove/list"
190+
- "Add resource checks (disk, memory)"
191+
unblocks: ["phase_2", "phase_3"]
192+
phase_2:
193+
name: "Analysis"
194+
tasks:
195+
- "Build task decomposition logic"
196+
- "Implement file prediction heuristics"
197+
- "Create overlap detection"
198+
unblocks: ["phase_3"]
199+
phase_3:
200+
name: "Orchestration"
201+
tasks:
202+
- "Build parallel executor with Task tool"
203+
- "Implement merge orchestration"
204+
- "Add progress reporting"
205+
unblocks: ["phase_4"]
206+
phase_4:
207+
name: "Integration"
208+
tasks:
209+
- "Create /parallel command"
210+
- "Add auto-suggestion hooks"
211+
- "Write documentation"
212+
unblocks: []
213+
214+
validation_gates:
215+
phase_1:
216+
- "Worktrees can be created and removed without errors"
217+
- "Resource monitor accurately reports available capacity"
218+
phase_2:
219+
- "Task analyzer correctly identifies independent tasks"
220+
- "File predictor accuracy >80% on test cases"
221+
- "No false negatives in overlap detection (safety critical)"
222+
phase_3:
223+
- "Parallel execution completes faster than sequential"
224+
- "Merge produces correct combined result"
225+
- "Failed agent doesn't affect main worktree"
226+
phase_4:
227+
- "/parallel command works end-to-end"
228+
- "Auto-suggestion triggers appropriately"
229+
- "User can opt-out easily"

0 commit comments

Comments
 (0)