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
2 changes: 1 addition & 1 deletion .antigravity-plugin/plugin.json
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
{
"name": "agy-pstack-next",
"displayName": "agy-pstack-next",
"version": "2.0.0",
"version": "2.1.0",
"description": "Swarm-centric engineering workflows for Antigravity. Hook-enforced role capsules, worktree isolation, adversarial verification, and 14 composable skills for high-rigor parallel code.",
"author": {
"name": "Lauren Tan"
Expand Down
79 changes: 77 additions & 2 deletions .github/workflows/ci.yml
Original file line number Diff line number Diff line change
Expand Up @@ -95,6 +95,10 @@ jobs:
};
checkExecutable("hooks/guard.mjs");
checkExecutable("skills/pstack/scripts/watch-pr");
checkExecutable("skills/pstack/scripts/check-plan.mjs");
checkExecutable("skills/pstack/scripts/worktree-audit.sh");
checkExecutable("skills/pstack/scripts/decision-log.sh");
checkExecutable("skills/setup-pstack/scripts/sync-hooks.mjs");

for (const capsule of ["coordinator", "poteto-agent", "research", "comment-sicko"]) {
const p = join("roles", `${capsule}.md`);
Expand Down Expand Up @@ -209,11 +213,82 @@ jobs:
- name: Run swarm guard unit tests
run: node --test hooks/guard.test.mjs

- name: Run pstack script syntax and unit tests
env:
GIT_CONFIG_COUNT: "1"
GIT_CONFIG_KEY_0: commit.gpgsign
GIT_CONFIG_VALUE_0: "false"
run: |
bash -n skills/pstack/scripts/worktree-audit.sh
bash -n skills/pstack/scripts/decision-log.sh
node --test skills/pstack/scripts/watch-pr.test.mjs skills/pstack/scripts/check-plan.test.mjs

- name: Smoke check watch-pr CLI
run: ./skills/pstack/scripts/watch-pr --help > /dev/null

- name: Verify TLA+ tools pin matches statechart runner
run: |
bun - <<'EOF'
import { readFileSync } from "node:fs";

const runTs = readFileSync("skills/statechart/scripts/run.ts", "utf8");
const ciYml = readFileSync(".github/workflows/ci.yml", "utf8");

const toolMatch = runTs.match(
/const TLC_TOOL =\s*"http:tla2tools\[url=(https:\/\/[^,\]]+),checksum=sha256:([0-9a-f]{64})\]@([^"]+)"/,
);
if (!toolMatch) {
throw new Error("Could not parse TLC_TOOL from skills/statechart/scripts/run.ts");
}
const [, url, sha256, version] = toolMatch;

const requiredSnippets = [
`path: ~/.cache/tla2tools/tla2tools-${version}.jar`,
`key: tla2tools-${version}`,
url,
`${sha256} $HOME/.cache/tla2tools/tla2tools-${version}.jar`,
`TLA2TOOLS="$HOME/.cache/tla2tools/tla2tools-${version}.jar"`,
];
for (const snippet of requiredSnippets) {
if (!ciYml.includes(snippet)) {
throw new Error(`ci.yml missing pinned TLC_TOOL snippet: ${snippet}`);
}
}

for (const m of ciYml.matchAll(/https:\/\/github\.com\/tlaplus\/tlaplus\/releases\/download\/[^/\s"']+\/tla2tools\.jar/g)) {
if (m[0] !== url) {
throw new Error(`ci.yml tla2tools URL "${m[0]}" does not match run.ts "${url}"`);
}
}
for (const m of ciYml.matchAll(/tla2tools-([0-9]+\.[0-9]+\.[0-9]+)(?:\.jar)?/g)) {
if (m[1] !== version) {
throw new Error(`ci.yml tla2tools version "${m[1]}" does not match run.ts "${version}"`);
}
}
EOF

- name: Setup Java
uses: actions/setup-java@v4
with:
distribution: temurin
java-version: "25"

- name: Cache TLA+ tools
id: cache-tla2tools
uses: actions/cache@v4
with:
path: ~/.cache/tla2tools/tla2tools-1.7.4.jar
key: tla2tools-1.7.4

- name: Download TLA+ tools
if: steps.cache-tla2tools.outputs.cache-hit != 'true'
run: |
mkdir -p "$HOME/.cache/tla2tools"
curl -fsSL https://github.com/tlaplus/tlaplus/releases/download/v1.7.4/tla2tools.jar -o "$HOME/.cache/tla2tools/tla2tools-1.7.4.jar"
echo "936a262061c914694dfd669a543be24573c45d5aa0ff20a8b96b23d01e050e88 $HOME/.cache/tla2tools/tla2tools-1.7.4.jar" | sha256sum -c -

- name: Test statechart
working-directory: skills/statechart/scripts
run: |
bun install
bun run test
bun install --frozen-lockfile
TLA2TOOLS="$HOME/.cache/tla2tools/tla2tools-1.7.4.jar" bun run test
12 changes: 6 additions & 6 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -24,7 +24,7 @@ agy plugin list

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 [`/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.
1. Run [`/agy-pstack-next:setup-pstack`](./skills/setup-pstack/SKILL.md) to discover your available models, validate and write `~/.gemini/config/rules/pstack-models.md` with `trigger: always_on` (including `monitor` and separate `impl-*` and `lead-*` rows), sync `pstack-swarm-guard` in global `~/.gemini/config/hooks.json` via [`sync-hooks.mjs`](./skills/setup-pstack/scripts/sync-hooks.mjs) (plus `--check`), 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
Expand Down Expand Up @@ -52,7 +52,7 @@ Every swarm member's prefix determines its workspace isolation, injected role ca
| `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. |
| `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]`). |

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

Expand All @@ -67,7 +67,7 @@ Every swarm member's prefix determines its workspace isolation, injected role ca

- **Warm context forks.** Pass `fork: "<member>"` in `swarm{action: "add"}` to branch an implementation worker directly from a winning `ro-*` investigator or `cand-*` prototype without re-reading the repo cold.
- **Safe landing before teardown.** Because `swarm{action: "kill"}` permanently deletes a worker's `share` worktree, the coordinator always runs `git fetch <worker_cwd> <sha> && git merge` (or `cherry-pick`) before killing a worker.
- **Board `#seq` citations and doorbell `@mentions`.** Workers cite earlier findings by `#seq` number instead of re-quoting logs and `@mention` only the specific peer who acts next.
- **Board `#seq` citations, `$PWD` paths, and `/tmp` reports.** Workers fetch cited `#seq` posts with `read_board` `seqs` instead of reading from `0`, pass absolute `$PWD/...` paths inside `share` worktrees, write detailed reports over `4` KB to `/tmp/<worker-name>-report.md` with a summary on the board, and `@mention` only 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.

## The 14 Skills
Expand All @@ -77,7 +77,7 @@ 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`, global `~/.gemini/config/hooks.json` guard registration, budget presets, workflow advisor, and `/schedule` automation setup. |
| [`/setup-pstack`](./skills/setup-pstack/SKILL.md) | 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`](./skills/setup-pstack/scripts/sync-hooks.mjs) global hook sync (`--check`), workflow advisor, and `/schedule` 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`. |
Expand All @@ -97,8 +97,8 @@ 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 (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. |
| [`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, [`check-plan.mjs`](./skills/pstack/scripts/check-plan.mjs), [`decision-log.sh`](./skills/pstack/scripts/decision-log.sh), [`worktree-audit.sh`](./skills/pstack/scripts/worktree-audit.sh), 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, conditional `sicko-*` diff cleanup on comments or non-trivial code changes, 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. |
Expand Down
13 changes: 7 additions & 6 deletions docs/guide/01-setup.md
Original file line number Diff line number Diff line change
Expand Up @@ -22,20 +22,21 @@ Run the setup skill inside Antigravity:
/agy-pstack-next:setup-pstack
```

[`/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.
[`/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, validates any existing model IDs in `~/.gemini/config/rules/pstack-models.md` against that live catalog (alongside `inherit`, which runs workers on your active session model), asks for your budget preset (`frugal`, `balanced`, `max`, or `inherit`), 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 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.
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, with separate `impl-*` and `lead-*` lines plus `monitor` pinned to the fast low-cost tier (such as `gemini-3.8-flash-low`).
2. **Syncs `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` runs [`sync-hooks.mjs`](../../skills/setup-pstack/scripts/sync-hooks.mjs) (and `--check` for drift verification) to preserve existing entries (such as `herdr`) and register `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, `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.

- **`coordinator`.** Plans slices, manages the board, and synthesizes results.
- **`impl-*`, `cand-*`, `lead-*`.** Author code, prototypes, and sub-area slices in `workspace: "share"` worktrees.
- **`impl-*`, `lead-*`, `cand-*`.** Separate prefixes for slice implementation (`impl-*`), multi-area coordination (`lead-*`), and competing prototypes (`cand-*`) in `workspace: "share"` worktrees.
- **`ro-*` and `ro-verify`.** Run read-only exploration, trace probes, and independent behavioral verification in `workspace: "inherit"`.
- **`adv-*` and `ro-judge`.** Run adversarial bug repros and cross-family design or eval judging so a model family does not grade its own blind spots.
- **`sicko-*`.** Runs post-pass comment and slop surgery across diffs.
- **`sicko-*`.** Runs conditional post-pass comment and slop surgery on diffs that add comments or non-trivial code changes.
- **`monitor`.** Runs built-in stall detection (`swarm_monitor`) on multi-wave or long-running swarms, pinned to the fast low-cost tier (such as `gemini-3.8-flash-low`) while skipped on short `<= 4` worker runs.

You override only the roles you care about. Roles omitted from `pstack-models.md` fall back to `inherit` or the skill's preset defaults. If a worker hits rate limits or low quota mid-run, `/pstack` hot-swaps its model live via `swarm{action: "model"}` without losing its conversation or worktree.

Expand All @@ -55,7 +56,7 @@ Start a fresh chat after updating `pstack-models.md` and `~/.gemini/config/hooks

Parallel swarms trade tokens for wall-clock speed and independent verification. Four levers control spend.

- Pick a leaner budget preset in `/setup-pstack` so `ro-*` explorers and `sicko-*` cleanup workers use fast, inexpensive models while `coordinator` and `ro-judge` keep frontier reasoning models.
- Pick the `frugal` or `balanced` budget preset in `/setup-pstack` so `monitor`, `ro-*`, and `sicko-*` workers use fast, low-cost models while `coordinator` and `ro-judge` keep frontier reasoning models.
- Leave roles on `inherit` when your active session already uses the exact model you want.
- Right-size candidate counts in `/crucible` and `/interrogate` (`2` or `3` candidates for routine boundaries, more only for irreversible interfaces).
- Use `/pstack` for multi-file, risky, or verifiable engineering tasks rather than single-line typo edits.
Expand Down
Loading
Loading