agentleFS
toonighttoonight/get-shit-done-for-antigravity/.agents/skills/subagent-delegation/SKILL.md

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

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
  1. Very specific:

    Call invoke_subagent, targeting the subagent by the name in its .agents/agents/*.md definition.

    line 56
  2. Distinctive:

    Every invocation prompt must carry:

    line 63
  3. Distinctive:

    Never paste file contents into a subagent prompt.

    line 70
  4. Very specific:

    Every subagent definition in .agents/agents/ therefore declares its tools explicitly.

    line 81
  5. Distinctive:

    A dead subagent is not a completed one: If a subagent returns nothing or dies, report it as a failure and stop.

    line 123
  6. Distinctive:

    When falling back, tell the user once, at the start:

    line 141
  7. Distinctive:

    Do not silently pretend to delegate.

    line 155

“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.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

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.

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.

Download now (ZIP)

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
What did you use it for? e.g. Reviewing pull requests in a Rails app

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.