Stop Letting AI Code Blindly! Use Gemini Superpowers Instead

Here's the brutal truth: Most developers using AI coding assistants are building on quicksand. You type "build me a CLI tool," watch the AI furiously generate code, and halfway through realize it's completely wrong—wrong architecture, wrong assumptions, wrong everything. You've just wasted 20 minutes and a mountain of context tokens on garbage. Sound familiar?

This isn't a skill issue. It's a workflow problem. AI coding tools are incredibly powerful but structurally chaotic. They reward immediate action over thoughtful planning, creating what I call "code first, think later" syndrome. The result? Refactor hell, technical debt explosions, and that sinking feeling when you have to tell your PM that the "simple feature" needs a complete rewrite.

But what if you could force AI to plan before coding? To ask clarifying questions, write verifiable steps, and get your approval before touching a single line of code? Enter Gemini Superpowers for Antigravity—the secret weapon that transforms Google Antigravity from a chaotic code generator into a disciplined, test-driven development partner. Inspired by the legendary Claude Superpowers framework, this tool adds the guardrails your AI coding desperately needs.

What Is Gemini Superpowers for Antigravity?

Gemini Superpowers for Antigravity is a systematic workflow framework created by Anthony Lee that supercharges Google Antigravity with structured planning, test-driven development, and optional parallel execution capabilities. Think of it as installing a professional software engineering process directly into your AI assistant's brain.

The project draws direct inspiration from Claude Superpowers by Obra, one of the most influential AI coding workflow systems ever created. Anthony Lee recognized that Google Antigravity users needed the same structural discipline—and built it from the ground up with native Antigravity integration.

Why it's trending now: The AI coding landscape has reached an inflection point. Developers are no longer amazed that AI can write code; they're frustrated that it writes the wrong code. Frameworks like Gemini Superpowers represent the next evolution—AI coding 2.0—where the focus shifts from raw generation speed to accuracy, verifiability, and maintainability. Early adopters are reporting 3-5x reductions in refactoring time and dramatically fewer "AI hallucination" bugs.

The framework operates through three interconnected layers:

• Workflows (slash commands that guide the conversation flow)
• Skills (behavioral instructions that teach the AI how to work)
• Rules (hard guardrails that enforce good practices automatically)

This isn't just another prompt engineering trick. It's a complete operating system for AI-assisted development that lives in your project's .agent/ directory and persists across sessions.

Key Features That Transform Your AI Coding

🎯 Structured Workflow Commands

The framework replaces chaotic AI conversations with seven precision-engineered slash commands:

• /superpowers-brainstorm — Forces the AI to explore requirements through clarifying questions before any code appears
• /superpowers-write-plan — Generates detailed, step-by-step implementation plans with verification criteria
• /superpowers-execute-plan — Builds code incrementally with mandatory verification after each step
• /superpowers-execute-plan-parallel — Spawns multiple AI subagents for independent tasks, cutting execution time by ~60%
• /superpowers-review — Systematic code quality analysis against best practices
• /superpowers-debug — Structured problem-solving that prevents random fix attempts
• /superpowers-finish — Automatic documentation generation and session summarization

🧠 Behavioral Skills (The Secret Sauce)

These aren't commands you type—they're instructions that reshape how the AI thinks:

🛡️ Unbreakable Rules (The Guardrails)

These aren't suggestions—they're automatically enforced constraints:

• ✅ Must write a plan before coding — No exceptions, no "I'll just start coding and figure it out"
• ✅ Must get explicit approval — The AI stops and waits for your APPROVED confirmation
• ✅ Must verify each step — Every implementation includes a verification command that must pass
• ✅ Must save outputs to disk — All artifacts persist to artifacts/superpowers/, never lost in chat history

Real-World Use Cases Where This Shines

Use Case 1: The Startup MVP Sprint

You're building a startup's core API under brutal time pressure. Without guardrails, AI generates a messy monolith that "works" but collapses under load. With Gemini Superpowers:

/superpowers-brainstorm → "I need a user authentication API"
→ AI asks: "JWT or session-based? OAuth providers? Rate limiting?"
→ You clarify requirements in 2 minutes instead of discovering gaps at 2 AM

/superpowers-write-plan → Detailed plan with database schema, endpoint specs, test coverage
→ You spot the missing password reset flow BEFORE coding starts

/superpowers-execute-plan → Verified implementation with passing tests at every step

Result: Production-ready code in half the time, with zero 3 AM disaster recoveries.

Use Case 2: The Legacy Refactor

That 5,000-line spaghetti script your predecessor left? The one everyone fears touching? Gemini Superpowers structures the untangling:

/superpowers-write-plan → Breaks refactor into 12 small, verifiable steps
→ Each step isolated and testable
→ No "while I'm here, I'll just rewrite everything" scope creep

The plan becomes your accountability partner—the AI literally cannot proceed to step 7 until step 6 passes verification.

Use Case 3: The Parallel Feature Blitz

Your CLI tool needs logging, config files, and a verbose flag—all independent features. Instead of 15 minutes sequential:

/superpowers-execute-plan-parallel → 3 subagents attack simultaneously
→ 5.2 seconds vs. 15 minutes
→ Each subagent's work logged separately for review

The catch: Parallel mode requires the Gemini CLI (npm install -g @google/gemini-cli). Without it, sequential execution still works perfectly—just slower.

Use Case 4: The Junior Developer Onboarding

New team member needs to understand your codebase? The artifacts/superpowers/ directory becomes self-documenting project history:

• plan.md — What we intended to build
• execution.md — Exactly what happened step-by-step
• finish.md — Final architecture decisions and known limitations

No more "why did we do it this way?" mysteries. The decision trail is permanent and searchable.

Step-by-Step Installation & Setup Guide

Prerequisites Check

Before installing, verify your environment:

# Check Python version (must be 3.10+)
python --version
# Expected: Python 3.10.x or higher

# Check Gemini CLI (optional, for parallel execution)
gemini --version
# Expected: @google/gemini-cli version X.X.X
# If missing: npm install -g @google/gemini-cli

Windows users: After npm installation, verify in a fresh PowerShell window:

gemini --version

If still not found, check your PATH includes npm's global bin directory:

npm config get prefix
# Add this path to your system PATH environment variable

Installation: Two Paths

Option A: New Project (Recommended)

# Create your project directory
mkdir my-awesome-project
cd my-awesome-project

# Copy the framework from cloned repo (Mac/Linux)
cp -r /path/to/gemini-superpowers-antigravity/.agent .

# Or Windows PowerShell
Copy-Item -Recurse C:\path\to\gemini-superpowers-antigravity\.agent .

# Initialize git (REQUIRED for framework operation)
git init
git add .agent
git commit -m "Add Superpowers framework"

# Open this folder in Antigravity

Option B: Direct Repo Clone (For Testing)

# Clone and enter the repository
git clone https://github.com/anthonylee991/gemini-superpowers-antigravity.git
cd gemini-superpowers-antigravity

# Create Python virtual environment
python -m venv .venv

# Activate environment
source .venv/bin/activate  # Mac/Linux
# Or: .\.venv\Scripts\Activate.ps1  # Windows PowerShell

# Install demo dependencies
pip install -U pip
pip install fastapi uvicorn httpx pytest

# Verify setup
pytest -q
# Expected: 6 passed ✅

Verification: Confirm Everything Works

In Antigravity, type:

/superpowers-reload

Expected output:

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.

Troubleshooting: If you see "command not found," ensure Antigravity is opened in the folder containing .agent/, then restart Antigravity.

REAL Code Examples from the Repository

The following examples are adapted directly from the repository's documentation, showing actual workflow usage patterns.

Example 1: Brainstorm Command — Preventing Requirements Disasters

# This is the CONVERSATION FLOW you type in Antigravity, not Python code
# The AI's behavior is controlled by the framework's .agent/ configuration

/superpowers-brainstorm

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

What happens behind the scenes: The framework loads superpowers-brainstorm skill, which instructs the AI to:

1. Ask clarifying questions instead of coding:

   • "Should it support decimal numbers or integers only?"
   • "Command-line arguments or interactive REPL mode?"
   • "Need error handling for division by zero?"
   • "Output formatting preferences?"

2. Write structured output to artifacts/superpowers/brainstorm.md:

# Brainstorm: Calculator CLI

## Clarifying Questions & Answers
- **Number type:** User confirmed decimal support needed
- **Interface:** Command-line arguments via argparse
- **Error handling:** Yes, division by zero protection required
- **Testing:** pytest with 100% function coverage

## Decisions Made
- Use `argparse` for CLI interface
- Implement as module + CLI wrapper for testability
- Return float results, handle ZeroDivisionError gracefully

Why this matters: That 2-minute Q&A session prevents the classic "oh, you wanted decimals?" rewrite that destroys productivity. The framework forces this discipline through its rules file.

Example 2: Plan Creation with Explicit Approval Gate

# CONVERSATION FLOW in Antigravity

/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.

The AI generates a structured plan file at artifacts/superpowers/plan.md:

## Plan: Calculator CLI Implementation

### Step 1: Create calculator module
- **Files:** `calculator.py`
- **Changes:** Add functions for add, subtract, multiply, divide
- **Verification:** `python -c "from calculator import add; print(add(2, 3))"`
- **Expected output:** `5`
- **Time estimate:** 5 minutes

### Step 2: Add comprehensive tests
- **Files:** `test_calculator.py`
- **Changes:** Add pytest tests for all four functions including edge cases
- **Verification:** `pytest test_calculator.py -v`
- **Expected output:** `4 passed`
- **Time estimate:** 5 minutes

### Step 3: Create CLI interface
- **Files:** `cli.py`
- **Changes:** Use argparse to parse command-line arguments, call calculator functions
- **Verification:** `python cli.py add 2 3`
- **Expected output:** `5.0`
- **Time estimate:** 5 minutes

---
**APPROVAL REQUIRED:** Reply `APPROVED` to begin implementation.

The critical gate: The AI stops completely here. No code generation happens without your explicit APPROVED response. This is enforced by the superpowers.md rules file, not by politeness.

Example 3: Sequential Execution with Verification

# CONVERSATION FLOW — after typing APPROVED

/superpowers-execute-plan

The AI's execution trace (written to artifacts/superpowers/execution.md):

## Execution Log

### Step 1: Create calculator module
```python
# calculator.py — Generated by AI under framework constraints
def add(a: float, b: float) -> float:
    """Add two numbers."""
    return a + b

def subtract(a: float, b: float) -> float:
    """Subtract b from a."""
    return a - b

def multiply(a: float, b: float) -> float:
    """Multiply two numbers."""
    return a * b

def divide(a: float, b: float) -> float:
    """Divide a by b, handling division by zero."""
    if b == 0:
        raise ValueError("Cannot divide by zero")
    return a / b

Verification: python -c "from calculator import add; print(add(2, 3))" Result: ✅ 5 — PASSED

Step 2: Add comprehensive tests

# test_calculator.py — Test-first development enforced by TDD skill
import pytest
from calculator import add, subtract, multiply, divide

def test_add():
    assert add(2, 3) == 5
    assert add(-1, 1) == 0
    assert add(2.5, 2.5) == 5.0

def test_divide_by_zero():
    with pytest.raises(ValueError, match="Cannot divide by zero"):
        divide(10, 0)

Verification: pytest test_calculator.py -v Result: ✅ 4 passed — PASSED

Step 3: Create CLI interface

# cli.py — argparse implementation with error handling
import argparse
from calculator import add, subtract, multiply, divide

def main():
    parser = argparse.ArgumentParser(description="Simple calculator")
    parser.add_argument("operation", choices=["add", "subtract", "multiply", "divide"])
    parser.add_argument("a", type=float)
    parser.add_argument("b", type=float)
    args = parser.parse_args()
    
    operations = {
        "add": add,
        "subtract": subtract,
        "multiply": multiply,
        "divide": divide
    }
    
    try:
        result = operations[args.operation](args.a, args.b)
        print(result)
    except ValueError as e:
        print(f"Error: {e}")
        exit(1)

if __name__ == "__main__":
    main()

Verification: python cli.py add 2 3 Result: ✅ 5.0 — PASSED

**Why this pattern is powerful:** Each step's verification becomes a **regression test** for the next. If step 3 breaks step 1's functionality, the framework catches it immediately rather than at "integration testing" (which often means production).

---

### Example 4: Parallel Execution for Independent Features

```python
# CONVERSATION FLOW — for plans with 3+ independent steps

/superpowers-execute-plan-parallel

Behind the scenes, the framework analyzes step dependencies and spawns subagents:

## Parallel Execution Analysis

**Detected independent steps:**
- Step 1: Add file logging (touches `logger.py`, `config.py`)
- Step 2: Add config file support (touches `config.py` only — CONFLICT!)
- Step 3: Add --verbose flag (touches `cli.py` only)

**Resolution:** Steps 1 and 3 are fully independent. Step 2 has file conflict with Step 1.
**Execution strategy:** 
- Batch 1 (parallel): Steps 1 and 3
- Batch 2 (sequential): Step 2

---

## Batch 1 — Parallel Execution

🤖 Spawning 2 subagents...
- Subagent A: Working on Step 1 (file logging)
- Subagent B: Working on Step 3 (--verbose flag)

✅ Batch 1 completed in 5.2s (vs. 10s sequential)

**Logs available:**
- `artifacts/superpowers/subagents/subagent_A_log.md`
- `artifacts/superpowers/subagents/subagent_B_log.md`

Critical requirement: Parallel mode needs gemini CLI in your PATH. Without it, the framework gracefully falls back to sequential execution with a warning.

Advanced Usage & Best Practices

🎯 The "Start Small" Principle

Your first project with this framework should be the calculator example from the README. Not because you're a beginner, but because the workflow discipline is different from raw AI prompting. Master the /superpowers-write-plan → APPROVED → /superpowers-execute-plan rhythm before tackling complex architectures.

🔍 Plan Review Is Non-Negotiable

The framework lets you type APPROVED blindly. Don't. The AI's plan quality depends on your prompt quality. Look for:

• Verification commands that actually verify — ls is not verification; pytest is
• Reasonable step granularity — 2-10 minutes per step, not "build entire backend"
• Explicit file lists — Vague "update files" plans fail more often

⚡ Parallel Mode: Speed vs. Debuggability

Parallel execution is insanely fast for independent features but creates debugging complexity when subagents conflict. Pro tip: Run your first parallel execution on a git branch you can abandon. The subagent logs in artifacts/superpowers/subagents/ are essential forensic tools when things go sideways.

🔄 The /superpowers-reload Habit

Anytime you modify .agent/ files—customizing rules, adding skills, tweaking workflows—immediately run:

/superpowers-reload

Antigravity caches these files aggressively. Without reload, you're debugging phantom behavior from stale configurations.

📁 Artifact Archaeology

The artifacts/superpowers/ directory is your project's black box recorder. Before asking "why did the AI do this?", check:

• plan.md — Did the plan actually say to do this? (Often: yes, and you approved it)
• execution.md — Did verification pass or fail at each step?
• subagents/*.md — Which parallel agent made which change?

Comparison with Alternatives

The verdict: Raw Antigravity is faster for trivial tasks. Cursor's Composer is slicker for UI work. But for serious software engineering—where correctness matters more than speed—Gemini Superpowers provides structural integrity that no other tool matches.

FAQ: Developer Concerns Answered

Does this work without Gemini CLI?

Yes, completely. Gemini CLI is only required for /superpowers-execute-plan-parallel. All other workflows—including the critical planning and sequential execution—work with just Antigravity and Python 3.10+.

Can I customize the rules for my team?

Absolutely. The .agent/rules/superpowers.md file is plain Markdown that Antigravity reads as instructions. Add your team's coding standards, security requirements, or technology preferences. Run /superpowers-reload after changes.

What if the AI ignores the workflow and starts coding immediately?

This happens when rules aren't loaded. Solutions: (1) Confirm .agent/rules/superpowers.md exists, (2) run /superpowers-reload, (3) start a fresh Antigravity conversation, (4) explicitly invoke /superpowers-write-plan rather than describing your task conversationally.

How does parallel execution handle merge conflicts?

The framework analyzes file dependencies before spawning subagents. Steps touching the same files are automatically sequenced. True conflicts are logged in subagent files for manual resolution—rare in practice for well-designed plans.

Is this production-ready or just a demo?

The repository includes a fully functional FastAPI demo with 6 passing pytest tests. The framework itself is being used by early adopters for real production code, though as with any AI tool, human review of plans remains essential.

Can I use this with languages other than Python?

Yes. The workflow structure is language-agnostic. The included skills emphasize Python and REST automation, but you can create custom skills for TypeScript, Go, Rust, or any stack by adding files to .agent/skills/.

What's the performance overhead?

Planning adds 2-5 minutes upfront but typically saves 15-30 minutes in debugging and refactoring. Parallel execution can reduce multi-feature implementation by 60%. Net result: faster delivery of correct code.

Conclusion: The Guardrails Your AI Coding Needs

AI coding assistants aren't going away—they're becoming essential infrastructure. But raw AI generation without structure is technical debt at velocity. Gemini Superpowers for Antigravity solves this by embedding software engineering discipline directly into the AI's behavior.

The framework's genius is its irreversibility: once loaded, the AI literally cannot skip planning, cannot bypass approval, cannot forget to verify. These aren't suggestions in a system prompt—they're behavioral constraints enforced through Antigravity's native workflow system.

My honest assessment? If you're building anything more complex than a one-off script, this framework pays for itself in the first project. The time invested in structured planning returns tenfold in reduced debugging, clearer team communication, and maintainable code.

Ready to stop letting AI code blindly? Grab the framework, run through the calculator demo, and experience what disciplined AI-assisted development feels like. Your future self—reviewing clean, tested, well-documented code—will thank you.

👉 Get Gemini Superpowers for Antigravity on GitHub — Star the repo, try the demo, and join the growing community of developers who've discovered that the best AI coding happens with guardrails.

Happy structured coding! 🚀