|
| 1 | +# superpowers |
| 2 | + |
| 3 | +[中文文档](./README_CN.md) |
| 4 | + |
| 5 | +A comprehensive, battle-tested skills library for ZCode: brainstorming, test-driven development, systematic debugging, planning, code review, and subagent-driven development — packaged for ZCode from [obra/superpowers](https://github.com/obra/superpowers) v7.0.0. |
| 6 | + |
| 7 | +## What it does |
| 8 | + |
| 9 | +1. **Bootstraps skills awareness at every session start.** A `SessionStart` hook injects the `using-superpowers` skill into the model context, wrapped so the agent treats it as a hard rule: *if a skill might apply — even a 1% chance — invoke it before acting.* This bootstrap is what makes the rest of the library active instead of inert files on disk. |
| 10 | +2. **Installs 15 workflow skills that auto-trigger by context.** Skills are discovered from their `name` + `description` frontmatter and invoked with ZCode's native `Skill` tool as `superpowers:<name>` (e.g. `superpowers:brainstorming`). You can also invoke them explicitly from the composer's skill picker. |
| 11 | + |
| 12 | +Typical effect: a request like *"Let's make a react todo list"* triggers `superpowers:brainstorming` to refine the design **before** any code is written; *"fix this bug"* triggers `superpowers:systematic-debugging` before any patching. |
| 13 | + |
| 14 | +## The skills |
| 15 | + |
| 16 | +| Skill | Use it for | |
| 17 | +| --- | --- | |
| 18 | +| `brainstorming` | Refine a rough idea into a validated design before any implementation | |
| 19 | +| `test-driven-development` | RED / GREEN / REFACTOR discipline: no production code without a failing test first | |
| 20 | +| `systematic-debugging` | Find root causes with a four-phase framework instead of patching symptoms | |
| 21 | +| `writing-plans` | Turn a validated design into a detailed implementation plan with exact file changes | |
| 22 | +| `executing-plans` | Execute a written plan task by task, with verification per task | |
| 23 | +| `subagent-driven-development` | Execute a plan via per-task implementer/reviewer subagent pairs | |
| 24 | +| `dispatching-parallel-agents` | Fan out independent subagent work and collect the results | |
| 25 | +| `requesting-code-review` | Hand a clean, reviewable changeset to a code-reviewer | |
| 26 | +| `receiving-code-review` | Respond to review feedback with technical judgment, not blind compliance | |
| 27 | +| `verification-before-completion` | Claim "done" only with evidence (tests run, output shown) | |
| 28 | +| `finishing-a-development-branch` | Decide merge / PR / cleanup after verification passes | |
| 29 | +| `using-git-worktrees` | Isolated worktrees for parallel tasks and risky experiments | |
| 30 | +| `writing-skills` | Create or edit skills with testing discipline (used to maintain this library) | |
| 31 | +| `using-superpowers` | The meta-skill: how to find and use skills (injected at session start) | |
| 32 | +| `diagnosing-superpowers` | Diagnose sessions where skills did not trigger or the workflow failed | |
| 33 | + |
| 34 | +## Structure |
| 35 | + |
| 36 | +```text |
| 37 | +superpowers/ |
| 38 | +├── .zcode-plugin/plugin.json # manifest |
| 39 | +├── skills/<name>/SKILL.md # 15 skills with references, prompts, and helper scripts |
| 40 | +├── hooks/hooks.json # SessionStart registration (auto-discovered) |
| 41 | +├── hooks/session-start.mjs # bootstrap injector (Node, no dependencies) |
| 42 | +├── LICENSE # MIT (upstream + packaging) |
| 43 | +├── README.md / README_CN.md |
| 44 | +``` |
| 45 | + |
| 46 | +## Hook: SessionStart bootstrap |
| 47 | + |
| 48 | +| Event | Matcher | What it does | |
| 49 | +| --- | --- | --- | |
| 50 | +| `SessionStart` | `startup\|clear\|compact` | Runs `hooks/session-start.mjs`, which reads `skills/using-superpowers/SKILL.md`, strips the frontmatter, and returns it as `hookSpecificOutput.additionalContext` so it enters the model context. | |
| 51 | + |
| 52 | +Side effects, explicitly: |
| 53 | + |
| 54 | +- The hook **reads one file inside the plugin directory**. It writes nothing, makes no network requests, and collects nothing. |
| 55 | +- It requires `node` on `PATH` (any recent version; the script uses only Node built-ins). If the skill file cannot be read, it exits cleanly and the session continues without the bootstrap. |
| 56 | +- ZCode snapshots hook configuration when a session starts: after installing or enabling the plugin, open a **new session** to see the bootstrap. |
| 57 | +- Manual smoke test: |
| 58 | + |
| 59 | + ```shell |
| 60 | + printf '%s\n' '{"hook_event_name":"SessionStart","session_id":"manual","source":"startup"}' \ |
| 61 | + | node hooks/session-start.mjs |
| 62 | + ``` |
| 63 | + |
| 64 | + Stdout must be a single JSON object with `hookSpecificOutput.hookEventName = "SessionStart"`. Diagnostics go to stderr only. |
| 65 | + |
| 66 | +Some skills ship small helper scripts under `skills/*/scripts/` and run them only when the skill's workflow calls for it (invoked through their interpreter, e.g. `bash scripts/start-server.sh` or `node ./render-graphs.js`); they operate on the current workspace. |
| 67 | + |
| 68 | +## Install |
| 69 | + |
| 70 | +1. In ZCode, open the plugin manager (**Settings → Plugin Management → Discover**), find **superpowers**, and install it. It is enabled by default. |
| 71 | +2. Start a **new session**. |
| 72 | +3. Smoke check: ask *"What are your superpowers?"* — the agent should describe its skills. |
| 73 | +4. Try it: send *"Let's make a react todo list"* in a clean session — the agent should invoke `superpowers:brainstorming` before writing any code. |
| 74 | + |
| 75 | +## Provenance and license |
| 76 | + |
| 77 | +- All skill content is vendored from [obra/superpowers](https://github.com/obra/superpowers) **v7.0.0** (commit `bb92a77`), MIT License © Jesse Vincent. See [LICENSE](./LICENSE). |
| 78 | +- This packaging's ZCode-specific changes: the `.zcode-plugin` manifest, the Node `SessionStart` hook, `skills/using-superpowers/references/zcode-tools.md` (tool mapping for ZCode), one pointer line in `using-superpowers/SKILL.md`'s "Platform Adaptation" list, and the README/LICENSE files. Everything else is verbatim upstream so future upstream releases can be re-synced cleanly. |
0 commit comments