agent-superpowers
<div align="center">
# β‘ AGENT SUPERPOWERS
### Transform Your AI Coding Agent into a Battle-Tested Principal Staff Engineer
**Stop AI hallucinations, broken production commits, and 100k-token context bloat.**
*A disciplined, deterministic 7-stage autonomous engineering framework natively compatible with **Claude Code, Cursor, Google Antigravity, Windsurf, Codex, and Model Context Protocol (MCP)**.*
<br/>
[](https://github.com/GabrieleDattile/agent-superpowers/releases)
[](https://github.com/GabrieleDattile/agent-superpowers/tree/main/skills)
[-10B981?style=for-the-badge&logo=githubactions)](https://github.com/GabrieleDattile/agent-superpowers/blob/main/tests/test_skills.py)
[](https://github.com/GabrieleDattile/agent-superpowers/blob/main/mcp/server.py)
[](https://github.com/GabrieleDattile/agent-superpowers/blob/main/LICENSE)
<br/>
<!-- Hero Terminal Showcase -->
<p align="center">
<img src="https://raw.githubusercontent.com/GabrieleDattile/agent-superpowers/main/assets/demo.gif" alt="Agent Superpowers Live Terminal Demo" width="920" style="max-width: 100%; border-radius: 12px; border: 1px solid #30363d; box-shadow: 0 20px 40px -15px rgba(0,0,0,0.7);"/>
</p>
<!-- Live Execution Breakdown Bar -->
| π 1. Deterministic Repro | π¦ 2. Ephemeral Sandbox | π’ 3. Minimal Surgical Patch | βοΈ 4. Red-Team Fuzzing | π 5. Production Gate |
| :---: | :---: | :---: | :---: | :---: |
| **`RED Test Required`** | **`Worktree Isolation`** | **`GREEN Verification`** | **`11 Attack Payloads`** | **`Verified Merge`** |
| Zero code edits allowed until bug replicates | Primary branch protected from corrupting edits | Minimal patch turns failing repro green | Null-bytes, SQLi & overflow injection | 100% regression suite verified |
<br/>
> **β Found this useful? Star this repository to empower the open-source autonomous engineering movement!**
</div>
---
## β‘ Quick Start (Instant 1-Command Setup)
Install the complete 36-skill suite and autonomous Python engines in seconds:
### πͺ Windows (Native PowerShell)
```powershell
irm https://raw.githubusercontent.com/GabrieleDattile/agent-superpowers/main/install.ps1 | iex
```
### π§ macOS / Linux (Native Bash)
```bash
curl -fsSL https://raw.githubusercontent.com/GabrieleDattile/agent-superpowers/main/install.sh | bash
```
### π Universal MCP Server (Claude Desktop, Cursor, Zed, Antigravity)
Add to your `claude_desktop_config.json` or `.cursor/mcp.json`:
```json
{
"mcpServers": {
"agent-superpowers": {
"command": "python",
"args": ["mcp/server.py"],
"cwd": "/path/to/agent-superpowers"
}
}
}
```
### π¦ Node.js / NPX
```bash
npx github:GabrieleDattile/agent-superpowers list
```
---
## β‘ The Difference: Default AI vs. Agent Superpowers
Without guardrails, even state-of-the-art LLMs behave like chaotic junior developers: they jump straight into editing files, hallucinate non-existent APIs, break existing tests, and push unverified changes.
| The Chaos of Default AI β | With Agent Superpowers Protocol π’ |
| :--- | :--- |
| **Hallucinates bug fixes**: Edits production code based on guesswork | **Ghost Runner**: Strictly forbidden from editing source code until a minimal failing test reproduces the defect (`RED β GREEN`) |
| **Corrupts your workspace**: Makes sweeping multi-file edits directly on your active working branch | **Git Worktree Sandbox**: Runs all experiments in ephemeral, isolated git worktrees; primary branch remains 100% clean |
| **Generates fragile edge-cases**: Writes happy-path code vulnerable to boundary crashes and exploits | **Adversarial Duelist**: Automated pre-commit red-team fuzzer injects null-bytes, SQLi payloads, and zero-divisions |
| **Produces generic AI slop**: Default purple gradients, formulaic 3-card grids, Inter font, unanchored blur blobs | **Hallmark**: Anti-AI-slop design engine with 24 distinct material themes and automated `sloplint` auditor |
| **Blows token budgets**: Dumps full source files into context, hitting rate limits and burning money | **Token Squeezer**: Shrinks prompt context by 50β70% using AST extraction without losing architectural semantics |
| **Breaks frontend layouts**: Generates UI code that looks fine on desktop but breaks on mobile viewports | **Frontend Sentinel**: WCAG 2.1 accessibility and responsive breakpoint auditor with visual HTML reports |
| **Session amnesia**: Forgets past architectural decisions and conventions every time the CLI restarts | **Memory Nexus**: Append-only local decision ledger (`.superpowers/decisions.jsonl`) persists context cross-session |
| **Locked into closed ecosystems**: Inability to interface with proprietary tools and APIs | **Blackbox Cloner & API Synthesizer**: Clean-room tool replication and automatic cURL-to-SDK synthesis |
---
## π¬ Live Deep-Dives: See How the Skills Work in Action
### 1. π Ghost Runner: Strict TDD Bug Reproduction
> **Rule**: An agent is **forbidden from modifying production files** until it writes an isolated test that replicates the bug and fails (`RED`).
```bash
# Run Ghost Runner reproduction gate
python cli/superpowers.py run ghost-runner reproduce --test "python -m unittest tests/test_reproduce.py"
```
```text
=== π» Ghost Runner: TDD Reproduction Protocol ===
Test Command: python -m unittest tests/test_reproduce.py
Expected Outcome: FAILURE (RED)
Running test under isolated subshell...
----------------------------------------------------------------------
ZeroDivisionError: division by zero in calculate_discount()
Ran 1 test in 0.002s
FAILED (failures=1)
β SUCCESS: Defect reproduced deterministically (Exit Code: 1).
Agent is now AUTHORIZED to apply minimal surgical patch in worktree.
```
---
### 2. π‘οΈ Adversarial Duelist: Pre-Commit Red-Team Fuzzing
> **Rule**: Before any commit or PR is approved, the agent attacks the proposed function with 11 boundary payloads to catch unhandled crashes.
```bash
# Fuzz an authentication or payment function
python cli/superpowers.py run duelist --target services/auth.py --func authenticate_user
```
```text
=== βοΈ Adversarial Duelist: Red-Team Fuzzer ===
Target: services/auth.py :: authenticate_user()
Testing 11 adversarial injection vectors...
β [01/11] Null-Byte Poisoning ('admin\x00') β Handled (ValueError)
β [02/11] SQL Injection (' OR '1'='1' --) β Handled (Safe Query)
β [03/11] Memory Bounding ('A' * 100,000) β Handled (LengthGuard)
β [04/11] Zero Divisor (divisor=0) β Handled (ZeroGuard)
β [05/11] Float NaN / Infinity (val=float('nan')) β Handled (TypeError)
β [06/11] Boundary Integer (2^63 - 1) β Handled (OverflowSafe)
...
β 11/11 Attack Vectors Defended. Pre-commit authorization granted.
```
---
### 3. π¨ Hallmark & Sloplint: The Anti-AI-Slop Design Engine
> **Rule**: Prevent LLMs from defaulting to generic AI tropes (purple gradients, predictable 3-card grids, floating blur balls).
```bash
# Audit a landing page or UI component for machine-made design tells
python cli/superpowers.py run sloplint src/components/Hero.tsx
```
```text
=================================================================
π¨ Hallmark Sloplint: Autonomous Anti-AI-Slop Auditor
=================================================================
Scanned: src/components/Hero.tsx
Found 3 aesthetic tells:
π΄ [SLOP-001] Generic AI Purple Gradient (Line 14)
Match: 'bg-gradient-to-r from-purple-500 to-indigo-600'
Fix: Adopt a deliberate palette from Hallmark themes (e.g. Cobalt, Atelier, Furrow).
π΄ [SLOP-002] Unanchored Floating Blur Orb (Line 8)
Match: 'rounded-full blur-3xl bg-purple-500/30'
Fix: Replace decorative blobs with real photography, technical diagrams, or clean space.
π‘ [SLOP-003] AI Buzzword Copy (Line 18)
Match: 'Supercharge your productivity with AI'
Fix: Write concrete, specific value propositions with real numbers and features.
Overall Slop Index: 60 / 100 [FAIL (HIGH SLOP CONTENT)]
Guidance: Apply curated theme tokens from references/themes.json
```
---
### 4. β‘ Token Squeezer: AST-Based Prompt Compressor
> **Rule**: Shrink massive codebases by **50β70%** before injecting them into prompt context windows, preserving signatures and docstrings.
```bash
# Compress a 500-line service down to its architectural essence
python cli/superpowers.py run squeezer services/payment.py --mode interface
```
```python
# === ORIGINAL (1,420 Tokens) === # === SQUEEZED (-68% Tokens) ===
class PaymentGateway: class PaymentGateway:
"""Handles Stripe and PayPal charges.""" """Handles Stripe and PayPal charges."""
def __init__(self, key: str): def __init__(self, key: str): ...
self.key = key def charge(self, amount: float,
self._init_vault() currency: str = "USD") -> bool: ...
self._connect_webhook() def refund(self, txn_id: str) -> bool: ...
def charge(self, amount: float, ...) -> bool:
# [80 lines of internal logic]
...
```
---
### 5. πΊοΈ Arch Archaeologist & Graphify: Codebase Cartography
> **Rule**: Map live module dependencies, trace call trees, and detect dead zombie functions across the entire repository.
```text
flowchart TD
subgraph Core ["π¦ Core Services"]
AUTH["auth.py<br/><i>authenticate_user()</i>"]
GATEWAY["gateway.py<br/><i>process_payment()</i>"]
end
subgraph Storage ["πΎ Storage Layer"]
DB["database.py<br/><i>query_records()</i>"]
CACHE["cache.py<br/><i>get_session()</i>"]
end
subgraph DeadCode ["β οΈ Dead Zombie Code (Isolated)"]
LEGACY["legacy_v1_api.py<br/><i>[0 references detected]</i>"]
end
AUTH --> DB
AUTH --> CACHE
GATEWAY --> DB
style LEGACY stroke:#ef4444,stroke-dasharray: 5 5,color:#ef4444
```
---
## π The 7-Stage Autonomous Lifecycle
Every coding task executes through an auditable, deterministic state machine:
```text
βββββββββββββββββββ βββββββββββββββββββ βββββββββββββββββββ
β 1. BRAINSTORM β ββββ> β 2. WORKTREE β ββββ> β 3. MAP & β
β Requirements β β Sandbox Branch β β Compress (AST) β
βββββββββββββββββββ βββββββββββββββββββ βββββββββββββββββββ
β
βΌ
βββββββββββββββββββ βββββββββββββββββββ βββββββββββββββββββ
β 6. RED-TEAM β <ββββ β 5. SURGICAL β <ββββ β 4. TDD PROOF β
β Fuzzing & Audit β β Green Patch β β Fail First (RED)β
βββββββββββββββββββ βββββββββββββββββββ βββββββββββββββββββ
β
βΌ
βββββββββββββββββββ
β 7. SAFE MERGE β ββββ> Verified Production-Ready Artifact
β & PR Gate β
βββββββββββββββββββ
```
---
## π¦ Complete Autonomous Superpowers Suite (36 Skills)
<details open>
<summary><b>π§ Core Orchestration & Lifecycle (3 Skills)</b></summary>
| Superpower | Category | Primary Capability |
| :--- | :--- | :--- |
| [**`using-superpowers`**](skills/orchestration/using-superpowers/SKILL.md) | π§ Orchestration | Master bootstrap meta-skill; enforces the 7-stage engineering lifecycle |
| [**`feature-brainstormer`**](skills/workflow/feature-brainstormer/SKILL.md) | π‘ Workflow | Socratic requirements refiner; asks 3 clarifying questions before writing code |
| [**`git-worktree-sandbox`**](skills/workflow/git-worktree-sandbox/SKILL.md) | π¦ Workflow | Ephemeral git worktree isolation; zero risk of corrupting your active workspace |
</details>
<details open>
<summary><b>π Debugging & Verification (3 Skills)</b></summary>
| Superpower | Category | Primary Capability |
| :--- | :--- | :--- |
| [**`ghost-runner`**](skills/debugging/ghost-runner/SKILL.md) | π Debugging | Zero-assumption bug reproducer; enforces strict RED β GREEN TDD cycle |
| [**`testsprite-verify`**](skills/testing/testsprite-verify/SKILL.md) | π§ͺ Testing | Closed-loop automated regression and user flow verification |
| [**`testsprite-ci`**](skills/testing/testsprite-ci/SKILL.md) | π§ͺ Testing | CI pipeline test automation and test suite orchestration |
</details>
<details open>
<summary><b>π‘οΈ Security & Reverse Engineering (3 Skills)</b></summary>
| Superpower | Category | Primary Capability |
| :--- | :--- | :--- |
| [**`adversarial-duelist`**](skills/security/adversarial-duelist/SKILL.md) | π‘οΈ Security | Pre-commit red-team fuzzer; injects malicious edge-case payloads |
| [**`blackbox-cloner`**](skills/reverse-engineering/blackbox-cloner/SKILL.md) | π΅οΈ Reverse Engineering | Clean-room tool replicator; deconstructs proprietary software into open-source scaffolds |
| [**`api-synthesizer`**](skills/reverse-engineering/api-synthesizer/SKILL.md) | π Integration | Network-to-SDK generator; converts cURL traffic into typed Python client SDKs |
</details>
<details open>
<summary><b>πΊοΈ Architecture & Memory (5 Skills)</b></summary>
| Superpower | Category | Primary Capability |
| :--- | :--- | :--- |
| [**`arch-archaeologist`**](skills/architecture/arch-archaeologist/SKILL.md) | πΊοΈ Architecture | Codebase cartographer; traces dependency graphs and isolates dead zombie functions |
| [**`graphify`**](skills/architecture/graphify/SKILL.md) | πΊοΈ Architecture | AST-driven persistent knowledge graph of codebases, schemas, and docs without vector DB |
| [**`hindsight-architect`**](skills/architecture/hindsight-architect/SKILL.md) | πΊοΈ Architecture | Memory architect for application design patterns and decisions |
| [**`memory-nexus`**](skills/memory/memory-nexus/SKILL.md) | πΎ Memory | Cross-session architecture ledger; eliminates agent amnesia between restarts |
| [**`hindsight-memory`**](skills/memory/hindsight-memory/SKILL.md) | πΎ Memory | Adaptive long-term project memory and automatic session synthesis |
</details>
<details open>
<summary><b>β‘ Optimization & Token Efficiency (4 Skills)</b></summary>
| Superpower | Category | Primary Capability |
| :--- | :--- | :--- |
| [**`token-squeezer`**](skills/optimization/token-squeezer/SKILL.md) | β‘ Optimization | AST-based context compressor; cuts LLM prompt token costs by 50β70% |
| [**`caveman`**](skills/optimization/caveman/SKILL.md) | β‘ Optimization | Terse smart-caveman voice; eliminates fluff while preserving all technical facts |
| [**`caveman-compress`**](skills/optimization/caveman-compress/SKILL.md) | β‘ Optimization | Extreme token compression for memory files and long context |
| [**`prompt-optimizer`**](skills/optimization/prompt-optimizer/SKILL.md) | β‘ Optimization | Systematic prompt evaluation, few-shot generation, and constraint tuning |
</details>
<details open>
<summary><b>π¨ Frontend, Design & Anti-Slop (5 Skills)</b></summary>
| Superpower | Category | Primary Capability |
| :--- | :--- | :--- |
| [**`hallmark`**](skills/frontend/hallmark/SKILL.md) | π¨ Frontend | Anti-AI-slop design engine; overrides generic purple gradients with 24 material themes & sloplint |
| [**`frontend-sentinel`**](skills/frontend/frontend-sentinel/SKILL.md) | π¨ Frontend | Production UI/UX auditor; checks a11y, mobile viewports & generates visual HTML reports |
| [**`figma-designer`**](skills/frontend/figma-designer/SKILL.md) | π¨ Frontend | Token-driven Figma design specs, components, auto-layout, and design systems |
| [**`landing-page-design`**](skills/frontend/landing-page-design/SKILL.md) | π¨ Frontend | High-converting landing page blueprints, copywriting, and visual structure |
| [**`review-frontend-production`**](skills/frontend/review-frontend-production/SKILL.md) | π¨ Frontend | Production frontend inspection, compliance checks, and handover verification |
</details>
<details open>
<summary><b>πΈοΈ Web Data, Scraping & Social (7 Skills)</b></summary>
| Superpower | Category | Primary Capability |
| :--- | :--- | :--- |
| [**`scrapling`**](skills/scraping/scrapling/SKILL.md) | πΈοΈ Scraping | Adaptive web scraping framework with anti-bot bypass and stealth browser sessions |
| [**`firecrawl-build`**](skills/scraping/firecrawl-build/SKILL.md) | πΈοΈ Scraping | In-app Firecrawl integration for live web data, extraction, and search |
| [**`firecrawl-scrape`**](skills/scraping/firecrawl-scrape/SKILL.md) | πΈοΈ Scraping | Single-page extraction into structured markdown |
| [**`firecrawl-search`**](skills/scraping/firecrawl-search/SKILL.md) | πΈοΈ Scraping | Agent web discovery before extraction |
| [**`firecrawl-interact`**](skills/scraping/firecrawl-interact/SKILL.md) | πΈοΈ Scraping | Post-scrape browser actions, form filling, and pagination |
| [**`firecrawl-onboard`**](skills/scraping/firecrawl-onboard/SKILL.md) | πΈοΈ Scraping | Firecrawl SDK credentials, auth flows, and project onboarding |
| [**`agent-reach`**](skills/scraping/agent-reach/SKILL.md) | πΈοΈ Scraping | Zero-API reading and search across public web sources, video transcripts, and developer platforms |
</details>
<details open>
<summary><b>π Lean Engineering & Multimedia (6 Skills)</b></summary>
| Superpower | Category | Primary Capability |
| :--- | :--- | :--- |
| [**`ponytail`**](skills/workflow/ponytail/SKILL.md) | π Workflow | YAGNI principal engineer mindset; smallest change that fully solves the task |
| [**`ponytail-audit`**](skills/workflow/ponytail-audit/SKILL.md) | π Workflow | Whole-repo bloat and unnecessary dependency audit |
| [**`ponytail-debt`**](skills/workflow/ponytail-debt/SKILL.md) | π Workflow | Technical debt and shortcut tracking ledger |
| [**`ponytail-review`**](skills/workflow/ponytail-review/SKILL.md) | π Workflow | Pull request quality and anti-overengineering reviewer |
| [**`caveman-commit`**](skills/workflow/caveman-commit/SKILL.md) | π Workflow | Intent-only Conventional Commits generator |
| [**`video-shotcraft`**](skills/multimedia/video-shotcraft/SKILL.md) | π¬ Multimedia | Programmatic Remotion cinematic product video synthesis |
</details>
---
## π οΈ Universal Platform Support
Agent Superpowers is completely runtime-agnostic. Drop it into your existing workflow with zero configuration:
* **π£ Claude Code**: Native plugin manifest in [`.claude-plugin/plugin.json`](.claude-plugin/plugin.json) with startup lifecycle hooks in [`hooks/`](hooks/).
* **π΅ Cursor**: Modern `.mdc` Project Rules in [`.cursor/rules/agent-superpowers.mdc`](.cursor/rules/agent-superpowers.mdc).
* **π Google Antigravity & Gemini CLI**: Native workspace extension in [`extension.yaml`](extension.yaml).
* **π Windsurf**: Native IDE rules in [`.windsurfrules`](.windsurfrules).
* **π’ OpenAI Codex**: Configured via [`.codex/INSTALL.md`](.codex/INSTALL.md).
* **π Model Context Protocol (MCP)**: Native stdio JSON-RPC server in [`mcp/server.py`](mcp/server.py). Compatible with Claude Desktop, Cursor, Antigravity, and Zed.
---
## π Mission Control Dashboard
Agent Superpowers ships with an interactive local web dashboard with **zero external dependencies**. Visualize your skills, architecture dependency graphs, and test telemetry in real time:
```bash
python cli/superpowers.py dashboard
```
---
## π CLI Commands & Validation
Agent Superpowers includes a built-in verification suite:
```bash
# List all 36 registered superpowers
python cli/superpowers.py list
# Run system health check across all engines
python cli/superpowers.py status
# Validate specification compliance
python cli/superpowers.py validate
# Run the automated unit test suite
python -m unittest tests/test_skills.py
```
---
## π€ Contributing
Contributions are warmly welcomed!
1. Check our formal [Agent Skill Specification](docs/SPECIFICATION.md).
2. Propose new skills via the [New Skill Template](.github/ISSUE_TEMPLATE/new_skill.yml).
3. Ensure CI verification passes (`python cli/superpowers.py validate`).
---
## π€ Author
**Gabriele D'Attile**
* Portfolio & Technical Dossier: [https://gabrieledattile.github.io/agent-superpowers.html](https://gabrieledattile.github.io/agent-superpowers.html)
* Website: [https://gabrieledattile.github.io](https://gabrieledattile.github.io)
* GitHub: [@GabrieleDattile](https://github.com/GabrieleDattile)
* Repository: [https://github.com/GabrieleDattile/agent-superpowers](https://github.com/GabrieleDattile/agent-superpowers)
---
## π License
This project is licensed under the [MIT License](https://github.com/GabrieleDattile/agent-superpowers/blob/main/LICENSE).
TDQS
Scored across 9 tools
Most tools target clearly distinct capabilities: API synthesis, TDD bug reproduction, fuzzing, context compression, dependency archaeology, git sandboxing, frontend accessibility auditing, blackbox cloning, and AI-design linting. There is some conceptual adjacency between api_synthesizer and blackbox_cloner (both reverse engineering) and between frontend_sentinel and hallmark_sloplint (both frontend/design audits), but their descriptions make the boundaries usable.
All names use consistent snake_case and follow a descriptive agent-persona pattern rather than a verb_noun action pattern. The style is predictable overall, with only minor variation such as the three-word git_worktree_sandbox and a mix of modifier_noun forms.
Nine tools is well within the appropriate range for a specialized agent-superpowers toolkit. Each tool represents a distinct capability and none appear redundant or purely filler.
The set covers several advanced coding-agent workflows, but as a broad 'superpowers' toolkit it has notable gaps: no general code search/navigation, refactoring, documentation generation, dependency management, or performance profiling. These omissions are not fatal because the tools are specialized add-ons, but they mean the surface is not a complete lifecycle.