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
20 changes: 10 additions & 10 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -39,7 +39,7 @@ New to the toolkit or unsure which workflow fits a task? Ask [`/agy-pstack-next:

## Hook-Enforced Swarm Architecture

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/`.
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 `SessionStart`, `PreInvocation`, `PreToolUse`, and `Stop` hook while sharing per-conversation state under `<appDataDir>/plugin_data/agy-pstack-next/capsules/`), [`hooks/guard.mjs`](./hooks/guard.mjs), and four role capsules under `roles/`.

### Prefix-Typed Roster Contract

Expand All @@ -48,19 +48,19 @@ Every swarm member's prefix determines its workspace isolation, injected role ca
| Member Prefix | Default Workspace | Role Capsule | Enforced Permissions |
|---|---|---|---|
| Coordinator (root chat) | Primary checkout | [`roles/coordinator.md`](./roles/coordinator.md) | Plans slices, manages swarm lifecycle, judges `#seq` evidence, and merges verified commits. |
| `impl-*`, `cand-*`, `lead-*` | `workspace: "share"` | [`roles/poteto-agent.md`](./roles/poteto-agent.md) | Edits strictly inside its own worktree. `git push` blocked unless `PSTACK_ALLOW_PUSH=1` is set. |
| `adv-*` | `workspace: "share"` | [`roles/poteto-agent.md`](./roles/poteto-agent.md) | Writes executable repros and exploit probes inside its own worktree. `git push` always blocked. |
| `ro-*` | `workspace: "inherit"` | [`roles/research.md`](./roles/research.md) | Strictly read-only. Blocks `edit_file`, `write_file`, mutating shell or git commands, and mutating MCP calls outside temp roots and brain-directory timeline screenshots. |
| `sicko-*` | `workspace: "share"` | [`roles/comment-sicko.md`](./roles/comment-sicko.md) | Comment and slop surgeon. Allows `edit_file` inside its own worktree. Blocks `write_file` and `git push`. |
| `impl-*`, `cand-*`, `lead-*` | `workspace: "share"` | [`roles/poteto-agent.md`](./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`](./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`](./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`](./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) | Native stall detection (`swarm_monitor`) and board narration (`swarm_narrator`, skipped when `swarm_pane` Overview is active unless requested) with zero extra capsule tokens. |

### Mechanical Guardrails in `hooks/guard.mjs`

- **One-time capsule injection.** `SessionStart` and `PreInvocation` resolve each conversation against local `<appDataDir>/brain/*/.system_generated/swarm/members.json` or remote `swarm.json` (`--roster-only`) rosters and inject its matching `roles/*.md` capsule once per role, upgrading cleanly if a worker's roster entry appears after startup.
- **Scoped lifecycle and plain `/swarm` pass-through.** Global `~/.gemini/config/hooks.json` commands guard execution with `test ! -f '<abs_guard_path>' ||` so `agy plugin uninstall agy-pstack-next` leaves a clean exit-0 no-op. `hooks/guard.mjs` inspects `~/.gemini/config/config.json` (`plugins["agy-pstack-next"].enabled`) so `agy plugin disable agy-pstack-next` suspends capsule injection and `PreToolUse` gating globally, and plain built-in `/swarm` sessions without a pstack skill or pstack worker prefixes (`impl-*`, `cand-*`, `lead-*`, `ro-*`, `adv-*`, `sicko-*`) pass through unmanaged.
- **Native swarm exclusivity.** `PreToolUse` blocks legacy subagent tools and `run_workflow` across all managed roles so every pstack 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, symlink escapes into sibling worktrees, and worker writes inside `.system_generated/`.
- **Read-only research integrity.** `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/`, while `hooks/guard.mjs` denies repository mutations.
- **Per-conversation capsule injection.** `SessionStart` and `PreInvocation` resolve each conversation against local `<appDataDir>/brain/*/.system_generated/swarm/members.json` or remote `swarm.json` (`--roster-only`) rosters, write per-conversation state atomically under `<appDataDir>/plugin_data/agy-pstack-next/capsules/<conversation-id>.json`, and inject its matching `roles/*.md` capsule 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.json` commands guard execution with `test ! -f '<abs_guard_path>' ||` so `agy plugin uninstall agy-pstack-next` leaves a clean exit-0 no-op. `hooks/guard.mjs` inspects `~/.gemini/config/config.json` (`plugins["agy-pstack-next"].enabled`) so `agy plugin disable agy-pstack-next` suspends capsule injection, `PreToolUse` gating, and `Stop` cleanliness checks globally. Coordinator activation triggers only on leading swarm-orchestrating slash commands (`/pstack`, `/understand`, `/crucible`, `/interrogate`, `/reflect`, `/verify-gen`, or `/ketchup` without `--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 `/pstack` mentions, and plain built-in `/swarm` sessions without pstack prefixes pass through unmanaged.
- **Native swarm exclusivity.** `PreToolUse` blocks `run_workflow` and legacy subagent tools (except `invoke_subagent` targeting `image-generator`) across all managed roles so every pstack workflow runs on the shared `#seq` message board.
- **Zero-regex, zero-sandbox structural confinement.** `PreToolUse` resolves `realpathSync` on the deepest existing ancestor of every `edit_file` and `write_file` path, blocking `../` traversal, symlink escapes into sibling worktrees, and worker writes inside `.system_generated/`, while parsing `run_command` argv structurally only for `git` and `gh` footguns with zero shell regexes or OS sandboxing.
- **Read-only research integrity and `Stop` cleanliness 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/`, while `Stop` verifies `git status` cleanliness for `ro-*` and rejects untracked or deleted files for `sicko-*`.
- **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`.

### Native Swarm Mechanics
Expand Down
4 changes: 2 additions & 2 deletions docs/guide/01-setup.md
Original file line number Diff line number Diff line change
Expand Up @@ -25,9 +25,9 @@ Run the setup skill inside Antigravity:
[`/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` as `test ! -f '<abs_guard_path>' || node '<abs_guard_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.
2. **Registers `pstack-swarm-guard` in global `~/.gemini/config/hooks.json`.** Root plugin [`hooks.json`](../../hooks.json) covers top-level sessions across `SessionStart`, `PreInvocation`, `PreToolUse`, and `Stop`, 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` as `test ! -f '<abs_guard_path>' || node '<abs_guard_path>'` across those four hook events. Both hook paths share `<appDataDir>/plugin_data/agy-pstack-next` state (per-conversation `capsules/<conversation-id>.json` files and `member-map.json`), so swarm workers enforce capsules, structural zero-regex/zero-sandbox tool confinement, and `Stop` cleanliness checks without duplicate injections in the root coordinator.

That global entry stays inert outside active pstack runs. Guarding the command with `test ! -f '<abs_guard_path>' ||` keeps `~/.gemini/config/hooks.json` a clean exit-0 no-op if `agy plugin uninstall agy-pstack-next` removes the plugin directory. `hooks/guard.mjs` also inspects `~/.gemini/config/config.json` (`plugins["agy-pstack-next"].enabled`), so running `agy plugin disable agy-pstack-next` suspends capsule injection and `PreToolUse` gating across global hooks too. Plain built-in `/swarm` sessions that do not invoke a pstack skill or pstack worker prefixes (`impl-*`, `cand-*`, `lead-*`, `ro-*`, `adv-*`, `sicko-*`) pass through `hooks/guard.mjs` unmanaged.
That global entry stays inert outside active pstack runs. Guarding the command with `test ! -f '<abs_guard_path>' ||` keeps `~/.gemini/config/hooks.json` a clean exit-0 no-op if `agy plugin uninstall agy-pstack-next` removes the plugin directory. `hooks/guard.mjs` also inspects `~/.gemini/config/config.json` (`plugins["agy-pstack-next"].enabled`), so running `agy plugin disable agy-pstack-next` suspends capsule injection, `PreToolUse` gating, and `Stop` cleanliness checks across global hooks too. Standalone inline skills (`/bro`, `/technical-writing`, `/setup-pstack`, `/statechart`, `/control-ui`, `/control-cli`, `/make-bot-ui`, and `/ketchup --plain`), mid-sentence `/pstack` prose mentions, and plain built-in `/swarm` sessions without pstack worker prefixes (`impl-*`, `cand-*`, `lead-*`, `ro-*`, `adv-*`, `sicko-*`) pass through `hooks/guard.mjs` unmanaged.

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

Expand Down
6 changes: 3 additions & 3 deletions docs/guide/02-pstack.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
# Route work through `/pstack`

[`/pstack`](../../skills/pstack/SKILL.md) is the swarm coordinator kernel. You describe the outcome and how to verify it. The coordinator selects one of six composable topologies, sizes a prefix-typed worker roster on the native swarm board, enforces worktree boundaries through `hooks/guard.mjs`, and lands only verified commits.
[`/pstack`](../../skills/pstack/SKILL.md) is the swarm coordinator kernel. You describe the outcome and how to verify it. The coordinator selects one of six composable topologies, sizes a prefix-typed worker roster on the native swarm board, enforces structural zero-regex, zero-sandbox worktree boundaries through [`hooks.json`](../../hooks.json) and [`hooks/guard.mjs`](../../hooks/guard.mjs), and lands only verified commits.

![A dispatcher pulls a switch lever to route robots on rail handcars toward lit gates for bug fixes, features, and investigations.](./images/router.jpg)

Expand Down Expand Up @@ -63,8 +63,8 @@ If you want help tightening a high-stakes prompt before launching a swarm, ask [

Running parallel authors in one directory corrupts files, git index state, and dev ports. Pstack v2 isolates swarm execution mechanically.

- **`workspace: "share"` per author.** Every `impl-*`, `cand-*`, `lead-*`, `adv-*`, and `sicko-*` worker gets its own git working copy. [`hooks/guard.mjs`](../../hooks/guard.mjs) resolves `realpathSync` on every `edit_file` and `write_file` call so no worker can escape its worktree via `../` or symlinks.
- **Read-only `ro-*` workers.** Explorers and verifiers run in `workspace: "inherit"` with zero repository write permissions, keeping temporary test artifacts strictly under `/tmp`.
- **`workspace: "share"` per author.** Every `impl-*`, `cand-*`, `lead-*`, `adv-*`, and `sicko-*` worker gets its own git working copy. [`hooks/guard.mjs`](../../hooks/guard.mjs) stores per-conversation capsule state under `capsules/` and resolves `realpathSync` on every `edit_file` and `write_file` call with zero regexes or OS sandboxing so no worker can escape its worktree via `../` or symlinks.
- **Read-only `ro-*` workers and `Stop` cleanliness checks.** Explorers and verifiers run in `workspace: "inherit"` with zero repository write permissions (`edit_file` and mutating `git`, `gh`, and MCP calls are blocked, keeping `write_file` probes strictly under canonical temp roots and timeline screenshots). On `Stop`, `hooks/guard.mjs` checks `git status` cleanliness for `ro-*` and rejects untracked or deleted files for `sicko-*`. Inline non-swarm skills (`/bro`, `/technical-writing`, `/setup-pstack`, `/statechart`, `/control-ui`, `/control-cli`, `/make-bot-ui`, and `/ketchup --plain`) pass through unmanaged.
- **Merge before `kill`.** Calling `swarm{action: "kill"}` permanently deletes a worker's `share` worktree. The coordinator always fetches and merges (or cherry-picks) verified worker SHAs before killing any worker.
- **`#seq` citations and doorbell `@mentions`.** Workers reference earlier board messages by `#seq` number rather than pasting duplicate logs, and `@mention` only the specific peer who needs to wake next.

Expand Down
4 changes: 2 additions & 2 deletions docs/guide/03-understand.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,7 @@ Editing unfamiliar code blind is the fastest way to ship subtle regressions. Age

## One parallel `ro-*` mesh, three modes

[`/understand`](../../skills/understand/SKILL.md) spawns a read-only swarm mesh (`ro-code`, `ro-git`, `ro-tracker`, `ro-docs` in `workspace: "inherit"`). Because `hooks/guard.mjs` enforces read-only safety mechanically across files, shell commands, and MCP tools, every `ro-*` worker can cross-query source files, `git log` and `git blame`, GitHub PRs, issue trackers, and design docs simultaneously. Workers post `#seq` clues on the shared board so peers pivot live when `git blame` uncovers a decisive PR or incident ticket.
[`/understand`](../../skills/understand/SKILL.md) spawns a read-only swarm mesh (`ro-code`, `ro-git`, `ro-tracker`, `ro-docs` in `workspace: "inherit"`). Because `hooks/guard.mjs` enforces structural zero-regex, zero-sandbox read-only gating across `edit_file`, `write_file`, mutating `git` and `gh` commands, and mutating MCP tools (with per-conversation `capsules/` state and `Stop` `git status` cleanliness checks), every `ro-*` worker can cross-query source files, `git log` and `git blame`, GitHub PRs, issue trackers, and design docs simultaneously. Workers post `#seq` clues on the shared board so peers pivot live when `git blame` uncovers a decisive PR or incident ticket.

Pick any of `/understand`'s three modes through natural phrasing.

Expand Down Expand Up @@ -54,7 +54,7 @@ When returning to a long-running swarm or resuming work from earlier in the week

Parallel `ro-*` gatherers inspect `board.jsonl` `#seq` deltas, `members.json` roster state (plus `<appDataDir>/brain/<narrator-conversation-id>/swarm_view/view.json` when `narrator` is active in Antigravity 2.0), prior `<appDataDir>/brain/*/.system_generated/swarm/` boards, `git log`, and open `gh pr` status without mutating anything. Every item waiting on your decision comes back with options, `#seq` evidence, and risk so you can decide from the briefing alone.

Run [`/bro`](../../skills/bro/SKILL.md) (`/agy-pstack-next:bro`) to restate the previous message in plain everyday words, pass `--plain` to `/ketchup` for a zero-jargon catch-up summary, or pass `--video` for a short subtitled slide walkthrough of what changed:
Run [`/bro`](../../skills/bro/SKILL.md) (`/agy-pstack-next:bro`) to restate the previous message in plain everyday words, pass `--plain` to `/ketchup` for a zero-jargon catch-up summary, or pass `--video` for a short subtitled slide walkthrough of what changed. Standalone `/bro` and `/ketchup --plain` invocations pass through `hooks/guard.mjs` unmanaged without activating coordinator capsules or blocking subagents:

```text
/agy-pstack-next:bro
Expand Down
Loading
Loading