subagent-delegation
Skill952 starsChanged 3 months agoMITView on GitHub
Canonical protocol for delegating GSD work to native Antigravity subagents — when to delegate, how to invoke, workspace isolation modes, and the inline fallback for older IDE versions
12 other projects use a version of this.
Adopted by
Most recently taken up by
- rmkr/skillstheir own version, first seen Nov 12, 2026
- shinpr/codex-workflowstheir own version, first seen Nov 11, 2026
- chrisbanes/skillstheir own version, first seen Nov 8, 2026
- TrueImmortal82/open-code-skillstheir own version, first seen Nov 8, 2026
- 0xUrsanomics/utopia-ostheir own version, first seen Nov 1, 2026
- PracticalSwan/agent-skillstheir own version, first seen Oct 19, 2026
Other versions12 projects use a version of this.
Word for word · 0
None found.
Edited · 0
None found.
Wrote their own version · 12
- chrisbanes/skills★ 1.2ksame name
- sammcj/agentic-coding★ 172same name
- shinpr/codex-workflows★ 41same name
- PracticalSwan/agent-skills★ 22same name
- shinpr/codex-subagent-playbook★ 8same name
- code-dimension/code-dimension-skills★ 3same name
- 0xUrsanomics/utopia-os★ 2same name
- p10ns11y/skills★ 2same name
- buildpad-ai/skills★ 1same name
- lfake2320-collab/agentdesk★ 0same name
2 more not listed
How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.
In this repository12 other files it gives its agents.
- adapters/CLAUDE.mdCLAUDE.md
- codebase-mapperSkill
- context-compressorSkill
- context-fetchSkill
- context-health-monitorSkill
- debuggerSkill
- empirical-validationSkill
- executorSkill
- plan-checkerSkill
- plannerSkill
- token-budgetSkill
- verifierSkill
The file
We split this skill into the rules it gives an agent
7 rules. 0 are common, 5 are distinctive, and 2 are very specific to this project.
0
Common
Most of the 12 edited versions we read keep these.
5
Distinctive
This author's own choices. Worth a look.
2
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 56
Call invoke_subagent, targeting the subagent by the name in its .agents/agents/*.md definition.
- Distinctive: line 63
Every invocation prompt must carry:
- Distinctive: line 70
Never paste file contents into a subagent prompt.
- Very specific: line 81
Every subagent definition in .agents/agents/ therefore declares its tools explicitly.
- Distinctive: line 123
A dead subagent is not a completed one: If a subagent returns nothing or dies, report it as a failure and stop.
- Distinctive: line 141
When falling back, tell the user once, at the start:
- Distinctive: line 155
Do not silently pretend to delegate.
“Common” is measured: kept by at least 6 in 10 of the 12 edited versions of this file we could read. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Subagent Delegation Protocol
<role>
You are an orchestrator. Your context is a budget, and the work you do yourself spends it.Delegation is not an optimization in GSD — it is the mechanism that makes the quality
thresholds in PROJECT_RULES.md achievable. An orchestrator that reads twenty files to plan a
phase has already spent the context the phase needed.
</role>
Requirements
Native subagents require Antigravity 2.0 or later (invoke_subagent).
Detect capability by checking whether invoke_subagent is in your available tools. Do not
probe by calling it — a failed call wastes a turn and confuses the user.
| Capability | Behavior |
invoke_subagent available | Delegate per this protocol |
| Not available | Inline fallback (see below) |
Plan requirements: none beyond 2.0. Plain subagents are not plan-gated — only
Multi-Agent Teamwork (/teamwork-preview, Agent Teams) is Ultra-exclusive, and GSD never
uses it. If delegation is unavailable, the cause is the IDE version, not the subscription.
What to Delegate
| Work | Subagent | Why |
| Executing a PLAN.md | gsd-executor | One clean context per plan is the core GSD promise |
| Authoring plans for a phase | gsd-planner | Plan authoring reads spec + roadmap + research |
| Verifying a phase | gsd-verifier | Independence requires a context that never saw the work |
| Codebase mapping / research | gsd-researcher | Exploration is the largest single context cost |
| Diagnosing a bug | gsd-debugger | A polluted context repeats its own failed hypotheses |
Keep in the orchestrator: argument parsing, file existence checks, wave grouping, reading compact subagent results, updating STATE.md and ROADMAP.md, and talking to the user.
Everything else is delegable. When in doubt, delegate — the cost of an extra subagent is tokens; the cost of a poisoned orchestrator context is the rest of the session.
Invocation
Call invoke_subagent, targeting the subagent by the name in its .agents/agents/*.md
definition. The tool's exact parameter schema is supplied by the IDE — follow it. This
protocol governs what you put in the prompt, not the wire format.
A subagent does not inherit your conversation history. It starts from a clean slate. Anything you do not put in its prompt does not exist for it.
Every invocation prompt must carry:
- The contract fields the target subagent declares in its Invocation Contract table
- Paths, not contents —
.gsd/phases/2/1-PLAN.md, never the pasted plan - Constraints from STATE.md that bound the work — decisions already made, known blockers
- The return contract — restate that you want the compact block, nothing more
Never paste file contents into a subagent prompt. It can read. Pasting doubles the token cost and desynchronizes it from disk the moment anything changes.
Tool Grants
tools: defaults to an empty list — it does not inherit the parent's toolset. A subagent
whose definition omits tools: cannot write files. It will explore happily, then discover at
the end that it has no way to produce its artifact.
Every subagent definition in .agents/agents/ therefore declares its tools explicitly.
| Need | Tools |
| Read and search | view_file, list_dir, find_by_name, grep_search |
| Write artifacts | write_to_file, replace_file_content, multi_replace_file_content |
| Commits, tests, verification commands | run_command |
| External research | search_web, read_url_content |
| Return to the parent | send_message |
Copy tool names exactly. An unmapped or misspelled name makes the subagent hang rather than fail — the worst possible failure mode, because it looks like slow work.
scripts/validate-agents.ps1/.sh enforces both rules: tools: must be present and non-empty,
and every declared name must exist in the registry above.
Workspace Isolation
| Mode | Use when |
inherit | Sequential work — one subagent touching the workspace at a time |
branch | Two or more subagents writing files concurrently (isolated git worktree) |
share | Read-only concurrent work — research, mapping, verification |
Wave mapping: a wave with one plan runs inherit. A wave with multiple plans runs
branch, one worktree per plan, merged after the wave completes. Concurrent writers sharing
a workspace corrupt each other's commits — this is not a theoretical risk.
Handling Results
A subagent returns its compact block. That block is what enters your context — nothing else.
- Do not re-read the artifact the subagent wrote to confirm it. If you need its contents later, read it then.
- Do not summarize the summary back to the user in full. Report status, path, and the one thing they must decide.
- Route on status.
blocked,checkpoint,needs_input,escalate, andfaileach have a defined next step in the calling workflow. Follow it. - A dead subagent is not a completed one. If a subagent returns nothing or dies, report it as a failure and stop. Do not silently redo its work inline — that is precisely the context blow-up delegation exists to prevent.
- A subagent that returns file contents has failed, however complete it sounds. The
contract is a path; a payload means the artifact never reached disk. Treat it as
blocked, find out which capability it lacked, and fix the definition — do not paste the content onward, or the delegation cost you tokens and bought you nothing.
Depth is capped at 10 levels of nesting. GSD never needs more than 2 — orchestrator to
subagent. A subagent that wants to delegate should return needs_input instead.
Inline Fallback
On Antigravity 1.x, invoke_subagent does not exist. Workflows still run, in degraded
mode: the orchestrator does the work itself, in its own context.
When falling back, tell the user once, at the start:
⚠️ Subagent delegation unavailable (requires Antigravity 2.0+)
Running inline — context will fill faster.
Recommended: one plan per session, /pause between plans.Then apply the degraded-mode discipline:
- Execute one plan per invocation, never a full wave
/pauseafter each plan and let the user/resumein a fresh session- Watch
skills/context-health-monitorthresholds and stop at 70%
Do not silently pretend to delegate. The failure this protocol was written to fix was workflows describing subagents they never spawned.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

