Skip to content

amanpal3/Dr-SKILLs / .agent/plugins/gsd/skills/gsd-subagent-delegation

gsd-subagent-delegation

Verified

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

Subagent Delegation Protocol

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.


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.

CapabilityBehavior
invoke_subagent availableDelegate per this protocol
Not availableInline 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

WorkSubagentWhy
Executing a PLAN.mdgsd-executorOne clean context per plan is the core GSD promise
Authoring plans for a phasegsd-plannerPlan authoring reads spec + roadmap + research
Verifying a phasegsd-verifierIndependence requires a context that never saw the work
Codebase mapping / researchgsd-researcherExploration is the largest single context cost
Diagnosing a buggsd-debuggerA 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:

  1. The contract fields the target subagent declares in its Invocation Contract table
  2. Paths, not contents — .gsd/phases/2/1-PLAN.md, never the pasted plan
  3. Constraints from STATE.md that bound the work — decisions already made, known blockers
  4. 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.

NeedTools
Read and searchview_file, list_dir, find_by_name, grep_search
Write artifactswrite_to_file, replace_file_content, multi_replace_file_content
Commits, tests, verification commandsrun_command
External researchsearch_web, read_url_content
Return to the parentsend_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

ModeUse when
inheritSequential work — one subagent touching the workspace at a time
branchTwo or more subagents writing files concurrently (isolated git worktree)
shareRead-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, and fail each 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
  • /pause after each plan and let the user /resume in a fresh session
  • Watch skills/context-health-monitor thresholds 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.

reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis.Stars: 471kUpdated Claude CodeCodexVerifiedInstall
diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness.Stars: 322kUpdated Claude CodeCodexVerifiedInstall
dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependenciesStars: 322kUpdated Claude CodeCodexVerifiedInstall
executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is availableStars: 322kUpdated Claude CodeCodexVerifiedInstall