Superpowers

Superpowers skills use action-oriented language which the plugin maps to specific OpenCode tools. This abstraction allows skills to remain portable across different runtimes.

A plan is considered a failure if it contains placeholders or vague instructions. Every step must contain the actual content an engineer needs to perform the action.

Do NOT use the following:

• "TBD", "TODO", "implement later", or "fill in details"
• Vague instructions like "Add appropriate error handling", "add validation", or "handle edge cases"
• "Write tests for the above" without providing the actual test code.
• "Similar to Task N" (always repeat the necessary code blocks; engineers may read tasks out of order).
• Steps that describe an action without showing how (e.g., missing code blocks for implementation steps).
• References to types, functions, or methods that are not explicitly defined in any task.

When multiple skills apply to a task, follow a hierarchy where process skills are executed before implementation skills. Process skills set the approach, while implementation skills carry out the work.

Common Patterns:

• Building new features: Use superpowers:brainstorming first to establish the approach, then use implementation skills (e.g., frontend-design).
• Fixing bugs: Use superpowers:systematic-debugging first, then use domain-specific skills to execute the fix.

Always prioritize process skills like brainstorming and systematic-debugging to ensure a disciplined approach.

When skills reference tools that are native to other platforms (like Claude Code), OpenCode agents should use the following mappings:

Note on Skill Directories: Skill directories may contain supporting scripts (run via bash), additional documentation (read via read tool), and skill-specific utilities.

Superpowers uses a 'detect-and-defer' strategy to handle worktrees across different AI harnesses. The mechanism used depends on whether the harness provides a native, agent-callable tool or requires a manual git fallback.

Instructions follow a specific precedence order. When resolving conflicts between different instruction sources, follow this hierarchy:

1. User Instructions (Highest Priority): Direct requests from the user or configuration files like CLAUDE.md, AGENTS.md, or GEMINI.md.
2. Superpowers Skills: The workflows defined within the superpowers repository.
3. Default Behavior (Lowest Priority): The standard operating procedure of the agent/platform.

Only skip a skill workflow if the human partner has explicitly instructed you to do so.

The server implements a zero-dependency WebSocket protocol layer to facilitate real-time communication between the server and clients (like browsers).

• Upgrades: The server handles the upgrade event to switch from HTTP to the WebSocket protocol.
• Message Handling:
  • TEXT: JSON-encoded messages are parsed. If a message contains a choice key, the event is appended to a .events file in the BRAINSTORM_DIR.
  • PING/PONG: The server responds to PING frames with PONG to maintain the connection.
  • CLOSE: Gracefully handles connection termination.
• Broadcasting: The server can broadcast messages (e.g., { "type": "reload" }) to all connected clients, triggering UI updates when files change.

When using the superpowers system, you must invoke relevant or requested skills BEFORE any response or action. This includes before asking clarifying questions, exploring the codebase, or checking files.

Workflow:

1. Identify if a skill applies (if there is even a 1% chance, you must invoke it).
2. Announce your intent using the format: Using [skill] to [purpose].
3. Follow the skill's specific instructions exactly. If the skill contains a checklist, create a todo item for each requirement.

Note on Brainstorming: Before entering 'plan mode', if you have not yet brainstormed, you must invoke the superpowers:brainstorming skill first.

To prevent cross-origin WebSocket attacks, the server enforces origin matching. When a WebSocket upgrade request is received, the server validates that the Origin header matches the Host header.

• Browser Clients: Must provide an Origin header that matches http://<host>. If the origin is cross-site, the connection is destroyed.
• Non-Browser Clients: If no Origin header is present, the server allows the connection, provided the client uses a valid session key in the query string.

Implementation logic for the check:

function isAllowedWebSocketOrigin(req) {
  const origin = req.headers.origin;
  if (!origin) return true; // non-browser clients still need the session key
  const host = req.headers.host;
  if (!host) return false;
  return origin === 'http://' + host;
}