Superpowers for Agent Zero

An Agent Zero community plugin that adapts the Superpowers v6.2.0 skills framework and development methodology without modifying Agent Zero core.

What the plugin provides

• All 14 locked upstream skills, mandatory using-superpowers bootstrap, native Skills discovery, and a collision-safe superpowers: resolver.
• A resumable task supervisor with isolated Agent Zero contexts and worktrees, bounded parallel workers, evidence gates, explicit integration approval, and the Superpowers subagent-driven-development review loop.
• A live Methodology Map showing primary agents, SDD reviewers, replacement agents, and parallel workers across Orient, Plan, Build, Review, and Finish.
• A separate Visual Companion for sandboxed design candidates, bounded feedback, and explicit submission through the ordinary Agent Zero message boundary.
• Transactional lifecycle, integrity, recovery, and standalone-distribution operations owned by the plugin's root hooks.py.

Current capabilities

Version 1.0.0 provides the complete Superpowers plugin runtime implemented by the accepted feature workstreams. Full-framework parity, live provider acceptance, and community-index publication remain separate evidence gates.

Installation

Place or clone the standalone repository at /a0/usr/plugins/superpowers, then enable it in Agent Zero's Plugins UI. The install hook verifies the locked upstream payload and the local Mermaid vendor before writing plugin runtime state. It installs no Python or system package, starts no sidecar, opens no port, and does not modify Agent Zero core.

The repository must include both byte-identical thumbnail.jpg files, the root MERMAID.lock.json, and the complete webui/vendor/mermaid/ closure.

Activation and scoped settings

Agent Zero owns global, project, profile, and project-profile activation. Superpowers resolves the selected Agent Zero scope and layers its partial configuration over strict defaults. Available settings are:

• maximum parallel workers (1..4);
• Methodology Map enabled and auto-open;
• Visual Companion enabled and idle timeout (5..1440 minutes);
• strict integrity;
• interrupted-task retention (1..365 days);
• optional mechanical, standard, review, escalation, and final-review model preset identities.

The compact Settings panel reports current runtime health and opens the existing right-canvas Methodology Map. Canonical skills remain in Agent Zero's native Skills UI.

Methodology and skill resolution

Every prompt cycle receives one verified bootstrap marker before model action, including after compaction. The bootstrap requires the agent to load applicable skills before responding. Use Agent Zero's Skills UI for discovery or the superpowers_skill tool with a canonical name such as superpowers:systematic-debugging. Skill contents and support files are read only after the upstream lock has been verified and are activated only for the owning chat context.

Supervised, parallel, and SDD work

superpowers_task admits a bounded task graph with explicit write ownership. Independent tasks may use up to four isolated workers; conflicting scopes are rejected before dispatch. Durable records retain context, worktree, Git-head, tool-evidence, verification, cleanup, and restart state.

In SDD mode, implementation and review use distinct contexts. Findings are fixed and re-reviewed, unsupported feedback can be challenged with evidence, and integration requires an exact-head user approval. Final review is a separate gate. Failed or unverifiable evidence blocks completion.

Live Methodology Map

The Methodology Map is a read-only observability projection. It shows current phase, skill, actor role, relationships, blocked work, and evidence-safe status; it never stores prompt text, tool arguments, chat content, raw context IDs, or transport credentials. Reconnect uses short-lived, one-use, browser/SID-bound authority and an opaque subscription identity so stale streams cannot update a new chat.

Mermaid 11.16.0 is vendored locally and verified offline from the root lock. No CDN, npm, telemetry, or renderer fallback request is permitted at runtime. If rendering fails, the semantic list/inspector remains complete and keyboard accessible; reduced-motion and narrow layouts remain supported.

Visual Companion

The Visual Companion has a distinct authority and storage boundary from the Methodology Map. Candidate HTML is opaque, validated before persistence, served through same-origin plugin APIs, and displayed in a sandboxed iframe with a restrictive CSP. Selecting a candidate does not wake the agent. Only explicit submit crosses the ordinary Agent Zero message boundary. Context changes abort in-flight work synchronously and cannot restore the previous session.

Integrity and maintainer refresh

UPSTREAM.lock.json pins Superpowers v6.2.0 and the exact protected 180-file tree. Reads fail closed on missing, extra, changed, symlinked, or mode-mismatched content. MERMAID.lock.json separately records the official package identity, npm SHA-512 integrity, SPDX license, file sizes, and hashes for the local ESM closure.

Ordinary install, startup, health, and rendering are offline. A maintainer may refresh only through hooks.py with the exact confirmation refresh mermaid@11.16.0. The hook accepts only the pinned official metadata and tarball URLs, rejects redirects and unsafe archive members/imports, verifies the complete staged closure, and atomically replaces the tree and lock.

Lifecycle and recovery

Install is idempotent. Shutdown, disable, pre-update, restart, context deletion, and uninstall reconcile plugin-owned workers and both visual surfaces, revoke transport authority, and record explicit retained or failed cleanup. Project .superpowers/ evidence, worktrees, branches, plans, and durable Companion artifacts are never disposable plugin data. See docs/lifecycle.md.

Troubleshooting

• Initialization fails: inspect the bounded status diagnostic, then run the offline upstream and Mermaid verification operations. Do not bypass strict integrity.
• A skill is unavailable: confirm Superpowers is enabled for the selected scope and use its canonical superpowers: name.
• Map or Companion is disconnected: keep the chat selected and reconnect; capabilities are deliberately reissued after expiry or restart.
• A supervised run is interrupted: inspect its durable record and resume or cancel explicitly. Never delete its worktree to clear a status.
• Update/uninstall reports retained resources: resolve the reported active context or cleanup failure and retry; project evidence is intentionally left untouched.

Verification and distribution

Run from the Agent Zero repository root with the framework runtime:

PYTHONPATH=/a0 /opt/venv-a0/bin/python -m pytest -q usr/plugins/superpowers/tests

The hook-owned distribution builder creates a temporary standalone export, rejects secrets, runtime data, symlinks, undeclared executable bits, remote Mermaid fallbacks, and missing locked content, and returns a content digest. GitHub publication and the separate a0-plugins index entry require explicit maintainer authorization and are not performed by install or distribution.

Plugin Index contract

If publication is separately authorized after technical acceptance, the community-index entry belongs at superpowers/index.yaml. The lowercase, underscore-safe superpowers/ directory may contain only index.yaml and an optional thumbnail.jpg. Repository and index metadata must name the real authorized public repository; this source tree intentionally carries no placeholder repository URL.

Limitations

• Real-model behavior depends on a working Agent Zero provider session.
• The map is observability, not a task-control surface; approvals stay in the dedicated supervisor UI.
• The Companion accepts bounded visual feedback, not arbitrary browser code or hidden agent messages.
• Technical parity, a deployed instance, provider authentication, and Plugin Index publication are separate acceptance surfaces.

License and attribution

Superpowers is Copyright (c) 2025 Jesse Vincent and is distributed under the MIT License. This Agent Zero adaptation preserves the upstream bytes and records their identity in NOTICE and UPSTREAM.lock.json. Vendored Mermaid is also MIT licensed and recorded separately in MERMAID.lock.json.