Skip to content

t217: Enforce Task tool parallelism for independent subtasks in worker dispatch #2621

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
alex-solovyev merged 1 commit into from
Mar 1, 2026
Merged

t217: Enforce Task tool parallelism for independent subtasks in worker dispatch #2621

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 2 additions & 0 deletions .agents/scripts/commands/full-loop.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -355,6 +355,8 @@ The AI will iterate on the task until outputting:
6. Conventional commits used (for auto-changelog)
7. **Headless rules observed** (see below)

**Parallelism rule (t217)**: When your task involves multiple independent operations (reading several files, running lint + typecheck + tests, researching separate modules), use the Task tool to run them concurrently in a single message — not one at a time. Serial execution of independent work wastes wall-clock time proportional to the number of subtasks. See `tools/ai-assistants/headless-dispatch.md` "Worker Efficiency Protocol" point 5 for criteria and examples.

**Replanning rule**: If your approach isn't working after a reasonable attempt, step back
and try a fundamentally different strategy before giving up. A fresh approach often
succeeds where incremental fixes to a broken one fail.
Expand Down
36 changes: 34 additions & 2 deletions .agents/tools/ai-assistants/headless-dispatch.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -570,7 +570,39 @@ Workers are injected with an efficiency protocol via the supervisor dispatch pro

4. **Research offloading** — Spawn Task sub-agents for heavy codebase exploration (reading 500+ line files, understanding patterns across multiple files). Sub-agents get fresh context windows and return concise summaries, saving the parent worker's context for implementation.

5. **Parallel sub-work** — For independent subtasks (e.g., tests + docs), workers can use the Task tool to spawn sub-agents. This is faster than sequential execution when subtasks don't modify the same files.
5. **Parallel sub-work (MANDATORY for independent subtasks)** — Workers MUST use the Task tool to run independent operations concurrently, not serially. This is not optional — serial execution of independent work wastes time proportional to the number of subtasks.

**When to parallelise** (use Task tool with multiple concurrent calls):
- Reading/analyzing multiple independent files or directories
- Running independent quality checks (lint + typecheck + test)
Copy link

@gemini-code-assist gemini-code-assist bot Mar 1, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

medium

This is a good list of examples. To avoid ambiguity, it's worth clarifying that these quality checks should be parallelized only when they are read-only operations. If they include auto-fixing capabilities (e.g., lint --fix), they become write operations and may need to be sequential if they modify the same files, as per the rules in the 'When to stay sequential' section.

Suggested change
- Running independent quality checks (lint + typecheck + test)
- Running independent read-only quality checks (e.g., lint, typecheck, tests)
References
  1. When documenting restrictions, provide the technical reason behind them to improve understanding.
  2. When documenting a critical process, explain the reasoning behind rules.
  3. When documenting agent behavior, restore detailed explanations for key concepts with examples for clarity.

- Generating tests for separate modules that don't share state
- Researching multiple parts of the codebase simultaneously
- Creating independent documentation sections
- Any two+ operations where neither depends on the other's output

**When to stay sequential** (do NOT parallelise):
- Operations that modify the same files (merge conflicts)
Copy link

@gemini-code-assist gemini-code-assist bot Mar 1, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

medium

The parenthetical (merge conflicts) might be too specific and could be misinterpreted as only applying to situations that would cause a git merge conflict. The underlying principle is to avoid any file-based race conditions (write-write, read-write, or write-read). A more general phrasing would be clearer for the AI worker.

Suggested change
- Operations that modify the same files (merge conflicts)
- Operations that write to the same files, or where one task reads a file modified by another.
References
  1. When documenting restrictions, provide the technical reason behind them to improve understanding.
  2. When documenting a critical process, explain the reasoning behind rules.
  3. When documenting agent behavior, restore detailed explanations for key concepts with examples for clarity.

- Steps where output of one feeds input of the next
- Git operations (add → commit → push must be sequential)
- Operations that depend on a shared resource (same DB table, same API endpoint)

**How**: Call the Task tool multiple times in a single message. Each Task call spawns a sub-agent with a fresh context window. Sub-agents return concise results that the parent worker uses to continue.

```text
# WRONG — serial execution of independent research
Task("Read src/auth/ and summarise patterns")
# wait for result
Task("Read src/api/ and summarise patterns")
# wait for result
Task("Read src/utils/ and summarise patterns")

# RIGHT — parallel execution of independent research
Task("Read src/auth/ and summarise patterns") ─┐
Task("Read src/api/ and summarise patterns") ─┤ all in one message
Task("Read src/utils/ and summarise patterns") ─┘
```

**Throughput impact**: 3 independent 2-minute tasks take 6 minutes serial vs 2 minutes parallel. Over a typical worker session with 4-6 parallelisable operations, this saves 30-60% of wall-clock time.

6. **Checkpoint after each subtask** — Workers call `session-checkpoint-helper.sh save` after completing each subtask. If the session restarts or compacts, the worker can resume from the last checkpoint instead of restarting from scratch.

Expand All @@ -588,7 +620,7 @@ Workers are injected with an efficiency protocol via the supervisor dispatch pro
| Context compacts → worker restarts from zero | Checkpoint + TodoWrite → resume from last subtask |
| Complex task done linearly → 1 failure = full restart | Subtask tracking → only redo the failed subtask |
| No internal structure → steps skipped or repeated | Explicit subtask list → nothing missed |
| All work sequential → slower | Independent subtasks parallelised via Task tool |
| All work sequential → 3x slower for 3 independent tasks | Independent subtasks parallelised via Task tool (mandatory) |
| ShellCheck failures found in CI 5-10 min later | Pre-push gate catches violations instantly |

### Token Cost
Expand Down
Loading