<p align="center">
  <img src="asset/banner.png" alt="antigravity-superpowers" width="100%" />
</p>

<h1 align="center">antigravity-superpowers</h1>

<p align="center">
  <strong>Bring the power of <a href="https://github.com/obra/superpowers">Superpowers</a> to <a href="https://antigravity.google/">Antigravity</a>.</strong>
</p>

<p align="center">
  <a href="https://www.npmjs.com/package/antigravity-superpowers"><img src="https://img.shields.io/npm/v/antigravity-superpowers.svg" alt="npm version" /></a>
  <a href="https://www.npmjs.com/package/antigravity-superpowers"><img src="https://img.shields.io/npm/dm/antigravity-superpowers.svg" alt="npm downloads" /></a>
  <img src="https://img.shields.io/badge/node-%3E%3D20-brightgreen.svg" alt="node version" />
  <img src="https://img.shields.io/badge/license-MIT-blue.svg" alt="license" />
</p>

---

Superpowers is an incredible skill-based workflow system that gives AI coding assistants structured, reliable behavior — brainstorming, planning, test-driven development, code review, debugging, and more. It was originally designed for Claude Code, but the workflows themselves are platform-agnostic gold.

**This project ports that entire system to Antigravity**, preserving the original flow as faithfully as possible. The goal is not to reinvent Superpowers — it's to make them available on Antigravity with the minimal set of changes needed for native compatibility. If you've used Superpowers before, everything should feel familiar. If you haven't, this is a great way to start.

> **One command. Full profile. Ready to go.**

```bash
npx antigravity-superpowers init
```

---

## What's New in v0.2.0

| Feature | Description |
| --- | --- |
| `validate` command | Run 78 automated checks on your `.agent` profile (files, skills, frontmatter, legacy patterns, AGENTS mapping) |
| `list` command | List all 13 bundled skills with names and descriptions |
| `--version` / `-v` | Show CLI version |
| `--dry-run` / `-n` | Preview files that would be copied without making changes |
| `--backup` / `-b` | Backup existing `.agent` to `.agent-backup-<timestamp>` before overwrite |
| 20 automated tests | Expanded from 3 to 20 tests covering CLI, init, and validate |
| Node >= 21 fix | Fixed `npm test` compatibility with newer Node.js versions |

---

## Installation

### Option 1: Run directly with npx (no install)

```bash
npx antigravity-superpowers init
```

### Option 2: Install globally from npm

```bash
npm install -g antigravity-superpowers
```

### Option 3: Install from source

```bash
git clone https://git.visssoft.com/hanh.tonguyen/antigravity-superpowers.git
cd antigravity-superpowers
npm link
```

After install, verify CLI is available:

```bash
antigravity-superpowers --version
# 0.2.0
```

---

## Usage

### 1. Initialize a project

```bash
# Initialize in current directory
antigravity-superpowers init

# Initialize in a specific project
antigravity-superpowers init /path/to/project
```

This copies the complete `.agent` profile (13 skills, 3 workflows, validation tests) into your project root.

### 2. Validate the profile

```bash
antigravity-superpowers validate
```

Runs 78 checks: required files, all 13 skills present, frontmatter validity, no legacy patterns, AGENTS mapping contract.

### 3. List available skills

```bash
antigravity-superpowers list
```

Output:

```
Antigravity Superpowers — 13 skills available:

  brainstorming                    You MUST use this before any creative work...
  executing-plans                  Use when you have a written implementation plan...
  finishing-a-development-branch   Use when implementation is complete, all tests pass...
  receiving-code-review            Use when receiving code review feedback...
  requesting-code-review           Use when completing tasks, implementing major features...
  single-flow-task-execution       Use when executing implementation plans...
  systematic-debugging             Use when encountering any bug, test failure...
  test-driven-development          Use when implementing any feature or bugfix...
  using-git-worktrees              Use when starting feature work that needs isolation...
  using-superpowers                Use when starting any conversation...
  verification-before-completion   Use when about to claim work is complete...
  writing-plans                    Use when you have a spec or requirements...
  writing-skills                   Use when creating new skills, editing existing skills...
```

### 4. Preview before copying (dry run)

```bash
antigravity-superpowers init --dry-run
```

Shows all 43 files that would be copied, without making any changes.

### 5. Update an existing profile

```bash
# Replace .agent with latest version
antigravity-superpowers init --force

# Or backup first, then replace
antigravity-superpowers init --force --backup
```

With `--backup`, the existing `.agent` is renamed to `.agent-backup-2026-03-19T10-30-00` before the new profile is copied.

---

## CLI Reference

```
antigravity-superpowers <command> [options]

Commands:
  init [dir]       Initialize .agent profile in a project
  validate [dir]   Validate .agent profile in a project
  list             List available skills

Init options:
  -f, --force      Overwrite existing .agent directory
  -b, --backup     Backup existing .agent before overwrite (use with --force)
  -n, --dry-run    Preview files that would be copied

Global options:
  -v, --version    Show version
  -h, --help       Show help
```

---

## What's Included

**13 skills** covering the full development lifecycle:

| Skill                            | Description                                             |
| -------------------------------- | ------------------------------------------------------- |
| `brainstorming`                  | Structured exploration before committing to an approach |
| `writing-plans`                  | Detailed, step-by-step implementation plans             |
| `executing-plans`                | Disciplined plan execution with progress tracking       |
| `single-flow-task-execution`     | Ordered task decomposition with review gates _(new)_    |
| `test-driven-development`        | Write tests first, implement second                     |
| `systematic-debugging`           | Root cause tracing with supporting techniques           |
| `requesting-code-review`         | Structured review flow with checklists                  |
| `receiving-code-review`          | Handling feedback systematically                        |
| `verification-before-completion` | Prove it works before claiming it's done                |
| `finishing-a-development-branch` | Clean branch wrap-up with workflow options              |
| `using-git-worktrees`            | Parallel branch management                              |
| `using-superpowers`              | Skill routing and session bootstrap                     |
| `writing-skills`                 | Create new skills that follow the system's conventions  |

Plus supporting infrastructure: 3 workflows, 1 reviewer agent, validation tests, and an `AGENTS.md` contract that ties it all together.

---

## How It Works

The CLI copies a complete `.agent` profile into your project root. Once initialized, Antigravity picks up the profile automatically:

1. **Session starts** — loads `.agent/AGENTS.md` rules and `using-superpowers` skill
2. **Each request gets routed** to the most relevant skill
3. **Design work** flows through brainstorming → planning → execution
4. **Every task** is tracked in `docs/plans/task.md` (created at runtime)
5. **Nothing is marked done** without running verification commands first

```
Session Start → Load AGENTS.md → Load using-superpowers
                                        ↓
                              Route to relevant skill
                                        ↓
                          ┌─── Design change? ───┐
                          │ yes                   │ no
                     Brainstorm            Single-flow execution
                          ↓                       ↓
                    Writing plans          Verify before completion
                          ↓                       ↓
                  Single-flow execution   Finish branch
                          ↓
                  Verify before completion
                          ↓
                     Finish branch
```

---

## Why This Exists

The original Superpowers repo doesn't support Antigravity, and there's no official port planned. I wanted to use Superpowers workflows in Antigravity projects, so I built this myself.

This is my attempt to bring the full Superpowers skill set to Antigravity — as close to the original as possible. The goal was never to fork and diverge; it was to translate just enough to make everything work natively on a different platform. Superpowers skills bring real structure to AI-assisted development — brainstorming before implementation, planning before coding, verification before completion claims — and that discipline shouldn't be locked to one platform.

This port keeps **12 out of 14 original skills intact** and consolidates the remaining 2 into a single new skill that fits Antigravity's execution model. Every skill preserves its original intent, logic, and flow — only the platform-specific references, tool names, and execution primitives have been adapted.

---

## What Changed from Original Superpowers

> This port aims to stay as close to the original Superpowers as possible. The changes are the minimum required to run natively on Antigravity.

### Execution Model

The one notable structural change. The original Superpowers dispatches multiple coding subagents in parallel — but Antigravity doesn't support parallel subagent execution. So the two skills that relied on that capability (`dispatching-parallel-agents` and `subagent-driven-development`) couldn't be ported as-is. Instead, they were consolidated into a single new skill — **`single-flow-task-execution`** — which preserves the same decomposition logic, task queuing, and review gates, just executed sequentially rather than in parallel. The workflow is the same; the concurrency model is what changed.

| Original Skill                | What Happened                                                   |
| ----------------------------- | --------------------------------------------------------------- |
| `dispatching-parallel-agents` | Merged into `single-flow-task-execution`                        |
| `subagent-driven-development` | Merged into `single-flow-task-execution`                        |
| `single-flow-task-execution`  | **New** — consolidates decomposition, queuing, and review loops |

### Task Tracking

|              | Approach                                                                            |
| ------------ | ----------------------------------------------------------------------------------- |
| **Original** | `TodoWrite` tool                                                                    |
| **Port**     | Live table at `<project-root>/docs/plans/task.md` (created at runtime, not bundled) |

### Tool & Platform Vocabulary

Platform-specific references were translated — the underlying behavior is unchanged:

| Original                 | Antigravity Port                 |
| ------------------------ | -------------------------------- |
| `Claude` / `Claude Code` | `Antigravity`                    |
| `Skill` tool             | `view_file`                      |
| `TodoWrite`              | Update `docs/plans/task.md`      |
| `superpowers:<skill>`    | `.agent/skills/<skill>/SKILL.md` |
| `CLAUDE.md`              | `.agent/AGENTS.md`               |

### Skill Adaptations

Most skills required only terminology and path updates. A few needed slightly more work:

- **`requesting-code-review`** — uses a checklist-based review flow instead of subagent dispatch
- **`writing-plans`** / **`executing-plans`** — handoff paths and tracker references updated for Antigravity conventions

The rest — `brainstorming`, `test-driven-development`, `verification-before-completion`, `finishing-a-development-branch`, and others — preserve their original behavior with only naming and path normalization.

### Antigravity-Native Additions

Infrastructure added to make the profile work as a first-class Antigravity citizen:

- `.agent/AGENTS.md` — tool translation contract and execution rules
- `.agent/workflows/` — workflow entrypoints (`brainstorm.md`, `execute-plan.md`, `write-plan.md`)
- `.agent/agents/code-reviewer.md` — reviewer agent profile
- `.agent/tests/` — automated profile validation (skill presence, frontmatter, legacy pattern detection)

> **Full Diff:** See [ANTIGRAVITY-PORT-DIFFERENCES.md](ANTIGRAVITY-PORT-DIFFERENCES.md) for the exhaustive skill-by-skill comparison and [CURRENT-FLOW.md](CURRENT-FLOW.md) for the complete workflow diagram.

---

## Development

```bash
git clone https://git.visssoft.com/hanh.tonguyen/antigravity-superpowers.git
cd antigravity-superpowers

npm test              # Run 20 tests (cli, init, validate)
npm run smoke:pack    # Verify all 31 required files are packaged
npm link              # Install CLI globally from source
```

### Publishing to npm

```bash
npm adduser           # Login to npm (first time only)
npm version patch     # or minor / major
npm publish
```

`prepublishOnly` runs `npm test` and `npm run smoke:pack` automatically before publish.

---

## Contributing

Contributions are welcome! If you find a skill that could be ported more faithfully, a translation that's off, or an Antigravity convention that's not followed — open an issue or PR.

When making changes, run the validation suite:

```bash
npm test                           # 20 automated tests
antigravity-superpowers validate   # 78 profile checks
npm run smoke:pack                 # Package integrity
```

---

## License

MIT
