### Develop Documentation and Guides

Source: https://github.com/abudhahir/superpowers/blob/main/docs/plans/2025-12-29-supremepower-design.md

Create comprehensive documentation, including installation guides, migration instructions, skill authoring guides, and troubleshooting resources.

```text
1. Write installation documentation for Gemini CLI
2. Create migration guide with SuperGemini examples
3. Write skills authoring guide (context hints, conditionals)
4. Document agent routing algorithm and tuning
5. Create example projects (small, medium, large)
6. Record video walkthrough (installation, basic usage, advanced features)
7. Write contribution guidelines
8. Create FAQ and troubleshooting guide
9. Set up documentation website (GitHub Pages)
10. Write blog post announcement
```

--------------------------------

### Example Workflow with Git Worktrees

Source: https://github.com/abudhahir/superpowers/blob/main/skills/using-git-worktrees/SKILL.md

Demonstrates a typical workflow using the using-git-worktrees skill, from setup to readiness for feature implementation.

```bash
You: I'm using the using-git-worktrees skill to set up an isolated workspace.

[Check .worktrees/ - exists]
[Verify ignored - git check-ignore confirms .worktrees/ is ignored]
[Create worktree: git worktree add .worktrees/auth -b feature/auth]
[Run npm install]
[Run npm test - 47 passing]

Worktree ready at /Users/jesse/myproject/.worktrees/auth
Tests passing (47 tests, 0 failures)
Ready to implement auth feature
```

--------------------------------

### Run Project Setup Commands

Source: https://github.com/abudhahir/superpowers/blob/main/core/skills/using-git-worktrees/SKILL.md

Automatically detects and runs appropriate setup commands based on project files like package.json, Cargo.toml, requirements.txt, pyproject.toml, or go.mod. Skips installation if no relevant file is found.

```bash
# Node.js
if [ -f package.json ]; then npm install; fi

# Rust
if [ -f Cargo.toml ]; then cargo build; fi

# Python
if [ -f requirements.txt ]; then pip install -r requirements.txt; fi
if [ -f pyproject.toml ]; then poetry install; fi

# Go
if [ -f go.mod ]; then go mod download; fi
```

--------------------------------

### Basic Setup for SupremePower API

Source: https://github.com/abudhahir/superpowers/blob/main/examples/README.md

Demonstrates the fundamental setup for using the SupremePower API to load agents and analyze skills. Ensure the 'supremepower' package is installed.

```javascript
import { analyzeSkillAndActivateAgents, loadAgentDefinitions } from 'supremepower';

// Load agents
const agents = loadAgentDefinitions('./core/agents');

// Analyze a skill
const result = analyzeSkillAndActivateAgents(
  skillContent,
  userMessage,
  agents
);

// Access results
console.log('Activated agents:', result.activatedAgents);
console.log('Context hints:', result.hints);
console.log('Scores:', result.scores);
```

--------------------------------

### Configuration Profiles: Setup

Source: https://github.com/abudhahir/superpowers/blob/main/docs/usage.md

Create multiple configuration profiles for different projects by copying the default config file and modifying it. This example shows setting up an 'aggressive' agent use profile.

```bash
# Project 1: aggressive agent use
cp ~/.supremepower/config.json ~/.supremepower/config-aggressive.json
# Edit: agentActivationThreshold = 4
```

--------------------------------

### Commit Installation Guide

Source: https://github.com/abudhahir/superpowers/blob/main/docs/plans/2025-11-22-opencode-support-implementation.md

Stage and commit the `.opencode/INSTALL.md` file after it has been created. This is part of the standard Git workflow to track changes in the project.

```bash
git add .opencode/INSTALL.md
git commit -m "docs: add opencode installation guide"
```

--------------------------------

### Install Superpowers Plugin

Source: https://github.com/abudhahir/superpowers/blob/main/RELEASE-NOTES.md

Use these commands to add and install the Superpowers plugin from the marketplace. The plugin handles all setup automatically.

```bash
# In Claude Code
/plugin marketplace add obra/superpowers-marketplace
/plugin install superpowers@superpowers-marketplace
```

--------------------------------

### Run Basic Usage Example

Source: https://github.com/abudhahir/superpowers/blob/main/examples/README.md

Execute the main example script to see core orchestration API in action.

```bash
node examples/basic-usage.js
```

--------------------------------

### Initiate Test-Driven Development

Source: https://github.com/abudhahir/superpowers/blob/main/docs/platforms/claude-code.md

Example command to start a Test-Driven Development workflow using the 'test-driven-development' skill.

```plaintext
Use the test-driven-development skill to implement a user search function
```

--------------------------------

### Install SupremePower from GitHub

Source: https://github.com/abudhahir/superpowers/blob/main/docs/installation.md

Install the latest version of SupremePower directly from its GitHub repository using the Gemini CLI.

```bash
gemini extensions install https://github.com/superclaude-org/supremepower-gemini
```

--------------------------------

### Install and Make Wrapper Executable

Source: https://github.com/abudhahir/superpowers/blob/main/docs/troubleshooting.md

Install the `gemini-sp` wrapper script by copying it to your local bin directory and making it executable. This is necessary if the command is not found.

```bash
cd ~/.gemini/extensions/supremepower
cp scripts/gemini-sp ~/.local/bin/
chmod +x ~/.local/bin/gemini-sp
```

--------------------------------

### Quick Install Superpowers for Codex

Source: https://github.com/abudhahir/superpowers/blob/main/docs/README.codex.md

Use this command to fetch and follow instructions for installing Superpowers with Codex.

```bash
Fetch and follow instructions from https://raw.githubusercontent.com/obra/superpowers/refs/heads/main/.codex/INSTALL.md
```

--------------------------------

### Initiate Test-Driven Development Workflow

Source: https://github.com/abudhahir/superpowers/blob/main/docs/platforms/gemini-cli.md

Start a TDD session using the '/tdd' command, then describe the feature to be implemented. The skill will guide through RED, GREEN, REFACTOR cycles.

```bash
/tdd
```

```text
I need to implement a user search function that filters by name and email
```

--------------------------------

### Manual Install OpenCode Plugin - Step 1

Source: https://github.com/abudhahir/superpowers/blob/main/docs/platforms/opencode.md

Manually install the Superpowers plugin by cloning the repository into the OpenCode configuration directory.

```bash
mkdir -p ~/.config/opencode/superpowers
git clone https://github.com/obra/superpowers.git ~/.config/opencode/superpowers
```

--------------------------------

### Install Gemini-SP Wrapper

Source: https://github.com/abudhahir/superpowers/blob/main/docs/platforms/gemini-cli.md

Manually install the optional 'gemini-sp' wrapper for automatic agent activation by creating a symbolic link.

```bash
sudo ln -s ~/.supremepower/bin/gemini-sp /usr/local/bin/gemini-sp
```

--------------------------------

### Install SupremePower via Gemini Extensions

Source: https://github.com/abudhahir/superpowers/blob/main/docs/plans/2025-12-29-supremepower-design.md

Use this command to install SupremePower from a GitHub repository using the Gemini CLI. For local development, clone the repository, install dependencies, build the project, and then link it.

```bash
# Install from GitHub
gemini extensions install https://github.com/org/supremepower

# Or install locally for development
git clone https://github.com/org/supremepower
cd supremepower
npm install
npm run build
gemini extensions link .
```

--------------------------------

### Start Development Server

Source: https://github.com/abudhahir/superpowers/blob/main/tests/subagent-driven-dev/svelte-todo/plan.md

Command to start the Vite development server for the Svelte project.

```bash
npm run dev
```

--------------------------------

### Install VS Code Extension

Source: https://github.com/abudhahir/superpowers/blob/main/README.md

Install the VS Code extension by navigating to the extension directory, installing dependencies, and compiling the code. Open the extension in VS Code using F5.

```bash
cd vscode-extension
npm install
npm run compile
# Open in VS Code (F5)
```

--------------------------------

### Install Extension from GitHub (Bash)

Source: https://github.com/abudhahir/superpowers/blob/main/docs/plans/2025-12-29-phase2-gemini-integration-design.md

Commands to install the Supremepower Gemini extension from a GitHub repository, supporting installation from the main branch, a specific version, or a pre-release.

```bash
# Install from main branch (latest)
gemini extensions install https://github.com/superclaude-org/supremepower-gemini

# Or install specific version
gemini extensions install https://github.com/superclaude-org/supremepower-gemini --ref=v2.0.0

# Or install pre-release
gemini extensions install https://github.com/superclaude-org/supremepower-gemini --pre-release
```

--------------------------------

### Install Node.js Dependencies

Source: https://github.com/abudhahir/superpowers/blob/main/docs/vscode-extension.md

Run this command in the extension's directory to install all necessary npm packages.

```bash
npm install
```

--------------------------------

### Manual Installation of SupremePower

Source: https://github.com/abudhahir/superpowers/blob/main/docs/plans/2025-12-29-supremepower-design.md

This method involves cloning the repository and running an installation script. The script copies core components, agents, commands, hooks, and merges settings.

```bash
# Clone repository
git clone https://github.com/org/supremepower
cd supremepower

# Run installation script
./adapters/gemini-cli/install.sh

# Installation script performs:
# 1. Copy core/skills/ → ~/.gemini/skills/
# 2. Copy core/agents/ → ~/.gemini/agents/
# 3. Copy commands/*.toml → ~/.gemini/commands/
# 4. Install hooks → ~/.gemini/hooks/
# 5. Merge settings.json.template → ~/.gemini/settings.json
# 6. Copy GEMINI.md → ~/.gemini/GEMINI.md
```

--------------------------------

### Install SupremePower Extension

Source: https://github.com/abudhahir/superpowers/blob/main/tests/e2e/README.md

Installs the SupremePower extension locally. Navigate to the extension's directory before running this command.

```bash
cd /path/to/supremepower
gemini extension install .
```

--------------------------------

### Install Wrapper Script

Source: https://github.com/abudhahir/superpowers/blob/main/docs/plans/2025-12-29-phase2-implementation.md

Installs the gemini-sp wrapper script by creating a directory if it doesn't exist and creating a symbolic link to the script. It also provides instructions on how to add the installation path to the system's PATH environment variable.

```bash
echo
echo "Would you like to install the gemini-sp wrapper script for automatic agent activation?"
read -p "(y/n) " -n 1 -r
echo

if [[ $REPLY =~ ^[Yy]$ ]]; then
  INSTALL_PATH="$HOME/.local/bin"
  mkdir -p "$INSTALL_PATH"

  EXTENSION_PATH="$(pwd)"
  ln -sf "$EXTENSION_PATH/scripts/gemini-sp" "$INSTALL_PATH/gemini-sp"

  echo "Wrapper script installed to: $INSTALL_PATH/gemini-sp"
  echo
  echo "Make sure $INSTALL_PATH is in your PATH:"
  echo "  export PATH=\"	$HOME/.local/bin:$PATH\"
fi

echo
echo "=== Installation Complete ==="
echo
echo "Next steps:"
echo "  1. Restart Gemini CLI to load the extension"
echo "  2. Try: /brainstorm 'test the extension'"
echo "  3. Try: /sp:agents (list available agents)"
echo "  4. Try: gemini-sp 'help me build a React app' (if wrapper installed)"
echo
echo "Documentation: https://github.com/superclaude-org/supremepower-gemini"
```

--------------------------------

### Example Compression (Markdown)

Source: https://github.com/abudhahir/superpowers/blob/main/core/skills/writing-skills/SKILL.md

Demonstrates compressing examples in Markdown to save tokens. The goal is to reduce the word count while retaining essential information.

```markdown
# ❌ BAD: Verbose example (42 words)
your human partner: "How did we handle authentication errors in React Router before?"
You: I'll search past conversations for React Router authentication patterns.
[Dispatch subagent with search query: "React Router authentication error handling 401"]

# ✅ GOOD: Minimal example (20 words)
Partner: "How did we handle auth errors in React Router?"
You: Searching...
[Dispatch subagent → synthesis]
```

--------------------------------

### Install SupremePower Extension

Source: https://github.com/abudhahir/superpowers/blob/main/docs/platforms/gemini-cli.md

Installs the SupremePower extension from GitHub into Gemini CLI. Use the `--ref` flag to specify a version.

```bash
gemini extensions install https://github.com/abudhahir/superpowers
```

```bash
gemini extensions install https://github.com/abudhahir/superpowers --ref=v2.0.0
```

--------------------------------

### Verify Wrapper Installation

Source: https://github.com/abudhahir/superpowers/blob/main/docs/troubleshooting.md

After installation and PATH configuration, use `which gemini-sp` to confirm that the system can locate the wrapper script.

```bash
which gemini-sp
```

--------------------------------

### Quick Install Superpowers for OpenCode

Source: https://github.com/abudhahir/superpowers/blob/main/docs/README.opencode.md

Use this command to quickly install the Superpowers plugin for OpenCode. It clones the repository, creates necessary directories, and sets up a symlink.

```bash
Clone https://github.com/obra/superpowers to ~/.config/opencode/superpowers, then create directory ~/.config/opencode/plugin, then symlink ~/.config/opencode/superpowers/.opencode/plugin/superpowers.js to ~/.config/opencode/plugin/superpowers.js, then restart opencode.
```

--------------------------------

### Install Wrapper Script System-Wide on Linux

Source: https://github.com/abudhahir/superpowers/blob/main/docs/installation.md

For a system-wide installation of the wrapper script on Linux, copy it to `/usr/local/bin/` and set execute permissions using `sudo`.

```bash
sudo cp scripts/gemini-sp /usr/local/bin/
sudo chmod +x /usr/local/bin/gemini-sp
```

--------------------------------

### Local Development Installation of SupremePower

Source: https://github.com/abudhahir/superpowers/blob/main/docs/installation.md

Set up SupremePower for local development by cloning the repository, installing dependencies, building the project, and linking it as a local extension.

```bash
git clone https://github.com/superclaude-org/supremepower-gemini.git
cd supremepower-gemini
npm install
npm run build
gemini extensions link .
```

--------------------------------

### Custom Skill Frontmatter Example

Source: https://github.com/abudhahir/superpowers/blob/main/docs/platforms/codex.md

Example of the required frontmatter for a custom skill's SKILL.md file, including name and description.

```markdown
---
name: my-custom-skill
description: Use when you need to do X, Y, or Z
---

# My Custom Skill

## Overview
[Detailed instructions for Codex...]

## When to Use
This skill applies when:
- Condition 1
- Condition 2

## Workflow
1. Step 1
2. Step 2
3. Step 3

## Tool Mapping for Codex
This skill references these tools:
- Use native Codex tools for file operations
- Manual task tracking instead of TodoWrite
```

--------------------------------

### Install Custom Skills from Git

Source: https://github.com/abudhahir/superpowers/blob/main/docs/platforms/gemini-cli.md

Fetches and installs custom skills from a specified Git repository URL within the Gemini CLI.

```bash
# In Gemini CLI
/skills:fetch-skills <your-repo-url>
```

--------------------------------

### Install Superpowers Plugin for OpenCode

Source: https://github.com/abudhahir/superpowers/blob/main/docs/README.opencode.md

Manual installation steps for the Superpowers plugin. This involves cloning the repository and creating a symlink for the plugin.

```bash
mkdir -p ~/.config/opencode/superpowers
git clone https://github.com/obra/superpowers.git ~/.config/opencode/superpowers
```

```bash
mkdir -p ~/.config/opencode/plugin
ln -sf ~/.config/opencode/superpowers/.opencode/plugin/superpowers.js ~/.config/opencode/plugin/superpowers.js
```

--------------------------------

### Skill Description Examples (YAML)

Source: https://github.com/abudhahir/superpowers/blob/main/core/skills/writing-skills/SKILL.md

Examples of good and bad skill descriptions in YAML format. Focus on 'Use when...' for triggering conditions and avoid workflow summaries.

```yaml
# ❌ BAD: Summarizes workflow - Claude may follow this instead of reading skill
description: Use when executing plans - dispatches subagent per task with code review between tasks

# ❌ BAD: Too much process detail
description: Use for TDD - write test first, watch it fail, write minimal code, refactor

# ✅ GOOD: Just triggering conditions, no workflow summary
description: Use when executing implementation plans with independent tasks in the current session

# ✅ GOOD: Triggering conditions only
description: Use when implementing any feature or bugfix, before writing implementation code
```

```yaml
# ❌ BAD: Too abstract, vague, doesn't include when to use
description: For async testing

# ❌ BAD: First person
description: I can help you with async tests when they're flaky

# ❌ BAD: Mentions technology but skill isn't specific to it
description: Use when tests use setTimeout/sleep and are flaky

# ✅ GOOD: Starts with "Use when", describes problem, no workflow
description: Use when tests have race conditions, timing dependencies, or pass/fail inconsistently

# ✅ GOOD: Technology-specific skill with explicit trigger
description: Use when using React Router and handling authentication redirects
```

--------------------------------

### Manual Installation: Create Skills Directory

Source: https://github.com/abudhahir/superpowers/blob/main/docs/platforms/codex.md

Creates a directory for personal skills.

```bash
mkdir -p ~/.codex/skills
```

--------------------------------

### High Freedom Instruction Example

Source: https://github.com/abudhahir/superpowers/blob/main/core/skills/writing-skills/anthropic-best-practices.md

Use high freedom instructions when multiple approaches are valid, decisions depend on context, or heuristics guide the approach. This example outlines a code review process.

```markdown
## Code review process

1. Analyze the code structure and organization
2. Check for potential bugs or edge cases
3. Suggest improvements for readability and maintainability
4. Verify adherence to project conventions
```

--------------------------------

### Invoke TDD Skill

Source: https://github.com/abudhahir/superpowers/blob/main/docs/platforms/gemini-cli.md

Starts the test-driven development workflow in Gemini CLI, guiding through the RED-GREEN-REFACTOR cycle.

```bash
/tdd
```

--------------------------------

### Create Implementation Plan with /plan

Source: https://github.com/abudhahir/superpowers/blob/main/docs/usage.md

Generate a detailed, step-by-step implementation plan with success criteria using the /plan command. It breaks down tasks, identifies risks, and defines testing approaches.

```bash
/plan "OAuth2 integration with Google and GitHub"
```

--------------------------------

### Receive Code Review Feedback

Source: https://github.com/abudhahir/superpowers/blob/main/docs/platforms/claude-code.md

Example command to start processing feedback after a code review using the 'receiving-code-review' skill.

```plaintext
Use the receiving-code-review skill
```

--------------------------------

### Post-Installation Commands for Gemini CLI

Source: https://github.com/abudhahir/superpowers/blob/main/docs/plans/2025-12-29-supremepower-design.md

After installation, restart the Gemini CLI to load the extension. Use the /help command to verify the installation and then test basic functionality with a sample command.

```bash
# Restart Gemini CLI to load extension
gemini --restart

# Verify installation
/help  # Should show /supremepower:* commands

# Test basic functionality
/supremepower:brainstorm "How should I structure my API?"
```

--------------------------------

### Create Installation Script

Source: https://github.com/abudhahir/superpowers/blob/main/docs/plans/2025-12-29-phase2-implementation.md

A bash script to set up the necessary directories for the SupremePower extension, including logs, skills, and agents.

```bash
#!/usr/bin/env bash
set -euo pipefail

echo "=== SupremePower Extension Installation ==="
echo

# Create user directory
SUPREMEPOWER_DIR="$HOME/.supremepower"
echo "Creating SupremePower directory: $SUPREMEPOWER_DIR"
mkdir -p "$SUPREMEPOWER_DIR"/{skills,agents,logs}
```

--------------------------------

### Finish Development Branch Workflow

Source: https://github.com/abudhahir/superpowers/blob/main/docs/platforms/claude-code.md

Example command to conclude a development branch workflow, guiding through merge, PR creation, or cleanup.

```plaintext
Use the finishing-a-development-branch skill
```

--------------------------------

### Quick Diagnostic Checklist

Source: https://github.com/abudhahir/superpowers/blob/main/docs/troubleshooting.md

A checklist to quickly verify common setup and configuration points for the Supremepower Gemini extension. Run these commands to check installation, configuration validity, build status, command existence, wrapper installation, logs, and agent availability.

```bash
# 1. Extension installed and active?
gemini extensions list

# 2. Config valid?
cat ~/.supremepower/config.json | jq .

# 3. MCP server built?
ls -la ~/.gemini/extensions/supremepower/mcp-server/dist/server.js

# 4. Commands exist?
ls ~/.gemini/extensions/supremepower/commands/sp/

# 5. Wrapper installed?
which gemini-sp

# 6. Logs show errors?
tail -n 20 ~/.supremepower/logs/errors.log

# 7. Config loading?
/sp:status

# 8. Agents available?
/sp:agents
```

--------------------------------

### Example: Generic Data Processing Skill Description

Source: https://github.com/abudhahir/superpowers/blob/main/skills/writing-skills/anthropic-best-practices.md

Illustrates a generic description that should be avoided. Descriptions must be specific to guide Claude effectively.

```yaml
description: Processes data
```

--------------------------------

### Initializing Git Repository for Extensions

Source: https://github.com/abudhahir/superpowers/blob/main/docs/extending.md

Initialize a Git repository, add your skills and agents, and set up a remote origin for pushing your extensions.

```bash
cd ~/.supremepower
git init
git add skills/ agents/
git commit -m "My SupremePower extensions"
git remote add origin https://github.com/yourname/supremepower-extensions
git push -u origin main
```

--------------------------------

### Workflow Example: Debugging Production Issue

Source: https://github.com/abudhahir/superpowers/blob/main/docs/usage.md

Use this workflow for debugging production issues, starting with the debug command and proceeding through investigation and verification steps.

```bash
/debug
```

```bash
/skills:verification-before-completion
```

```bash
/skills:requesting-code-review "rate limiting fix" --focus=performance
```

--------------------------------

### Initialize Repository Structure

Source: https://github.com/abudhahir/superpowers/blob/main/docs/plans/2025-12-29-supremepower-design.md

Set up the core repository structure for the SupremePower project, including the adapter pattern and initial modules.

```text
1. Initialize repository with adapter pattern structure
2. Copy and validate all Superpowers skills
3. Copy and enhance SuperGemini agent definitions with YAML frontmatter
4. Implement context-parser.js (extract hints from skills)
5. Implement agent-matcher.js (score and select agents)
6. Implement conditional-evaluator.js (if/then rules)
7. Write unit tests for core modules
```

--------------------------------

### Run Baseline Tests

Source: https://github.com/abudhahir/superpowers/blob/main/core/skills/using-git-worktrees/SKILL.md

Executes project-specific test commands to verify the worktree starts from a clean baseline. Examples include npm test, cargo test, pytest, and go test.

```bash
# Examples - use project-appropriate command
npm test
cargo test
pytest
go test ./...
```

--------------------------------

### Manual Install OpenCode Plugin - Step 2

Source: https://github.com/abudhahir/superpowers/blob/main/docs/platforms/opencode.md

Register the Superpowers plugin by creating a symbolic link from the cloned repository to the OpenCode plugin directory.

```bash
mkdir -p ~/.config/opencode/plugin
ln -sf ~/.config/opencode/superpowers/.opencode/plugin/superpowers.js ~/.config/opencode/plugin/superpowers.js
```

--------------------------------

### Failing Test Case Example

Source: https://github.com/abudhahir/superpowers/blob/main/tests/skill-triggering/prompts/systematic-debugging.txt

This snippet shows a typical test failure output, indicating a TypeError during parsing. It points to the specific file, line number, and error message, guiding the debugging process.

```text
FAIL src/utils/parser.test.ts
  ● Parser › should handle nested objects
    TypeError: Cannot read property 'value' of undefined
      at parse (src/utils/parser.ts:42:18)
      at Object.<anonymous> (src/utils/parser.test.ts:28:20)
```

--------------------------------

### Commit Message Examples

Source: https://github.com/abudhahir/superpowers/blob/main/core/skills/writing-skills/anthropic-best-practices.md

Provide input/output pairs to guide Claude on desired commit message formats. This helps in generating messages that follow a specific style, including type, scope, and detailed explanations.

```markdown
feat(auth): implement JWT-based authentication

Add login endpoint and token validation middleware
```

```markdown
fix(reports): correct date formatting in timezone conversion

Use UTC timestamps consistently across report generation
```

```markdown
chore: update dependencies and refactor error handling

- Upgrade lodash to 4.17.21
- Standardize error response format across endpoints
```

--------------------------------

### SKILL.md Frontmatter Example

Source: https://github.com/abudhahir/superpowers/blob/main/core/skills/writing-skills/SKILL.md

The frontmatter for a SKILL.md file requires 'name' and 'description' fields. The 'name' should use only letters, numbers, and hyphens, while the 'description' should focus on triggering conditions and symptoms, starting with 'Use when...'.

```markdown
---
name: Skill-Name-With-Hyphens
description: Use when [specific triggering conditions and symptoms]
---
```

--------------------------------

### Integration Test: Extension Setup

Source: https://github.com/abudhahir/superpowers/blob/main/docs/plans/2025-12-29-phase2-implementation.md

Tests the integration of the extension by ensuring the MCP server starts correctly and lists all expected tools. It uses Jest for testing and imports necessary functions from the MCP server.

```javascript
import { describe, it, expect, beforeAll } from '@jest/globals';
import { createMCPServer } from '../../mcp-server/dist/server.js';

describe('Extension Integration', () => {
  let server;

  beforeAll(async () => {
    const result = createMCPServer();
    server = result.server;
  });

  it('should load all MCP tools', () => {
    const tools = server.listTools();

    expect(tools).toContain('activate_agents');
    expect(tools).toContain('get_agent_persona');
    expect(tools).toContain('list_skills');
    expect(tools).toContain('fetch_skills');
    expect(tools).toContain('auto_agent_create');
  });

  it('should handle full orchestration workflow', async () => {
    const { handleActivateAgents } = await import('../../mcp-server/dist/tools/activate-agents.js');

    const result = await handleActivateAgents({
      userMessage: 'help me build a React component with performance optimization',
    });

    expect(result.content[0].text).toContain('Frontend Architect');
    expect(result.content[0].text).toContain('Performance Engineer');
  });
});
```

--------------------------------

### Run Post-Install Script Manually

Source: https://github.com/abudhahir/superpowers/blob/main/docs/troubleshooting.md

Execute the extension's post-install script manually if it fails during the initial installation process.

```bash
cd ~/.gemini/extensions/supremepower
bash scripts/install.sh
```

--------------------------------

### Project-Local Plugin Installation

Source: https://github.com/abudhahir/superpowers/blob/main/docs/README.opencode.md

Installs the Superpowers plugin locally within an OpenCode project. This is an alternative to global installation.

```bash
# In your OpenCode project
mkdir -p .opencode/plugin
ln -sf ~/.config/opencode/superpowers/.opencode/plugin/superpowers.js .opencode/plugin/superpowers.js
```

--------------------------------

### Create and Set Permissions for .supremepower Directory

Source: https://github.com/abudhahir/superpowers/blob/main/docs/troubleshooting.md

Manually create the ~/.supremepower directory and set appropriate permissions if the post-install script fails due to permission denied errors.

```bash
ls -ld ~
```

```bash
mkdir -p ~/.supremepower
chmod 755 ~/.supremepower
```

--------------------------------

### Skills Library - Process-Oriented Example

Source: https://github.com/abudhahir/superpowers/blob/main/skills/writing-skills/examples/CLAUDE_MD_TESTING.md

This documentation variant outlines a clear, step-by-step workflow for agents to follow when working with skills, emphasizing the importance of checking for and using skills to avoid common mistakes.

```markdown
## Working with Skills

Your workflow for every task:

1. **Before starting:** Check for relevant skills
   - Browse: `ls ~/.claude/skills/`
   - Search: `grep -r "symptom" ~/.claude/skills/`

2. **If skill exists:** Read it completely before proceeding

3. **Follow the skill** - it encodes lessons from past failures

The skills library prevents you from repeating common mistakes. 
Not checking before you start is choosing to repeat those mistakes.

Start here: `skills/using-skills`
```

--------------------------------

### Install Supremepower Gemini Extension

Source: https://github.com/abudhahir/superpowers/blob/main/docs/troubleshooting.md

Install the Supremepower Gemini extension if it is not found or listed. This command installs the extension from a GitHub repository.

```bash
gemini extensions list
# If not listed:
gemini extensions install https://github.com/superclaude-org/supremepower-gemini
```

--------------------------------

### Add and Install SupremePower Marketplace

Source: https://github.com/abudhahir/superpowers/blob/main/docs/platforms/claude-code.md

Commands to add the Superpowers marketplace and install the plugin. Ensure you have the Claude Code CLI installed.

```bash
/plugin marketplace add obra/superpowers-marketplace

/plugin install superpowers@superpowers-marketplace
```

--------------------------------

### Initializing Git Repository for Custom Skills

Source: https://github.com/abudhahir/superpowers/blob/main/docs/platforms/claude-code.md

Steps to initialize a Git repository, add a custom skill, and push it to a remote origin.

```bash
cd ~/.claude/skills
git init
git add my-custom-skill/
git commit -m "Add custom skill"
git remote add origin <your-repo-url>
git push
```

--------------------------------

### Check Git Installation

Source: https://github.com/abudhahir/superpowers/blob/main/docs/troubleshooting.md

Ensure Git is installed on your system. If not, install it using your package manager (e.g., Homebrew for macOS, apt for Ubuntu/Debian).

```bash
git --version
```

```bash
# macOS
brew install git
```

```bash
# Ubuntu/Debian
sudo apt install git
```

--------------------------------

### Create a Custom Skill Directory

Source: https://github.com/abudhahir/superpowers/blob/main/docs/platforms/gemini-cli.md

Sets up the necessary directory structure for a new custom skill.

```bash
mkdir -p ~/.supremepower/skills/my-skill
```

--------------------------------

### Install Playwright

Source: https://github.com/abudhahir/superpowers/blob/main/tests/subagent-driven-dev/svelte-todo/plan.md

Command to install Playwright for end-to-end testing.

```bash
npm init playwright@latest
```

--------------------------------

### Install VS Code Extension

Source: https://github.com/abudhahir/superpowers/blob/main/docs/phase3-active-engine.md

Install the VS Code extension from source. This involves navigating to the extension directory, installing dependencies, compiling the code, and then debugging within VS Code.

```bash
cd .worktrees/phase3-active-engine/vscode-extension
npm install
npm run compile
# Then open in VS Code and press F5 to debug
```

--------------------------------

### Use gemini-sp for Simple Queries

Source: https://context7.com/abudhahir/superpowers/llms.txt

Demonstrates using the `gemini-sp` wrapper for a simple query. Queries below a certain complexity threshold are passed through unchanged.

```bash
gemini-sp "What is JavaScript?"
```

--------------------------------

### Check Git Version

Source: https://github.com/abudhahir/superpowers/blob/main/docs/installation.md

Ensure Git is installed, which is necessary for GitHub-based installations.

```bash
git --version
```

--------------------------------

### Install and Verify SupremePower Extension

Source: https://context7.com/abudhahir/superpowers/llms.txt

Commands to install the SupremePower extension for Gemini CLI, link it locally for development, and verify its installation and status. Includes checking the MCP server and slash commands.

```bash
gemini extensions install https://github.com/superclaude-org/supremepower-gemini

# Or clone and link locally for development
git clone https://github.com/superclaude-org/supremepower-gemini.git
cd supremepower-gemini
npm install
npm run build
gemini extensions link .

# Verify installation
gemini extensions list
# supremepower (v2.0.0) - Active

# Start Gemini CLI and check system status
/sp:status
# SupremePower Status:
# - Version: 2.0.0
# - Skills loaded: 14
# - Agents loaded: 13
# - Config path: ~/.supremepower/config.json
# - MCP server: Active

# Optionally install the automatic orchestration wrapper
cp scripts/gemini-sp ~/.local/bin/gemini-sp
chmod +x ~/.local/bin/gemini-sp
```

--------------------------------

### Example of Skill File Organization (Reusable Tool)

Source: https://github.com/abudhahir/superpowers/blob/main/skills/writing-skills/SKILL.md

This structure illustrates a skill that includes a reusable tool, such as a helper script or library. The SKILL.md file provides the overview and patterns, while a separate file (e.g., example.ts) contains the working code to adapt.

```tree
condition-based-waiting/
  SKILL.md    # Overview + patterns
  example.ts  # Working helpers to adapt
```

--------------------------------

### Verify SupremePower Installation

Source: https://github.com/abudhahir/superpowers/blob/main/docs/plans/2025-12-29-phase2-implementation.md

Verify the installation of the SupremePower extension by listing available agents.

```bash
# In Gemini CLI
/sp:agents
```

--------------------------------

### Directory Structure Example

Source: https://github.com/abudhahir/superpowers/blob/main/core/skills/writing-skills/SKILL.md

Skills are organized in a flat namespace under the 'skills/' directory. Each skill has a dedicated subdirectory containing at least 'SKILL.md'. Supporting files or heavy reference material can be placed in separate files.

```bash
skills/
  skill-name/
    SKILL.md              # Main reference (required)
    supporting-file.*	     # Only if needed
```

--------------------------------

### Install Gemini Extension from Specific Version

Source: https://github.com/abudhahir/superpowers/blob/main/docs/installation.md

To install a specific version of the extension, first uninstall the current version, then install using a GitHub URL with a specified reference (tag or branch). User configuration is preserved.

```bash
gemini extensions uninstall supremepower
gemini extensions install https://github.com/superclaude-org/supremepower-gemini --ref=v2.1.0
```

--------------------------------

### Commit Installation Changes

Source: https://github.com/abudhahir/superpowers/blob/main/docs/plans/2025-12-29-phase2-implementation.md

Stages and commits the installation script and updated extension manifest to the Git repository.

```bash
git add scripts/install.sh gemini-extension.json
git commit -m "feat: add installation script with post-install setup"
```

--------------------------------

### Verify Superpowers Installation with Codex

Source: https://github.com/abudhahir/superpowers/blob/main/docs/README.codex.md

Command to run after installation to check if Codex can find available skills.

```bash
Run ~/.codex/superpowers/.codex/superpowers-codex find-skills to show available skills
```