agent-superpowers
β‘ 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).*
π 1. Deterministic Repro | π¦ 2. Ephemeral Sandbox | π’ 3. Minimal Surgical Patch | βοΈ 4. Red-Team Fuzzing | π 5. Production Gate |
|
|
|
|
|
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 |
β Found this useful? Star this repository to empower the open-source autonomous engineering movement!
β‘ Quick Start (Instant 1-Command Setup)
Install the complete 36-skill suite and autonomous Python engines in seconds:
πͺ Windows (Native PowerShell)
irm https://raw.githubusercontent.com/GabrieleDattile/agent-superpowers/main/install.ps1 | iexπ§ macOS / Linux (Native 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:
{
"mcpServers": {
"agent-superpowers": {
"command": "python",
"args": ["mcp/server.py"],
"cwd": "/path/to/agent-superpowers"
}
}
}π¦ Node.js / NPX
npx github:GabrieleDattile/agent-superpowers listRelated MCP server: local-skills-mcp
β‘ 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 ( |
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 |
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 ( |
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).
# Run Ghost Runner reproduction gate
python cli/superpowers.py run ghost-runner reproduce --test "python -m unittest tests/test_reproduce.py"=== π» 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.
# Fuzz an authentication or payment function
python cli/superpowers.py run duelist --target services/auth.py --func authenticate_user=== βοΈ 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).
# Audit a landing page or UI component for machine-made design tells
python cli/superpowers.py run sloplint src/components/Hero.tsx=================================================================
π¨ 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.json4. β‘ Token Squeezer: AST-Based Prompt Compressor
Rule: Shrink massive codebases by 50β70% before injecting them into prompt context windows, preserving signatures and docstrings.
# Compress a 500-line service down to its architectural essence
python cli/superpowers.py run squeezer services/payment.py --mode interface# === 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.
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:
βββββββββββββββββββ βββββββββββββββββββ βββββββββββββββββββ
β 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)
Superpower | Category | Primary Capability |
π§ Orchestration | Master bootstrap meta-skill; enforces the 7-stage engineering lifecycle | |
π‘ Workflow | Socratic requirements refiner; asks 3 clarifying questions before writing code | |
π¦ Workflow | Ephemeral git worktree isolation; zero risk of corrupting your active workspace |
Superpower | Category | Primary Capability |
π Debugging | Zero-assumption bug reproducer; enforces strict RED β GREEN TDD cycle | |
π§ͺ Testing | Closed-loop automated regression and user flow verification | |
π§ͺ Testing | CI pipeline test automation and test suite orchestration |
Superpower | Category | Primary Capability |
π‘οΈ Security | Pre-commit red-team fuzzer; injects malicious edge-case payloads | |
π΅οΈ Reverse Engineering | Clean-room tool replicator; deconstructs proprietary software into open-source scaffolds | |
π Integration | Network-to-SDK generator; converts cURL traffic into typed Python client SDKs |
Superpower | Category | Primary Capability |
πΊοΈ Architecture | Codebase cartographer; traces dependency graphs and isolates dead zombie functions | |
πΊοΈ Architecture | AST-driven persistent knowledge graph of codebases, schemas, and docs without vector DB | |
πΊοΈ Architecture | Memory architect for application design patterns and decisions | |
πΎ Memory | Cross-session architecture ledger; eliminates agent amnesia between restarts | |
πΎ Memory | Adaptive long-term project memory and automatic session synthesis |
Superpower | Category | Primary Capability |
β‘ Optimization | AST-based context compressor; cuts LLM prompt token costs by 50β70% | |
β‘ Optimization | Terse smart-caveman voice; eliminates fluff while preserving all technical facts | |
β‘ Optimization | Extreme token compression for memory files and long context | |
β‘ Optimization | Systematic prompt evaluation, few-shot generation, and constraint tuning |
Superpower | Category | Primary Capability |
π¨ Frontend | Anti-AI-slop design engine; overrides generic purple gradients with 24 material themes & sloplint | |
π¨ Frontend | Production UI/UX auditor; checks a11y, mobile viewports & generates visual HTML reports | |
π¨ Frontend | Token-driven Figma design specs, components, auto-layout, and design systems | |
π¨ Frontend | High-converting landing page blueprints, copywriting, and visual structure | |
π¨ Frontend | Production frontend inspection, compliance checks, and handover verification |
Superpower | Category | Primary Capability |
πΈοΈ Scraping | Adaptive web scraping framework with anti-bot bypass and stealth browser sessions | |
πΈοΈ Scraping | In-app Firecrawl integration for live web data, extraction, and search | |
πΈοΈ Scraping | Single-page extraction into structured markdown | |
πΈοΈ Scraping | Agent web discovery before extraction | |
πΈοΈ Scraping | Post-scrape browser actions, form filling, and pagination | |
πΈοΈ Scraping | Firecrawl SDK credentials, auth flows, and project onboarding | |
πΈοΈ Scraping | Zero-API reading and search across public web sources, video transcripts, and developer platforms |
Superpower | Category | Primary Capability |
π Workflow | YAGNI principal engineer mindset; smallest change that fully solves the task | |
π Workflow | Whole-repo bloat and unnecessary dependency audit | |
π Workflow | Technical debt and shortcut tracking ledger | |
π Workflow | Pull request quality and anti-overengineering reviewer | |
π Workflow | Intent-only Conventional Commits generator | |
π¬ Multimedia | Programmatic Remotion cinematic product video synthesis |
π οΈ 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.jsonwith startup lifecycle hooks inhooks/.π΅ Cursor: Modern
.mdcProject Rules in.cursor/rules/agent-superpowers.mdc.π Google Antigravity & Gemini CLI: Native workspace extension in
extension.yaml.π Windsurf: Native IDE rules in
.windsurfrules.π’ OpenAI Codex: Configured via
.codex/INSTALL.md.π Model Context Protocol (MCP): Native stdio JSON-RPC server in
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:
python cli/superpowers.py dashboardπ CLI Commands & Validation
Agent Superpowers includes a built-in verification suite:
# 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!
Check our formal Agent Skill Specification.
Propose new skills via the New Skill Template.
Ensure CI verification passes (
python cli/superpowers.py validate).
π€ Author
Gabriele D'Attile
Portfolio & Technical Dossier: https://gabrieledattile.github.io/agent-superpowers.html
Website: https://gabrieledattile.github.io
GitHub: @GabrieleDattile
Repository: https://github.com/GabrieleDattile/agent-superpowers
π License
This project is licensed under the MIT License.
Available Tools
9 toolsadversarial_duelistB
Offensive red-team fuzzer. Attacks a Python function with null-bytes, zero-divisions, overflow payloads, and SQLi vectors.
Inputs: target_file (required), function_name (required).
api_synthesizerC
Reverse-engineers raw cURL network traffic into a fully typed Python client SDK.
Inputs: curl_command (required), client_name.
arch_archaeologistC
Scans codebase AST to map module dependency graphs and detect uncalled zombie/dead functions.
Inputs: dir_path (required).
blackbox_clonerC
Clean-room reverse engineering engine. Deconstructs proprietary tools and SaaS widgets into independent open-source specs and scaffolds.
Inputs: action (required), tool_name (required), category.
frontend_sentinelA
Audits React, Vue, and HTML templates for accessibility defects, mobile viewport breaks, and hydration hazards.
Inputs: path (required), html_report.
ghost_runnerB
Zero-assumption TDD bug reproducer. Requires test to FAIL before patching, and PASS after patching.
Inputs: mode (required), test_cmd (required).
git_worktree_sandboxB
Creates, merges, or discards isolated git worktrees so agent experiments never corrupt main workspace.
Inputs: action (required), task_name.
hallmark_sloplintA
Anti-AI-slop design auditor. Scans HTML, JSX, TSX, Svelte, and Vue files for generic AI tells (purple gradients, predictable 3-card grids, unanchored blur orbs, corporate buzzwords).
Inputs: target, fail_under.
token_squeezerC
AST-based context compressor. Shrinks Python source files by 50-70% by extracting structural interfaces and docstrings.
Inputs: file_path (required), mode.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelogβ¦
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.
Maintenance
Related MCP Connectors
Hosted MCP server and Agent Skills for specs, engineering threads, and project memory.
Hosted MCP server for live public-data APIs and Skills for AI agents.
Capability registry for the agentic economy. Semantic search over verified MCP server listings.
Governed AI agent skills β one library, distributed to devs and exposed to remote agents over MCP.
Related MCP Servers
- AlicenseNot gradedqualityCmaintenanceMulti-server MCP aggregator with 266 skills, an orchestration runtime, fleet/claims coordination, and hook-driven session governance for autonomous Claude/Cursor/Gemini agent runs.3MIT
- AlicenseAqualityBmaintenanceA universal MCP server that enables any LLM or AI agent to access expert skills from your local filesystem.3214 npm42MIT
- AlicenseCqualityDmaintenanceA production-grade MCP server providing an autonomous AI agent swarm, persistent semantic memory, browser automation, multi-model reasoning, and 78+ tools for AI-first testing and development.63MIT
- AlicenseNot gradedqualityDmaintenanceA production-ready MCP server that equips AI agents with dynamic, persistent, and executable skills. It enables secure script execution and progressive disclosure to reduce context window usage.23 npmMIT