diff --git a/README.md b/README.md index 096cdea..7c57e8a 100644 --- a/README.md +++ b/README.md @@ -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-` 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 [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-` 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 +``` ---