# ⚡ superpower_setup

> One-command installer for [obra/superpowers](https://github.com/obra/superpowers) — a curated collection of AI coding skills for [Google Antigravity](https://antigravity.google).

Superpower_setup downloads and installs 14 battle-tested skills that teach your Antigravity agent proven development workflows: TDD, systematic debugging, parallel agents, code review, and more.

## Table of Contents

- [Why Superpowers?](#why-superpowers)
- [Quick Start](#quick-start)
- [Installation Modes](#installation-modes)
- [Commands](#commands)
- [Options](#options)
- [Examples](#examples)
- [Directory Structure](#directory-structure)
- [Included Skills](#included-skills)
- [How It Works](#how-it-works)
- [Troubleshooting](#troubleshooting)
- [License](#license)

## Why Superpowers?

Out of the box, Antigravity is powerful — but it doesn't know *your* workflows. Superpowers fills that gap with a structured skill system that:

- 🧠 **Teaches patterns, not just prompts** — Each skill is a detailed methodology (e.g., RED-GREEN-REFACTOR for TDD) that the agent follows consistently.
- 🔄 **Stays up to date** — Run `update` anytime to pull the latest skills from the upstream repo.
- 🌍 **Works locally or globally** — Install per-project for team consistency, or globally for personal productivity across all repos.
- 📦 **Zero dependencies** — Pure Node.js, no external packages. Just `npx` and go.

## Quick Start

```bash
# Install into your current project
npx superpower_setup init

# Or install globally (available across all projects)
npx superpower_setup init --global
```

That's it. Your Antigravity agent now has access to 14 professional development skills.

## Installation Modes

### Local Mode (default)

Installs skills into the **current project's** `.agents/` directory. Best for:

- Team projects where everyone should share the same skills
- Project-specific skill configurations
- Keeping skills version-locked per repo

```bash
npx superpower_setup init
```

### Global Mode (`--global`)

Installs skills into `~/.gemini/antigravity/` so they are **available across all projects**. Best for:

- Personal productivity — install once, use everywhere
- Trying out superpowers without modifying any project
- Shared skills across multiple solo repos

```bash
npx superpower_setup init --global
```

> **Note:** Global mode does **not** create `gemini-extension.json` or modify `.gitignore`, since the global directory lives outside any git repository.

### Local vs Global Comparison

| Aspect | Local | Global |
|--------|-------|--------|
| **Skills location** | `<project>/.agents/skills/superpowers/` | `~/.gemini/antigravity/skills/superpowers/` |
| **GEMINI.md** | `<project>/GEMINI.md` | `~/.gemini/GEMINI.md` |
| **gemini-extension.json** | ✅ Created | ❌ Not needed |
| **.gitignore** | ✅ Updated | ❌ Not needed |
| **Scope** | Current project only | All projects |
| **Team sharing** | ✅ Commit config to repo | ❌ Per-user only |

## Commands

### `init`

Downloads and installs superpowers skills.

```bash
npx superpower_setup init [options]
```

- Creates the `.agents/` directory structure (or `~/.gemini/antigravity/` for global)
- Copies all skills, agents, commands, and hooks
- Sets up `GEMINI.md` with skill references
- Copies `gemini-extension.json` (local mode only)
- Adds `.agents` to `.gitignore` (local mode only)

**Will not overwrite** existing files unless `--force` is used.

### `update`

Updates superpowers to the latest version from the upstream repository.

```bash
npx superpower_setup update [options]
```

Functionally identical to `init --force` — it re-downloads and **overwrites all existing skill files** to ensure you have the latest version.

## Options

| Option | Description | Default |
|--------|-------------|---------|
| `--target <path>` | Target directory for installation (local mode only) | Current working directory |
| `--branch <name>` | Git branch of the superpowers repository to install from | `main` |
| `--force` | Overwrite all existing files without prompting | `false` |
| `--global` | Install to the global Antigravity directory (`~/.gemini/antigravity/`) instead of the current project | `false` |
| `--help`, `-h` | Show help message | — |
| `--version`, `-v` | Show version number | — |

> **Note:** If `--global` and `--target` are used together, `--target` is ignored with a warning. The global directory is always `~/.gemini/antigravity/`.

## Examples

```bash
# Basic local install
npx superpower_setup init

# Install globally
npx superpower_setup init --global

# Install into a specific project directory
npx superpower_setup init --target /path/to/my-project

# Force reinstall (overwrite existing files)
npx superpower_setup init --force

# Install from a development branch
npx superpower_setup init --branch develop

# Update local installation
npx superpower_setup update

# Update global installation
npx superpower_setup update --global

# Show help
npx superpower_setup --help
```

## Directory Structure

### After Local Install

```
project-root/
├── .agents/
│   ├── skills/superpowers/         # 14 skill definitions
│   │   ├── brainstorming/
│   │   ├── test-driven-development/
│   │   ├── systematic-debugging/
│   │   ├── writing-plans/
│   │   ├── executing-plans/
│   │   ├── subagent-driven-development/
│   │   ├── using-git-worktrees/
│   │   ├── requesting-code-review/
│   │   ├── receiving-code-review/
│   │   ├── finishing-a-development-branch/
│   │   ├── verification-before-completion/
│   │   ├── dispatching-parallel-agents/
│   │   ├── writing-skills/
│   │   └── using-superpowers/
│   ├── agents/superpowers/         # Agent definitions
│   ├── commands/superpowers/       # Custom slash commands
│   └── hooks/superpowers/          # Session lifecycle hooks
├── GEMINI.md                       # Context file (auto-generated references)
├── gemini-extension.json           # Extension metadata
└── .gitignore                      # .agents entry added automatically
```

### After Global Install

```
~/.gemini/
├── antigravity/
│   ├── skills/superpowers/         # 14 skill definitions
│   ├── agents/superpowers/         # Agent definitions
│   ├── commands/superpowers/       # Custom slash commands
│   └── hooks/superpowers/          # Session lifecycle hooks
└── GEMINI.md                       # Global context file
```

Platform-specific global paths:

| OS | Path |
|----|------|
| **Windows** | `C:\Users\<username>\.gemini\antigravity\` |
| **macOS** | `/Users/<username>/.gemini/antigravity/` |
| **Linux** | `/home/<username>/.gemini/antigravity/` |

## Included Skills

| Skill | Description | Use When |
|-------|-------------|----------|
| **brainstorming** | Socratic design refinement | Starting a new feature or exploring solutions |
| **test-driven-development** | RED-GREEN-REFACTOR cycle | Writing new functionality with tests first |
| **systematic-debugging** | 4-phase root cause process | Tracking down bugs methodically |
| **writing-plans** | Detailed implementation plans | Planning complex multi-file changes |
| **executing-plans** | Batch execution with checkpoints | Implementing a pre-written plan step by step |
| **subagent-driven-development** | Fast iteration with two-stage review | Rapid prototyping with quality checks |
| **using-git-worktrees** | Parallel development branches | Working on multiple features simultaneously |
| **requesting-code-review** | Pre-review checklist | Preparing code for peer review |
| **receiving-code-review** | Responding to feedback | Addressing review comments systematically |
| **finishing-a-development-branch** | Merge/PR decision workflow | Wrapping up a feature branch |
| **verification-before-completion** | Final validation checklist | Ensuring changes actually work before marking done |
| **dispatching-parallel-agents** | Concurrent subagent workflows | Splitting large tasks across multiple agents |
| **writing-skills** | Skill authoring guide | Creating your own custom skills |
| **using-superpowers** | Introduction to the skills system | Learning how the superpowers framework works |

## How It Works

1. **Clone** — The tool shallow-clones the [obra/superpowers](https://github.com/obra/superpowers) repository into a temporary directory.
2. **Copy** — Skills, agents, commands, and hooks are copied from the cloned repo to the target directory (`.agents/` for local, `~/.gemini/antigravity/` for global).
3. **Configure** — `GEMINI.md` is created or updated with `@`-references pointing to the installed skill files. For local mode, `gemini-extension.json` and `.gitignore` are also set up.
4. **Cleanup** — The temporary clone is deleted.

The `GEMINI.md` file uses marker comments (`<!-- SUPERPOWERS_START -->` / `<!-- SUPERPOWERS_END -->`) to manage its section, so it can safely coexist with your own content in the same file.

## Troubleshooting

### "Git is not installed"

Superpower_setup requires Git to clone the upstream repository. Install Git from [git-scm.com/downloads](https://git-scm.com/downloads).

### "Failed to clone repo"

- Check your internet connection
- Verify the branch name exists: `git ls-remote --heads https://github.com/obra/superpowers.git`
- Try with the default branch: `npx superpower_setup init` (without `--branch`)

### Files already exist

By default, `init` will **not overwrite** existing files. Use one of:

```bash
# Overwrite everything
npx superpower_setup init --force

# Or use update (which implies --force)
npx superpower_setup update
```

### Skills not being picked up by Antigravity

- Ensure `GEMINI.md` exists and contains the `<!-- SUPERPOWERS_START -->` section
- For local installs, verify `gemini-extension.json` is present at the project root
- For global installs, check that files exist in `~/.gemini/antigravity/skills/superpowers/`
- Restart your Antigravity session after installation

## Prerequisites

- **Node.js** >= 18.0.0 (for `parseArgs` support)
- **Git** (for cloning the superpowers repository)
- **npx** (included with Node.js)

## License

MIT