From da00e59958c16f0667f0cec2d8b5c861eaad81f4 Mon Sep 17 00:00:00 2001 From: Jesse Vincent Date: Mon, 1 Jun 2026 10:18:28 -0700 Subject: [PATCH] feat: add Antigravity CLI (agy) support MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Antigravity (Google's `agy` CLI) installs the existing Superpowers plugin directly: agy plugin install https://github.com/obra/superpowers agy imports the bundled skills and runs the plugin's SessionStart hook, so using-superpowers bootstraps from the first message — verified on agy 1.0.3: a fresh session given "Let's make a react todo list" auto-triggers the brainstorming skill instead of writing code. agy discovers skills natively and, having no Skill tool, loads them by reading SKILL.md with view_file. No scaffold, installer, or generated context file is needed. This adds only: - README.md: an Antigravity install section + Quickstart link - skills/using-superpowers/SKILL.md: reference to the agy tool mapping - skills/using-superpowers/references/antigravity-tools.md: action->tool mapping for agy (view_file, write_to_file, invoke_subagent, manage_task, and skill loading via view_file on SKILL.md) - tests/antigravity/: structural test for the tool mapping, mirroring tests/pi/ --- README.md | 13 ++- skills/using-superpowers/SKILL.md | 2 +- .../references/antigravity-tools.md | 96 +++++++++++++++++++ tests/antigravity/run-tests.sh | 16 ++++ tests/antigravity/test-antigravity-tools.sh | 53 ++++++++++ 5 files changed, 178 insertions(+), 2 deletions(-) create mode 100644 skills/using-superpowers/references/antigravity-tools.md create mode 100755 tests/antigravity/run-tests.sh create mode 100755 tests/antigravity/test-antigravity-tools.sh diff --git a/README.md b/README.md index ea7b53aa..83af0a3d 100644 --- a/README.md +++ b/README.md @@ -4,7 +4,7 @@ Superpowers is a complete software development methodology for your coding agent ## Quickstart -Give your agent Superpowers: [Claude Code](#claude-code), [Codex App](#codex-app), [Codex CLI](#codex-cli), [Cursor](#cursor), [Factory Droid](#factory-droid), [Gemini CLI](#gemini-cli), [GitHub Copilot CLI](#github-copilot-cli), [OpenCode](#opencode), [Pi](#pi). +Give your agent Superpowers: [Claude Code](#claude-code), [Antigravity](#antigravity), [Codex App](#codex-app), [Codex CLI](#codex-cli), [Cursor](#cursor), [Factory Droid](#factory-droid), [Gemini CLI](#gemini-cli), [GitHub Copilot CLI](#github-copilot-cli), [OpenCode](#opencode), [Pi](#pi). ## How it works @@ -60,6 +60,17 @@ The Superpowers marketplace provides Superpowers and some other related plugins /plugin install superpowers@superpowers-marketplace ``` +### Antigravity + +Install Superpowers as a plugin from this repository: + +```bash +agy plugin install https://github.com/obra/superpowers +``` + +Antigravity runs the plugin's session-start hook, so Superpowers is active from +the first message. Reinstall with the same command to update. + ### Codex App Superpowers is available via the [official Codex plugin marketplace](https://github.com/openai/plugins). diff --git a/skills/using-superpowers/SKILL.md b/skills/using-superpowers/SKILL.md index e9294781..53712217 100644 --- a/skills/using-superpowers/SKILL.md +++ b/skills/using-superpowers/SKILL.md @@ -41,7 +41,7 @@ If CLAUDE.md, GEMINI.md, or AGENTS.md says "don't use TDD" and a skill says "alw ## Platform Adaptation -Skills speak in actions ("dispatch a subagent", "create a todo", "read a file") rather than naming any one runtime's tools. For per-platform tool equivalents and instructions-file conventions, see [claude-code-tools.md](references/claude-code-tools.md), [codex-tools.md](references/codex-tools.md), [copilot-tools.md](references/copilot-tools.md), [gemini-tools.md](references/gemini-tools.md), and [pi-tools.md](references/pi-tools.md). Gemini CLI users get the tool mapping loaded automatically via GEMINI.md. +Skills speak in actions ("dispatch a subagent", "create a todo", "read a file") rather than naming any one runtime's tools. For per-platform tool equivalents and instructions-file conventions, see [claude-code-tools.md](references/claude-code-tools.md), [codex-tools.md](references/codex-tools.md), [copilot-tools.md](references/copilot-tools.md), [gemini-tools.md](references/gemini-tools.md), [pi-tools.md](references/pi-tools.md), and [antigravity-tools.md](references/antigravity-tools.md). Gemini CLI users get the tool mapping loaded automatically via GEMINI.md. # Using Skills diff --git a/skills/using-superpowers/references/antigravity-tools.md b/skills/using-superpowers/references/antigravity-tools.md new file mode 100644 index 00000000..723048b7 --- /dev/null +++ b/skills/using-superpowers/references/antigravity-tools.md @@ -0,0 +1,96 @@ +# 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 | +|----------------------|----------------------| +| Read a file | `view_file` | +| Create a new file | `write_to_file` | +| Edit a file | `replace_file_content` | +| Edit a file in several places at once | `multi_replace_file_content` | +| Run a shell command | `run_command` | +| Search file contents | `grep_search` | +| Find files by name / list a directory | `list_dir` (no dedicated glob tool — combine `list_dir` with `grep_search`) | +| Fetch a URL | `read_url_content` | +| Search the web | `search_web` | +| Pose a structured question to your human partner | `ask_question` | +| Dispatch a subagent (`Subagent (general-purpose):` template) | `invoke_subagent` with a built-in `TypeName` — `self` for full-capability work, `research` for read-only (see [Subagent support](#subagent-support)) | +| Multiple parallel dispatches | Multiple entries in one `invoke_subagent` call's `Subagents` array | +| 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. | + +## Invoking a skill — read its `SKILL.md` + +Antigravity surfaces every installed skill's `name` + `description` to you at the +start of each session, but it has **no `Skill`/`activate_skill` tool**. To load a +skill, **read its `SKILL.md` with `view_file`, setting `IsSkillFile: true`** when +the skill applies — e.g. `view_file` on +`.../plugins/superpowers/skills//SKILL.md` with `IsSkillFile: true`. +(`IsSkillFile` is agy's own signal that you're reading a file to *execute its +instructions*, not to edit or preview it — set it whenever you load a skill.) + +This is the blessed skill-loading mechanism on this harness. The general rule +"never read skill files manually" means "don't bypass your platform's +skill-loading mechanism" — and on Antigravity, reading `SKILL.md` *is* that +mechanism. Reading it honors the rule rather than breaking it. + +You already know which skills exist and what they're for: their names and +descriptions are in front of you at session start. When a description matches +what you're about to do, read that skill's `SKILL.md` before acting. + +## Subagent support + +Antigravity dispatches subagents with `invoke_subagent`, passing each one a +`TypeName` in the `Subagents` array. Two `TypeName`s are **built in** — use them +directly, no `define_subagent` needed: + +- **`self`** — a full clone of you, with every tool you have (including + `write_to_file`/`replace_file_content`/`run_command`). The safe default for + general-purpose work: implementing, fixing, anything that edits files or runs + commands. +- **`research`** — read-only (file reading, `grep_search`, web/URL fetch; no write + or command access). Use it when you specifically want a subagent that can't make + changes — investigation and read-only review. + +Call `define_subagent` only for a custom system prompt or capability mix: set +`enable_write_tools: true` to grant file edits **and** `run_command`, +`enable_subagent_tools` for nested dispatch, `enable_mcp_tools` for MCP. Then +invoke it by the name you gave it. (`manage_subagents` lists/kills running +subagents.) + +Skills dispatch with `Subagent (general-purpose):` and either reference a +prompt-template file (e.g. `superpowers:subagent-driven-development`'s +`./implementer-prompt.md`) or supply an inline prompt. On Antigravity: + +| Skill dispatch form | Antigravity equivalent | +|---------------------|----------------------| +| An implementer-style `*-prompt.md` template (writes code, runs tests) | Fill the template, then `invoke_subagent` with `TypeName: "self"` and the filled prompt | +| A read-only reviewer template (`spec-reviewer`, `code-quality-reviewer`, `code-reviewer`, `requesting-code-review`'s `./code-reviewer.md`) | `invoke_subagent` with `TypeName: "research"` and the filled review template | +| Inline prompt (no template referenced) | `invoke_subagent` with `TypeName: "self"` (or `"research"` if the task only reads) and your inline prompt | + +### Prompt filling + +Skills provide prompt templates with placeholders like `{WHAT_WAS_IMPLEMENTED}` or +`[FULL TEXT of task]`. Fill all placeholders before passing the complete prompt to +`invoke_subagent`. The prompt template itself contains the agent's role, review +criteria, and expected output format — the subagent will follow it. + +### Parallel dispatch + +Put multiple entries in a single `invoke_subagent` call's `Subagents` array to run +independent subagent work in parallel. Keep dependent tasks sequential, but do not +serialize independent subagent tasks just to preserve a simpler history. + +## Task tracking + +Antigravity has **no todo / `TodoWrite` 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/tests/antigravity/run-tests.sh b/tests/antigravity/run-tests.sh new file mode 100755 index 00000000..2d0c869c --- /dev/null +++ b/tests/antigravity/run-tests.sh @@ -0,0 +1,16 @@ +#!/usr/bin/env bash +# Run all Antigravity (agy) integration tests. +set -euo pipefail + +SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)" + +echo "=== Antigravity integration tests ===" + +for t in "$SCRIPT_DIR"/test-*.sh; do + echo + echo ">>> $t" + bash "$t" +done + +echo +echo "=== All Antigravity tests passed ===" diff --git a/tests/antigravity/test-antigravity-tools.sh b/tests/antigravity/test-antigravity-tools.sh new file mode 100755 index 00000000..e370ac06 --- /dev/null +++ b/tests/antigravity/test-antigravity-tools.sh @@ -0,0 +1,53 @@ +#!/usr/bin/env bash +# Validate the Antigravity (agy) integration. agy installs the existing plugin +# directly (`agy plugin install `): 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 — agy has no `Skill` tool and +# loads skills by reading SKILL.md with view_file — and SKILL.md pointing at it. +# +# Mirrors tests/pi/test-pi-extension.mjs's "tools reference documents +# harness-specific mappings" check. CI-safe: does not require `agy` installed. +set -euo pipefail + +SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)" +REPO_ROOT="$(cd "$SCRIPT_DIR/../.." && pwd)" + +MAPPING="$REPO_ROOT/skills/using-superpowers/references/antigravity-tools.md" +SKILL="$REPO_ROOT/skills/using-superpowers/SKILL.md" + +fail() { echo "FAIL: $*" >&2; exit 1; } + +echo "test-antigravity-tools: checking Antigravity tool mapping" + +# --- Mapping exists --------------------------------------------------------- +[ -f "$MAPPING" ] || fail "tool mapping missing at $MAPPING" + +# --- Skill-load mechanism: view_file on SKILL.md (IsSkillFile), no Skill tool - +grep -qiE "view_file" "$MAPPING" \ + || fail "mapping does not document view_file as the file/skill-read tool" +grep -qiE "SKILL\.md" "$MAPPING" \ + || fail "mapping does not document reading SKILL.md as the skill-load path" +grep -q "IsSkillFile" "$MAPPING" \ + || fail "mapping does not document setting IsSkillFile when loading a skill" + +# --- Core action→tool mappings are documented ------------------------------- +for tool in write_to_file replace_file_content run_command grep_search invoke_subagent; do + grep -q "$tool" "$MAPPING" \ + || fail "mapping does not document the '$tool' tool" +done + +# --- Subagents use the built-in self/research types ------------------------- +grep -q '`self`' "$MAPPING" \ + || fail "mapping does not document the built-in 'self' subagent type" +grep -q '`research`' "$MAPPING" \ + || fail "mapping does not document the built-in 'research' subagent type" + +# --- Task tracking documents the 'task' artifact mechanism ------------------ +grep -qE 'ArtifactType.*task|task. artifact' "$MAPPING" \ + || fail "mapping does not document task tracking as a 'task' artifact" + +# --- SKILL.md Platform Adaptation links the mapping ------------------------- +grep -q "antigravity-tools.md" "$SKILL" \ + || fail "SKILL.md Platform Adaptation does not reference antigravity-tools.md" + +echo "PASS: Antigravity tool mapping valid (view_file skill-load, agy tools, SKILL.md link)"