hanh.tonguyen/antigravity-superpowers
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Rewrite README.md for v0.2.0 with complete usage guide

Browse Source 
- 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>
This commit is contained in:
To Nguyen
2026-03-19 01:37:30 +07:00
parent 415022d1dc
commit 220e480516
1 changed files with 162 additions and 129 deletions
Download Patch File Download Diff File Expand all files Collapse all files

291
README.md
View File

@@ -29,13 +29,140 @@ npx antigravity-superpowers init
---
## Why This Exists
## What's New in v0.2.0
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.
| 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 |
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.
## 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
```
---
@@ -59,107 +186,7 @@ This port keeps **12 out of 14 original skills intact** and consolidates the rem
| `using-superpowers` | Skill routing and session bootstrap |
| `writing-skills` | Create new skills that follow the system's conventions |
Plus supporting infrastructure: workflows, agents, validation tests, and an `AGENTS.md` contract that ties it all together.
---
## Quick Start
```bash
# Scaffold the .agent profile into your project
npx antigravity-superpowers init
```
Or install globally:
```bash
npm install -g antigravity-superpowers
antigravity-superpowers init
```
Or install from source (Git):
```bash
git clone https://git.visssoft.com/hanh.tonguyen/antigravity-superpowers.git
cd antigravity-superpowers
npm link
# Now use it anywhere
antigravity-superpowers init
```
After init, verify everything is wired up:
```bash
antigravity-superpowers validate
```
---
## CLI Reference
### `antigravity-superpowers init [dir] [options]`
Initialize the `.agent` profile in a project directory.
```bash
# Initialize in current directory
antigravity-superpowers init
# Initialize in a specific project
antigravity-superpowers init /path/to/project
# Preview files that would be copied (no changes made)
antigravity-superpowers init --dry-run
# Replace an existing .agent profile
antigravity-superpowers init --force
# Backup existing .agent before replacing
antigravity-superpowers init --force --backup
```
| Option | Short | Description |
| --- | --- | --- |
| `--force` | `-f` | Overwrite existing `.agent` directory |
| `--backup` | `-b` | Backup existing `.agent` to `.agent-backup-<timestamp>` before overwrite (use with `--force`) |
| `--dry-run` | `-n` | Preview the file list without copying anything |
### `antigravity-superpowers validate [dir]`
Run profile validation checks on an initialized project. Verifies file presence, skill completeness, frontmatter validity, legacy pattern absence, and AGENTS mapping contract.
```bash
# Validate current directory
antigravity-superpowers validate
# Validate a specific project
antigravity-superpowers validate /path/to/project
```
### `antigravity-superpowers list`
List all 13 bundled skills with their names and descriptions.
```bash
antigravity-superpowers list
```
### `antigravity-superpowers --version`
Show the current CLI version.
```bash
antigravity-superpowers --version # or -v
```
### `antigravity-superpowers --help`
Show usage information.
```bash
antigravity-superpowers --help # or -h
```
Plus supporting infrastructure: 3 workflows, 1 reviewer agent, validation tests, and an `AGENTS.md` contract that ties it all together.
---
@@ -193,6 +220,16 @@ Session Start → Load AGENTS.md → Load using-superpowers
---
## 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.
@@ -248,19 +285,6 @@ Infrastructure added to make the profile work as a first-class Antigravity citiz
---
## 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 to make sure everything still checks out:
```bash
npm test
antigravity-superpowers validate
```
---
## Development
```bash
@@ -268,24 +292,33 @@ 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 package contents (31 required files)
npm run smoke:pack # Verify all 31 required files are packaged
npm link # Install CLI globally from source
```
### Install from Source
### Publishing to npm
```bash
npm link # Symlink CLI globally
antigravity-superpowers --version
```
### Publishing
```bash
npm version patch # or minor/major
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.
`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
```
---