summaryrefslogtreecommitdiff
path: root/docs
diff options
context:
space:
mode:
Diffstat (limited to 'docs')
-rw-r--r--docs/README.opencode.md2
-rw-r--r--docs/porting-to-a-new-harness.md40
-rw-r--r--docs/superpowers/plans/2026-10-06-antigravity-marketplace.md711
-rw-r--r--docs/superpowers/specs/2026-10-05-brainstorming-rebuild-design.md165
-rw-r--r--docs/superpowers/specs/2026-10-06-antigravity-marketplace-design.md181
-rw-r--r--docs/windows/polyglot-hooks.md15
6 files changed, 1093 insertions, 21 deletions
diff --git a/docs/README.opencode.md b/docs/README.opencode.md
index 404a65d..980941e 100644
--- a/docs/README.opencode.md
+++ b/docs/README.opencode.md
@@ -111,7 +111,7 @@ V1 `plugin` key and the V2 `plugins` key):
```json
{
- "plugin": ["superpowers@git+https://github.com/obra/superpowers.git#v6.4.2"]
+ "plugin": ["superpowers@git+https://github.com/obra/superpowers.git#v7.0.0"]
}
```
diff --git a/docs/porting-to-a-new-harness.md b/docs/porting-to-a-new-harness.md
index ce37418..f52cd70 100644
--- a/docs/porting-to-a-new-harness.md
+++ b/docs/porting-to-a-new-harness.md
@@ -292,10 +292,10 @@ part of the installed extension** — never substitute "edit the user's global
| runs a shell command at session start and reads its stdout | A (shell-hook) | Cursor (`hooks/session-start` + `hooks/hooks-cursor.json` + `.cursor-plugin/`) |
| is a JS/TS plugin host with session/message lifecycle callbacks | B (in-process) | OpenCode (`.opencode/`) — or pi (`.pi/`) if it has no native skill tool |
| ships an extension-declared context file it always loads | C (instructions-file) | Gemini (`gemini-extension.json` + `GEMINI.md` + `references/gemini-tools.md`) |
-| has a plugin install command and a manifest `contextFileName` (or equivalent) the installer keeps | C via the plugin installer | Antigravity (`.antigravity-plugin/` — `agy plugin install` ships a generated context file; verify the installer preserves it — Part 6) |
+| lists each installed skill's description, with no session-start event and no context-file field | skill-index bootstrap (Part 5 Step 5, case 2 fallback) | Antigravity (`.antigravity-plugin/plugin.json` + `skills/` only) |
-Most real harnesses fit one row cleanly; the last is the hybrid case (rule 2 still
-holds — the bootstrap rides the install mechanism, never a user-config edit).
+Most real harnesses fit one row cleanly; the last is the soft case — see Step 5's
+fallback caveats (rule 2 still holds — never a user-config edit).
---
@@ -525,11 +525,22 @@ honors the rule rather than breaking it. Distinguish three cases:
the file-read tool when the skill applies** — the sanctioned mechanism here,
the way `references/pi-tools.md` states it.
- **For the bootstrap itself, prefer a declared context file (Part 6).** If the
- harness has a `contextFileName`-style manifest field — as Antigravity does —
- ship a generated context file through the installer: it's guaranteed-loaded and
- carries both the `using-superpowers` content and the tool mapping. That is the
- strong, preferred path.
+ **For the bootstrap itself, prefer something the harness loads every
+ session (Part 6)** — a declared context file where the manifest has a
+ `contextFileName`-style field. Antigravity has none, and its other options
+ cost more than they buy, so it uses the surfaced skill index below:
+ - Its hooks have no session-start event. `PreInvocation` runs before every
+ model call; an `ephemeralMessage` it injects is dropped on the next call,
+ and `invocationNum` resets on each user turn. A `userMessage` gated on
+ `invocationNum == 0` and `initialNumSteps == 1` injects exactly once per
+ conversation, but agy still starts the hook process on every model call.
+ `${PLUGIN_ROOT}` is not set in hooks (they run from the plugin root).
+ `hooks.json` must sit at the plugin root; no manifest field moves it.
+ - It loads `rules/*.md` from a plugin every session, but harnesses that
+ install from the git repo share its root, and Cursor is one of them: it
+ also loads any `rules/*.md` a plugin ships. A file in a shared plugin root
+ is visible to every harness that reads that root — check before adding
+ one.
**Fallback — the surfaced skill index.** If there's no context-file field but
the harness surfaces each installed skill's name + description at session start,
@@ -678,7 +689,7 @@ it. Distribution differs per harness ecosystem — find yours:
| External marketplace fork, synced by script | Codex | `scripts/sync-to-codex-plugin.sh` rsyncs the tracked plugin files into a separate fork repo and opens a PR. Read its include/exclude list so you ship the right tree (it deliberately drops repo-internal dirs and other harnesses' dotdirs). |
| Git-URL extension install | Gemini, Kimi Code, OpenCode | Users install from a git URL (`gemini extensions install …`; Kimi Code `/plugins install …`; an `opencode.json` `plugin` array entry). Document the exact command. |
| Package-manifest fields | pi | Declared through fields in the repo-root `package.json`; users install via the harness's package command. |
-| Local installer (plugin install) | Antigravity (`agy`) | A small `install.sh` that runs the harness's own `agy plugin install` against a staging dir holding the manifest, the skills, and a generated `contextFileName` context file (the bootstrap). Everything arrives through the install mechanism — *not* by editing the user's config (see below). |
+| Git-URL plugin install + marketplace | Antigravity (`agy`) | Users run `agy plugin install https://github.com/obra/superpowers`. agy reads `.antigravity-plugin/plugin.json`, whose Marketplace fields (`displayName`, `logo`, `suggestedPrompts`, `version`, `author`) also drive the Antigravity Marketplace listing. Without that manifest, agy falls back to importing `gemini-extension.json`. |
Then:
@@ -694,13 +705,9 @@ Then:
session), that is the strongest clean bootstrap: declare it, and the installer
preserves it *and* the harness loads it. Generate it at install time from the
live `using-superpowers/SKILL.md` + the tool mapping (wrapped in
- `<EXTREMELY_IMPORTANT>`) so the installed bootstrap never drifts. This is what
- `.antigravity-plugin/install.sh` does — `agy plugin install` reports
- `✔ context : ANTIGRAVITY.md`, and a clean session reads `using-superpowers`'s
- SKILL.md, loads `brainstorming`, and enters the brainstorming flow before any
- code. **Verify with a marker** that the installer keeps the file and the
- harness loads it: one porter wrongly concluded it couldn't, because they
- shipped the file *without* declaring `contextFileName` and it was stripped as
+ `<EXTREMELY_IMPORTANT>`) so the installed bootstrap never drifts.
+ **Verify with a marker** that the installer keeps the file and the
+ harness loads it: a file the manifest doesn't declare can be stripped as
unrecognized.
- **Otherwise lean on the installed `using-superpowers` skill itself.** If the
harness surfaces each installed skill's name + description at session start,
@@ -796,6 +803,7 @@ Use this as the live index; when in doubt, read the files, not this table.
| Harness | Entry point | Bootstrap mechanism | Tool mapping | Tests | Distribution |
|---|---|---|---|---|---|
+| Antigravity (`agy`) | `.antigravity-plugin/plugin.json` | surfaced skill index: `using-superpowers`' description triggers it (no session-start hook event exists) | `references/antigravity-tools.md` | `tests/antigravity/` | `agy plugin install` git URL; Antigravity Marketplace |
| Claude Code | `.claude-plugin/plugin.json` + `hooks/hooks.json` | shell hook → `hooks/session-start` (`hookSpecificOutput.additionalContext`) | native `Skill` tool; no adapter file needed | `tests/hooks/` | marketplace |
| Codex | `.codex-plugin/plugin.json` (declares empty `hooks`) | native skill discovery (no session-start hook) | `references/codex-tools.md` | `tests/codex/`, `tests/codex-plugin-sync/` | fork sync (`scripts/sync-to-codex-plugin.sh`) |
| Cursor | `.cursor-plugin/plugin.json` + `hooks/hooks-cursor.json` | shell hook → `hooks/session-start` (`additional_context`) | none needed (Claude Code–compatible tool surface) | `tests/hooks/` | hand-authored |
diff --git a/docs/superpowers/plans/2026-10-06-antigravity-marketplace.md b/docs/superpowers/plans/2026-10-06-antigravity-marketplace.md
new file mode 100644
index 0000000..5804e05
--- /dev/null
+++ b/docs/superpowers/plans/2026-10-06-antigravity-marketplace.md
@@ -0,0 +1,711 @@
+# Antigravity Marketplace Plugin Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Ship a native Antigravity plugin (manifest with Marketplace fields, logo, always-on rule bootstrap) so Superpowers can be listed in the Antigravity Marketplace.
+
+**Architecture:** agy reads `.antigravity-plugin/plugin.json` and discovers `skills/` by default. A one-line always-on rule, `rules/AGENTS.md`, `@`-points at `skills/using-superpowers/SKILL.md`; agy rewrites that path to an absolute install path and the model reads it with `view_file`. The logo is a PNG rendered from `assets/superpowers-small.svg` by a script.
+
+**Tech Stack:** bash, python3 (stdlib only, in tests), `rsvg-convert` (logo rendering only), `agy` 1.3.1 (optional in tests, required for live acceptance), `jq`.
+
+**Spec:** `docs/superpowers/specs/2026-10-06-antigravity-marketplace-design.md`
+
+> **Historical record.** This plan was executed as written. The `rules/AGENTS.md` bootstrap it describes was later removed in favor of skill discovery, and the Marketplace copy was replaced; see spec §1 and §2 for the shipped design.
+
+## Global Constraints
+
+- Work on branch `antigravity-marketplace`. PRs target `dev`.
+- Never copy `using-superpowers` content into another file. The rule is a pointer only.
+- No root `plugin.json` and no root `hooks.json` (either changes how agy reads the plugin).
+- Manifest `name` is `superpowers`; must match `^[a-z0-9]+(-[a-z0-9]+)*$`.
+- Manifest `description` is at most 160 characters.
+- `suggestedPrompts`: 1–3 non-empty strings.
+- Manifest `version` equals `.claude-plugin/plugin.json`'s `version` (6.4.2 at time of writing).
+- `author` matches `.claude-plugin/plugin.json`: `{ "name": "Jesse Vincent", "email": "jesse@fsck.com" }`.
+- Logo: `assets/antigravity-logo.png`, 512×512 RGBA PNG; white rounded square inset 31px, corner radius 100; mark `#1a1a1a`, scale 0.905 about (256,256).
+- `${PLUGIN_ROOT}` is not substituted in rules. Do not use it in `rules/AGENTS.md`.
+- New shell scripts must pass `scripts/lint-shell.sh <file>`.
+- Any `agy plugin install` done for testing must be followed by `agy plugin uninstall superpowers`.
+
+---
+
+## File Map
+
+| File | Action | Responsibility |
+|---|---|---|
+| `scripts/render-antigravity-logo.sh` | Create | Compose logo SVG from `assets/superpowers-small.svg`, rasterize to PNG |
+| `assets/antigravity-logo.png` | Create (generated) | Marketplace logo |
+| `.antigravity-plugin/plugin.json` | Create | Native manifest with Marketplace fields |
+| `rules/AGENTS.md` | Create | Always-on bootstrap pointer |
+| `.version-bump.json` | Modify | Register the new manifest's version |
+| `tests/antigravity/test-logo.sh` | Create | Logo file shape checks |
+| `tests/antigravity/test-plugin-manifest.sh` | Create | Manifest, rule, and layout checks; `agy plugin validate` when available |
+| `tests/antigravity/test-antigravity-tools.sh` | Modify | Fix stale header comment |
+| `scripts/sync-to-codex-plugin.sh` | Modify | Exclude Antigravity-only files from the Codex sync |
+| `tests/codex-plugin-sync/test-sync-to-codex-plugin.sh` | Modify | Assert those exclusions |
+| `README.md` | Modify | Antigravity section prose |
+| `docs/porting-to-a-new-harness.md` | Modify (separate commit) | Remove phantom installer; record agy findings |
+
+---
+
+### Task 1: Logo renderer and logo
+
+**Files:**
+- Create: `scripts/render-antigravity-logo.sh`
+- Create: `assets/antigravity-logo.png` (generated by the script)
+- Test: `tests/antigravity/test-logo.sh`
+
+**Interfaces:**
+- Produces: `assets/antigravity-logo.png` (Task 2's manifest `logo` field points here). `scripts/render-antigravity-logo.sh [--output PATH]`, default output `assets/antigravity-logo.png`.
+
+- [ ] **Step 1: Write the failing test**
+
+Create `tests/antigravity/test-logo.sh`:
+
+```bash
+#!/usr/bin/env bash
+# Check the Antigravity Marketplace logo: a square RGBA PNG at least 128x128
+# (the Marketplace minimum), at the path the manifest names. When rsvg-convert
+# is available, also check the committed PNG matches a fresh render, so the
+# asset can't drift from scripts/render-antigravity-logo.sh.
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+REPO_ROOT="$(cd "$SCRIPT_DIR/../.." && pwd)"
+LOGO="$REPO_ROOT/assets/antigravity-logo.png"
+
+fail() { echo "FAIL: $*" >&2; exit 1; }
+
+echo "test-logo: checking Antigravity logo"
+
+[ -f "$LOGO" ] || fail "logo missing at $LOGO"
+
+python3 - "$LOGO" <<'PY'
+import struct
+import sys
+
+data = open(sys.argv[1], "rb").read()
+if data[:8] != b"\x89PNG\r\n\x1a\n":
+ raise SystemExit("FAIL: logo is not a PNG")
+width, height, bit_depth, color_type = struct.unpack(">IIBB", data[16:26])
+if width != height:
+ raise SystemExit(f"FAIL: logo is not square ({width}x{height})")
+if width < 128:
+ raise SystemExit(f"FAIL: logo is smaller than 128x128 ({width}x{height})")
+if color_type != 6:
+ raise SystemExit(f"FAIL: logo is not RGBA (PNG color type {color_type})")
+PY
+
+if command -v rsvg-convert >/dev/null 2>&1; then
+ tmp="$(mktemp -d)"
+ trap 'rm -f "$tmp/logo.png"; rmdir "$tmp"' EXIT
+ bash "$REPO_ROOT/scripts/render-antigravity-logo.sh" --output "$tmp/logo.png" >/dev/null
+ cmp -s "$tmp/logo.png" "$LOGO" \
+ || fail "assets/antigravity-logo.png is stale; run scripts/render-antigravity-logo.sh"
+else
+ echo "SKIP: rsvg-convert not on PATH; not checking logo freshness"
+fi
+
+echo "PASS: Antigravity logo valid"
+```
+
+- [ ] **Step 2: Run test to verify it fails**
+
+Run: `bash tests/antigravity/test-logo.sh`
+Expected: `FAIL: logo missing at .../assets/antigravity-logo.png`, exit 1.
+
+- [ ] **Step 3: Write the renderer**
+
+Create `scripts/render-antigravity-logo.sh`:
+
+```bash
+#!/usr/bin/env bash
+#
+# Render the Antigravity Marketplace logo from assets/superpowers-small.svg.
+#
+# Usage:
+# scripts/render-antigravity-logo.sh [--output PATH]
+#
+# Draws the Superpowers mark in near-black on a white rounded square with
+# transparent corners, 512x512 PNG. Run it whenever superpowers-small.svg
+# changes; tests/antigravity/test-logo.sh fails if the committed PNG is stale.
+# Requires rsvg-convert (Homebrew: librsvg).
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+REPO_ROOT="$(cd "$SCRIPT_DIR/.." && pwd)"
+SOURCE_SVG="$REPO_ROOT/assets/superpowers-small.svg"
+OUTPUT="$REPO_ROOT/assets/antigravity-logo.png"
+
+usage() {
+ sed -n '2,11p' "$0" | sed 's/^# \{0,1\}//'
+}
+
+die() {
+ echo "error: $*" >&2
+ exit 1
+}
+
+while [[ $# -gt 0 ]]; do
+ case "$1" in
+ --output)
+ [[ $# -ge 2 ]] || die "--output needs a path"
+ OUTPUT="$2"
+ shift 2
+ ;;
+ -h | --help)
+ usage
+ exit 0
+ ;;
+ *)
+ usage >&2
+ die "unknown argument: $1"
+ ;;
+ esac
+done
+
+command -v rsvg-convert >/dev/null 2>&1 \
+ || die "rsvg-convert is not on PATH (install librsvg, e.g. 'brew install librsvg')"
+[[ -r "$SOURCE_SVG" ]] || die "source mark not readable: $SOURCE_SVG"
+
+# Everything inside the source <svg> element: the mark's paths and ellipse.
+mark="$(sed -E 's/^.*<svg[^>]*>//; s#</svg>.*$##' "$SOURCE_SVG")"
+[[ -n "$mark" ]] || die "could not extract the mark from $SOURCE_SVG"
+
+# The mark's bounding box is centered at (256,256) in its 512 viewBox and is
+# 348 units wide; scale 0.905 makes it ~70% of the 450-unit rounded square.
+composed="$(mktemp)"
+trap 'rm -f "$composed"' EXIT
+cat >"$composed" <<EOF
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 512 512" width="512" height="512">
+ <rect x="31" y="31" width="450" height="450" rx="100" ry="100" fill="#ffffff"/>
+ <g fill="#1a1a1a" transform="translate(256 256) scale(0.905) translate(-256 -256)">$mark</g>
+</svg>
+EOF
+
+rsvg-convert -w 512 -h 512 "$composed" -o "$OUTPUT"
+echo "wrote $OUTPUT"
+```
+
+Then: `chmod +x scripts/render-antigravity-logo.sh`
+
+- [ ] **Step 4: Render the logo and look at it**
+
+Run: `bash scripts/render-antigravity-logo.sh`
+Expected: `wrote .../assets/antigravity-logo.png`.
+
+Open `assets/antigravity-logo.png` with the Read tool and confirm: white rounded square, transparent corners, full mark (two arcs, two inner strokes, and the center dot) centered in near-black.
+
+- [ ] **Step 5: Run the test and the shell linter**
+
+Run: `bash tests/antigravity/test-logo.sh && scripts/lint-shell.sh scripts/render-antigravity-logo.sh tests/antigravity/test-logo.sh`
+Expected: `PASS: Antigravity logo valid`, linter clean. Also run `bash scripts/render-antigravity-logo.sh --help` and confirm it prints usage.
+
+- [ ] **Step 6: Commit**
+
+```bash
+git add scripts/render-antigravity-logo.sh assets/antigravity-logo.png tests/antigravity/test-logo.sh
+git commit -m "feat(antigravity): render Marketplace logo from the Superpowers mark"
+```
+
+---
+
+### Task 2: Native manifest, bootstrap rule, version bump
+
+**Files:**
+- Create: `.antigravity-plugin/plugin.json`
+- Create: `rules/AGENTS.md`
+- Modify: `.version-bump.json` (add one entry to `files`)
+- Test: `tests/antigravity/test-plugin-manifest.sh`
+
+**Interfaces:**
+- Consumes: `assets/antigravity-logo.png` from Task 1.
+- Produces: `.antigravity-plugin/plugin.json`, `rules/AGENTS.md` (Task 3 excludes both from the Codex sync; Task 5 installs them).
+
+- [ ] **Step 1: Write the failing test**
+
+Create `tests/antigravity/test-plugin-manifest.sh`:
+
+```bash
+#!/usr/bin/env bash
+# Validate the native Antigravity plugin: the Marketplace manifest, the
+# always-on rule that bootstraps using-superpowers, and the repo layout agy
+# depends on. CI-safe; when `agy` is on PATH, also runs `agy plugin validate`.
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+REPO_ROOT="$(cd "$SCRIPT_DIR/../.." && pwd)"
+
+echo "test-plugin-manifest: checking Antigravity plugin"
+
+python3 - "$REPO_ROOT" <<'PY'
+import json
+import re
+import struct
+import sys
+from pathlib import Path
+
+root = Path(sys.argv[1])
+
+def fail(message):
+ raise SystemExit(f"FAIL: {message}")
+
+manifest_path = root / ".antigravity-plugin" / "plugin.json"
+if not manifest_path.is_file():
+ fail(f"manifest missing at {manifest_path}")
+manifest = json.loads(manifest_path.read_text(encoding="utf-8"))
+
+# --- Marketplace-required fields -------------------------------------------
+for field in ["name", "description", "displayName", "logo",
+ "suggestedPrompts", "version", "author"]:
+ if not manifest.get(field):
+ fail(f"manifest field {field!r} is missing or empty")
+
+if manifest["name"] != "superpowers":
+ fail(f"name must be 'superpowers', got {manifest['name']!r}")
+if not re.fullmatch(r"[a-z0-9]+(-[a-z0-9]+)*", manifest["name"]):
+ fail("name is not kebab-case")
+
+description_length = len(manifest["description"])
+if not 120 <= description_length <= 160:
+ fail(f"description is {description_length} characters; Marketplace wants 120-160")
+
+prompts = manifest["suggestedPrompts"]
+if not isinstance(prompts, list) or not 1 <= len(prompts) <= 3:
+ fail("suggestedPrompts must be a list of 1-3 prompts")
+if not all(isinstance(p, str) and p.strip() for p in prompts):
+ fail("suggestedPrompts entries must be non-empty strings")
+
+claude_manifest = json.loads(
+ (root / ".claude-plugin" / "plugin.json").read_text(encoding="utf-8"))
+if manifest["version"] != claude_manifest["version"]:
+ fail(f"version {manifest['version']!r} != .claude-plugin version "
+ f"{claude_manifest['version']!r}")
+if manifest["author"] != claude_manifest["author"]:
+ fail("author does not match .claude-plugin/plugin.json")
+
+# --- Logo ------------------------------------------------------------------
+logo = root / manifest["logo"]
+if not logo.is_file():
+ fail(f"logo {manifest['logo']!r} does not exist")
+header = logo.read_bytes()[:26]
+if header[:8] != b"\x89PNG\r\n\x1a\n":
+ fail("logo is not a PNG")
+width, height = struct.unpack(">II", header[16:24])
+if width != height or width < 128:
+ fail(f"logo must be square and at least 128x128, got {width}x{height}")
+
+# --- Version bumps ---------------------------------------------------------
+version_config = json.loads((root / ".version-bump.json").read_text(encoding="utf-8"))
+if not any(entry.get("path") == ".antigravity-plugin/plugin.json"
+ and entry.get("field") == "version"
+ for entry in version_config.get("files", [])):
+ fail(".version-bump.json does not register .antigravity-plugin/plugin.json")
+
+# --- Bootstrap rule: @-pointers only, each resolving from rules/ -----------
+rule = root / "rules" / "AGENTS.md"
+if not rule.is_file():
+ fail(f"bootstrap rule missing at {rule}")
+lines = [line.strip() for line in rule.read_text(encoding="utf-8").splitlines()
+ if line.strip()]
+if not lines:
+ fail("bootstrap rule is empty")
+for line in lines:
+ if not line.startswith("@"):
+ fail(f"bootstrap rule must contain only @-pointers, found: {line!r}")
+ target = (rule.parent / line[1:]).resolve()
+ if not target.is_file():
+ fail(f"rule pointer {line!r} does not resolve from rules/ to a file")
+if not any(line.endswith("skills/using-superpowers/SKILL.md") for line in lines):
+ fail("bootstrap rule does not point at using-superpowers")
+
+# --- Layout agy depends on -------------------------------------------------
+for stray in ["plugin.json", "hooks.json"]:
+ if (root / stray).exists():
+ fail(f"root {stray} must not exist; agy would read it instead")
+PY
+
+if command -v agy >/dev/null 2>&1; then
+ output="$(agy plugin validate "$REPO_ROOT" 2>&1)" \
+ || { echo "$output" >&2; echo "FAIL: agy plugin validate failed" >&2; exit 1; }
+ grep -q '\[ok\]' <<<"$output" \
+ || { echo "$output" >&2; echo "FAIL: agy plugin validate did not report [ok]" >&2; exit 1; }
+ grep -qE 'skills +: [0-9]+ processed' <<<"$output" \
+ || { echo "$output" >&2; echo "FAIL: agy found no skills" >&2; exit 1; }
+else
+ echo "SKIP: agy not on PATH; not running agy plugin validate"
+fi
+
+echo "PASS: Antigravity plugin manifest and bootstrap rule valid"
+```
+
+Note: `agy plugin validate` output contains ANSI color codes around `[ok]`; the `grep -q '\[ok\]'` still matches because the codes surround, not split, the text. Verify this in Step 4; if it does not match, strip codes with `sed 's/\x1b\[[0-9;]*m//g'` before grepping.
+
+- [ ] **Step 2: Run test to verify it fails**
+
+Run: `bash tests/antigravity/test-plugin-manifest.sh`
+Expected: `FAIL: manifest missing at .../.antigravity-plugin/plugin.json`, exit 1.
+
+- [ ] **Step 3: Write the manifest, the rule, and the version-bump entry**
+
+Create `.antigravity-plugin/plugin.json`:
+
+```json
+{
+ "name": "superpowers",
+ "displayName": "Superpowers",
+ "version": "6.4.2",
+ "description": "Skills that make your coding agent work like a senior engineer: brainstorming, planning, test-driven development, systematic debugging, and code review.",
+ "logo": "assets/antigravity-logo.png",
+ "suggestedPrompts": [
+ "Let's brainstorm a new feature before writing any code",
+ "Help me systematically debug a failing test",
+ "Write an implementation plan for this change"
+ ],
+ "category": "Developer Tools",
+ "keywords": [
+ "skills",
+ "tdd",
+ "debugging",
+ "collaboration",
+ "best-practices",
+ "workflows"
+ ],
+ "author": {
+ "name": "Jesse Vincent",
+ "email": "jesse@fsck.com"
+ },
+ "homepage": "https://github.com/obra/superpowers",
+ "repository": "https://github.com/obra/superpowers",
+ "license": "MIT"
+}
+```
+
+The `description` and `suggestedPrompts` copy needs Jesse's approval before this commit. If he changes it, keep the description 120–160 characters.
+
+Create `rules/AGENTS.md` containing exactly one line:
+
+```
+@../skills/using-superpowers/SKILL.md
+```
+
+In `.version-bump.json`, add after the `.kimi-plugin/plugin.json` entry:
+
+```json
+ { "path": ".antigravity-plugin/plugin.json", "field": "version" },
+```
+
+- [ ] **Step 4: Run tests to verify they pass**
+
+Run: `bash tests/antigravity/test-plugin-manifest.sh && scripts/bump-version.sh --check && scripts/bump-version.sh --audit && bash tests/version-bump/test-bump-version.sh && scripts/lint-shell.sh tests/antigravity/test-plugin-manifest.sh`
+Expected: `PASS: Antigravity plugin manifest and bootstrap rule valid` (with the agy validate step running, since agy is installed here), version check reports all files at 6.4.2, audit finds no unlisted version strings, version-bump test passes, linter clean.
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add .antigravity-plugin/plugin.json rules/AGENTS.md .version-bump.json tests/antigravity/test-plugin-manifest.sh
+git commit -m "feat(antigravity): native plugin manifest with always-on bootstrap rule"
+```
+
+---
+
+### Task 3: Keep Antigravity-only files out of the Codex sync
+
+**Files:**
+- Modify: `scripts/sync-to-codex-plugin.sh` (the `EXCLUDES=(` array, ~line 45)
+- Test: `tests/codex-plugin-sync/test-sync-to-codex-plugin.sh`
+
+**Interfaces:**
+- Consumes: the paths `.antigravity-plugin/plugin.json`, `rules/AGENTS.md`, `assets/antigravity-logo.png`.
+
+- [ ] **Step 1: Write the failing test**
+
+In `tests/codex-plugin-sync/test-sync-to-codex-plugin.sh`:
+
+In `write_upstream_fixture`, add `"$repo/.antigravity-plugin"` and `"$repo/rules"` to the `mkdir -p` list. After the `.kimi-plugin/plugin.json` heredoc (~line 242), add:
+
+```bash
+ cat > "$repo/.antigravity-plugin/plugin.json" <<EOF
+{
+ "name": "superpowers",
+ "version": "$MANIFEST_VERSION"
+}
+EOF
+
+ printf '@../skills/using-superpowers/SKILL.md\n' > "$repo/rules/AGENTS.md"
+ printf 'antigravity png fixture\n' > "$repo/assets/antigravity-logo.png"
+```
+
+Add these three paths to that function's `git -C "$repo" add` list:
+
+```bash
+ .antigravity-plugin/plugin.json \
+ rules/AGENTS.md \
+ assets/antigravity-logo.png \
+```
+
+After the existing assertion `assert_not_contains "$preview_section" ".kimi-plugin/plugin.json" ...` (~line 659), add:
+
+```bash
+ assert_not_contains "$preview_section" ".antigravity-plugin/plugin.json" "Preview excludes Antigravity manifest from Codex sync"
+ assert_not_contains "$preview_section" "rules/AGENTS.md" "Preview excludes Antigravity bootstrap rule from Codex sync"
+ assert_not_contains "$preview_section" "assets/antigravity-logo.png" "Preview excludes Antigravity logo from Codex sync"
+```
+
+- [ ] **Step 2: Run test to verify it fails**
+
+Run: `bash tests/codex-plugin-sync/test-sync-to-codex-plugin.sh`
+Expected: the three new assertions FAIL (the files appear in the preview); the rest pass.
+
+- [ ] **Step 3: Add the exclusions**
+
+In `scripts/sync-to-codex-plugin.sh`, in `EXCLUDES=(`:
+
+After `"/.claude/"` (alphabetical among dotdirs), add:
+
+```bash
+ "/.antigravity-plugin/"
+```
+
+Under `# Directories not shipped by canonical Codex plugins`, add `"/rules/"` in alphabetical position (after `"/lib/"`):
+
+```bash
+ "/rules/"
+```
+
+Add a new group after the directories group:
+
+```bash
+
+ # Other harnesses' assets
+ "/assets/antigravity-logo.png"
+```
+
+- [ ] **Step 4: Run test to verify it passes**
+
+Run: `bash tests/codex-plugin-sync/test-sync-to-codex-plugin.sh && scripts/lint-shell.sh scripts/sync-to-codex-plugin.sh tests/codex-plugin-sync/test-sync-to-codex-plugin.sh`
+Expected: all assertions pass, including `assets/app-icon.png` and `assets/superpowers-small.svg` still included; linter clean.
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add scripts/sync-to-codex-plugin.sh tests/codex-plugin-sync/test-sync-to-codex-plugin.sh
+git commit -m "fix(codex-sync): exclude Antigravity manifest, rule, and logo"
+```
+
+---
+
+### Task 4: README and stale test comment
+
+**Files:**
+- Modify: `README.md:84-93` (the `### Antigravity` section)
+- Modify: `tests/antigravity/test-antigravity-tools.sh:1-10` (header comment)
+
+**Interfaces:** none.
+
+- [ ] **Step 1: Update the README section**
+
+Replace the body of `### Antigravity` (keep the heading) with:
+
+````markdown
+Install Superpowers as a plugin from this repository:
+
+```bash
+agy plugin install https://github.com/obra/superpowers
+```
+
+The plugin ships an always-on rule that loads the `using-superpowers` skill, so
+Superpowers is active from the first message. Reinstall with the same command to
+update.
+````
+
+- [ ] **Step 2: Fix the stale header comment**
+
+In `tests/antigravity/test-antigravity-tools.sh`, replace lines 2–7:
+
+```bash
+# Validate the Antigravity (agy) integration. agy installs the existing plugin
+# directly (`agy plugin install <repo-url>`): it loads the bundled skills and
+# runs the SessionStart hook for bootstrap, so there is no agy-specific scaffold
+# to test. What IS agy-specific is the tool mapping — subagent dispatch via
+# invoke_subagent (self/research types) and task tracking via a task artifact —
+# and SKILL.md pointing at it.
+```
+
+with:
+
+```bash
+# Validate the Antigravity (agy) tool mapping: subagent dispatch via
+# invoke_subagent (self/research types), task tracking via a task artifact, and
+# SKILL.md pointing at the mapping. The plugin manifest and bootstrap rule are
+# checked by test-plugin-manifest.sh.
+```
+
+- [ ] **Step 3: Run the Antigravity suite**
+
+Run: `bash tests/antigravity/run-tests.sh`
+Expected: all three tests pass, ending `=== All Antigravity tests passed ===`.
+
+- [ ] **Step 4: Commit**
+
+```bash
+git add README.md tests/antigravity/test-antigravity-tools.sh
+git commit -m "docs(antigravity): describe the always-on rule bootstrap"
+```
+
+---
+
+### Task 5: Live acceptance on agy
+
+No repo changes. This is the end-to-end proof required by AGENTS.md's "New Harness Support" section.
+
+**Files:** none (scratch only).
+
+**Interfaces:**
+- Consumes: the committed tree from Tasks 1–4.
+
+- [ ] **Step 1: Stage the committed tree and install it**
+
+Use the scratchpad directory (`$SCRATCH` below), never the repo:
+
+```bash
+mkdir -p "$SCRATCH/accept/superpowers"
+git archive HEAD | tar -x -C "$SCRATCH/accept/superpowers"
+agy plugin install "$SCRATCH/accept/superpowers"
+agy plugin list
+```
+
+Expected: install `[ok]`, skills processed, hooks skipped; `agy plugin list` shows `"source": "antigravity"`.
+
+- [ ] **Step 2: Run the acceptance prompt three times in fresh workspaces**
+
+For `n` in 1 2 3:
+
+```bash
+mkdir -p "$SCRATCH/accept/ws$n"
+cd "$SCRATCH/accept/ws$n"
+agy -p "Let's make a react todo list" --output-format stream-json --print-timeout 240s > out.jsonl 2> err.txt
+```
+
+For each run, list the tool steps:
+
+```bash
+python3 -I -c "
+import json
+for l in open('out.jsonl'):
+ e=json.loads(l); s=e.get('step_update') or {}
+ if s.get('state') in ('DONE','ERROR'):
+ p=(s.get('tool_info') or {}).get('parameters') or {}
+ print(s.get('step_index'), s.get('tool_name'), str(p.get('AbsolutePath') or p.get('TargetFile') or p.get('CommandLine') or '')[-90:])
+ if e.get('event')=='result': print('RESULT:', e['result'].get('response','')[:600])
+"
+```
+
+Pass criteria for each run: a `view_file` of `.../skills/using-superpowers/SKILL.md` and of `.../skills/brainstorming/SKILL.md` occur before any `write_to_file` outside the agy `brain/` directory, and no project files (`package.json`, `*.jsx`, `*.tsx`) exist in the workspace afterward. Record each run's tool sequence and the final response.
+
+Also confirm `grep -c 'failed to parse hooks' ~/.gemini/antigravity-cli/cli.log` did not increase across the runs.
+
+- [ ] **Step 3: Uninstall**
+
+```bash
+agy plugin uninstall superpowers
+agy plugin list
+```
+
+Expected: `No imported plugins.`
+
+- [ ] **Step 4: Report**
+
+If any run fails, stop and report to Jesse with the tool sequence; do not change the rule without his approval. If all pass, save the three transcripts' tool sequences for the PR description.
+
+---
+
+### Task 6: Porting guide (separate commit)
+
+**Files:**
+- Modify: `docs/porting-to-a-new-harness.md` (lines ~295, ~520-534, ~681, ~690-705, index table ~797-810)
+
+**Interfaces:** none.
+
+- [ ] **Step 1: Routing table row (~line 295)**
+
+Replace:
+
+```markdown
+| has a plugin install command and a manifest `contextFileName` (or equivalent) the installer keeps | C via the plugin installer | Antigravity (`.antigravity-plugin/` — `agy plugin install` ships a generated context file; verify the installer preserves it — Part 6) |
+```
+
+with:
+
+```markdown
+| loads always-on rule files shipped inside a plugin | C via a plugin rule | Antigravity (`.antigravity-plugin/plugin.json` + `rules/AGENTS.md`, a one-line `@` pointer to `using-superpowers` — Part 6) |
+```
+
+- [ ] **Step 2: "No `Skill` tool" case (~lines 527-532)**
+
+Replace the paragraph beginning `**For the bootstrap itself, prefer a declared context file (Part 6).**` with:
+
+```markdown
+ **For the bootstrap itself, prefer something the harness loads every
+ session (Part 6).** That's a declared context file where the manifest has a
+ `contextFileName`-style field, or an always-on rule where the plugin format
+ has rules. Antigravity uses a rule: `rules/AGENTS.md` holds one line,
+ `@../skills/using-superpowers/SKILL.md`. agy rewrites a rule-relative `@`
+ path to the absolute install path but does not inline the file; the model
+ reads it with `view_file`. agy does not substitute `${PLUGIN_ROOT}` in rules.
+ Point at `using-superpowers`; never copy it into the rule.
+```
+
+- [ ] **Step 3: Distribution table row (~line 681)**
+
+Replace:
+
+```markdown
+| Local installer (plugin install) | Antigravity (`agy`) | A small `install.sh` that runs the harness's own `agy plugin install` against a staging dir holding the manifest, the skills, and a generated `contextFileName` context file (the bootstrap). Everything arrives through the install mechanism — *not* by editing the user's config (see below). |
+```
+
+with:
+
+```markdown
+| Git-URL plugin install + marketplace | Antigravity (`agy`) | Users run `agy plugin install https://github.com/obra/superpowers`. agy reads `.antigravity-plugin/plugin.json`, whose Marketplace fields (`displayName`, `logo`, `suggestedPrompts`, `version`, `author`) also drive the Antigravity Marketplace listing. Without that manifest, agy falls back to importing `gemini-extension.json`. |
+```
+
+- [ ] **Step 4: Installer-stripping section (~lines 690-705)**
+
+In the bullet beginning `**Ship a context file the manifest declares.**`, delete the sentences from `This is what` through `unrecognized.` (the `.antigravity-plugin/install.sh` / `ANTIGRAVITY.md` example), and replace them with:
+
+```markdown
+ **Verify with a marker** that the installer keeps the file and the
+ harness loads it: a file the manifest doesn't declare can be stripped as
+ unrecognized.
+```
+
+Immediately after that bullet, add a new bullet:
+
+```markdown
+ - **Or ship an always-on rule, if the plugin format has rules.** Antigravity
+ loads `rules/AGENTS.md` from an installed plugin every session; a one-line
+ `@` pointer there bootstraps `using-superpowers`. Run a marker test to
+ confirm what the harness does with `@` paths in rules — agy rewrites them
+ to absolute paths without inlining them.
+```
+
+- [ ] **Step 5: Harness index row (~line 799)**
+
+The table is alphabetical. Add this as the first data row, directly above `| Claude Code | ...`:
+
+```markdown
+| Antigravity (`agy`) | `.antigravity-plugin/plugin.json` + `rules/AGENTS.md` | always-on plugin rule `@`-points at `using-superpowers` (no session-start hook event exists) | `references/antigravity-tools.md` | `tests/antigravity/` | `agy plugin install` git URL; Antigravity Marketplace |
+```
+
+- [ ] **Step 6: Check nothing else references the phantom files**
+
+Run: `grep -rn 'install.sh\|ANTIGRAVITY.md\|contextFileName' docs/porting-to-a-new-harness.md`
+Expected: no remaining line ties `install.sh` or `ANTIGRAVITY.md` to Antigravity. Remaining `contextFileName` mentions must be generic or about Gemini.
+
+- [ ] **Step 7: Commit (on its own)**
+
+```bash
+git add docs/porting-to-a-new-harness.md
+git commit -m "docs(porting): describe Antigravity's rule bootstrap, drop phantom installer"
+```
diff --git a/docs/superpowers/specs/2026-10-05-brainstorming-rebuild-design.md b/docs/superpowers/specs/2026-10-05-brainstorming-rebuild-design.md
new file mode 100644
index 0000000..527a298
--- /dev/null
+++ b/docs/superpowers/specs/2026-10-05-brainstorming-rebuild-design.md
@@ -0,0 +1,165 @@
+# Brainstorming rebuild: intent
+
+## Why this exists
+
+Coding agents are very good at building. They build what they believe the
+human wants, and they rarely ask enough or look around enough before they
+start. The brainstorming skill exists to close that gap: draw the human's
+real intent out of them, including the parts they haven't worked out yet,
+before anything gets built.
+
+The original superpowers prompt did this well in about forty words: "I've
+got an idea in my head. I'd like you to ask me lots of questions about it.
+As you think you understand what I really want, describe it to me in
+chunks of about 200-300 words. Once we're dialed in, write out an informal
+spec." The current skill has grown to about 2,600 words, almost all of it
+about routing (spike / bounded / architectural), approval gates, and the
+spec-to-plan handoff. Intent got squeezed into one paragraph whose default
+move is "ask one focused question about purpose", which doesn't work on
+people.
+
+This is a rewrite from scratch, not an edit.
+
+## Goals
+
+- The agent understands the *why* behind anything non-trivial, because an
+ agent that knows the why makes the hundred unstated decisions well.
+- The human ends up thinking through what they actually want. Good
+ questions help them flesh out an idea they haven't finished forming.
+- Works for any domain: software, a talk, a renovation, a small business.
+- Ends with a document a talented builder in that domain could plan from
+ without going back to the human.
+
+## How a session should feel
+
+**Start with a private check.** The agent asks itself: what do I actually
+know about what they want, and why? If the answer is "nearly everything"
+("make the icon cornflower blue"), it confirms and moves on. If anything
+non-trivial is missing, it starts asking.
+
+**Ask, one question at a time.** Plain language by default, pitched just a
+little above the human's level. Questions should help the human think, not
+quiz them.
+
+- Get them describing first. Open questions beat menus because menus
+ garden-path people toward the agent's assumptions.
+- Offer a menu only when they're struggling.
+- If they say "just guess" or "what do you think", always propose.
+- Ground questions in real moments ("walk me through the last time...")
+ and concrete tradeoffs ("if it could only do one of these well...").
+- Ask about prior art and current state: what exists elsewhere, what
+ exists now.
+- Ask which parts of the *how* they want to decide, and which they'd
+ rather hand to the builder.
+
+The ground to cover, loosely in order: what kind of thing this is, what
+makes it special, goals, non-goals, anti-goals, the details they care
+about, and what they want to delegate. These are territory, not a script.
+The agent never reads them out as literal questions.
+
+**Offer recon.** Once there's some grounding, the agent offers to go look:
+the codebase or project, the human's own files and data, or the web. The
+human decides whether it goes.
+
+**Show, don't tell, once things get concrete.** Use the visual companion
+for diagrams, mockups, and throwaway prototypes where seeing beats reading.
+
+**Spike to feel things out.** Agentic development is waterfall, but very,
+very fast. A quick throwaway build is often the cheapest way to find out
+what the human wants or whether something works, and the agent should
+offer one when it would help. When the human just wants to spike, the
+agent gets out of the way. Spikes have no tests or minimal ones, aren't
+bulletproof, and don't go through the full plan, implementation, and
+review process. What a spike teaches feeds back into the conversation.
+
+**Think wide internally.** Before proposing anything, the agent generates
+several ideas and discards the weak ones. It shows the human the comparison
+only when that helps them decide.
+
+**Play it back.** Once the agent thinks it understands, it describes its
+understanding in chunks of roughly 200-300 words and adjusts after each.
+
+## What it produces
+
+A plain written document covering:
+
+- intent and the why
+- goals, non-goals, anti-goals
+- constraints
+- the parts of the how the human cares about, as they decided them
+- what's explicitly left to the builder
+
+**Done test:** before the human reviews it, a fresh subagent playing a
+talented builder in the domain reads the document and lists what it would
+still need to ask. Those questions go back to the human. The document is
+done when the builder has nothing important left to ask.
+
+**Sizing the work.** Once intent is clear, the agent sorts the work into
+one of three sizes, says which out loud, and lets the human override:
+
+- **A quick, clear task.** Intent was clear from the start. Confirm and do it.
+- **A small change.** The full description lives in chat. No document file.
+- **A project with a written design.** The full description is the
+ document above, followed by a full plan (for software, the writing-plans
+ skill).
+
+This is where the old spike / bounded / architectural choice lives now:
+after intent, not before it, with plain names.
+
+**Approval.** Whatever the size, the human approves the full description
+before anything gets built: in chat for a small change, by reading the
+document for a project.
+
+**Opting out.** Early in the session, the agent mentions once that if the
+human doesn't want to go through this process, they can just say so.
+
+## Non-goals
+
+- Designing architecture the human didn't ask to decide. The doc records
+ the how the human cares about; the rest belongs to the builder.
+- Being software-specific.
+- Ceremony for trivial requests.
+
+## Anti-goals
+
+- Interrogation: a checklist of questions read at the human.
+- Garden-pathing: steering the human into the agent's preferred idea with
+ leading menus.
+- "What are you actually trying to do?" style questions that ask the human
+ to do the agent's thinking.
+- Small asks inflating into multi-phase projects.
+- Building before the human agrees with the playback.
+
+## Decisions
+
+- The skill keeps the name `brainstorming`. Other skills and the README
+ point at it.
+- The visual companion and its server scripts stay as they are.
+- `spec-document-reviewer-prompt.md` is replaced by the builder-check prompt.
+- The agent screens the builder check's questions before bringing them to
+ the human: it answers what it can from context and drops questions about
+ delegated details. Without a subagent tool, it runs the check itself.
+- A short hard gate stays: nothing gets built until the human approves the
+ full description. One exception: a spike the human said yes to. It stays
+ labeled throwaway. Keeping what it produced is a new request and goes
+ through the gate.
+- The builder check runs only on the written document. Small changes stay
+ in chat.
+- The trigger description keeps the strong "use before any creative work"
+ wording. The opening check keeps trivial asks cheap.
+- The todo-list example from the old skill goes. The evals that encode the
+ old routing (`brainstorming-todo-purpose-discovery`,
+ `brainstorming-todo-shared-intent`) get rewritten to match.
+- Software projects keep `docs/superpowers/specs/YYYY-MM-DD-<topic>-design.md`
+ as the default location for the document.
+
+## Left to the builder
+
+- Section structure and wording of the skill.
+- Exact prompts for the builder check.
+- Where non-software documents get saved, absent a human preference.
+
+## Will be tuned after first use
+
+Jesse expects to tune the skill after real sessions. Ship something small
+and sharp rather than complete.
diff --git a/docs/superpowers/specs/2026-10-06-antigravity-marketplace-design.md b/docs/superpowers/specs/2026-10-06-antigravity-marketplace-design.md
new file mode 100644
index 0000000..aab6ad2
--- /dev/null
+++ b/docs/superpowers/specs/2026-10-06-antigravity-marketplace-design.md
@@ -0,0 +1,181 @@
+# Antigravity Marketplace plugin
+
+## Goal
+
+List Superpowers in the Google Antigravity plugin Marketplace, as part of a
+partnership with Google. That requires a native Antigravity plugin manifest with
+the Marketplace presentation fields, a logo, and a session bootstrap that works
+on the native plugin path.
+
+Source: "Antigravity Plugin Marketplace Publishing Guide" (PDF from Google), plus
+probes against `agy` 1.3.1 recorded below.
+
+## Current state (agy 1.3.1)
+
+- `agy plugin install https://github.com/obra/superpowers` succeeds, but only
+ through agy's Gemini-extension fallback: `agy plugin list` reports
+ `"source": "gemini-cli"`. The bootstrap rides `GEMINI.md`'s `@` lines, which
+ the model treats as hints and follows with `view_file`. The acceptance test
+ passes on this path.
+- agy copies our Claude-format `hooks/hooks.json` to the install root as
+ `hooks.json` and fails to parse it on every session:
+ `invalid hook "hooks": command hook must specify 'command'`.
+- `agy plugin validate .` on the repo fails: `missing plugin.json`.
+
+## Probe findings (agy 1.3.1)
+
+Each probe installed a throwaway plugin, ran `agy -p`, and uninstalled it.
+
+1. agy's hook events are `PreToolUse`, `PostToolUse`, `PreInvocation`,
+ `PostInvocation`, and `Stop`. There is no `SessionStart`. agy's embedded docs
+ use named top-level hooks (`{"<name>": {"PreToolUse": [...]}}`), which differs
+ from the PDF's `{"hooks": {...}}` example.
+2. `rules/AGENTS.md` in a plugin loads as an always-on rule on every session.
+3. In a rule, an `@` path relative to the rule file is rewritten to an absolute
+ install path (`@../skills/x/SKILL.md` becomes
+ `@/Users/<u>/.gemini/config/plugins/<plugin>/skills/x/SKILL.md`). Its content
+ is not inlined. `${PLUGIN_ROOT}` is not substituted in rules. A path that does
+ not resolve relative to the rule file is left as written.
+4. With `.antigravity-plugin/plugin.json` present, agy installs the plugin as
+ `"source": "antigravity"`, finds all 15 skills, and skips hooks (no root
+ `hooks.json`), so the parse warning goes away.
+5. A staged copy of the repo with the native manifest and a one-line
+ `rules/AGENTS.md` (`@../skills/using-superpowers/SKILL.md`) passed the
+ acceptance test: the model read `using-superpowers`, then
+ `antigravity-tools.md`, then `brainstorming`, and replied
+ "Using superpowers:brainstorming…" with a clarifying question. No code.
+6. The repo-root `AGENTS.md` (contributor guidelines) is copied into the install
+ but is not loaded as a rule. Only `rules/AGENTS.md` is.
+
+## Design
+
+### 1. Native manifest: `.antigravity-plugin/plugin.json`
+
+The guide allows the manifest at `.antigravity-plugin/plugin.json`, which
+matches our other harness dotdirs. Fields:
+
+| Field | Value |
+|---|---|
+| `name` | `superpowers` |
+| `displayName` | `Superpowers` |
+| `version` | current release version, maintained by `.version-bump.json` |
+| `description` | `Make your coding agent a better engineer` (Jesse's copy; shorter than the guide's recommended 120–160, at most 160) |
+| `logo` | `assets/antigravity-logo.png` |
+| `suggestedPrompts` | `I've got an idea for something I'd like to build`, `Let's figure out why this broke` (Jesse's copy) |
+| `category` | `Developer Tools` |
+| `keywords` | lowercase, matching `.claude-plugin/plugin.json` keywords |
+| `author` | `{ "name": "Jesse Vincent", "email": "jesse@fsck.com" }`, matching `.claude-plugin/plugin.json` |
+| `homepage`, `repository` | `https://github.com/obra/superpowers` |
+| `license` | `MIT` |
+
+No `skills` or `mcpServers` fields: the defaults (`skills/`, no MCP config) are
+what we want, and probe 4 confirmed default discovery finds all skills.
+
+
+### 2. Bootstrap: skill discovery, no extra files
+
+agy lists each installed skill's description, and `using-superpowers`'
+"Use when starting any conversation" gets the model to load it. The plugin
+ships no `rules/` and no `hooks.json`.
+
+This replaced a first design, a one-line `rules/AGENTS.md` pointer, after the
+final review found that Cursor also loads any `rules/*.md` a plugin ships from
+the same repo root. Alternatives probed on agy 1.3.1 and rejected:
+
+- A `PreInvocation` hook. It runs before every model call and `hooks.json`
+ must sit at the plugin root. An `ephemeralMessage` is dropped on the next
+ call; a `userMessage` persists, and gating it on `invocationNum == 0` and
+ `initialNumSteps == 1` injects exactly once per conversation, but agy still
+ starts the hook process on every call.
+- No manifest field relocates `hooks.json` or `rules/`.
+
+Verified with no bootstrap file, 12/12 runs: "Let's make a react todo list"
+(3) and "add a settings page" (3) load brainstorming before any code; "this
+test is failing, can you fix it?" (3) loads systematic-debugging before any
+edit; a react-todo second turn after an unrelated first turn (3) loads
+brainstorming. Model: Gemini 3.8 Flash. The risk is that triggering depends on
+the model honoring a skill description; the once-per-conversation hook is the
+fallback if it slips.
+
+### 3. Logo: `assets/antigravity-logo.png`
+
+512×512 PNG, transparent background. A white rounded square (inset 31px,
+corner radius 100) holds the `assets/superpowers-small.svg` mark in `#1a1a1a`,
+scaled to about 70% of the square's width and centered. No border; on a light
+theme it reads as a bare mark on white, which is acceptable.
+
+`scripts/render-antigravity-logo.sh` composes the SVG from
+`superpowers-small.svg` and rasterizes it with `rsvg-convert`. It is the only way
+the PNG gets regenerated; it has help text and fails clearly when
+`rsvg-convert` is missing.
+
+### 4. Version bumps
+
+Add `{ "path": ".antigravity-plugin/plugin.json", "field": "version" }` to
+`.version-bump.json`.
+
+### 5. Codex sync
+
+Add `/.antigravity-plugin/` and `/assets/antigravity-logo.png` to
+`EXCLUDES` in `scripts/sync-to-codex-plugin.sh`, and cover them in
+`tests/codex-plugin-sync/test-sync-to-codex-plugin.sh`.
+
+### 6. README
+
+The Antigravity install command stays
+`agy plugin install https://github.com/obra/superpowers`. The prose changes from
+"runs the plugin's session-start hook" to describing skill discovery. Add the
+Marketplace route once it exists; until then, no claim about it.
+
+### 7. Tests: `tests/antigravity/`
+
+- `test-plugin-manifest.sh` (CI-safe, mirrors `tests/kimi/test-plugin-manifest.sh`):
+ - manifest parses; `name` matches the kebab-case pattern and equals
+ `superpowers`;
+ - every Marketplace-required field is present and non-empty: `name`,
+ `description`, `displayName`, `logo`, `suggestedPrompts` (1–3 non-empty
+ strings), `version`, `author`;
+ - `description` is at most 160 characters;
+ - `version` equals `.claude-plugin/plugin.json`'s version;
+ - `logo` file exists, is a PNG, and is square and at least 128×128;
+ - `.version-bump.json` lists the manifest;
+ - `using-superpowers`' description still says "Use when starting any
+ conversation", which the bootstrap relies on;
+ - no root `plugin.json`, `hooks.json`, or `rules/` exists.
+- When `agy` is on `PATH`, also run `agy plugin validate` on the repo and
+ require `[ok]` with skills processed.
+- Update the header comment of `test-antigravity-tools.sh`, which still says agy
+ runs the SessionStart hook.
+
+Live acceptance (not in CI): install the branch's tree into agy, run
+"Let's make a react todo list" at least three times in clean workspaces, and
+require that brainstorming triggers before any code each time. Uninstall
+afterward.
+
+### 8. Porting guide: separate commit
+
+`docs/porting-to-a-new-harness.md` describes `.antigravity-plugin/install.sh`
+and a generated `ANTIGRAVITY.md` that do not exist. Fix it in its own commit:
+
+- Routing table row: Antigravity uses the surfaced skill index.
+- The "no `Skill` tool" section: replace the `contextFileName` advice for
+ Antigravity with the skill-index bootstrap, and record the hook and rule
+ findings (no session-start event, `PreInvocation` per call, no
+ `${PLUGIN_ROOT}` in hooks, shared plugin roots leak `rules/` into Cursor).
+- The distribution table: Antigravity installs from a git URL (`agy plugin
+ install <url>`) and lists in its Marketplace.
+- The installer-stripping section: drop the `install.sh` / `ANTIGRAVITY.md`
+ example.
+- The harness index table has no Antigravity row; add one (manifest,
+ bootstrap, tool mapping, tests, install).
+
+## Out of scope
+
+- Marketplace submission mechanics. The guide does not describe how to submit;
+ that goes through Jesse's Google contact.
+- Antigravity 2.0 and the IDE. Not installed here, so not verified. The README
+ makes no claims about them.
+- Open PR #2350, which copies `using-superpowers` into a generated rule. Jesse
+ decides how to respond after this lands; I draft the reply.
+- `.hermes-plugin/` and `.muse-plugin/` are missing from the Codex sync
+ excludes. Unrelated; noted for a separate fix.
diff --git a/docs/windows/polyglot-hooks.md b/docs/windows/polyglot-hooks.md
index d1bcb84..3da01ae 100644
--- a/docs/windows/polyglot-hooks.md
+++ b/docs/windows/polyglot-hooks.md
@@ -77,12 +77,19 @@ afterward.
1. The batch section validates the script name and resolves the hook directory
from the dispatcher's own location.
-2. It tries bash in three places:
+2. It tries bash in four places, in order:
- `C:\Program Files\Git\bin\bash.exe`
- `C:\Program Files (x86)\Git\bin\bash.exe`
- - `bash` on `PATH` (MSYS2, Cygwin, or a non-default Git install)
+ - `%LOCALAPPDATA%\Programs\Git\bin\bash.exe` (a per-user Git for Windows
+ install), only when `LOCALAPPDATA` is set
+ - `bash` on `PATH` (MSYS2, Cygwin, or a non-default Git install), found by
+ running `%SystemRoot%\System32\where.exe $PATH:bash`, so neither `where`
+ nor `bash` is taken from the current directory. The WSL launchers
+ (`bash.exe` in `System32`, `Sysnative`, or
+ `%LOCALAPPDATA%\Microsoft\WindowsApps`) and extensionless matches are
+ skipped, since the launchers fail when no Linux distro is installed.
3. If bash is found, it runs the named extensionless hook script from the hooks
- directory.
+ directory and exits with the script's exit code.
4. If no bash is found, the dispatcher exits `0` silently — the plugin
continues working, it just skips the hook.
5. `exit /b` stops CMD before it reaches the Unix section.
@@ -142,7 +149,7 @@ escape_for_json() {
### "bash is not recognized"
-CMD couldn't find bash in any of the three locations the dispatcher tries. The dispatcher exits silently (0) rather than erroring, so the hook is skipped. Install Git for Windows at the standard path or ensure `bash` is on `PATH`.
+CMD couldn't find bash in any of the four locations the dispatcher tries. The dispatcher exits silently (0) rather than erroring, so the hook is skipped. Install Git for Windows (system-wide or per-user) or ensure a non-WSL `bash` is on `PATH`.
### Hook runs on Unix but does nothing on Windows