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
Expand Up @@ -2,7 +2,7 @@
"name": "agy-pstack-next",
"displayName": "agy-pstack-next",
"version": "2.0.0",
"description": "Swarm-centric engineering workflows for Antigravity. Hook-enforced role capsules, worktree isolation, adversarial verification, and 13 composable skills for high-rigor parallel code.",
"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
4 changes: 2 additions & 2 deletions .github/workflows/ci.yml
Original file line number Diff line number Diff line change
Expand Up @@ -152,8 +152,8 @@ jobs:
.map((d) => d.name)
.sort();

if (expectedSkills.length !== 13) {
fail(`Expected 13 skills, found ${expectedSkills.length}: ${expectedSkills.join(", ")}`);
if (expectedSkills.length !== 14) {
fail(`Expected 14 skills, found ${expectedSkills.length}: ${expectedSkills.join(", ")}`);
}

for (const dir of expectedSkills) {
Expand Down
5 changes: 3 additions & 2 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -70,9 +70,9 @@ Every swarm member's prefix determines its workspace isolation, injected role ca
- **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.
- **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 13 Skills
## The 14 Skills

`/pstack` orchestrates most end-to-end tasks automatically and composes with the other 12 skills whenever you want a focused workflow directly.
`/pstack` orchestrates most end-to-end tasks automatically and composes with the other 13 skills whenever you want a focused workflow directly.

| Skill | Purpose |
|---|---|
Expand All @@ -83,6 +83,7 @@ Every swarm member's prefix determines its workspace isolation, injected role ca
| [`/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 `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`](./skills/bro/SKILL.md) | Inline zero-jargon restatement of the preceding message in plain human language with no acronyms, file paths, or commit hashes. |
| [`/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 Down
2 changes: 1 addition & 1 deletion docs/guide/01-setup.md
Original file line number Diff line number Diff line change
Expand Up @@ -10,7 +10,7 @@ Install the plugin from the terminal with the `agy` CLI (`1.5.8+`):
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.
Installing registers root [`hooks.json`](../../hooks.json), [`hooks/guard.mjs`](../../hooks/guard.mjs), the four role capsules under `roles/`, and all 14 skills automatically.

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

Expand Down
6 changes: 5 additions & 1 deletion docs/guide/03-understand.md
Original file line number Diff line number Diff line change
Expand Up @@ -54,7 +54,11 @@ 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.

Pass `--plain` when you want a zero-jargon human summary of a dense technical thread, or `--video` when you want 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:

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

```text
/agy-pstack-next:ketchup --plain
Expand Down
2 changes: 1 addition & 1 deletion docs/guide/07-overnight.md
Original file line number Diff line number Diff line change
Expand Up @@ -57,7 +57,7 @@ When you return in the morning, run [`/ketchup`](../../skills/ketchup/SKILL.md)
/agy-pstack-next:ketchup
```

`/ketchup` inspects `board.jsonl` `#seq` checkpoints, `members.json` (plus optional `<appDataDir>/brain/<narrator-conversation-id>/swarm_view/view.json` when `narrator` runs), `git log`, and any open PRs in parallel across `ro-*` workers. It summarizes what landed, shows captured screenshots or metrics, and lists any decisions or blockers waiting on your call with `#seq` evidence pointers. Add `--plain` for a quick zero-jargon read on your phone, or `--video` for a short subtitled slide recap.
`/ketchup` inspects `board.jsonl` `#seq` checkpoints, `members.json` (plus optional `<appDataDir>/brain/<narrator-conversation-id>/swarm_view/view.json` when `narrator` runs), `git log`, and any open PRs in parallel across `ro-*` workers. It summarizes what landed, shows captured screenshots or metrics, and lists any decisions or blockers waiting on your call with `#seq` evidence pointers. Add `--plain` for a quick zero-jargon read on your phone, or `--video` for a short subtitled slide recap. To restate any dense reply in plain everyday words, run [`/bro`](../../skills/bro/SKILL.md) (`/agy-pstack-next:bro`).

## Scale across multi-area programs

Expand Down
8 changes: 6 additions & 2 deletions docs/guide/10-recipes-and-pitfalls.md
Original file line number Diff line number Diff line change
Expand Up @@ -91,7 +91,7 @@ Author pushes use `PSTACK_ALLOW_PUSH=1` only because you asked to open and updat
/goal keep going until done or genuinely blocked.
```

## Catch up in seconds (`ketchup`)
## Catch up in seconds (`ketchup` and `bro`)

```text
/agy-pstack-next:ketchup
Expand All @@ -101,11 +101,15 @@ Author pushes use `PSTACK_ALLOW_PUSH=1` only because you asked to open and updat
/agy-pstack-next:ketchup --plain
```

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

```text
/agy-pstack-next:ketchup --video
```

Get a structured `#seq` delta briefing, a zero-jargon plain-language summary, or a subtitled slide walkthrough without interrupting running workers.
Get a structured `#seq` delta briefing, a zero-jargon catch-up or plain-language restatement of the last message, or a subtitled slide walkthrough without interrupting running workers.

## Encode repeated corrections into structure (`reflect`)

Expand Down
2 changes: 1 addition & 1 deletion hooks/guard.mjs
Original file line number Diff line number Diff line change
Expand Up @@ -35,7 +35,7 @@ const SWARM_BOARD_TOOLS = new Set([
]);

const PSTACK_SLASH_COMMAND_RE =
/(?:^|\s)\/(?:agy-pstack-next:)?(?:pstack|setup-pstack|understand|crucible|interrogate|reflect|ketchup|verify-gen|control-ui|control-cli|statechart|technical-writing|make-bot-ui)\b/i;
/(?:^|\s)\/(?:agy-pstack-next:)?(?:pstack|setup-pstack|understand|crucible|interrogate|reflect|ketchup|bro|verify-gen|control-ui|control-cli|statechart|technical-writing|make-bot-ui)\b/i;

const BUILTIN_SWARM_SLASH_RE = /(?:^|\s)\/swarm\b/i;

Expand Down
14 changes: 14 additions & 0 deletions hooks/guard.test.mjs
Original file line number Diff line number Diff line change
Expand Up @@ -418,6 +418,18 @@ describe("Session classification (worker, coordinator, unmanaged) and O(1) looku
),
{},
);
assert.deepEqual(
runGuard(
{
hookEventName: "PreInvocation",
conversationId: "normal-chat",
transcriptPath: normalTranscript,
lastUserInput: "thanks bro, looks good",
},
{ PSTACK_APPDATA_DIR: sb.appDataDir },
),
{},
);

const slashPrompts = [
"/pstack ship auth",
Expand All @@ -428,6 +440,8 @@ describe("Session classification (worker, coordinator, unmanaged) and O(1) looku
"/interrogate hooks",
"/reflect session",
"/ketchup --plain",
"/bro",
"/agy-pstack-next:bro",
"/verify-gen --formal",
"/control-ui login",
"/control-cli repl",
Expand Down
15 changes: 9 additions & 6 deletions roles/coordinator.md
Original file line number Diff line number Diff line change
Expand Up @@ -10,12 +10,15 @@ to workers on the native swarm board. Never call legacy subagent tools or
## First response and goal framing

Open your first message on a task by restating the user's goal and the problem
they are trying to solve in your own words. When the task ships a code change,
name the smallest change you expect to meet that goal. Do not pause for
confirmation before starting reversible work. When initial evidence proves the
requested change cannot work, show that evidence immediately and stop. Restate
the user's goal in every worker brief, in every pull request rationale, and at
the top of your final reply unless the task was a single specified one-line edit.
they are trying to solve in your own words, unless you are handling an inline
plain-language restatement (`/bro` or `/ketchup --plain`). When the task ships a
code change, name the smallest change you expect to meet that goal. Do not pause
for confirmation before starting reversible work. When initial evidence proves
the requested change cannot work, show that evidence immediately and stop.
Restate the user's goal in every worker brief, in every pull request rationale,
and at the top of your final reply unless the task was a single specified
one-line edit or an inline plain-language restatement (`/bro` or
`/ketchup --plain`), which replies directly without a goal-framing preamble.

## Roster prefixes and hook contract

Expand Down
25 changes: 25 additions & 0 deletions skills/bro/SKILL.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,25 @@
---
name: bro
description: >-
Restates the last assistant reply or a named passage in plain everyday human
language with zero technical jargon. Use for /agy-pstack-next:bro, /bro,
"speak human", "plain English", or "explain that without jargon".
---

# Bro

Restate your last message in plain spoken human language so another person understands it on the first read.

## Rules

- **Run inline with zero side effects.** Reply directly in the current turn. Never spawn swarm workers, write files, or edit the repository.
- **Skip goal-framing preambles.** Start straight with the plain restatement. Never open with "Your goal is" or chatbot pleasantries.
- **Cut all engineering jargon.** Replace technical terms, protocol acronyms, internal worker or type names, file paths, CLI commands, and commit hashes with what actually happened and why it matters. Keep an identifier only when the human needs it to make a decision.
- **Keep real choices and risks.** Preserve concrete user impact, open decisions, trade-offs, and risks in everyday words. Drop technical backstory that changes no human decision.
- **Write like one human talking to another.** Use short declarative sentences in active voice. Avoid em-dashes, en-dashes, mid-sentence prose colons, and abstract filler.

## Procedure

1. Read the preceding assistant reply in the conversation, or the specific passage the user named.
2. Identify the core outcome, what changed for the user, and any decision or risk that still awaits action.
3. Rewrite those points in simple conversational sentences that anyone outside the codebase can follow immediately.
2 changes: 1 addition & 1 deletion skills/ketchup/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -62,7 +62,7 @@ Write in plain spoken English like one teammate catching up another. Say "the te

### 2. Zero-jargon restatement (`/ketchup --plain`)

Restate the preceding message (or active catch-up) in clear, everyday human language with zero engineering jargon:
Restate the active catch-up or preceding message in clear, everyday human language with zero engineering jargon. Use [`/bro`](../bro/SKILL.md) (`/agy-pstack-next:bro`) as the standalone direct shortcut when you only want to restate the preceding message:

- Replace internal mechanics, type names, protocol acronyms, and tool names with what actually happens and why it matters.
- Keep sentences short, direct, and concrete. If a technical detail needs two paragraphs of backstory and changes no human decision, drop it.
Expand Down
1 change: 1 addition & 0 deletions skills/pstack/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -96,6 +96,7 @@ Route specialized sub-workflows directly to their sibling skills:
| `/interrogate` | [../interrogate/SKILL.md](../interrogate/SKILL.md) | Adversarial `adv-*` exploit reproduction and `ro-blast` transitive caller, schema, and rollout blast-radius mapping |
| `/reflect` | [../reflect/SKILL.md](../reflect/SKILL.md) | Post-mortems, mid-session correction capture, and mining `transcript.jsonl` + `board.jsonl` to encode lessons in hooks, capsules, or tests |
| `/ketchup` | [../ketchup/SKILL.md](../ketchup/SKILL.md) | Live swarm board, transcript, git, and PR catch-up briefings in standard, `--plain`, or `--video` formats |
| `/bro` | [../bro/SKILL.md](../bro/SKILL.md) | Inline zero-jargon restatement of the preceding message in plain human language with no swarm fan-out |
| `/verify-gen` | [../verify-gen/SKILL.md](../verify-gen/SKILL.md) | Author and maintain (`--maintain`) behavioral E2E verification skills and formal property/state-machine (`--formal`) suites |
| `/control-ui` | [../control-ui/SKILL.md](../control-ui/SKILL.md) | Drive and inspect web, IDE, and Electron UIs with isolated ephemeral ports and per-worker browser `--user-data-dir` profiles |
| `/control-cli` | [../control-cli/SKILL.md](../control-cli/SKILL.md) | Drive interactive CLIs and TUIs with isolated PTY sessions, temp state directories, and clean environment overrides |
Expand Down
3 changes: 2 additions & 1 deletion skills/setup-pstack/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -175,7 +175,7 @@ Inspect the workspace for an existing `verify-*` skill or automated E2E harness.

Answer help questions concisely. Recommend the single best v2 skill or `/pstack` topology, explain why in two sentences, and include one copyable prompt in a code block adapted from [`references/recipes.md`](references/recipes.md) and [`references/prompting.md`](references/prompting.md). Prefix plugin slash commands in CLI prompts with `/agy-pstack-next:<skill>` (for example `/agy-pstack-next:pstack`), while leaving built-in Antigravity commands such as `/goal` and `/schedule` unprefixed. Provide a link to [`../../README.md`](../../README.md) or the matching chapter in `docs/guide/`.

### The 13 pstack v2 skills
### The 14 pstack v2 skills

In the `agy` CLI (`1.5.8+`), invoke any plugin skill as `/agy-pstack-next:<skill>` (shown concisely as `/<skill>` in the table below).

Expand All @@ -188,6 +188,7 @@ In the `agy` CLI (`1.5.8+`), invoke any plugin skill as `/agy-pstack-next:<skill
| Break a diff or design with executable exploits (`adv-*`) and prove transitive caller, schema, and rollout safety (`ro-blast`) | [`/interrogate`](../interrogate/SKILL.md) |
| Mine transcripts and swarm boards for post-mortems, eliminate repeated repo mistakes structurally, or sharpen a draft prompt | [`/reflect`](../reflect/SKILL.md) |
| Catch up since your last message (`standard`), in zero-jargon speech (`--plain`), as a subtitled slide video (`--video`), or across recent sessions (`--recall`) | [`/ketchup`](../ketchup/SKILL.md) |
| Restate the last message directly in plain human language with zero jargon | [`/bro`](../bro/SKILL.md) |
| Create or `--maintain` behavioral E2E verification skills and `--formal` property or TLA+ verification skills | [`/verify-gen`](../verify-gen/SKILL.md) |
| Drive and inspect web, IDE, or Electron UIs with worker-isolated ports and browser profiles | [`/control-ui`](../control-ui/SKILL.md) |
| Drive, inspect, and profile interactive CLIs and TUIs in isolated PTY harnesses | [`/control-cli`](../control-cli/SKILL.md) |
Expand Down
1 change: 1 addition & 0 deletions skills/setup-pstack/references/recipes.md
Original file line number Diff line number Diff line change
Expand Up @@ -35,6 +35,7 @@ Swap in your real paths, targets, and pass/fail checks. Plain informal wording w

- `/agy-pstack-next:pstack I am stepping away. finish <goal> across stacked branches. done means <checks>. commit locally and do not push. /goal until checks pass.`
- `/agy-pstack-next:ketchup` (or `/agy-pstack-next:ketchup --video` for a short subtitled slide walkthrough, or `/agy-pstack-next:ketchup --plain` to restate the last technical message in plain words).
- `/agy-pstack-next:bro` (standalone shortcut to restate the previous message inline in plain words with zero jargon).
- `/agy-pstack-next:reflect mine this session's transcript and swarm board, then encode the top lessons into hooks, tests, or skills.`
- `/agy-pstack-next:reflect --correct find the mistakes agents keep repeating in this repo and block them with types, lints, or hooks.`
- `/agy-pstack-next:reflect --sharpen <draft prompt>`
Expand Down
Loading