hanh.tonguyen/antigravity-superpowers
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
220e4805169cd47834ab6315995a0e8c462588ab
antigravity-superpowers/README.md
To Nguyen 220e480516 Rewrite README.md for v0.2.0 with complete usage guide 
- Add What's New in v0.2.0 section highlighting all new features
- Restructure into clear Installation (3 options) and Usage (5 workflows) sections
- Add sample output for list command
- Add compact CLI Reference block with all commands, options, and flags
- Move Why This Exists below How It Works for better reading flow
- Update Development section with clone URL, test counts, and publish steps
- Remove all v0.1.0 references

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
2026-03-19 01:37:30 +07:00

328 lines
14 KiB
Markdown
Raw Blame History

<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
Reference in New Issue View Git Blame Copy Permalink