fix(antigravity): inline bootstrap in always-on rule

aimansour · Sep 20, 2026 · Sep 20, 2026 · Sep 20, 2026 · Sep 20, 2026 · Sep 20, 2026
commit 4c6747f1c317f9740b7f2cc1a23848ffaa206994
diff --git a/README.md b/README.md
@@ -89,10 +89,10 @@ Install Superpowers as a plugin from this repository:
 agy plugin install https://github.com/obra/superpowers
 ```
 
-Antigravity CLI loads the plugin's always-on rule, which includes the
-`using-superpowers` bootstrap and Antigravity tool mapping from the installed
-skills. This makes Superpowers active from the first message. Reinstall with the
-same command to update.
+Antigravity CLI loads the plugin's always-on rule, which contains the
+`using-superpowers` bootstrap and Antigravity tool mapping. The rule is generated
+from their canonical files so both reach the model from the first message.
+Reinstall with the same command to update.
 
 ### Codex App
 

diff --git a/docs/porting-to-a-new-harness.md b/docs/porting-to-a-new-harness.md
@@ -292,7 +292,7 @@ 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`) |
-| installs always-on rules as plugin components | C via the plugin installer | Antigravity CLI (`plugin.json` + `rules/superpowers.md`; verify rule activation in a clean session — Part 6) |
+| installs always-on rules as plugin components | C via the plugin installer | Antigravity CLI (`plugin.json` + generated `rules/superpowers.md`; verify inline content in a clean session — Part 6) |
 
 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).
@@ -527,9 +527,10 @@ honors the rule rather than breaking it. Distinguish three cases:
 
    **For the bootstrap itself, use an installable always-on surface (Part 6).**
    Antigravity CLI installs `rules/superpowers.md`, whose `trigger: always_on`
-   rule includes the `using-superpowers` content and tool mapping. Verify the
-   includes reach the model in a clean session; simply copying the rule is not
-   proof that it activates.
+   rule contains the `using-superpowers` content and tool mapping. Generate the
+   rule from their canonical files with `scripts/generate-antigravity-rule.sh`.
+   Verify a unique marker in each inlined source reaches the model without a
+   file-read tool call; an `@` reference may only prompt it to read a file later.
 
    **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 +679,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 CLI (`agy`) | `agy plugin install` installs the repository's root `plugin.json`, `skills/`, and `rules/superpowers.md`. The always-on rule includes the bootstrap and tool mapping through the plugin mechanism. |
+| Local installer (plugin install) | Antigravity CLI (`agy`) | `agy plugin install` installs the repository's root `plugin.json`, `skills/`, and generated `rules/superpowers.md`. The always-on rule carries the bootstrap and tool mapping through the plugin mechanism. |
 
 Then:
 
@@ -698,10 +699,11 @@ Then:
     **Verify with a marker** that the installer keeps the file and the harness
     loads it; a successful install alone does not prove activation.
   - **Ship an always-on plugin rule when the harness supports it.** Antigravity
-    CLI installs `rules/superpowers.md` with `trigger: always_on`. Relative
-    `@`-includes load the installed bootstrap and tool mapping without copying
-    either body or editing the user's global rules. Verify both includes and the
-    first-turn skill trigger in a clean session.
+    CLI installs `rules/superpowers.md` with `trigger: always_on`. A 2.0 marker
+    test showed that the rule's own text was present but relative `@` references
+    were not expanded into context. Generate the rule with the bootstrap and
+    mapping inlined from their canonical files, and test first-turn activation
+    without editing the user's global rules.
   - **Otherwise lean on the installed `using-superpowers` skill itself.** If the
     harness surfaces each installed skill's name + description at session start,
     the `using-superpowers` description ("Use when starting any conversation…")
@@ -801,7 +803,7 @@ Use this as the live index; when in doubt, read the files, not this table.
 | 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 |
 | Copilot CLI | (shares Claude Code hook path; `COPILOT_CLI` env) | shell hook → `hooks/session-start` (`additionalContext`) | none needed (Claude Code–compatible tool surface) | `tests/hooks/` | — |
 | Gemini CLI | `gemini-extension.json` + `GEMINI.md` | instructions file `@`-includes bootstrap + mapping | `references/gemini-tools.md` | — | `gemini extensions install` |
-| Antigravity CLI | root `plugin.json` + `rules/superpowers.md` | installed always-on rule `@`-includes bootstrap + mapping | `references/antigravity-tools.md` | `tests/antigravity/` + clean-session acceptance | `agy plugin install` |
+| Antigravity CLI | root `plugin.json` + generated `rules/superpowers.md` | installed always-on rule inlines bootstrap + mapping | `references/antigravity-tools.md` | `tests/antigravity/` + clean-session acceptance | `agy plugin install` |
 | Kimi Code | `.kimi-plugin/plugin.json` | manifest `sessionStart.skill` loads `using-superpowers` | inline `skillInstructions` in manifest | `tests/kimi/` | marketplace or `/plugins install` GitHub URL |
 | OpenCode | `.opencode/plugins/superpowers.js` (root `package.json` `main` for package installs; root `index.js` re-export for the V2 directory form) | in-process: `config` hook registers skills dir; `experimental.chat.messages.transform` (V1) / `session.hook("context")` (V2) injects user message | inline in `superpowers.js` | `tests/opencode/` | `opencode.json` `plugin` (V1) / `plugins` (V2) git URL |
 | pi | `.pi/extensions/superpowers.ts` | in-process: `resources_discover` registers skills; `context` event injects user message; lifecycle-flag + compaction-aware | `piToolMapping()` inline **and** `references/pi-tools.md` | `tests/pi/` | repo-root `package.json` fields |

diff --git a/rules/superpowers.md b/rules/superpowers.md
@@ -3,5 +3,98 @@ trigger: always_on
 description: Load Superpowers at the start of every Antigravity session
 ---
 
-@../skills/using-superpowers/SKILL.md
-@../skills/using-superpowers/references/antigravity-tools.md
+<!-- Generated by scripts/generate-antigravity-rule.sh. Do not edit directly. -->
+
+The Superpowers bootstrap and Antigravity tool mapping are already loaded below.
+Do not reopen those two files merely to load them. Read other skills when needed.
+
+---
+name: using-superpowers
+description: Use when starting any conversation - establishes how to find and use skills, requiring skill invocation before ANY response including clarifying questions
+---
+
+<SUBAGENT-STOP>
+If you were dispatched as a subagent to execute a specific task, ignore this skill.
+</SUBAGENT-STOP>
+
+<EXTREMELY-IMPORTANT>
+If you think there is even a 1% chance a skill might apply to what you are doing, you ABSOLUTELY MUST invoke the skill.
+
+IF A SKILL APPLIES TO YOUR TASK, YOU DO NOT HAVE A CHOICE. YOU MUST USE IT.
+
+This is not negotiable. You cannot rationalize your way out of this.
+</EXTREMELY-IMPORTANT>
+
+## The Rule
+
+**Invoke relevant or requested skills BEFORE any response or action** — including clarifying questions, exploring the codebase, or checking files. If it turns out wrong for the situation, you don't have to use it.
+
+**Before entering plan mode:** if you haven't already brainstormed, invoke the brainstorming skill first.
+
+Then announce "Using [skill] to [purpose]" and follow the skill exactly. If it has a checklist, create a todo per item.
+
+## Skill Priority
+
+When multiple skills apply, process skills come first — they set the approach, then implementation skills (frontend-design, etc.) carry it out. Brainstorming and systematic-debugging are Superpowers' most common process skills, but the rule holds for any of them.
+
+- "Let's build X" → superpowers:brainstorming first, then implementation skills.
+- "Fix this bug" → superpowers:systematic-debugging first, then domain skills.
+
+## Red Flags
+
+These thoughts mean STOP—you're rationalizing:
+
+| Thought | Reality |
+|---------|---------|
+| "This is just a simple question" | Questions are tasks. Check for skills. |
+| "I need more context first" | Skill check comes BEFORE clarifying questions. |
+| "Let me explore the codebase first" | Skills tell you HOW to explore. Check first. |
+| "I can check git/files quickly" | Files lack conversation context. Check for skills. |
+| "Let me gather information first" | Skills tell you HOW to gather information. |
+| "This doesn't need a formal skill" | If a skill exists, use it. |
+| "I remember this skill" | Skills evolve. Read current version. |
+| "This doesn't count as a task" | Action = task. Check for skills. |
+| "The skill is overkill" | Simple things become complex. Use it. |
+| "I'll just do this one thing first" | Check BEFORE doing anything. |
+| "This feels productive" | Undisciplined action wastes time. Skills prevent this. |
+| "I know what that means" | Knowing the concept ≠ using the skill. Invoke it. |
+
+## Platform Adaptation
+
+If your harness appears here, read its reference file for special instructions:
+
+- Claude Code: `references/claude-code-tools.md`
+- Codex: `references/codex-tools.md`
+- Pi: `references/pi-tools.md`
+- Antigravity: `references/antigravity-tools.md`
+- Hermes Agent: `references/hermes-tools.md`
+- Muse: `references/muse-tools.md`
+
+## User Instructions
+
+User instructions (CLAUDE.md, AGENTS.md, GEMINI.md, etc, direct requests) take precedence over skills, which in turn override default behavior. Only skip skill workflows or instructions when your human partner has explicitly told you to.
+
+
+# Antigravity CLI (`agy`) Tool Mapping
+
+Skills speak in actions ("dispatch a subagent", "create a todo", "read a file"). On the Antigravity CLI (`agy`) these resolve to the tools below.
+
+| Action skills request | Antigravity CLI equivalent |
+|----------------------|----------------------|
+| Dispatch a subagent (`Subagent (general-purpose):` template) | `invoke_subagent` with a built-in `TypeName` — `self` for full-capability work, `research` for read-only |
+| Task tracking ("create a todo", "mark complete") | a **task artifact** — `write_to_file` with `IsArtifact: true` and `ArtifactType: "task"` (see [Task tracking](#task-tracking)). **Not** `manage_task`, which manages background processes. |
+
+## Task tracking
+
+Antigravity has **no todo tool** (`manage_task` manages background
+processes — `list`/`kill`/`status`/`send_input` — it is *not* a checklist). When a
+skill says to create a todo list or track tasks, maintain a **task artifact**: a
+markdown checklist saved with `write_to_file` (`IsArtifact: true`,
+`ArtifactMetadata.ArtifactType: "task"`), edited with `replace_file_content` /
+`multi_replace_file_content` as you go.
+
+At the start of any multi-step task, create the task artifact listing every step of
+your plan. As you complete each step, edit the artifact to mark it done (`- [x]`).
+If the plan changes, update the checklist. Keep it current — it is your source of
+truth for what remains; once the conversation gets long, re-read it before starting
+each step.
diff --git a/scripts/generate-antigravity-rule.sh b/scripts/generate-antigravity-rule.sh
@@ -0,0 +1,24 @@
+#!/usr/bin/env bash
+# Render Antigravity's always-on rule from the canonical bootstrap and tool map.
+set -euo pipefail
+
+REPO_ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+OUTPUT="${1:-$REPO_ROOT/rules/superpowers.md}"
+
+{
+  cat <<'HEADER'
+---
+trigger: always_on
+description: Load Superpowers at the start of every Antigravity session
+---
+
+<!-- Generated by scripts/generate-antigravity-rule.sh. Do not edit directly. -->
+
+The Superpowers bootstrap and Antigravity tool mapping are already loaded below.
+Do not reopen those two files merely to load them. Read other skills when needed.
+
+HEADER
+  cat "$REPO_ROOT/skills/using-superpowers/SKILL.md"
+  printf '\n\n'
+  cat "$REPO_ROOT/skills/using-superpowers/references/antigravity-tools.md"
+} > "$OUTPUT"
diff --git a/tests/antigravity/test-plugin-install.sh b/tests/antigravity/test-plugin-install.sh
@@ -18,16 +18,31 @@ grep -q '^trigger: always_on$' "$REPO_ROOT/rules/superpowers.md" || {
   echo "FAIL: Antigravity bootstrap rule is not always on" >&2
   exit 1
 }
+rule_content="$(cat "$REPO_ROOT/rules/superpowers.md")"
 for relative_path in \
   ../skills/using-superpowers/SKILL.md \
   ../skills/using-superpowers/references/antigravity-tools.md; do
   included_file="$REPO_ROOT/rules/$relative_path"
-  test -f "$included_file" || { echo "FAIL: bootstrap include target is missing: $included_file" >&2; exit 1; }
-  grep -Fxq "@$relative_path" "$REPO_ROOT/rules/superpowers.md" || {
-    echo "FAIL: bootstrap rule does not include $included_file" >&2
+  test -f "$included_file" || { echo "FAIL: bootstrap source is missing: $included_file" >&2; exit 1; }
+  source_content="$(cat "$included_file")"
+  if [[ "$rule_content" != *"$source_content"* ]]; then
+    echo "FAIL: bootstrap rule does not inline $included_file" >&2
     exit 1
-  }
+  fi
 done
+if grep -q '^@\.\./skills/using-superpowers/' "$REPO_ROOT/rules/superpowers.md"; then
+  echo "FAIL: bootstrap rule still relies on lazy @ references" >&2
+  exit 1
+fi
+if [ "$(wc -c < "$REPO_ROOT/rules/superpowers.md")" -gt 12000 ]; then
+  echo "FAIL: Antigravity bootstrap rule exceeds the documented size limit" >&2
+  exit 1
+fi
+if ! cmp -s "$REPO_ROOT/rules/superpowers.md" \
+    <(bash "$REPO_ROOT/scripts/generate-antigravity-rule.sh" /dev/stdout); then
+  echo "FAIL: Antigravity bootstrap rule differs from its generated source" >&2
+  exit 1
+fi
 
 if [ -z "$AGY" ]; then
   AGY="$(command -v agy || true)"
@@ -66,6 +81,10 @@ done
 test -n "$INSTALLED" || { echo "FAIL: agy did not install the plugin in a supported profile path" >&2; exit 1; }
 test -f "$INSTALLED/plugin.json"
 test -f "$INSTALLED/rules/superpowers.md"
+cmp -s "$INSTALLED/rules/superpowers.md" "$REPO_ROOT/rules/superpowers.md" || {
+  echo "FAIL: agy changed the generated bootstrap rule during installation" >&2
+  exit 1
+}
 test -f "$INSTALLED/skills/using-superpowers/SKILL.md"
 test -f "$INSTALLED/skills/using-superpowers/references/antigravity-tools.md"
 test -f "$INSTALLED/skills/brainstorming/SKILL.md"