Skip to content

Commit 5aac852

Browse files
committed
docs(rules): clarify conductor vs worker dispatch — parallel-execution.md + claude-code.md Example 3
- parallel-execution.md: add "Conductor vs Worker Context (MANDATORY distinction)" subsection under "Implementation vs Read-Only Task Dispatch" with a three-layer table (conductor-impl / conductor-readonly / worker-internal), rationale, good worker sub-agent usage examples, and negative examples. - claude-code.md: add Example 3 (TaskMaestro outer + SubAgent inner within worker) to "Nested Execution Examples" with ASCII diagram, key invariant callout, and cross-reference to parallel-execution.md Conductor vs Worker Context section. Resolves the ambiguity where workers inside a taskMaestro pane wrongly assumed they were forbidden from using sub-agents at all. Workers already own an isolated git worktree, so the file-conflict rationale does not apply to their internal dispatch — they can freely use Explore/Plan sub-agents for research or context protection. Closes #1386
1 parent 36d951b commit 5aac852

2 files changed

Lines changed: 49 additions & 0 deletions

File tree

packages/rules/.ai-rules/adapters/claude-code.md

Lines changed: 22 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -577,6 +577,28 @@ SubAgent dispatch (outer)
577577
→ Collect results via TaskOutput
578578
```
579579

580+
**Example 3: TaskMaestro (outer) + SubAgent (inner, within worker)**
581+
582+
```
583+
TaskMaestro session (outer, conductor)
584+
├── Pane 1: Worker for Issue #101 (auth feature)
585+
│ ├── Explore subAgent → researches existing auth patterns
586+
│ ├── Plan subAgent → drafts TDD test plan
587+
│ ├── [Worker writes code directly in its own worktree]
588+
│ └── [Worker commits, pushes, creates PR, writes RESULT.json]
589+
├── Pane 2: Worker for Issue #102 (dashboard UI)
590+
│ └── Worker uses sub-agents for component research
591+
│ (no cross-pane interference because each worker owns its worktree)
592+
└── Pane 3: Review Agent (from review cycle protocol)
593+
└── EVAL mode reviewer for completed PRs
594+
```
595+
596+
This is the **recommended pattern for complex worker tasks** where parallel research or context protection would benefit the worker. The conductor still uses TaskMaestro for the outer dispatch — only the worker's internal orchestration uses sub-agents.
597+
598+
**Key invariant:** Sub-agents dispatched by a worker operate inside that worker's git worktree. Cross-pane file conflicts are impossible because each pane's worker owns its own isolated worktree.
599+
600+
See [`../rules/parallel-execution.md`](../rules/parallel-execution.md) "Conductor vs Worker Context" section for the authoritative rule.
601+
580602
### Execution Strategy Selection (MANDATORY)
581603

582604
When `parse_mode` returns `availableStrategies`, select the **outer transport** strategy:

packages/rules/.ai-rules/rules/parallel-execution.md

Lines changed: 27 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -92,6 +92,33 @@ Implementation tasks (code changes, file modifications, commits) MUST use tmux-b
9292

9393
**Why:** Background sub-agents lack proper git worktree isolation, cannot run pre-push checks reliably, and risk file conflicts when multiple agents write to the same workspace. taskMaestro provides each worker with an isolated worktree, proper shell environment, and full CI toolchain access.
9494

95+
### Conductor vs Worker Context (MANDATORY distinction)
96+
97+
The "Implementation → taskMaestro only" rule applies to the **conductor** (top-level orchestration session). Workers running inside a taskMaestro pane operate under different rules because they already own an isolated worktree.
98+
99+
| Layer | Context | Dispatch Tool | Rationale |
100+
|-------|---------|---------------|-----------|
101+
| Conductor → implementation | Outer orchestration session | **taskMaestro only** | Workers need worktree isolation + pre-push checks + visual monitoring |
102+
| Conductor → read-only research | Outer orchestration session | SubAgent allowed | No file mutations, safe to background |
103+
| **Worker → internal tasks** | Inside a taskMaestro pane | **SubAgent encouraged** | Worker owns its worktree; file-conflict rationale does not apply. Use Explore/Plan subagents for parallel research or context protection. |
104+
105+
**Why workers can use sub-agents freely:**
106+
107+
1. Each worker operates in an isolated git worktree — no file conflict with other workers
108+
2. Sub-agents within a worker inherit the worker's worktree, so they share the same isolation boundary
109+
3. Workers often benefit from parallel read-only research (Explore) or context-protected work before committing
110+
111+
**Examples of good worker-internal sub-agent usage:**
112+
113+
- Dispatch `Explore` sub-agent to survey existing patterns before writing code
114+
- Dispatch `Plan` sub-agent to draft implementation approach, then act on the plan directly
115+
- Dispatch multiple read-only sub-agents in parallel to gather context from different parts of the codebase
116+
117+
**What workers still must NOT do:**
118+
119+
- Dispatch sub-agents that modify files in **sibling** worktrees (impossible with proper isolation, but worth stating)
120+
- Dispatch sub-agents to create PRs on their behalf (the worker owns its PR)
121+
95122
## Monorepo Path Safety
96123

97124
In monorepo environments, always use absolute paths or `git -C <path>` for git commands to prevent path doubling:

0 commit comments

Comments
 (0)