Swarm-centric engineering workflows for the Antigravity CLI (agy 1.5.8+) and Antigravity 2.0, adapted from pstack by Lauren Tan (poteto).
Read the pstack guide for a step-by-step walkthrough from model setup to autonomous multi-branch programs.
If you want to go fast, go deep first. Throughput without verification only ships broken code faster. pstack turns Antigravity's native swarm runtime into an engineering team with mechanical guardrails, isolated git worktrees, cross-model verification, and zero-slop code hygiene.
Install the plugin with the Antigravity CLI:
agy plugin install https://github.com/pstack-ports/agy-pstack-nextVerify the installed plugin:
agy plugin listRun two commands to start working. In the agy CLI (1.5.8+), installed plugin skills are namespaced as /agy-pstack-next:<skill>, while built-in Antigravity commands such as /goal and /schedule stay unprefixed (prose and tables below use /<skill> as shorthand).
- Run
/agy-pstack-next:setup-pstackto discover your available models, validate and write~/.gemini/config/rules/pstack-models.mdwithtrigger: always_on(includingmonitorand separateimpl-*andlead-*rows), syncpstack-swarm-guardin global~/.gemini/config/hooks.jsonviasync-hooks.mjs(plus--check), and optionally generate a project verification skill. - Start engineering tasks with
/agy-pstack-next:pstack, stating the goal and a checkable finish condition.
/agy-pstack-next:pstack the scroll container drifts every 750ms while idle. reproduce it first, fix the root cause, and verify in the browser.
/agy-pstack-next:pstack migrate every caller to the new async store in isolated slices, delete the legacy store, and prove all integration suites pass.
New to the toolkit or unsure which workflow fits a task? Ask /agy-pstack-next:setup-pstack for a workflow recommendation or open the guide.
Pstack v2 replaces prompt-only delegation rules with mechanical enforcement via root hooks.json, global ~/.gemini/config/hooks.json registration (configured by /setup-pstack so native Swarm Worker subagents execute the same SessionStart, PreInvocation, PreToolUse, and Stop hook while sharing per-conversation state under <appDataDir>/plugin_data/agy-pstack-next/capsules/), hooks/guard.mjs, and four role capsules under roles/.
Every swarm member's prefix determines its workspace isolation, injected role capsule, and runtime permissions.
| Member Prefix | Default Workspace | Role Capsule | Enforced Permissions |
|---|---|---|---|
| Coordinator (root chat) | Primary checkout | roles/coordinator.md |
Plans slices, manages swarm lifecycle, judges #seq evidence, and merges verified commits. |
impl-*, cand-*, lead-* |
workspace: "share" |
roles/poteto-agent.md |
Edits strictly inside its own worktree, artifact dir outside .system_generated/, and canonical temp roots. git push blocked unless PSTACK_ALLOW_PUSH=1 is set. |
adv-* |
workspace: "share" |
roles/poteto-agent.md |
Writes executable repros and exploit probes inside its own worktree, artifact dir, and canonical temp roots. git push and mutating gh commands always blocked. |
ro-* |
workspace: "inherit" |
roles/research.md |
Strictly read-only. Blocks edit_file, write_file outside canonical temp roots and brain-directory timeline screenshots, mutating git, gh, and MCP calls, and verifies git status cleanliness on Stop. |
sicko-* |
workspace: "share" |
roles/comment-sicko.md |
Comment and slop surgeon. Confines edit_file to its own worktree. Blocks write_file, git push, file-restoring or history-rewriting git subcommands, and mutating gh commands, and rejects untracked or deleted files on Stop. |
monitor*, narrator* |
Built-in | None (skipped) | Selective stall detection (swarm_monitor, skipped on short <= 4 worker single-wave runs, spawned on multi-wave or long runs using monitor from pstack-models.md) and board narration (swarm_narrator, skipped when swarm_pane Overview is active unless requested). hooks/guard.mjs releases coordinator subagent locks automatically once all task workers are killed ([done]). |
- Per-conversation capsule injection.
SessionStartandPreInvocationresolve each conversation against local<appDataDir>/brain/*/.system_generated/swarm/members.jsonor remoteswarm.json(--roster-only) rosters, write per-conversation state atomically under<appDataDir>/plugin_data/agy-pstack-next/capsules/<conversation-id>.json, and inject its matchingroles/*.mdcapsule once per role, upgrading cleanly if a worker's roster entry appears after startup. - Scoped lifecycle, inline skill pass-through, and plain
/swarm. Global~/.gemini/config/hooks.jsoncommands guard execution withtest ! -f '<abs_guard_path>' ||soagy plugin uninstall agy-pstack-nextleaves a clean exit-0 no-op.hooks/guard.mjsinspects~/.gemini/config/config.json(plugins["agy-pstack-next"].enabled) soagy plugin disable agy-pstack-nextsuspends capsule injection,PreToolUsegating, andStopcleanliness checks globally. Coordinator activation triggers only on leading swarm-orchestrating slash commands (/pstack,/understand,/crucible,/interrogate,/reflect,/verify-gen, or/ketchupwithout--plain) or active swarm rosters, so standalone inline skills (/bro,/technical-writing,/setup-pstack,/statechart,/control-ui,/control-cli,/make-bot-ui, and/ketchup --plain), mid-sentence/pstackmentions, and plain built-in/swarmsessions without pstack prefixes pass through unmanaged. - Native swarm exclusivity.
PreToolUseblocksrun_workflowand legacy subagent tools (exceptinvoke_subagenttargetingimage-generator) across all managed roles so every pstack workflow runs on the shared#seqmessage board. - Zero-regex, zero-sandbox structural confinement.
PreToolUseresolvesrealpathSyncon the deepest existing ancestor of everyedit_fileandwrite_filepath, blocking../traversal, symlink escapes into sibling worktrees, and worker writes inside.system_generated/, while parsingrun_commandargv structurally only forgitandghfootguns with zero shell regexes or OS sandboxing. - Read-only research integrity and
Stopcleanliness checks.ro-*workers can inspect code, run tests, query read-only MCPs, write temporary probes under canonical temp roots, and save Swarm UI timeline screenshots inside their own<appDataDir>/brain/<conversation-id>/directory outside.system_generated/, whileStopverifiesgit statuscleanliness forro-*and rejects untracked or deleted files forsicko-*. - Push gating. Force-pushes to
mainormasterare always denied. Adversarial (adv-*) and cleanup (sicko-*) workers can never push, and author workers push only when explicitly authorized withPSTACK_ALLOW_PUSH=1.
- Warm context forks. Pass
fork: "<member>"inswarm{action: "add"}to branch an implementation worker directly from a winningro-*investigator orcand-*prototype without re-reading the repo cold. - Safe landing before teardown. Because
swarm{action: "kill"}permanently deletes a worker'sshareworktree, the coordinator always runsgit fetch <worker_cwd> <sha> && git merge(orcherry-pick) before killing a worker. - Board
#seqcitations,$PWDpaths, and/tmpreports. Workers fetch cited#seqposts withread_boardseqsinstead of reading from0, pass absolute$PWD/...paths insideshareworktrees, write detailed reports over4KB to/tmp/<worker-name>-report.mdwith a summary on the board, and@mentiononly the specific peer who acts next. - Live quota hot-swap. If a worker hits rate limits or low quota,
swarm{action: "model"}switches its model in place while preserving its conversation history and worktree.
/pstack orchestrates most end-to-end tasks automatically and composes with the other 13 skills whenever you want a focused workflow directly.
| Skill | Purpose |
|---|---|
/pstack |
Swarm coordinator kernel with 6 composable topologies (program, build, diagnose, hillclimb, ship, evolve), distilled engineering principles, TypeScript patterns, and PR babysitting. |
/setup-pstack |
Live swarm{action: "models", all: true} validation and configuration for ~/.gemini/config/rules/pstack-models.md (frugal, balanced, max, inherit presets including monitor), sync-hooks.mjs global hook sync (--check), workflow advisor, and /schedule setup. |
/understand |
Parallel ro-* clue-sharing mesh unifying mechanism walkthroughs, historical git and tracker provenance, and interactive Socratic explanations, with warm fork into implementation. |
/crucible |
Parallel multi-candidate design (sketch) and prototype (full) arena across orthogonal axes (cand-*), cross-family ro-judge scoring, and donor cherry-pick synthesis. |
/interrogate |
Adversarial bug hunting (adv-* executable repros) combined with transitive caller, schema, and rollout blast-radius mapping (ro-blast), gated by ro-verify. |
/reflect |
Post-mortem, user-correction mining, and structural tightening across transcripts and board.jsonl, encoding fixes into hooks, capsules, types, lints, tests, or skills. |
/ketchup |
Catch-up briefings across board.jsonl #seq deltas, members.json, Swarm UI Overview plan.json, optional narrator view.json, prior sessions, git log, and PR status in standard, --plain, and --video formats. |
/bro |
Inline zero-jargon restatement of the preceding message in plain human language with no acronyms, file paths, or commit hashes. |
/verify-gen |
Create and --maintain project-local behavioral E2E verification skills (features/ maps) and --formal invariant or TLA+ verification skills, proven live by ro-verify. |
/control-ui |
Local Playwright, browser, and CDP harness craft with per-worker ephemeral ports and isolated --user-data-dir profiles so parallel swarm workers never collide. |
/control-cli |
Local tmux, PTY, and runtime-inspector harness craft with isolated sockets, temp home directories, and deterministic terminal dimensions per worker. |
/statechart |
Check a TLA+ state machine with TLC and render user-facing Mermaid or Pele SVG statecharts showing shortest counterexample paths. |
/technical-writing |
Four-layer documentation standard (Diataxis, Google developer style, STE, Global English) with zero-slop hygiene and ro-* technical accuracy checks. |
/make-bot-ui |
Build local or Tailscale web UIs whose buttons wake Antigravity agents via agy agentapi or webhooks while keeping secrets strictly server-side. |
/pstack routes tasks across six composable swarm topologies under skills/pstack/topologies/.
| Topology | What It Orchestrates |
|---|---|
program |
Multi-phase plans, stacked branches, #area swarm channels (when swarm exposes channel) or lead-<area> sub-coordinators, autonomous overnight runs, check-plan.mjs, decision-log.sh, worktree-audit.sh, session resume, and safe worktree cleanup. |
build |
Features, caller-migrating refactors, prototypes, and visual parity loops across disjoint impl-* worktrees, conditional sicko-* diff cleanup on comments or non-trivial code changes, and ro-verify behavioral proof. |
diagnose |
Bug fixes, read-only investigations, live runtime forensics, and trace profiling via parallel ro-* hypothesis probes, warm fork into impl-fix, and regression verification. |
hillclimb |
Sustained metric optimization with ro-bench baseline and noise-floor locking, explain-the-number checks, parallel cand-* lever trials, and compounding cherry-picked wins. |
ship |
Pre-PR ro-verify and /interrogate gates, local branch landing, opt-in PR creation and push (PSTACK_ALLOW_PUSH=1), CI and review triage via watch-pr and bugbot-triage.md, and clean worker teardown. |
evolve |
Skill and role-capsule authoring plus blind behavioral evaluations in isolated agy -p --mode auto runs (--sandbox on read-only trials) scored by ro-judge without prompt overfitting. |
All 24 core, architecture, verification, delegation, and meta principles are compiled into skills/pstack/references/principles.md and distilled into the four role capsules (roles/*.md), alongside skills/pstack/references/ts-patterns.md for strict TypeScript boundary and union modeling. See Steer with principle names in the guide for how to redirect a live swarm in one sentence.
Validate the plugin manifest, hooks, and skills strictly with the Antigravity CLI, and run the hook guard unit test suite with Node:
agy plugin validate --strict --json .
node --test hooks/guard.test.mjsMIT