diff --git a/.antigravity-plugin/plugin.json b/.antigravity-plugin/plugin.json index 59c8b8b..5b65b39 100644 --- a/.antigravity-plugin/plugin.json +++ b/.antigravity-plugin/plugin.json @@ -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" }, diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 98c9a7c..7ad9f3a 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -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) { diff --git a/README.md b/README.md index 75cee04..443a55f 100644 --- a/README.md +++ b/README.md @@ -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 | |---|---| @@ -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. | diff --git a/docs/guide/01-setup.md b/docs/guide/01-setup.md index d24a1b2..930ce53 100644 --- a/docs/guide/01-setup.md +++ b/docs/guide/01-setup.md @@ -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:` 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 `/`, while copy-ready prompt blocks include `/agy-pstack-next:` so they paste cleanly into `agy`. diff --git a/docs/guide/03-understand.md b/docs/guide/03-understand.md index 6ab6515..077922f 100644 --- a/docs/guide/03-understand.md +++ b/docs/guide/03-understand.md @@ -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 `/brain//swarm_view/view.json` when `narrator` is active in Antigravity 2.0), prior `/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 diff --git a/docs/guide/07-overnight.md b/docs/guide/07-overnight.md index 99ac46f..e5d0cfa 100644 --- a/docs/guide/07-overnight.md +++ b/docs/guide/07-overnight.md @@ -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 `/brain//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 `/brain//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 diff --git a/docs/guide/10-recipes-and-pitfalls.md b/docs/guide/10-recipes-and-pitfalls.md index 879f189..ab62a5e 100644 --- a/docs/guide/10-recipes-and-pitfalls.md +++ b/docs/guide/10-recipes-and-pitfalls.md @@ -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 @@ -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`) diff --git a/hooks/guard.mjs b/hooks/guard.mjs index 5dfa068..f58bc02 100755 --- a/hooks/guard.mjs +++ b/hooks/guard.mjs @@ -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; diff --git a/hooks/guard.test.mjs b/hooks/guard.test.mjs index dc8caf4..2bef170 100644 --- a/hooks/guard.test.mjs +++ b/hooks/guard.test.mjs @@ -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", @@ -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", diff --git a/roles/coordinator.md b/roles/coordinator.md index d755434..cb34264 100644 --- a/roles/coordinator.md +++ b/roles/coordinator.md @@ -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 diff --git a/skills/bro/SKILL.md b/skills/bro/SKILL.md new file mode 100644 index 0000000..4754474 --- /dev/null +++ b/skills/bro/SKILL.md @@ -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. diff --git a/skills/ketchup/SKILL.md b/skills/ketchup/SKILL.md index d059c94..c1b8354 100644 --- a/skills/ketchup/SKILL.md +++ b/skills/ketchup/SKILL.md @@ -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. diff --git a/skills/pstack/SKILL.md b/skills/pstack/SKILL.md index 3fd1fc2..c6b3f52 100644 --- a/skills/pstack/SKILL.md +++ b/skills/pstack/SKILL.md @@ -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 | diff --git a/skills/setup-pstack/SKILL.md b/skills/setup-pstack/SKILL.md index 7f55158..36a6f3c 100644 --- a/skills/setup-pstack/SKILL.md +++ b/skills/setup-pstack/SKILL.md @@ -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:` (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:` (shown concisely as `/` in the table below). @@ -188,6 +188,7 @@ In the `agy` CLI (`1.5.8+`), invoke any plugin skill as `/agy-pstack-next: across stacked branches. done means . 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 `