gemini-superpowers-antigravity

内容来源：README.md（说明文档） · 原始地址 · 查看安装指南

原始内容

# Gemini Superpowers for Antigravity

A systematic workflow framework for **Google Antigravity** that helps you build better code through structured planning, test-driven development, and optional parallel execution.

Think of it as "guardrails for AI coding" - it prevents you from diving straight into code and instead guides you through brainstorming → planning → building → reviewing.

> **Inspired by:** [Claude Superpowers](https://github.com/obra/superpowers)
> **Adapted for:** Google Antigravity with native workflows and skills

---

## 🎯 What This Does

Instead of this chaotic workflow:
```
You: "Build me a CLI tool"
AI: *immediately starts writing code*
You: *realizes halfway through it's not what you wanted*
```

You get this structured approach:
```
You: "Build me a CLI tool"
→ Brainstorm: AI asks clarifying questions
→ Plan: AI writes a step-by-step plan with verification
→ You approve the plan
→ Execute: AI builds it step-by-step with tests
→ Review: AI checks for issues
→ Finish: Everything documented and working
```

**Bonus:** If your plan has independent steps (like "add 3 separate features"), the AI can work on them **in parallel** to save time!

---

## ✨ What's Included

### Workflows (Slash Commands)
These are commands you type in Antigravity:

- `/superpowers-brainstorm` - Explore ideas and ask questions before planning
- `/superpowers-write-plan` - Create a detailed plan (no code yet!)
- `/superpowers-execute-plan` - Build the code step-by-step
- `/superpowers-execute-plan-parallel` - Build independent steps in parallel (faster!)
- `/superpowers-review` - Check code quality
- `/superpowers-debug` - Systematic debugging
- `/superpowers-finish` - Final summary and documentation

### Skills (Building Blocks)
These teach the AI how to work:

- **TDD** - Test-driven development (write tests first)
- **Debug** - Systematic problem solving
- **Review** - Code quality checks
- **REST/Python Automation** - Best practices for specific tasks

### Rules (Guardrails)
Automatic enforcement of good practices:

- ✅ Must write a plan before coding
- ✅ Must get approval before implementing
- ✅ Must verify each step works
- ✅ Must save outputs to disk (not just chat)

---

## 🚀 Getting Started (Step-by-Step)

### Step 1: Check What You Have Installed

Before starting, make sure you have these tools:

#### ✅ Required (You must have these):

**Google Antigravity**
- How to check: Open Antigravity (if it opens, you have it!)
- Don't have it? [Install Antigravity](https://antigravity.google)

**Python 3.10 or newer**
- How to check:
  ```bash
  python --version
  ```
- Should show: `Python 3.10.x` or higher
- Don't have it? [Download Python](https://www.python.org/downloads/)

#### 🎨 Optional (Only needed for parallel execution):

**Gemini CLI** (makes things faster but not required)
- How to check:
  ```bash
  gemini --version
  ```
- If it says "command not found", you don't have it
- To install:
  ```bash
  npm install -g @google/gemini-cli
  ```

  **Windows users:** After installing, verify it works:
  ```powershell
  gemini --version
  ```
  If you see a version number, you're good! If not, see [Troubleshooting](#troubleshooting) below.

---

### Step 2: Set Up This Framework in Your Project

You have two options:

#### Option A: Start a New Project (Recommended for First-Time Users)

1. **Create a new folder for your project:**

   **Windows (PowerShell):**
   ```powershell
   mkdir my-awesome-project
   cd my-awesome-project
   ```

   **Mac/Linux:**
   ```bash
   mkdir my-awesome-project
   cd my-awesome-project
   ```

2. **Copy the `.agent` folder from this repo into your project:**

   **Windows (PowerShell):**
   ```powershell
   # Replace the path with where you downloaded this repo
   Copy-Item -Recurse C:\path\to\gemini-superpowers-antigravity\.agent .
   ```

   **Mac/Linux:**
   ```bash
   # Replace the path with where you cloned this repo
   cp -r /path/to/gemini-superpowers-antigravity/.agent .
   ```

3. **Initialize git (required for the framework to work):**
   ```bash
   git init
   git add .agent
   git commit -m "Add Superpowers framework"
   ```

4. **Open Antigravity in this folder:**

   **From your terminal:**
   ```bash
   # Make sure you're in my-awesome-project folder
   # Then open Antigravity (however you normally do it)
   ```

   **Or:** Open Antigravity → File → Open Folder → Select `my-awesome-project`

#### Option B: Use This Repo Directly (For Testing the Demo)

1. **Clone this repo:**
   ```bash
   git clone <your-repo-url>
   cd gemini-superpowers-antigravity
   ```

2. **Install Python dependencies (for the demo only):**

   **Windows (PowerShell):**
   ```powershell
   python -m venv .venv
   .\.venv\Scripts\Activate.ps1
   pip install -U pip
   pip install fastapi uvicorn httpx pytest
   ```

   **Mac/Linux:**
   ```bash
   python -m venv .venv
   source .venv/bin/activate
   pip install -U pip
   pip install fastapi uvicorn httpx pytest
   ```

3. **Run the demo tests (optional but cool to see it work):**
   ```bash
   pytest -q
   ```

   You should see: `6 passed` ✅

4. **Open Antigravity in this folder**

---

### Step 3: Verify It's Working

1. **In Antigravity, type:**
   ```
   /superpowers-reload
   ```

2. **You should see output like:**
   ```
   I've reloaded the Superpowers framework:

   Rules: superpowers.md
   Workflows: 8 loaded (brainstorm, debug, execute-plan, execute-plan-parallel, finish, reload, review, write-plan)
   Skills: 9 loaded (brainstorm, debug, finish, plan, python-automation, rest-automation, review, tdd, workflow)

   I will follow these instructions for the rest of this session.
   ```

3. **If you see this, you're ready!** 🎉

4. **If you see "command not found":**
   - Make sure Antigravity is opened in the folder that contains `.agent/`
   - Try closing and reopening Antigravity in the correct folder

---

## 📖 How to Use It (Your First Task)

Let's build something simple to see how it works.

### Example: Build a Simple Calculator CLI

#### Step 1: Brainstorm (Optional but Helpful)

In Antigravity, type:
```
/superpowers-brainstorm

I want to build a simple calculator CLI tool in Python that can add, subtract, multiply, and divide two numbers.
```

**What happens:**
- The AI will ask clarifying questions like:
  - "Should it support decimal numbers?"
  - "Command-line arguments or interactive mode?"
  - "Need error handling for division by zero?"
- Answer them to refine your idea
- The AI writes a brainstorm summary to `artifacts/superpowers/brainstorm.md`

**What you do:** Answer the questions to help the AI understand what you want.

---

#### Step 2: Write a Plan

In Antigravity, type:
```
/superpowers-write-plan

Build a Python calculator CLI with add, subtract, multiply, divide functions. Use argparse for command-line args. Include tests for each function.
```

**What happens:**
- The AI reads your project (if any files exist)
- Creates a step-by-step plan with:
  - Small steps (2-10 minutes each)
  - Files it will create/modify
  - How to verify each step works
- Writes the plan to `artifacts/superpowers/plan.md`
- Asks: **"Approve this plan? Reply APPROVED if it looks good."**

**What you do:**
1. Read the plan in `artifacts/superpowers/plan.md` (or in the chat)
2. Check if it makes sense
3. If you like it, type: `APPROVED`
4. If not, ask for changes

**Example plan you might see:**
```
## Plan

Step 1: Create calculator module
Files: calculator.py
Change: Add functions for add, subtract, multiply, divide
Verify: python -c "from calculator import add; print(add(2, 3))"

Step 2: Add tests
Files: test_calculator.py
Change: Add pytest tests for all functions
Verify: pytest test_calculator.py

Step 3: Create CLI
Files: cli.py
Change: Use argparse to create command-line interface
Verify: python cli.py add 2 3
```

---

#### Step 3: Execute the Plan

After you approve, the AI will say:
```
Plan approved. Run `/superpowers-execute-plan` to begin implementation.
```

Now type:
```
/superpowers-execute-plan
```

**What happens:**
- The AI reads the plan from `artifacts/superpowers/plan.md`
- Implements **one step at a time**
- After each step:
  - Runs the verification command
  - Writes what it did to `artifacts/superpowers/execution.md`
  - Shows you the results
- If verification fails, it stops and debugs
- At the end, writes a summary to `artifacts/superpowers/finish.md`

**What you see:**
```
Implementing Step 1: Create calculator module
[AI writes calculator.py]
Running verification: python -c "from calculator import add; print(add(2, 3))"
✅ Output: 5
Step 1 complete!

Implementing Step 2: Add tests
[AI writes test_calculator.py]
Running verification: pytest test_calculator.py
✅ 4 passed
Step 2 complete!

... (continues for each step)

All steps complete! 🎉
```

**What you do:** Just watch! The AI does the work. If it asks questions, answer them.

---

#### Step 4: Check the Results

1. **Look at the code:**
   ```bash
   ls
   ```
   You should see new files: `calculator.py`, `test_calculator.py`, `cli.py`

2. **Try running it:**
   ```bash
   python cli.py add 5 3
   ```
   Should show: `8`

3. **Check the artifacts:**
   ```bash
   # Windows
   ls artifacts\superpowers\

   # Mac/Linux
   ls artifacts/superpowers/
   ```

   You should see:
   - `plan.md` - The plan you approved
   - `execution.md` - Step-by-step log of what happened
   - `finish.md` - Final summary

---

## ⚡ Using Parallel Execution (Optional - Makes Things Faster!)

If your plan has **independent steps** (steps that don't depend on each other), you can run them in parallel to save time!

### When to Use Parallel Mode

**Good for parallel:**
- ✅ Adding 3 separate features to different files
- ✅ Creating 3 independent modules
- ✅ Writing tests for 3 different functions

**Not good for parallel:**
- ❌ Steps that build on each other (Step 2 needs Step 1's output)
- ❌ All steps modify the same file
- ❌ Only 1-2 steps total (not worth the overhead)

### How to Use It

**Option 1: Let the AI suggest it**

When you run `/superpowers-execute-plan`, if the AI detects independent steps, it will ask:
```
I notice steps 1, 2, 3 are independent and could run in parallel.
Would you like to use `/superpowers-execute-plan-parallel` for faster execution?
Or continue with sequential execution? (Reply: PARALLEL or SEQUENTIAL)
```

Reply: `PARALLEL`

**Option 2: Use it directly**

After approving your plan, type:
```
/superpowers-execute-plan-parallel
```

### What's Different in Parallel Mode?

**Sequential execution:**
```
Step 1 (5 min) → Step 2 (5 min) → Step 3 (5 min) = 15 minutes total
```

**Parallel execution:**
```
Step 1 (5 min) ┐
Step 2 (5 min) ├─ All run at the same time
Step 3 (5 min) ┘
Total: ~5 minutes (60% faster!)
```

**What you'll see:**
```
Analyzing plan for parallel execution...

Batch 1 (PARALLEL - 3 steps):
- Step 1: Add feature X
- Step 2: Add feature Y
- Step 3: Add feature Z

🤖 Spawning 3 subagents...
Subagent 1: Working on Step 1...
Subagent 2: Working on Step 2...
Subagent 3: Working on Step 3...

✅ Batch 1 completed in 5.2s
Time saved: 10 minutes vs sequential!
```

**Where are the logs?**

Check `artifacts/superpowers/subagents/` - you'll see one log file per subagent showing exactly what each one did.

---

## 🛠️ Troubleshooting

### "Command not found: /superpowers-..."

**Problem:** Antigravity doesn't see the workflows.

**Solution:**
1. Make sure you're in the folder that contains `.agent/`
2. Try running:
   ```
   /superpowers-reload
   ```
3. If that doesn't work, close Antigravity and reopen it in the correct folder

---

### Parallel execution fails with "gemini not found"

**Problem:** You don't have Gemini CLI installed, or it's not in your system PATH.

**Solution for Windows:**

1. **Install Gemini CLI:**
   ```powershell
   npm install -g @google/gemini-cli
   ```

2. **Verify it installed:**
   ```powershell
   gemini --version
   ```

   Should show: `@google/gemini-cli version X.X.X`

3. **If it still says "not found":**
   - Restart PowerShell (npm might have updated your PATH)
   - Check if npm's global bin directory is in your PATH:
     ```powershell
     npm config get prefix
     ```
   - The output should be something like `C:\Users\YourName\AppData\Roaming\npm`
   - Add that path to your system PATH environment variable

4. **Alternative:** Just use sequential execution instead:
   ```
   /superpowers-execute-plan
   ```
   (It's a bit slower but works without Gemini CLI)

**Solution for Mac/Linux:**

1. **Install Gemini CLI:**
   ```bash
   npm install -g @google/gemini-cli
   ```

2. **Verify:**
   ```bash
   which gemini
   ```
   Should show a path like: `/usr/local/bin/gemini`

3. **If not found:**
   - Make sure npm's bin directory is in PATH
   - Try: `echo $PATH` and look for npm's bin folder

---

### The AI starts coding immediately without planning

**Problem:** The AI isn't following the Superpowers rules.

**Solution:**
1. Make sure `.agent/rules/superpowers.md` exists
2. Try running:
   ```
   /superpowers-reload
   ```
3. Start a new Antigravity conversation
4. Explicitly use the workflows:
   ```
   /superpowers-write-plan <your task>
   ```

---

### Artifacts aren't being created

**Problem:** Files aren't being written to `artifacts/superpowers/`.

**Solution:**
1. Check if the folder was created:
   ```bash
   ls artifacts/superpowers/
   ```
2. If it's empty, the AI might not be following the workflow
3. Try explicitly saying:
   ```
   Please follow the superpowers-execute-plan workflow and write artifacts to disk.
   ```

---

### I edited a workflow but nothing changed

**Problem:** Antigravity cached the old version.

**Solution:**
```
/superpowers-reload
```

This forces Antigravity to re-read all `.agent/` files.

---

## 📂 Where Everything Lives

```
your-project/
├── .agent/                          ← The Superpowers framework (copy this!)
│   ├── rules/
│   │   └── superpowers.md          ← Rules the AI must follow
│   ├── workflows/
│   │   ├── superpowers-write-plan.md
│   │   ├── superpowers-execute-plan.md
│   │   └── ...                      ← Slash commands
│   └── skills/
│       ├── superpowers-tdd/
│       ├── superpowers-debug/
│       └── ...                      ← Building blocks for the AI
│
├── artifacts/                       ← Generated outputs (git-ignored)
│   └── superpowers/
│       ├── plan.md                  ← Your approved plan
│       ├── execution.md             ← Step-by-step execution log
│       ├── finish.md                ← Final summary
│       └── subagents/               ← Parallel execution logs
│
├── your-code-here.py               ← Your actual project files
├── tests/                          ← Tests the AI creates
└── README.md                       ← Your project docs
```

---

## 🎓 Learning by Example

### Example 1: Simple Python Script

**Task:** "Create a script that counts words in a text file"

**Commands you'd use:**
```
/superpowers-write-plan Create a Python script that counts words in a text file
→ Review plan
APPROVED
→ AI creates plan

/superpowers-execute-plan
→ AI builds: word_counter.py, test_word_counter.py
→ AI verifies it works
→ Done!
```

**Result:** Working script with tests in ~5 minutes

---

### Example 2: REST API Client

**Task:** "Build a GitHub API client that lists user repos"

**Commands:**
```
/superpowers-brainstorm I want to build a GitHub API client
→ AI asks: Authentication? Rate limiting? Which endpoints?
→ You answer

/superpowers-write-plan Build a GitHub API client with authentication, rate limiting, and repo listing
→ AI creates detailed plan
APPROVED

/superpowers-execute-plan
→ AI implements step-by-step
→ Each step verified
→ Done!
```

**Result:** Production-ready API client with error handling and tests

---

### Example 3: Three Independent Features (Parallel!)

**Task:** "Add logging, config file support, and --verbose flag to my CLI"

**Commands:**
```
/superpowers-write-plan

Add three features to my CLI:
1. Logging to a file
2. Load settings from a config file
3. --verbose flag for detailed output

Each feature should be independent.

→ AI creates plan with 3 independent steps
APPROVED

/superpowers-execute-plan-parallel
→ AI spawns 3 subagents
→ All 3 features built simultaneously
→ 60% faster than sequential!
```

**Result:** All three features done in ~5 minutes instead of ~15 minutes

---

## 🎯 Quick Reference

### Most Common Workflow

```
1. /superpowers-write-plan <describe what you want>
2. Read the plan, type: APPROVED
3. /superpowers-execute-plan
4. Done! Check your code and artifacts/superpowers/finish.md
```

### All Available Commands

| Command | What It Does | When to Use |
|---------|-------------|-------------|
| `/superpowers-brainstorm` | Explore ideas with Q&A | When you're not sure exactly what you want |
| `/superpowers-write-plan` | Create a detailed plan | Start of every task |
| `/superpowers-execute-plan` | Build code step-by-step | After approving plan |
| `/superpowers-execute-plan-parallel` | Build independent steps in parallel | When plan has 3+ independent steps |
| `/superpowers-review` | Check code quality | Before finishing, or when debugging |
| `/superpowers-debug` | Systematic debugging | When something's broken |
| `/superpowers-finish` | Create final summary | After everything works |
| `/superpowers-reload` | Reload all workflows/rules | After editing .agent/ files |

---

## 🤝 Contributing

Want to improve this framework? PRs welcome!

**Good ideas for contributions:**
- More language-specific skills (Node/TS, Go, Rust, etc.)
- Additional workflows (git worktree management, branch cleanup, etc.)
- Better parallel execution (smarter dependency detection)
- More E2E demos showing real-world usage
- Better error messages and troubleshooting

---

## 📄 License

MIT License - See LICENSE file

---

## 🙏 Credits

- **Inspired by:** [obra/superpowers](https://github.com/obra/superpowers) (Claude Superpowers)
- **Adapted for:** Google Antigravity
- **Parallel execution concept:** Based on community discussions about multi-agent workflows

---

## 💡 Tips for Success

1. **Start small:** Try the calculator example first before tackling big projects
2. **Read the plans:** Don't just blindly approve - actually review what the AI suggests
3. **Use parallel mode wisely:** It's faster but harder to debug if something goes wrong
4. **Check artifacts:** The `artifacts/superpowers/` folder tells you exactly what happened
5. **Reload often:** If you edit workflows, always run `/superpowers-reload`
6. **Ask questions:** If the plan doesn't make sense, ask the AI to clarify before approving

Happy coding! 🚀

Gemini Superpowers for Antigravity

A systematic workflow framework for Google Antigravity that helps you build better code through structured planning, test-driven development, and optional parallel execution.

Think of it as "guardrails for AI coding" - it prevents you from diving straight into code and instead guides you through brainstorming → planning → building → reviewing.

Inspired by: Claude Superpowers Adapted for: Google Antigravity with native workflows and skills

🎯 What This Does

Instead of this chaotic workflow:

You: "Build me a CLI tool"
AI: *immediately starts writing code*
You: *realizes halfway through it's not what you wanted*

You get this structured approach:

You: "Build me a CLI tool"
→ Brainstorm: AI asks clarifying questions
→ Plan: AI writes a step-by-step plan with verification
→ You approve the plan
→ Execute: AI builds it step-by-step with tests
→ Review: AI checks for issues
→ Finish: Everything documented and working

Bonus: If your plan has independent steps (like "add 3 separate features"), the AI can work on them in parallel to save time!

✨ What's Included

Workflows (Slash Commands)

These are commands you type in Antigravity:

/superpowers-brainstorm - Explore ideas and ask questions before planning
/superpowers-write-plan - Create a detailed plan (no code yet!)
/superpowers-execute-plan - Build the code step-by-step
/superpowers-execute-plan-parallel - Build independent steps in parallel (faster!)
/superpowers-review - Check code quality
/superpowers-debug - Systematic debugging
/superpowers-finish - Final summary and documentation

Skills (Building Blocks)

These teach the AI how to work:

TDD - Test-driven development (write tests first)
Debug - Systematic problem solving
Review - Code quality checks
REST/Python Automation - Best practices for specific tasks

Rules (Guardrails)

Automatic enforcement of good practices:

✅ Must write a plan before coding
✅ Must get approval before implementing
✅ Must verify each step works
✅ Must save outputs to disk (not just chat)

🚀 Getting Started (Step-by-Step)

Step 1: Check What You Have Installed

Before starting, make sure you have these tools:

✅ Required (You must have these):

Google Antigravity

How to check: Open Antigravity (if it opens, you have it!)
Don't have it? Install Antigravity

Python 3.10 or newer

How to check:
```
python --version
```
Should show: Python 3.10.x or higher
Don't have it? Download Python

🎨 Optional (Only needed for parallel execution):

Gemini CLI (makes things faster but not required)

How to check:
```
gemini --version
```
If it says "command not found", you don't have it
To install:
```
npm install -g @google/gemini-cli
```
Windows users: After installing, verify it works:
```
gemini --version
```
If you see a version number, you're good! If not, see Troubleshooting below.

Step 2: Set Up This Framework in Your Project

You have two options:

Option A: Start a New Project (Recommended for First-Time Users)

Create a new folder for your project:

Windows (PowerShell):

mkdir my-awesome-project
cd my-awesome-project

Mac/Linux:

mkdir my-awesome-project
cd my-awesome-project

Copy the .agent folder from this repo into your project:

Windows (PowerShell):

# Replace the path with where you downloaded this repo
Copy-Item -Recurse C:\path\to\gemini-superpowers-antigravity\.agent .

Mac/Linux:

# Replace the path with where you cloned this repo
cp -r /path/to/gemini-superpowers-antigravity/.agent .

Initialize git (required for the framework to work):

git init
git add .agent
git commit -m "Add Superpowers framework"

Open Antigravity in this folder:

From your terminal:
```
# Make sure you're in my-awesome-project folder
# Then open Antigravity (however you normally do it)
```
Or: Open Antigravity → File → Open Folder → Select my-awesome-project

Option B: Use This Repo Directly (For Testing the Demo)

Clone this repo:

git clone <your-repo-url>
cd gemini-superpowers-antigravity

Install Python dependencies (for the demo only):

Windows (PowerShell):

python -m venv .venv
.\.venv\Scripts\Activate.ps1
pip install -U pip
pip install fastapi uvicorn httpx pytest

Mac/Linux:

python -m venv .venv
source .venv/bin/activate
pip install -U pip
pip install fastapi uvicorn httpx pytest

Run the demo tests (optional but cool to see it work):
```
pytest -q
```
You should see: 6 passed ✅
Open Antigravity in this folder

Step 3: Verify It's Working

In Antigravity, type:
```
/superpowers-reload
```

You should see output like:

I've reloaded the Superpowers framework:

Rules: superpowers.md
Workflows: 8 loaded (brainstorm, debug, execute-plan, execute-plan-parallel, finish, reload, review, write-plan)
Skills: 9 loaded (brainstorm, debug, finish, plan, python-automation, rest-automation, review, tdd, workflow)

I will follow these instructions for the rest of this session.

If you see this, you're ready! 🎉
If you see "command not found":
- Make sure Antigravity is opened in the folder that contains .agent/
- Try closing and reopening Antigravity in the correct folder

📖 How to Use It (Your First Task)

Let's build something simple to see how it works.

Example: Build a Simple Calculator CLI

Step 1: Brainstorm (Optional but Helpful)

In Antigravity, type:

/superpowers-brainstorm

I want to build a simple calculator CLI tool in Python that can add, subtract, multiply, and divide two numbers.

What happens:

The AI will ask clarifying questions like:
- "Should it support decimal numbers?"
- "Command-line arguments or interactive mode?"
- "Need error handling for division by zero?"
Answer them to refine your idea
The AI writes a brainstorm summary to artifacts/superpowers/brainstorm.md

What you do: Answer the questions to help the AI understand what you want.

Step 2: Write a Plan

In Antigravity, type:

/superpowers-write-plan

Build a Python calculator CLI with add, subtract, multiply, divide functions. Use argparse for command-line args. Include tests for each function.

What happens:

The AI reads your project (if any files exist)
Creates a step-by-step plan with:
- Small steps (2-10 minutes each)
- Files it will create/modify
- How to verify each step works
Writes the plan to artifacts/superpowers/plan.md
Asks: "Approve this plan? Reply APPROVED if it looks good."

What you do:

Read the plan in artifacts/superpowers/plan.md (or in the chat)
Check if it makes sense
If you like it, type: APPROVED
If not, ask for changes

Example plan you might see:

## Plan

Step 1: Create calculator module
Files: calculator.py
Change: Add functions for add, subtract, multiply, divide
Verify: python -c "from calculator import add; print(add(2, 3))"

Step 2: Add tests
Files: test_calculator.py
Change: Add pytest tests for all functions
Verify: pytest test_calculator.py

Step 3: Create CLI
Files: cli.py
Change: Use argparse to create command-line interface
Verify: python cli.py add 2 3

Step 3: Execute the Plan

After you approve, the AI will say:

Plan approved. Run `/superpowers-execute-plan` to begin implementation.

Now type:

/superpowers-execute-plan

What happens:

The AI reads the plan from artifacts/superpowers/plan.md
Implements one step at a time
After each step:
- Runs the verification command
- Writes what it did to artifacts/superpowers/execution.md
- Shows you the results
If verification fails, it stops and debugs
At the end, writes a summary to artifacts/superpowers/finish.md

What you see:

Implementing Step 1: Create calculator module
[AI writes calculator.py]
Running verification: python -c "from calculator import add; print(add(2, 3))"
✅ Output: 5
Step 1 complete!

Implementing Step 2: Add tests
[AI writes test_calculator.py]
Running verification: pytest test_calculator.py
✅ 4 passed
Step 2 complete!

... (continues for each step)

All steps complete! 🎉

What you do: Just watch! The AI does the work. If it asks questions, answer them.

Step 4: Check the Results

Look at the code:
```
ls
```
You should see new files: calculator.py, test_calculator.py, cli.py
Try running it:
```
python cli.py add 5 3
```
Should show: 8
Check the artifacts:
```
# Windows
ls artifacts\superpowers\

# Mac/Linux
ls artifacts/superpowers/
```
You should see:
- plan.md - The plan you approved
- execution.md - Step-by-step log of what happened
- finish.md - Final summary

⚡ Using Parallel Execution (Optional - Makes Things Faster!)

If your plan has independent steps (steps that don't depend on each other), you can run them in parallel to save time!

When to Use Parallel Mode

Good for parallel:

✅ Adding 3 separate features to different files
✅ Creating 3 independent modules
✅ Writing tests for 3 different functions

Not good for parallel:

❌ Steps that build on each other (Step 2 needs Step 1's output)
❌ All steps modify the same file
❌ Only 1-2 steps total (not worth the overhead)

How to Use It

Option 1: Let the AI suggest it

When you run /superpowers-execute-plan, if the AI detects independent steps, it will ask:

I notice steps 1, 2, 3 are independent and could run in parallel.
Would you like to use `/superpowers-execute-plan-parallel` for faster execution?
Or continue with sequential execution? (Reply: PARALLEL or SEQUENTIAL)

Reply: PARALLEL

Option 2: Use it directly

After approving your plan, type:

/superpowers-execute-plan-parallel

What's Different in Parallel Mode?

Sequential execution:

Step 1 (5 min) → Step 2 (5 min) → Step 3 (5 min) = 15 minutes total

Parallel execution:

Step 1 (5 min) ┐
Step 2 (5 min) ├─ All run at the same time
Step 3 (5 min) ┘
Total: ~5 minutes (60% faster!)

What you'll see:

Analyzing plan for parallel execution...

Batch 1 (PARALLEL - 3 steps):
- Step 1: Add feature X
- Step 2: Add feature Y
- Step 3: Add feature Z

🤖 Spawning 3 subagents...
Subagent 1: Working on Step 1...
Subagent 2: Working on Step 2...
Subagent 3: Working on Step 3...

✅ Batch 1 completed in 5.2s
Time saved: 10 minutes vs sequential!

Where are the logs?

Check artifacts/superpowers/subagents/ - you'll see one log file per subagent showing exactly what each one did.

🛠️ Troubleshooting

"Command not found: /superpowers-..."

Problem: Antigravity doesn't see the workflows.

Solution:

Make sure you're in the folder that contains .agent/
Try running:
```
/superpowers-reload
```
If that doesn't work, close Antigravity and reopen it in the correct folder

Parallel execution fails with "gemini not found"

Problem: You don't have Gemini CLI installed, or it's not in your system PATH.

Solution for Windows:

Install Gemini CLI:
```
npm install -g @google/gemini-cli
```
Verify it installed:
```
gemini --version
```
Should show: @google/gemini-cli version X.X.X
If it still says "not found":
- Restart PowerShell (npm might have updated your PATH)
- Check if npm's global bin directory is in your PATH:
```
npm config get prefix
```
- The output should be something like C:\Users\YourName\AppData\Roaming\npm
- Add that path to your system PATH environment variable
Alternative: Just use sequential execution instead:
```
/superpowers-execute-plan
```
(It's a bit slower but works without Gemini CLI)

Solution for Mac/Linux:

Install Gemini CLI:
```
npm install -g @google/gemini-cli
```
Verify:
```
which gemini
```
Should show a path like: /usr/local/bin/gemini
If not found:
- Make sure npm's bin directory is in PATH
- Try: echo $PATH and look for npm's bin folder

The AI starts coding immediately without planning

Problem: The AI isn't following the Superpowers rules.

Solution:

Make sure .agent/rules/superpowers.md exists
Try running:
```
/superpowers-reload
```
Start a new Antigravity conversation
Explicitly use the workflows:
```
/superpowers-write-plan <your task>
```

Artifacts aren't being created

Problem: Files aren't being written to artifacts/superpowers/.

Solution:

Check if the folder was created:
```
ls artifacts/superpowers/
```
If it's empty, the AI might not be following the workflow

Try explicitly saying:

Please follow the superpowers-execute-plan workflow and write artifacts to disk.

I edited a workflow but nothing changed

Problem: Antigravity cached the old version.

Solution:

/superpowers-reload

This forces Antigravity to re-read all .agent/ files.

📂 Where Everything Lives

your-project/
├── .agent/                          ← The Superpowers framework (copy this!)
│   ├── rules/
│   │   └── superpowers.md          ← Rules the AI must follow
│   ├── workflows/
│   │   ├── superpowers-write-plan.md
│   │   ├── superpowers-execute-plan.md
│   │   └── ...                      ← Slash commands
│   └── skills/
│       ├── superpowers-tdd/
│       ├── superpowers-debug/
│       └── ...                      ← Building blocks for the AI
│
├── artifacts/                       ← Generated outputs (git-ignored)
│   └── superpowers/
│       ├── plan.md                  ← Your approved plan
│       ├── execution.md             ← Step-by-step execution log
│       ├── finish.md                ← Final summary
│       └── subagents/               ← Parallel execution logs
│
├── your-code-here.py               ← Your actual project files
├── tests/                          ← Tests the AI creates
└── README.md                       ← Your project docs

🎓 Learning by Example

Example 1: Simple Python Script

Task: "Create a script that counts words in a text file"

Commands you'd use:

/superpowers-write-plan Create a Python script that counts words in a text file
→ Review plan
APPROVED
→ AI creates plan

/superpowers-execute-plan
→ AI builds: word_counter.py, test_word_counter.py
→ AI verifies it works
→ Done!

Result: Working script with tests in ~5 minutes

Example 2: REST API Client

Task: "Build a GitHub API client that lists user repos"

Commands:

/superpowers-brainstorm I want to build a GitHub API client
→ AI asks: Authentication? Rate limiting? Which endpoints?
→ You answer

/superpowers-write-plan Build a GitHub API client with authentication, rate limiting, and repo listing
→ AI creates detailed plan
APPROVED

/superpowers-execute-plan
→ AI implements step-by-step
→ Each step verified
→ Done!

Result: Production-ready API client with error handling and tests

Example 3: Three Independent Features (Parallel!)

Task: "Add logging, config file support, and --verbose flag to my CLI"

Commands:

/superpowers-write-plan

Add three features to my CLI:
1. Logging to a file
2. Load settings from a config file
3. --verbose flag for detailed output

Each feature should be independent.

→ AI creates plan with 3 independent steps
APPROVED

/superpowers-execute-plan-parallel
→ AI spawns 3 subagents
→ All 3 features built simultaneously
→ 60% faster than sequential!

Result: All three features done in ~5 minutes instead of ~15 minutes

🎯 Quick Reference

Most Common Workflow

1. /superpowers-write-plan <describe what you want>
2. Read the plan, type: APPROVED
3. /superpowers-execute-plan
4. Done! Check your code and artifacts/superpowers/finish.md

All Available Commands

Command	What It Does	When to Use
`/superpowers-brainstorm`	Explore ideas with Q&A	When you're not sure exactly what you want
`/superpowers-write-plan`	Create a detailed plan	Start of every task
`/superpowers-execute-plan`	Build code step-by-step	After approving plan
`/superpowers-execute-plan-parallel`	Build independent steps in parallel	When plan has 3+ independent steps
`/superpowers-review`	Check code quality	Before finishing, or when debugging
`/superpowers-debug`	Systematic debugging	When something's broken
`/superpowers-finish`	Create final summary	After everything works
`/superpowers-reload`	Reload all workflows/rules	After editing .agent/ files

🤝 Contributing

Want to improve this framework? PRs welcome!

Good ideas for contributions:

More language-specific skills (Node/TS, Go, Rust, etc.)
Additional workflows (git worktree management, branch cleanup, etc.)
Better parallel execution (smarter dependency detection)
More E2E demos showing real-world usage
Better error messages and troubleshooting

📄 License

MIT License - See LICENSE file

🙏 Credits

Inspired by: obra/superpowers (Claude Superpowers)
Adapted for: Google Antigravity
Parallel execution concept: Based on community discussions about multi-agent workflows

💡 Tips for Success

Start small: Try the calculator example first before tackling big projects
Read the plans: Don't just blindly approve - actually review what the AI suggests
Use parallel mode wisely: It's faster but harder to debug if something goes wrong
Check artifacts: The artifacts/superpowers/ folder tells you exactly what happened
Reload often: If you edit workflows, always run /superpowers-reload
Ask questions: If the plan doesn't make sense, ask the AI to clarify before approving

Happy coding! 🚀