feat: add Worker Efficiency Protocol to headless worker dispatch#793
feat: add Worker Efficiency Protocol to headless worker dispatch#793marcusquinn merged 1 commit intomainfrom
Conversation
Inject structured efficiency guidance into supervisor-dispatched workers: - MANDATORY TodoWrite decomposition (3-7 subtasks at session start) - Checkpoint after each subtask for compaction resilience - Parallel sub-work via Task tool for independent subtasks - Fail-fast verification before writing code - Token waste minimisation guidelines Workers currently operate linearly with no internal structure. When context compacts mid-task, they restart from scratch (2x token cost). This protocol gives workers a progress breadcrumb trail that survives compaction, reducing wasted retries by 30-150x ROI on the ~200 token overhead. Also documents the protocol in headless-dispatch.md with rationale table.
Summary of ChangesHello @marcusquinn, I'm Gemini Code Assist1! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed! This pull request introduces a "Worker Efficiency Protocol" designed to significantly improve the efficiency and cost-effectiveness of headless AI workers. By integrating structured guidance directly into the worker dispatch prompt and providing comprehensive documentation, the changes aim to prevent token waste from unnecessary restarts due to context compaction and ensure more systematic, checkpointed task execution. This initiative is projected to yield substantial token savings and lead to more reliable task completion. Highlights
Changelog
Activity
Using Gemini Code AssistThe full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips. Invoking Gemini You can request assistance from Gemini at any point by creating a comment using either
Customization To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a Limitations & Feedback Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for Github and other Google products, sign up here. You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension. Footnotes
|
|
Caution Review failedThe pull request is closed. WalkthroughAdds "Worker Efficiency Protocol" explanatory text to the BLOCKED-state message in supervisor-helper.sh and introduces the same protocol guidance to headless-dispatch.md documentation. Changes are purely content-focused with no functional logic modifications or API alterations. Changes
Estimated Code Review Effort🎯 2 (Simple) | ⏱️ ~10 minutes Possibly Related PRs
Poem
✨ Finishing touches
🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
🔍 Code Quality Report�[0;35m[MONITOR]�[0m Code Review Monitoring Report �[0;34m[INFO]�[0m Latest Quality Status: �[0;34m[INFO]�[0m Recent monitoring activity: 📈 Current Quality Metrics
Generated on: Mon Feb 9 18:03:16 UTC 2026 Generated by AI DevOps Framework Code Review Monitoring |
|
![gemini-code-assist[bot]](https://avatars.githubusercontent.com/in/956858?s=60&v=4){kind=small}
There was a problem hiding this comment.
Code Review
This pull request introduces a 'Worker Efficiency Protocol' for headless workers. The changes are clear and well-documented. My main feedback remains a suggestion to improve maintainability by externalizing the large prompt text from supervisor-helper.sh into a separate file, aligning with existing repository patterns for managing prompts.
| ## Worker Efficiency Protocol | ||
|
|
||
| Maximise your output per token. Follow these practices to avoid wasted work: | ||
|
|
||
| **1. Decompose with TodoWrite (MANDATORY)** | ||
| At the START of your session, use the TodoWrite tool to break your task into 3-7 subtasks. | ||
| Example for 'add retry logic to API client': | ||
| - Research: read existing API client code and error handling patterns | ||
| - Implement: add retry with exponential backoff to the HTTP client | ||
| - Test: write unit tests for retry behaviour (success, max retries, backoff timing) | ||
| - Integrate: update callers if the API surface changed | ||
| - Verify: run linters, shellcheck, and existing tests | ||
|
|
||
| Mark each subtask in_progress when you start it and completed when done. | ||
| Only have ONE subtask in_progress at a time. | ||
|
|
||
| **2. Checkpoint after each subtask** | ||
| After completing each subtask, run: | ||
| \`session-checkpoint-helper.sh save --task <your-task-id> --next 'remaining subtask descriptions'\` | ||
| This persists your progress to disk. If context compacts or the session restarts, | ||
| your checkpoint survives and you can resume from where you left off instead of restarting. | ||
|
|
||
| **3. Parallel sub-work with Task tool** | ||
| If your subtasks include independent work (e.g., writing tests while docs are separate), | ||
| use the Task tool to spawn a sub-agent for the independent piece. This is faster than | ||
| doing everything sequentially. Only parallelise when the subtasks don't modify the same files. | ||
|
|
||
| **4. Fail fast, not late** | ||
| Before writing any code, verify your assumptions: | ||
| - Read the files you plan to modify (stale assumptions waste entire sessions) | ||
| - Check that dependencies/imports you plan to use actually exist in the project | ||
| - If the task seems already done, EXIT immediately with explanation — don't redo work | ||
|
|
||
| **5. Minimise token waste** | ||
| - Don't read entire large files — use line ranges from search results | ||
| - Don't output verbose explanations in commit messages — be concise | ||
| - Don't retry failed approaches more than once — exit with BLOCKED instead" |
There was a problem hiding this comment.
This large block of prompt text is being added directly into the script. For better maintainability and separation of concerns, consider moving this 'Worker Efficiency Protocol' into its own file within a prompts directory (e.g., .agents/prompts/worker_efficiency_protocol.md).
This would decouple the prompt content from the script logic, making it easier to manage and edit the protocol without modifying the shell script, which is already quite large. The script could then load this content dynamically.
This pattern of externalizing prompt content appears to be in use elsewhere in the repository (e.g., prompts/build.txt).
1 participant
Summary
build_dispatch_cmd) so all headless workers receive structured efficiency guidanceheadless-dispatch.mdwith rationale and ROI analysisWhat Changed
supervisor-helper.sh— Dispatch Prompt EnhancementAdded a new
## Worker Efficiency Protocolsection to the prompt injected into every worker session. Workers are now instructed to:session-checkpoint-helper.sh saveso progress persists to disk. Enables resume-from-checkpoint instead of restart-from-scratch.headless-dispatch.md— DocumentationNew "Worker Efficiency Protocol" section documenting:
Why
Workers currently operate linearly with no internal structure. When context compacts mid-task, they lose all progress and restart from scratch — burning 2x the tokens. Complex tasks with multiple phases (research, implement, test, PR) have no explicit tracking, so workers sometimes skip steps or repeat them.
The protocol adds ~200-300 tokens per session but prevents full restarts that cost 10,000-50,000 tokens each.
Testing
<your-task-id>placeholder)bash -n: syntax OKmarkdownlint: cleanbuild_dispatch_cmdfunctionSummary by CodeRabbit