Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 3 additions & 3 deletions .antigravity-plugin/plugin.json
Original file line number Diff line number Diff line change
Expand Up @@ -20,8 +20,8 @@
],
"logo": "assets/logo.png",
"suggestedPrompts": [
"/pstack reproduce this bug, fix the root cause in an isolated worktree, and verify the result",
"/understand walk me through how this subsystem works before we /crucible competing designs",
"/interrogate adversarially test the current branch diff and map its blast radius"
"/agy-pstack-next:setup-pstack configure per-role swarm models, global guard hooks, and autonomy gates",
"/agy-pstack-next:pstack reproduce this bug, fix the root cause in an isolated worktree, and verify the result",
"/agy-pstack-next:understand walk me through how this subsystem works and trace why its invariants are shaped this way"
]
}
26 changes: 13 additions & 13 deletions README.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
# pstack

Swarm-centric engineering workflows for Antigravity (`agy` v2.0), adapted from [pstack](https://github.com/cursor/plugins/tree/c742dd61706fbacc1b95f1a20b7b988cf096ce6c/pstack) by [Lauren Tan (poteto)](https://x.com/poteto).
Swarm-centric engineering workflows for the Antigravity CLI (`agy` `1.5.8+`) and Antigravity 2.0, adapted from [pstack](https://github.com/cursor/plugins/tree/c742dd61706fbacc1b95f1a20b7b988cf096ce6c/pstack) by [Lauren Tan (poteto)](https://x.com/poteto).

Read the [pstack guide](./docs/guide/README.md) for a step-by-step walkthrough from model setup to autonomous multi-branch programs.

Expand All @@ -22,24 +22,24 @@ agy plugin list

## Quick Start

Run two commands to start working.
Run 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).

1. Run [`/setup-pstack`](./skills/setup-pstack/SKILL.md) to discover your available models, set per-role defaults, and optionally generate a project verification skill.
2. Start engineering tasks with [`/pstack`](./skills/pstack/SKILL.md), stating the goal and a checkable finish condition.
1. Run [`/agy-pstack-next:setup-pstack`](./skills/setup-pstack/SKILL.md) to discover your available models, write `~/.gemini/config/rules/pstack-models.md` with `trigger: always_on`, register `pstack-swarm-guard` in global `~/.gemini/config/hooks.json` for swarm workers, and optionally generate a project verification skill.
2. Start engineering tasks with [`/agy-pstack-next:pstack`](./skills/pstack/SKILL.md), stating the goal and a checkable finish condition.

```text
/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 the scroll container drifts every 750ms while idle. reproduce it first, fix the root cause, and verify in the browser.
```

```text
/pstack migrate every caller to the new async store in isolated slices, delete the legacy store, and prove all integration suites pass.
/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 [`/setup-pstack`](./skills/setup-pstack/SKILL.md) for a workflow recommendation or open the [guide](./docs/guide/README.md).
New to the toolkit or unsure which workflow fits a task? Ask [`/agy-pstack-next:setup-pstack`](./skills/setup-pstack/SKILL.md) for a workflow recommendation or open the [guide](./docs/guide/README.md).

## Hook-Enforced Swarm Architecture

Pstack v2 replaces prompt-only delegation rules with mechanical enforcement via root [`hooks.json`](./hooks.json), [`hooks/guard.mjs`](./hooks/guard.mjs), and four role capsules under `roles/`.
Pstack v2 replaces prompt-only delegation rules with mechanical enforcement via root [`hooks.json`](./hooks.json), global `~/.gemini/config/hooks.json` registration (configured by `/setup-pstack` so native `Swarm Worker` subagents execute the same hook while sharing `<appDataDir>/plugin_data/agy-pstack-next` state), [`hooks/guard.mjs`](./hooks/guard.mjs), and four role capsules under `roles/`.

### Prefix-Typed Roster Contract

Expand All @@ -57,7 +57,7 @@ Every swarm member's prefix determines its workspace isolation, injected role ca
### Mechanical Guardrails in `hooks/guard.mjs`

- **One-time capsule injection.** `SessionStart` and `PreInvocation` resolve each conversation against `<appDataDir>/brain/*/.system_generated/swarm/members.json` and inject its matching `roles/*.md` capsule once per role, upgrading cleanly if a worker's roster entry appears after startup.
- **Native swarm exclusivity.** `PreToolUse` blocks legacy subagent tools across all roles so every multi-agent workflow runs on the shared `#seq` message board.
- **Native swarm exclusivity.** `PreToolUse` blocks legacy subagent tools and `run_workflow` across all roles so every multi-agent workflow runs on the shared `#seq` message board.
- **Symlink-safe worktree confinement.** `PreToolUse` resolves `realpathSync` on the nearest existing ancestor of every `edit_file` and `write_file` path, blocking `../` traversal and symlink escapes into sibling worktrees.
- **Read-only research integrity.** `ro-*` workers can inspect code, run tests, query read-only MCPs, and write temporary probes under `/tmp`, while `hooks/guard.mjs` denies repository mutations.
- **Push gating.** Force-pushes to `main` or `master` are always denied. Adversarial (`adv-*`) and cleanup (`sicko-*`) workers can never push, and author workers push only when explicitly authorized with `PSTACK_ALLOW_PUSH=1`.
Expand All @@ -76,12 +76,12 @@ Every swarm member's prefix determines its workspace isolation, injected role ca
| Skill | Purpose |
|---|---|
| [`/pstack`](./skills/pstack/SKILL.md) | Swarm coordinator kernel with 6 composable topologies (`program`, `build`, `diagnose`, `hillclimb`, `ship`, `evolve`), distilled engineering principles, TypeScript patterns, and PR babysitting. |
| [`/setup-pstack`](./skills/setup-pstack/SKILL.md) | Live `swarm{action: "models"}` configuration for `~/.gemini/config/rules/pstack-models.md`, budget presets, workflow and prompt advisor, and `/schedule` automation setup. |
| [`/setup-pstack`](./skills/setup-pstack/SKILL.md) | Live `swarm{action: "models"}` configuration for `~/.gemini/config/rules/pstack-models.md`, global `~/.gemini/config/hooks.json` guard registration, budget presets, workflow advisor, and `/schedule` automation setup. |
| [`/understand`](./skills/understand/SKILL.md) | Parallel `ro-*` clue-sharing mesh unifying mechanism walkthroughs, historical git and tracker provenance, and interactive Socratic explanations, with warm `fork` into implementation. |
| [`/crucible`](./skills/crucible/SKILL.md) | Parallel multi-candidate design (`sketch`) and prototype (`full`) arena across orthogonal axes (`cand-*`), cross-family `ro-judge` scoring, and donor `cherry-pick` synthesis. |
| [`/interrogate`](./skills/interrogate/SKILL.md) | Adversarial bug hunting (`adv-*` executable repros) combined with transitive caller, schema, and rollout blast-radius mapping (`ro-blast`), gated by `ro-verify`. |
| [`/reflect`](./skills/reflect/SKILL.md) | Post-mortem, user-correction mining, and structural tightening across transcripts and `board.jsonl`, encoding fixes into hooks, capsules, types, lints, tests, or skills. |
| [`/ketchup`](./skills/ketchup/SKILL.md) | Catch-up briefings across live swarm `view.json`, `#seq` board deltas, prior sessions, `git log`, and PR status in standard, `--plain`, and `--video` formats. |
| [`/ketchup`](./skills/ketchup/SKILL.md) | Catch-up briefings across `board.jsonl` `#seq` deltas, `members.json`, optional narrator `swarm_view/view.json`, prior sessions, `git log`, and PR status in standard, `--plain`, and `--video` formats. |
| [`/verify-gen`](./skills/verify-gen/SKILL.md) | 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`](./skills/control-ui/SKILL.md) | 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`](./skills/control-cli/SKILL.md) | Local `tmux`, PTY, and runtime-inspector harness craft with isolated sockets, temp home directories, and deterministic terminal dimensions per worker. |
Expand All @@ -95,12 +95,12 @@ Every swarm member's prefix determines its workspace isolation, injected role ca

| Topology | What It Orchestrates |
|---|---|
| [`program`](./skills/pstack/topologies/program.md) | Multi-phase plans, stacked branches, `#area` swarm channels, `lead-<area>` sub-coordinators, autonomous overnight runs, board checkpointing, session resume, and safe worktree cleanup. |
| [`program`](./skills/pstack/topologies/program.md) | Multi-phase plans, stacked branches, `#area` swarm channels (when `swarm` exposes `channel`) or `lead-<area>` sub-coordinators, autonomous overnight runs, board checkpointing, session resume, and safe worktree cleanup. |
| [`build`](./skills/pstack/topologies/build.md) | Features, caller-migrating refactors, prototypes, and visual parity loops across disjoint `impl-*` worktrees, `sicko-*` diff cleanup, and `ro-verify` behavioral proof. |
| [`diagnose`](./skills/pstack/topologies/diagnose.md) | 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`](./skills/pstack/topologies/hillclimb.md) | 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`](./skills/pstack/topologies/ship.md) | 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`](./skills/pstack/scripts/watch-pr) and [`bugbot-triage.md`](./skills/pstack/references/bugbot-triage.md), and clean worker teardown. |
| [`evolve`](./skills/pstack/topologies/evolve.md) | Skill and role-capsule authoring plus blind behavioral evaluations in isolated `agy -p --sandbox` runs scored by `ro-judge` without prompt overfitting. |
| [`evolve`](./skills/pstack/topologies/evolve.md) | 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. |

## Engineering Principles and References

Expand Down
21 changes: 13 additions & 8 deletions docs/guide/01-setup.md
Original file line number Diff line number Diff line change
@@ -1,28 +1,33 @@
# Set up pstack

In this page you install `agy-pstack-next`, map swarm worker prefixes to models, optionally bootstrap project verification skills, and run your first swarm task.
In this page you install `agy-pstack-next` in the Antigravity CLI (`agy` `1.5.8+`) or Antigravity 2.0, map swarm worker prefixes to models, register the global swarm guard hook, optionally bootstrap project verification skills, and run your first swarm task.

## Install the plugin

Install the plugin from the terminal with the Antigravity CLI:
Install the plugin from the terminal with the `agy` CLI (`1.5.8+`):

```bash
agy plugin install https://github.com/pstack-ports/agy-pstack-next
```

Installing registers root [`hooks.json`](../../hooks.json), [`hooks/guard.mjs`](../../hooks/guard.mjs), the four role capsules under `roles/`, and all 13 skills automatically.

## Configure swarm models and budgets
In the `agy` CLI (`1.5.8+`), installed plugin slash commands use the `/agy-pstack-next:<skill>` namespace (for example `/agy-pstack-next:setup-pstack` and `/agy-pstack-next:pstack`). Drop the `agy-pstack-next:` prefix only when a skill is installed standalone under `.agents/skills/` or `~/.gemini/config/skills/`. Built-in Antigravity commands such as `/goal` and `/schedule` always stay unprefixed. Throughout this guide, prose refers to skills concisely as `/<skill>`, while copy-ready prompt blocks include `/agy-pstack-next:<skill>` so they paste cleanly into `agy`.

## Configure swarm models, budgets, and global guard hooks

Run the setup skill inside Antigravity:

```text
/setup-pstack
/agy-pstack-next:setup-pstack
```

[`/setup-pstack`](../../skills/setup-pstack/SKILL.md) queries `swarm{action: "models"}` to discover every model currently available in your Antigravity environment across Claude, Gemini, and GPT-OSS families, alongside `inherit` (which runs workers on your active session model). It asks for your budget preset and writes `~/.gemini/config/rules/pstack-models.md`.
[`/setup-pstack`](../../skills/setup-pstack/SKILL.md) queries `swarm{action: "models", all: true}` to discover every model currently available in your Antigravity environment across Claude, Gemini, and GPT-OSS families, alongside `inherit` (which runs workers on your active session model). It asks for your budget preset and performs two machine-local setup steps.

1. **Writes `~/.gemini/config/rules/pstack-models.md` with `trigger: always_on` frontmatter.** Named rule files under `~/.gemini/config/rules/*.md` require `trigger: always_on` YAML frontmatter in `agy` so every coordinator turn receives your model and autonomy settings automatically.
2. **Registers `pstack-swarm-guard` in global `~/.gemini/config/hooks.json`.** Root plugin [`hooks.json`](../../hooks.json) covers top-level sessions, whereas `agy` native `Swarm Worker` subagents do not inherit user-plugin hooks. `/setup-pstack` reads any existing `~/.gemini/config/hooks.json` object first (preserving entries such as `herdr`) and registers `pstack-swarm-guard` pointing to your absolute `hooks/guard.mjs` path. Both hook paths share `<appDataDir>/plugin_data/agy-pstack-next` state (`injected-capsules.json` and `member-map.json`), so swarm workers enforce capsules and tool confinement without duplicate injections in the root coordinator.

Every swarm workflow reads that rule to pin models by role prefix.
Every swarm workflow reads `pstack-models.md` to pin models by role prefix.

- **`coordinator`.** Plans slices, manages the board, and synthesizes results.
- **`impl-*`, `cand-*`, `lead-*`.** Author code, prototypes, and sub-area slices in `workspace: "share"` worktrees.
Expand All @@ -42,7 +47,7 @@ Say yes on any project you work in regularly. `/verify-gen` interviews the codeb

When your repository has concurrency, retries, leases, state machines, or parsers where unit tests miss interleavings, run [`/verify-gen --formal`](../../skills/verify-gen/SKILL.md) as well. It models or property-tests your highest-risk invariant and proves the check catches a real injected break. [Verify and ship](./06-verify-and-ship.md) covers both modes in detail.

Start a fresh chat after writing `pstack-models.md` so new sessions pick up the updated rule.
Start a fresh chat after updating `pstack-models.md` and `~/.gemini/config/hooks.json` so new sessions and newly spawned workers pick up both files.

## Keep token spend predictable

Expand All @@ -58,7 +63,7 @@ Parallel swarms trade tokens for wall-clock speed and independent verification.
Give `/pstack` a small, concrete change with an explicit invariant:

```text
/pstack add a --json flag to this CLI command. plain-text output must stay byte-identical. verify both modes.
/agy-pstack-next:pstack add a --json flag to this CLI command. plain-text output must stay byte-identical. verify both modes.
```

`/pstack` matches the [`build`](../../skills/pstack/topologies/build.md) topology, implements the change in an isolated `impl-*` worktree, runs `ro-verify` against both CLI modes, merges the verified commit locally, and tears down its workers cleanly.
Expand Down
8 changes: 4 additions & 4 deletions docs/guide/02-pstack.md
Original file line number Diff line number Diff line change
Expand Up @@ -31,7 +31,7 @@ Each topology lives under `skills/pstack/topologies/` and composes cleanly when
Skip hand-written implementation plans. State what is broken or what behavior you want, plus any known context that saves search time:

```text
/pstack users receive duplicate webhook deliveries after a worker restart. reproduce first, fix the root cause, and prove retries stay idempotent.
/agy-pstack-next:pstack users receive duplicate webhook deliveries after a worker restart. reproduce first, fix the root cause, and prove retries stay idempotent.
```

`"reproduce first"` is an executable constraint. In [`diagnose`](../../skills/pstack/topologies/diagnose.md), parallel `ro-*` workers trace competing hypotheses first, then the coordinator forks the winning investigator (`fork: "ro-winner"`) into an `impl-fix` (`workspace: "share"`) worktree to write the failing repro test and fix before `ro-verify` confirms it.
Expand All @@ -49,7 +49,7 @@ Most great `/pstack` prompts fit in two to four sentences built from five pieces
Here is all five in one prompt:

```text
/pstack CSV exports drop the final row on batches over 50k records (see job 4812). reproduce first, then fix. done means the 60k-row fixture exports all 60,000 rows. show before-and-after row counts.
/agy-pstack-next:pstack CSV exports drop the final row on batches over 50k records (see job 4812). reproduce first, then fix. done means the 60k-row fixture exports all 60,000 rows. show before-and-after row counts.
```

Leave two things out of your opening prompt.
Expand All @@ -75,13 +75,13 @@ When stale worktrees accumulate across cancelled sessions, run `/pstack` (`progr
Inside an active thread, short follow-ups work cleanly because the swarm board retains `#seq` history:

```text
/pstack proceed with option B and verify it
/agy-pstack-next:pstack proceed with option B and verify it
```

When switching to an unrelated problem in the same chat, say `"new task"` explicitly so the coordinator selects a fresh topology instead of extending the previous one:

```text
/pstack new task. trace why session tokens survive logout. do not change code yet.
/agy-pstack-next:pstack new task. trace why session tokens survive logout. do not change code yet.
```

When stepping away from your keyboard, pair `/pstack` with Antigravity's `/goal` command and state your finish predicate clearly. [Run work while you sleep](./07-overnight.md) covers the full autonomous contract.
Expand Down
Loading
Loading