supersaiyan

supersaiyan

A portable, installable plugin (Claude Code + Codex) that adds a mandatory pre-implementation UI investigation layer to any development workflow.

It does not replace Superpowers — it bundles it. Installing this plugin installs Superpowers as a declared dependency, so you get the full kit (brainstorming → planning → TDD → debugging → code review → finishing) plus a hard gate that runs before any of it: observe the real running UI before writing code.

What it does

When you ask the agent to fix a bug, add a feature, or change UI:

1. A UserPromptSubmit hook nudges the agent to invoke investigate-ui-first before touching code.
2. That skill confirms Playwright MCP is installed (auto-installs if missing), identifies the URL/route, and dispatches the read-only ui-validator sub-agent.
3. ui-validator drives the actual browser via Playwright MCP, takes snapshots, inspects console errors, and returns one of four verdicts: REPRODUCED, DIFFERS, NOT-REPRODUCED, BLOCKED. It has no edit tools and cannot modify code by design.
4. If the agent cannot reproduce the issue, it asks targeted questions instead of inventing behavior or coding blind.
5. Any unrelated bugs spotted during investigation are appended to .supersaiyan/discovered-bugs.md in the project root via the log-unrelated-bug skill — never silently ignored.
6. A SessionStart hook installs a sentinel-wrapped CLAUDE.md overlay that enforces these rules and tones down Superpowers' brainstorming to favor assumption-with-disclosure over back-and-forth question loops.

All of this runs without you asking for it.

Install

Claude Code

Shell one-liner (uses the claude CLI under the hood):

bash <(curl -fsSL https://raw.githubusercontent.com/florian60430/supersaiyan/main/scripts/install-claude.sh)

Or three slash commands inside a Claude Code session:

/plugin marketplace add obra/superpowers-marketplace
/plugin marketplace add florian60430/supersaiyan
/plugin install supersaiyan@supersaiyan

Either path installs both plugins (Superpowers is declared as a cross-marketplace dependency in plugin.json, so Claude Code auto-resolves it). User-level install — applies to every project on the machine, no per-project setup. See INSTALL.md for details and how the sentinel-managed CLAUDE.md injection works.

Codex

git clone https://github.com/florian60430/supersaiyan.git
cd supersaiyan
bash scripts/install-codex.sh

One command — the script also auto-clones obra/superpowers and symlinks its skills into ~/.agents/skills/ alongside ours. To skip Superpowers, set SUPERSAIYAN_SKIP_SUPERPOWERS=1. See codex/INSTALL.md for details.

Repo layout

supersaiyan/
├── .claude-plugin/marketplace.json     ← single-plugin marketplace catalog
├── plugin/                              ← the Claude Code plugin
│   ├── .claude-plugin/plugin.json
│   ├── skills/
│   │   ├── investigate-ui-first/       ← mandatory pre-impl skill
│   │   ├── playwright-mcp-setup/       ← runtime detect/install
│   │   └── log-unrelated-bug/          ← project bug log
│   ├── agents/ui-validator.md          ← read-only Playwright observer
│   ├── hooks/                          ← SessionStart + UserPromptSubmit
│   └── templates/CLAUDE.md.snippet     ← sentinel-wrapped overlay
├── codex/                               ← Codex entry point
│   ├── AGENTS.md                       ← Codex standing instructions
│   ├── agents/ui-validator.toml        ← Codex sub-agent definition
│   ├── skills/                         ← symlinks → ../plugin/skills/
│   └── INSTALL.md
└── scripts/                             ← install/uninstall + shared lib
    ├── install-codex.sh
    ├── uninstall-codex.sh
    └── lib/inject-snippet.sh

The Claude Code plugin in plugin/ is the canonical source for skill content. The Codex side uses symlinks (Codex officially supports symlinked skill folders) so there's one source of truth.

Design choices