docs: align skill workflow documentation
This commit is contained in:
Stefano Fiorini
@@ -44,8 +44,12 @@ Verify:
|
||||
|
||||
```bash
|
||||
test -f ~/.claude/skills/superpowers/brainstorming/SKILL.md
|
||||
test -f ~/.claude/skills/superpowers/writing-plans/SKILL.md
|
||||
test -f ~/.claude/skills/superpowers/test-driven-development/SKILL.md
|
||||
test -f ~/.claude/skills/superpowers/verification-before-completion/SKILL.md
|
||||
test -f ~/.claude/skills/superpowers/finishing-a-development-branch/SKILL.md
|
||||
test -f ~/.claude/skills/superpowers/executing-plans/SKILL.md
|
||||
test -f ~/.claude/skills/superpowers/using-git-worktrees/SKILL.md
|
||||
```
|
||||
|
||||
## Verify
|
||||
|
||||
@@ -50,6 +50,8 @@ Verify execution skills:
|
||||
test -f ~/.agents/skills/superpowers/test-driven-development/SKILL.md
|
||||
test -f ~/.agents/skills/superpowers/verification-before-completion/SKILL.md
|
||||
test -f ~/.agents/skills/superpowers/finishing-a-development-branch/SKILL.md
|
||||
test -f ~/.agents/skills/superpowers/executing-plans/SKILL.md
|
||||
test -f ~/.agents/skills/superpowers/using-git-worktrees/SKILL.md
|
||||
```
|
||||
|
||||
## Verify
|
||||
|
||||
+21
-12
@@ -12,7 +12,8 @@ Create structured implementation plans with milestone and story tracking, and op
|
||||
- `superpowers:writing-plans`
|
||||
- For Codex, native skill discovery must be configured:
|
||||
- `~/.agents/skills/superpowers -> ~/.codex/superpowers/skills`
|
||||
- For Cursor, skills must be installed under `.cursor/skills/` (repo-local) or `~/.cursor/skills/` (global)
|
||||
- Cursor can use the Cursor Superpowers plugin cache or manual `.cursor/skills/superpowers/skills` / `~/.cursor/skills/superpowers/skills` installs.
|
||||
- OpenCode can use `~/.agents/skills/superpowers` or `~/.config/opencode/skills/superpowers`.
|
||||
- Shared reviewer runtime must be installed beside agent skills when using reviewer CLIs:
|
||||
- Codex: `~/.codex/skills/reviewer-runtime/{run-review.sh,notify-telegram.sh}`
|
||||
- Claude Code: `~/.claude/skills/reviewer-runtime/{run-review.sh,notify-telegram.sh}`
|
||||
@@ -34,6 +35,7 @@ To use the iterative plan review feature, one of these CLIs must be installed:
|
||||
| `codex` | `npm install -g @openai/codex` | `codex --version` |
|
||||
| `claude` | `npm install -g @anthropic-ai/claude-code` | `claude --version` |
|
||||
| `cursor` | `curl https://cursor.com/install -fsS \| bash` | `cursor-agent --version` (binary: `cursor-agent`; alias `cursor agent` also works) |
|
||||
| `opencode` | `brew install opencode` or your package manager | `opencode --version` |
|
||||
| `pi` | Install Pi coding agent | `pi --version`; list models with `pi --list-models [search]` |
|
||||
|
||||
The reviewer CLI is independent of which agent is running the planning — e.g., Claude Code can send plans to Codex for review, and vice versa.
|
||||
@@ -48,7 +50,8 @@ The reviewer CLI is independent of which agent is running the planning — e.g.,
|
||||
mkdir -p ~/.codex/skills/create-plan
|
||||
cp -R skills/create-plan/codex/* ~/.codex/skills/create-plan/
|
||||
mkdir -p ~/.codex/skills/reviewer-runtime
|
||||
cp -R skills/reviewer-runtime/* ~/.codex/skills/reviewer-runtime/
|
||||
cp skills/reviewer-runtime/run-review.sh skills/reviewer-runtime/notify-telegram.sh ~/.codex/skills/reviewer-runtime/
|
||||
chmod +x ~/.codex/skills/reviewer-runtime/*.sh
|
||||
```
|
||||
|
||||
### Claude Code
|
||||
@@ -57,7 +60,8 @@ cp -R skills/reviewer-runtime/* ~/.codex/skills/reviewer-runtime/
|
||||
mkdir -p ~/.claude/skills/create-plan
|
||||
cp -R skills/create-plan/claude-code/* ~/.claude/skills/create-plan/
|
||||
mkdir -p ~/.claude/skills/reviewer-runtime
|
||||
cp -R skills/reviewer-runtime/* ~/.claude/skills/reviewer-runtime/
|
||||
cp skills/reviewer-runtime/run-review.sh skills/reviewer-runtime/notify-telegram.sh ~/.claude/skills/reviewer-runtime/
|
||||
chmod +x ~/.claude/skills/reviewer-runtime/*.sh
|
||||
```
|
||||
|
||||
### OpenCode
|
||||
@@ -66,7 +70,8 @@ cp -R skills/reviewer-runtime/* ~/.claude/skills/reviewer-runtime/
|
||||
mkdir -p ~/.config/opencode/skills/create-plan
|
||||
cp -R skills/create-plan/opencode/* ~/.config/opencode/skills/create-plan/
|
||||
mkdir -p ~/.config/opencode/skills/reviewer-runtime
|
||||
cp -R skills/reviewer-runtime/* ~/.config/opencode/skills/reviewer-runtime/
|
||||
cp skills/reviewer-runtime/run-review.sh skills/reviewer-runtime/notify-telegram.sh ~/.config/opencode/skills/reviewer-runtime/
|
||||
chmod +x ~/.config/opencode/skills/reviewer-runtime/*.sh
|
||||
```
|
||||
|
||||
### Cursor
|
||||
@@ -77,7 +82,8 @@ Copy into the repo-local `.cursor/skills/` directory (where the Cursor Agent CLI
|
||||
mkdir -p .cursor/skills/create-plan
|
||||
cp -R skills/create-plan/cursor/* .cursor/skills/create-plan/
|
||||
mkdir -p .cursor/skills/reviewer-runtime
|
||||
cp -R skills/reviewer-runtime/* .cursor/skills/reviewer-runtime/
|
||||
cp skills/reviewer-runtime/run-review.sh skills/reviewer-runtime/notify-telegram.sh .cursor/skills/reviewer-runtime/
|
||||
chmod +x .cursor/skills/reviewer-runtime/*.sh
|
||||
```
|
||||
|
||||
Or install globally (loaded via `~/.cursor/skills/`):
|
||||
@@ -86,7 +92,8 @@ Or install globally (loaded via `~/.cursor/skills/`):
|
||||
mkdir -p ~/.cursor/skills/create-plan
|
||||
cp -R skills/create-plan/cursor/* ~/.cursor/skills/create-plan/
|
||||
mkdir -p ~/.cursor/skills/reviewer-runtime
|
||||
cp -R skills/reviewer-runtime/* ~/.cursor/skills/reviewer-runtime/
|
||||
cp skills/reviewer-runtime/run-review.sh skills/reviewer-runtime/notify-telegram.sh ~/.cursor/skills/reviewer-runtime/
|
||||
chmod +x ~/.cursor/skills/reviewer-runtime/*.sh
|
||||
```
|
||||
|
||||
### Pi
|
||||
@@ -135,10 +142,10 @@ Verify Superpowers dependencies exist in your agent skills root:
|
||||
- Codex: `~/.agents/skills/superpowers/writing-plans/SKILL.md`
|
||||
- Claude Code: `~/.claude/skills/superpowers/brainstorming/SKILL.md`
|
||||
- Claude Code: `~/.claude/skills/superpowers/writing-plans/SKILL.md`
|
||||
- OpenCode: `~/.config/opencode/skills/superpowers/brainstorming/SKILL.md`
|
||||
- OpenCode: `~/.config/opencode/skills/superpowers/writing-plans/SKILL.md`
|
||||
- Cursor: `.cursor/skills/superpowers/skills/brainstorming/SKILL.md` or `~/.cursor/skills/superpowers/skills/brainstorming/SKILL.md`
|
||||
- Cursor: `.cursor/skills/superpowers/skills/writing-plans/SKILL.md` or `~/.cursor/skills/superpowers/skills/writing-plans/SKILL.md`
|
||||
- OpenCode: `~/.agents/skills/superpowers/brainstorming/SKILL.md` or `~/.config/opencode/skills/superpowers/brainstorming/SKILL.md`
|
||||
- OpenCode: `~/.agents/skills/superpowers/writing-plans/SKILL.md` or `~/.config/opencode/skills/superpowers/writing-plans/SKILL.md`
|
||||
- Cursor: `.cursor/skills/superpowers/skills/brainstorming/SKILL.md`, `~/.cursor/skills/superpowers/skills/brainstorming/SKILL.md`, or the Cursor Superpowers plugin cache
|
||||
- Cursor: `.cursor/skills/superpowers/skills/writing-plans/SKILL.md`, `~/.cursor/skills/superpowers/skills/writing-plans/SKILL.md`, or the Cursor Superpowers plugin cache
|
||||
- Pi: `.pi/skills/superpowers/brainstorming/SKILL.md` or `~/.pi/agent/skills/superpowers/brainstorming/SKILL.md` or `~/.agents/skills/superpowers/brainstorming/SKILL.md`
|
||||
- Pi: `.pi/skills/superpowers/writing-plans/SKILL.md` or `~/.pi/agent/skills/superpowers/writing-plans/SKILL.md` or `~/.agents/skills/superpowers/writing-plans/SKILL.md`
|
||||
|
||||
@@ -165,7 +172,7 @@ Verify Superpowers dependencies exist in your agent skills root:
|
||||
|
||||
After the plan is created (design + milestones + stories), the skill sends it to a second model for review:
|
||||
|
||||
1. **Configure** — user picks a reviewer CLI (`codex`, `claude`, `cursor`, `pi`), a model, and optional max rounds (default 10), or skips
|
||||
1. **Configure** — user picks a reviewer CLI (`codex`, `claude`, `cursor`, `opencode`, `pi`), a model, and optional max rounds (default 10), or skips
|
||||
2. **Prepare** — plan payload and a bash reviewer command script are written to temp files
|
||||
3. **Run** — the command script is executed through `reviewer-runtime/run-review.sh` when installed
|
||||
4. **Feedback** — reviewer evaluates correctness, risks, missing steps, alternatives, security, and returns `## Summary`, `## Findings`, and `## Verdict`
|
||||
@@ -219,6 +226,7 @@ ts=<ISO-8601> level=<info|warn|error> state=<running-silent|running-active|in-pr
|
||||
| `codex` | `codex exec -m <model> -s read-only` | Yes (`codex exec resume <id>`) | `-s read-only` |
|
||||
| `claude` | `claude -p --model <model> --strict-mcp-config --setting-sources user` | No (fresh call each round) | `--strict-mcp-config --setting-sources user` |
|
||||
| `cursor` | `cursor-agent -p --mode=ask --model <model> --trust --output-format json` | Yes (`--resume <id>`) | `--mode=ask` |
|
||||
| `opencode` | `opencode run -m <provider>/<model> --agent plan --format json` | Fresh call default; optional `-s <id>` | `--agent plan` |
|
||||
| `pi` | See [PI-COMMON-REVIEWER.md](./PI-COMMON-REVIEWER.md) | No (fresh call each round) | `--tools read,grep,find,ls` |
|
||||
|
||||
For all supported reviewer CLIs, the preferred execution path is:
|
||||
@@ -290,6 +298,7 @@ All plan templates now include guardrail sections that enforce:
|
||||
|
||||
- Must use OpenCode native skill tool (not Claude/Codex invocation syntax).
|
||||
- Must verify Superpowers skill discovery under:
|
||||
- `~/.agents/skills/superpowers`
|
||||
- `~/.config/opencode/skills/superpowers`
|
||||
- Must explicitly load:
|
||||
- `superpowers/brainstorming`
|
||||
@@ -297,7 +306,7 @@ All plan templates now include guardrail sections that enforce:
|
||||
|
||||
### Cursor
|
||||
|
||||
- Must use workspace discovery from `.cursor/skills/` (repo-local or `~/.cursor/skills/` global).
|
||||
- Must use Cursor-native discovery from `.cursor/skills/`, `~/.cursor/skills/`, or installed Cursor plugin cache entries.
|
||||
- Must announce skill usage explicitly before invocation.
|
||||
- Must use `--mode=ask` (read-only) and `--trust` when running reviewer non-interactively.
|
||||
- Must not use `--force` or `--mode=agent` for review (reviewer should never write files).
|
||||
|
||||
+1
-5
@@ -54,13 +54,9 @@ Global uses `~/.cursor/skills/reviewer-runtime/` instead.
|
||||
|
||||
## Superpowers
|
||||
|
||||
Cursor can discover Superpowers from the Cursor plugin cache or from manual
|
||||
repo-local/global skill roots. Prefer the plugin install when it is present;
|
||||
do not also install a manual Superpowers copy, or Cursor may show each
|
||||
Superpowers skill twice.
|
||||
Cursor can discover Superpowers from the Cursor plugin cache or from manual repo-local/global skill roots. Prefer the plugin install when it is present; do not also install a manual Superpowers copy, or Cursor may show each Superpowers skill twice.
|
||||
|
||||
```bash
|
||||
.cursor/plugins/cache/cursor-public/superpowers/<revision>/skills/<superpower>/SKILL.md
|
||||
~/.cursor/plugins/cache/cursor-public/superpowers/<revision>/skills/<superpower>/SKILL.md
|
||||
.cursor/skills/superpowers/skills/<superpower>/SKILL.md
|
||||
~/.cursor/skills/superpowers/skills/<superpower>/SKILL.md
|
||||
|
||||
+27
-23
@@ -18,8 +18,8 @@ Execute a single user-supplied prompt end-to-end with **two reviewer loops** (pl
|
||||
- `superpowers:using-git-worktrees` (only when the prompt opts in to a worktree)
|
||||
- For Codex, native skill discovery must be configured:
|
||||
- `~/.agents/skills/superpowers -> ~/.codex/superpowers/skills`
|
||||
- For Cursor, skills must be installed under `.cursor/skills/` (repo-local) or `~/.cursor/skills/` (global), and `jq` is a hard prerequisite.
|
||||
- For OpenCode, Superpowers must be installed at `~/.config/opencode/skills/superpowers`.
|
||||
- Cursor can use the Cursor Superpowers plugin cache or manual `.cursor/skills/superpowers/skills` / `~/.cursor/skills/superpowers/skills` installs, and `jq` is a hard prerequisite for the Cursor variant.
|
||||
- OpenCode can use `~/.agents/skills/superpowers` or `~/.config/opencode/skills/superpowers`.
|
||||
- Shared reviewer runtime (`run-review.sh`) AND Telegram notifier helper (`notify-telegram.sh`) must be installed beside agent skills. Both scripts ship under `skills/reviewer-runtime/` in this repo and must be copied into the per-variant location:
|
||||
- Codex: `~/.codex/skills/reviewer-runtime/{run-review.sh,notify-telegram.sh}`
|
||||
- Claude Code: `~/.claude/skills/reviewer-runtime/{run-review.sh,notify-telegram.sh}`
|
||||
@@ -29,15 +29,15 @@ Execute a single user-supplied prompt end-to-end with **two reviewer loops** (pl
|
||||
- Variant-specific prerequisites:
|
||||
- **Claude Code:** `claude --version`, explicit `Skill`-tool invocation of sub-skills.
|
||||
- **Codex:** `codex --version`; `~/.agents/skills/superpowers -> ~/.codex/superpowers/skills` symlink present.
|
||||
- **Cursor:** `cursor-agent --version`, `jq --version` (hard prereq), Superpowers installed under `.cursor/skills/` or `~/.cursor/skills/`.
|
||||
- **OpenCode:** `opencode --version`; Superpowers installed at `~/.config/opencode/skills/superpowers`; Phase 1 runs Bootstrap Superpowers Context.
|
||||
- **Cursor:** `cursor-agent --version`, `jq --version` (hard prereq), Superpowers available from the Cursor plugin cache or manual Cursor skill roots.
|
||||
- **OpenCode:** `opencode --version`; Superpowers available from `~/.agents/skills/superpowers` or `~/.config/opencode/skills/superpowers`; Phase 1 runs Bootstrap Superpowers Context.
|
||||
- Telegram notification setup is documented in [TELEGRAM-NOTIFICATIONS.md](./TELEGRAM-NOTIFICATIONS.md)
|
||||
|
||||
Dependency-missing messages are variant-specific:
|
||||
|
||||
- **Claude Code:** `Missing dependency: [specific missing item]. Install required Superpowers skills (https://github.com/obra/superpowers) and the reviewer-runtime helper, then retry.`
|
||||
- **Codex:** `Missing dependency: [specific missing item]. Install required Superpowers skills (https://github.com/obra/superpowers) and the reviewer-runtime helper, then retry.`
|
||||
- **Cursor:** `Missing dependency: [specific missing item]. Install Cursor Agent CLI, jq, and Superpowers skills under .cursor/skills/ or ~/.cursor/skills/, then retry.`
|
||||
- **Cursor:** `Missing dependency: [specific missing item]. Install Cursor Agent CLI, jq, and the Cursor Superpowers plugin or Superpowers skills under .cursor/skills/ or ~/.cursor/skills/, then retry.`
|
||||
- **OpenCode:** `Missing dependency: [specific missing item]. Install required OpenCode Superpowers skills (https://github.com/obra/superpowers, OpenCode setup) and the reviewer-runtime helper, then retry.`
|
||||
- **Pi:** `Missing dependency: [specific missing item]. Install Pi, required Superpowers skills, and the Pi reviewer-runtime helper, then retry.`
|
||||
|
||||
@@ -65,7 +65,8 @@ The reviewer CLI is independent of which agent is running the skill — e.g., Cl
|
||||
mkdir -p ~/.codex/skills/do-task
|
||||
cp -R skills/do-task/codex/* ~/.codex/skills/do-task/
|
||||
mkdir -p ~/.codex/skills/reviewer-runtime
|
||||
cp -R skills/reviewer-runtime/* ~/.codex/skills/reviewer-runtime/
|
||||
cp skills/reviewer-runtime/run-review.sh skills/reviewer-runtime/notify-telegram.sh ~/.codex/skills/reviewer-runtime/
|
||||
chmod +x ~/.codex/skills/reviewer-runtime/*.sh
|
||||
```
|
||||
|
||||
### Claude Code
|
||||
@@ -74,7 +75,8 @@ cp -R skills/reviewer-runtime/* ~/.codex/skills/reviewer-runtime/
|
||||
mkdir -p ~/.claude/skills/do-task
|
||||
cp -R skills/do-task/claude-code/* ~/.claude/skills/do-task/
|
||||
mkdir -p ~/.claude/skills/reviewer-runtime
|
||||
cp -R skills/reviewer-runtime/* ~/.claude/skills/reviewer-runtime/
|
||||
cp skills/reviewer-runtime/run-review.sh skills/reviewer-runtime/notify-telegram.sh ~/.claude/skills/reviewer-runtime/
|
||||
chmod +x ~/.claude/skills/reviewer-runtime/*.sh
|
||||
```
|
||||
|
||||
### OpenCode
|
||||
@@ -83,7 +85,8 @@ cp -R skills/reviewer-runtime/* ~/.claude/skills/reviewer-runtime/
|
||||
mkdir -p ~/.config/opencode/skills/do-task
|
||||
cp -R skills/do-task/opencode/* ~/.config/opencode/skills/do-task/
|
||||
mkdir -p ~/.config/opencode/skills/reviewer-runtime
|
||||
cp -R skills/reviewer-runtime/* ~/.config/opencode/skills/reviewer-runtime/
|
||||
cp skills/reviewer-runtime/run-review.sh skills/reviewer-runtime/notify-telegram.sh ~/.config/opencode/skills/reviewer-runtime/
|
||||
chmod +x ~/.config/opencode/skills/reviewer-runtime/*.sh
|
||||
```
|
||||
|
||||
### Cursor
|
||||
@@ -94,7 +97,8 @@ Copy into the repo-local `.cursor/skills/` directory (where the Cursor Agent CLI
|
||||
mkdir -p .cursor/skills/do-task
|
||||
cp -R skills/do-task/cursor/* .cursor/skills/do-task/
|
||||
mkdir -p .cursor/skills/reviewer-runtime
|
||||
cp -R skills/reviewer-runtime/* .cursor/skills/reviewer-runtime/
|
||||
cp skills/reviewer-runtime/run-review.sh skills/reviewer-runtime/notify-telegram.sh .cursor/skills/reviewer-runtime/
|
||||
chmod +x .cursor/skills/reviewer-runtime/*.sh
|
||||
```
|
||||
|
||||
Or install globally (loaded via `~/.cursor/skills/`):
|
||||
@@ -103,7 +107,8 @@ Or install globally (loaded via `~/.cursor/skills/`):
|
||||
mkdir -p ~/.cursor/skills/do-task
|
||||
cp -R skills/do-task/cursor/* ~/.cursor/skills/do-task/
|
||||
mkdir -p ~/.cursor/skills/reviewer-runtime
|
||||
cp -R skills/reviewer-runtime/* ~/.cursor/skills/reviewer-runtime/
|
||||
cp skills/reviewer-runtime/run-review.sh skills/reviewer-runtime/notify-telegram.sh ~/.cursor/skills/reviewer-runtime/
|
||||
chmod +x ~/.cursor/skills/reviewer-runtime/*.sh
|
||||
```
|
||||
|
||||
### Pi
|
||||
@@ -169,11 +174,10 @@ opencode --version
|
||||
test -f ~/.config/opencode/skills/do-task/SKILL.md
|
||||
test -x ~/.config/opencode/skills/reviewer-runtime/run-review.sh
|
||||
test -x ~/.config/opencode/skills/reviewer-runtime/notify-telegram.sh
|
||||
ls -l ~/.config/opencode/skills/superpowers
|
||||
test -f ~/.config/opencode/skills/superpowers/brainstorming/SKILL.md
|
||||
test -f ~/.config/opencode/skills/superpowers/test-driven-development/SKILL.md
|
||||
test -f ~/.config/opencode/skills/superpowers/verification-before-completion/SKILL.md
|
||||
test -f ~/.config/opencode/skills/superpowers/finishing-a-development-branch/SKILL.md
|
||||
test -f ~/.agents/skills/superpowers/brainstorming/SKILL.md || test -f ~/.config/opencode/skills/superpowers/brainstorming/SKILL.md
|
||||
test -f ~/.agents/skills/superpowers/test-driven-development/SKILL.md || test -f ~/.config/opencode/skills/superpowers/test-driven-development/SKILL.md
|
||||
test -f ~/.agents/skills/superpowers/verification-before-completion/SKILL.md || test -f ~/.config/opencode/skills/superpowers/verification-before-completion/SKILL.md
|
||||
test -f ~/.agents/skills/superpowers/finishing-a-development-branch/SKILL.md || test -f ~/.config/opencode/skills/superpowers/finishing-a-development-branch/SKILL.md
|
||||
```
|
||||
|
||||
### Cursor
|
||||
@@ -184,10 +188,10 @@ jq --version
|
||||
test -f .cursor/skills/do-task/SKILL.md || test -f ~/.cursor/skills/do-task/SKILL.md
|
||||
test -x .cursor/skills/reviewer-runtime/run-review.sh || test -x ~/.cursor/skills/reviewer-runtime/run-review.sh
|
||||
test -x .cursor/skills/reviewer-runtime/notify-telegram.sh || test -x ~/.cursor/skills/reviewer-runtime/notify-telegram.sh
|
||||
test -f .cursor/skills/superpowers/skills/brainstorming/SKILL.md || test -f ~/.cursor/skills/superpowers/skills/brainstorming/SKILL.md
|
||||
test -f .cursor/skills/superpowers/skills/test-driven-development/SKILL.md || test -f ~/.cursor/skills/superpowers/skills/test-driven-development/SKILL.md
|
||||
test -f .cursor/skills/superpowers/skills/verification-before-completion/SKILL.md || test -f ~/.cursor/skills/superpowers/skills/verification-before-completion/SKILL.md
|
||||
test -f .cursor/skills/superpowers/skills/finishing-a-development-branch/SKILL.md || test -f ~/.cursor/skills/superpowers/skills/finishing-a-development-branch/SKILL.md
|
||||
test -f .cursor/skills/superpowers/skills/brainstorming/SKILL.md || test -f ~/.cursor/skills/superpowers/skills/brainstorming/SKILL.md || find ~/.cursor/plugins/cache/cursor-public/superpowers -path '*/skills/brainstorming/SKILL.md' -print -quit 2>/dev/null | grep -q .
|
||||
test -f .cursor/skills/superpowers/skills/test-driven-development/SKILL.md || test -f ~/.cursor/skills/superpowers/skills/test-driven-development/SKILL.md || find ~/.cursor/plugins/cache/cursor-public/superpowers -path '*/skills/test-driven-development/SKILL.md' -print -quit 2>/dev/null | grep -q .
|
||||
test -f .cursor/skills/superpowers/skills/verification-before-completion/SKILL.md || test -f ~/.cursor/skills/superpowers/skills/verification-before-completion/SKILL.md || find ~/.cursor/plugins/cache/cursor-public/superpowers -path '*/skills/verification-before-completion/SKILL.md' -print -quit 2>/dev/null | grep -q .
|
||||
test -f .cursor/skills/superpowers/skills/finishing-a-development-branch/SKILL.md || test -f ~/.cursor/skills/superpowers/skills/finishing-a-development-branch/SKILL.md || find ~/.cursor/plugins/cache/cursor-public/superpowers -path '*/skills/finishing-a-development-branch/SKILL.md' -print -quit 2>/dev/null | grep -q .
|
||||
```
|
||||
|
||||
### Pi
|
||||
@@ -333,7 +337,7 @@ The user answers `yes` / `no` / `redact`:
|
||||
| `opencode` | `opencode run -m <provider>/<model> --agent plan --format json "<prompt>" > <out.json>` | Fresh call (default) OR `opencode run -s <id> -m <provider>/<model> --agent plan --format json "<prompt>" > <out.json>` (opt-in) | `jq -r '.[] \| select(.type == "message" and .role == "assistant") \| .content' <out.json> > <out.md>` |
|
||||
| `pi` | See [PI-COMMON-REVIEWER.md](./PI-COMMON-REVIEWER.md) | Fresh call | Markdown stdout copied to `<out.md>` |
|
||||
|
||||
For all four CLIs, the preferred execution path is:
|
||||
For all supported reviewer CLIs, the preferred execution path is:
|
||||
|
||||
1. Write the reviewer command to a bash script.
|
||||
2. Run that script through `reviewer-runtime/run-review.sh`.
|
||||
@@ -420,16 +424,16 @@ All four `templates/task-plan.md` files share identical core sections (14 `## `-
|
||||
|
||||
### OpenCode
|
||||
|
||||
- Must use OpenCode's native skill tool (not Claude's `Skill` tool syntax, not Codex's `~/.agents/skills/` paths).
|
||||
- Must use OpenCode's native skill tool (not Claude's `Skill` tool syntax). OpenCode may load shared skill files from `~/.agents/skills/`, but invocation is still OpenCode-native.
|
||||
- Phase 1 includes a Bootstrap Superpowers Context step that lists installed skills and confirms the required `superpowers/<skill>` set is discoverable before any other phase runs.
|
||||
- Must verify Superpowers skill discovery under `~/.config/opencode/skills/superpowers`.
|
||||
- Must verify Superpowers skill discovery under `~/.agents/skills/superpowers` or `~/.config/opencode/skills/superpowers`.
|
||||
- Helper paths: `~/.config/opencode/skills/reviewer-runtime/...`.
|
||||
- Opencode reviewer calls MUST use `--agent plan` (the built-in plan primary agent) for read-only posture.
|
||||
- No plan-mode guard (OpenCode has no plan-mode concept).
|
||||
|
||||
### Cursor
|
||||
|
||||
- Must use workspace discovery from `.cursor/skills/` (repo-local) or `~/.cursor/skills/` (global).
|
||||
- Must use Cursor-native discovery from `.cursor/skills/`, `~/.cursor/skills/`, or installed Cursor plugin cache entries.
|
||||
- Must announce skill usage explicitly before invocation.
|
||||
- `jq` is a hard prerequisite.
|
||||
- Helper paths: `.cursor/skills/reviewer-runtime/...` preferred, `~/.cursor/skills/reviewer-runtime/...` fallback.
|
||||
|
||||
+25
-16
@@ -19,7 +19,8 @@ Execute an existing plan (created by `create-plan`) in an isolated git worktree,
|
||||
- `superpowers:finishing-a-development-branch`
|
||||
- For Codex, native skill discovery must be configured:
|
||||
- `~/.agents/skills/superpowers -> ~/.codex/superpowers/skills`
|
||||
- For Cursor, skills must be installed under `.cursor/skills/` (repo-local) or `~/.cursor/skills/` (global)
|
||||
- Cursor can use the Cursor Superpowers plugin cache or manual `.cursor/skills/superpowers/skills` / `~/.cursor/skills/superpowers/skills` installs.
|
||||
- OpenCode can use `~/.agents/skills/superpowers` or `~/.config/opencode/skills/superpowers`.
|
||||
- Shared reviewer runtime must be installed beside agent skills when using reviewer CLIs:
|
||||
- Codex: `~/.codex/skills/reviewer-runtime/{run-review.sh,notify-telegram.sh}`
|
||||
- Claude Code: `~/.claude/skills/reviewer-runtime/{run-review.sh,notify-telegram.sh}`
|
||||
@@ -41,6 +42,7 @@ To use the iterative milestone review feature, one of these CLIs must be install
|
||||
| `codex` | `npm install -g @openai/codex` | `codex --version` |
|
||||
| `claude` | `npm install -g @anthropic-ai/claude-code` | `claude --version` |
|
||||
| `cursor` | `curl https://cursor.com/install -fsS \| bash` | `cursor-agent --version` (binary: `cursor-agent`; alias `cursor agent` also works) |
|
||||
| `opencode` | `brew install opencode` or your package manager | `opencode --version` |
|
||||
| `pi` | Install Pi coding agent | `pi --version`; list models with `pi --list-models [search]` |
|
||||
|
||||
The reviewer CLI is independent of which agent is running the implementation — e.g., Claude Code can send milestones to Codex for review, and vice versa.
|
||||
@@ -55,7 +57,8 @@ The reviewer CLI is independent of which agent is running the implementation —
|
||||
mkdir -p ~/.codex/skills/implement-plan
|
||||
cp -R skills/implement-plan/codex/* ~/.codex/skills/implement-plan/
|
||||
mkdir -p ~/.codex/skills/reviewer-runtime
|
||||
cp -R skills/reviewer-runtime/* ~/.codex/skills/reviewer-runtime/
|
||||
cp skills/reviewer-runtime/run-review.sh skills/reviewer-runtime/notify-telegram.sh ~/.codex/skills/reviewer-runtime/
|
||||
chmod +x ~/.codex/skills/reviewer-runtime/*.sh
|
||||
```
|
||||
|
||||
### Claude Code
|
||||
@@ -64,7 +67,8 @@ cp -R skills/reviewer-runtime/* ~/.codex/skills/reviewer-runtime/
|
||||
mkdir -p ~/.claude/skills/implement-plan
|
||||
cp -R skills/implement-plan/claude-code/* ~/.claude/skills/implement-plan/
|
||||
mkdir -p ~/.claude/skills/reviewer-runtime
|
||||
cp -R skills/reviewer-runtime/* ~/.claude/skills/reviewer-runtime/
|
||||
cp skills/reviewer-runtime/run-review.sh skills/reviewer-runtime/notify-telegram.sh ~/.claude/skills/reviewer-runtime/
|
||||
chmod +x ~/.claude/skills/reviewer-runtime/*.sh
|
||||
```
|
||||
|
||||
### OpenCode
|
||||
@@ -73,7 +77,8 @@ cp -R skills/reviewer-runtime/* ~/.claude/skills/reviewer-runtime/
|
||||
mkdir -p ~/.config/opencode/skills/implement-plan
|
||||
cp -R skills/implement-plan/opencode/* ~/.config/opencode/skills/implement-plan/
|
||||
mkdir -p ~/.config/opencode/skills/reviewer-runtime
|
||||
cp -R skills/reviewer-runtime/* ~/.config/opencode/skills/reviewer-runtime/
|
||||
cp skills/reviewer-runtime/run-review.sh skills/reviewer-runtime/notify-telegram.sh ~/.config/opencode/skills/reviewer-runtime/
|
||||
chmod +x ~/.config/opencode/skills/reviewer-runtime/*.sh
|
||||
```
|
||||
|
||||
### Cursor
|
||||
@@ -84,7 +89,8 @@ Copy into the repo-local `.cursor/skills/` directory (where the Cursor Agent CLI
|
||||
mkdir -p .cursor/skills/implement-plan
|
||||
cp -R skills/implement-plan/cursor/* .cursor/skills/implement-plan/
|
||||
mkdir -p .cursor/skills/reviewer-runtime
|
||||
cp -R skills/reviewer-runtime/* .cursor/skills/reviewer-runtime/
|
||||
cp skills/reviewer-runtime/run-review.sh skills/reviewer-runtime/notify-telegram.sh .cursor/skills/reviewer-runtime/
|
||||
chmod +x .cursor/skills/reviewer-runtime/*.sh
|
||||
```
|
||||
|
||||
Or install globally (loaded via `~/.cursor/skills/`):
|
||||
@@ -93,7 +99,8 @@ Or install globally (loaded via `~/.cursor/skills/`):
|
||||
mkdir -p ~/.cursor/skills/implement-plan
|
||||
cp -R skills/implement-plan/cursor/* ~/.cursor/skills/implement-plan/
|
||||
mkdir -p ~/.cursor/skills/reviewer-runtime
|
||||
cp -R skills/reviewer-runtime/* ~/.cursor/skills/reviewer-runtime/
|
||||
cp skills/reviewer-runtime/run-review.sh skills/reviewer-runtime/notify-telegram.sh ~/.cursor/skills/reviewer-runtime/
|
||||
chmod +x ~/.cursor/skills/reviewer-runtime/*.sh
|
||||
```
|
||||
|
||||
### Pi
|
||||
@@ -146,14 +153,14 @@ Verify Superpowers execution dependencies exist in your agent skills root:
|
||||
- Claude Code: `~/.claude/skills/superpowers/using-git-worktrees/SKILL.md`
|
||||
- Claude Code: `~/.claude/skills/superpowers/verification-before-completion/SKILL.md`
|
||||
- Claude Code: `~/.claude/skills/superpowers/finishing-a-development-branch/SKILL.md`
|
||||
- OpenCode: `~/.config/opencode/skills/superpowers/executing-plans/SKILL.md`
|
||||
- OpenCode: `~/.config/opencode/skills/superpowers/using-git-worktrees/SKILL.md`
|
||||
- OpenCode: `~/.config/opencode/skills/superpowers/verification-before-completion/SKILL.md`
|
||||
- OpenCode: `~/.config/opencode/skills/superpowers/finishing-a-development-branch/SKILL.md`
|
||||
- Cursor: `.cursor/skills/superpowers/skills/executing-plans/SKILL.md` or `~/.cursor/skills/superpowers/skills/executing-plans/SKILL.md`
|
||||
- Cursor: `.cursor/skills/superpowers/skills/using-git-worktrees/SKILL.md` or `~/.cursor/skills/superpowers/skills/using-git-worktrees/SKILL.md`
|
||||
- Cursor: `.cursor/skills/superpowers/skills/verification-before-completion/SKILL.md` or `~/.cursor/skills/superpowers/skills/verification-before-completion/SKILL.md`
|
||||
- Cursor: `.cursor/skills/superpowers/skills/finishing-a-development-branch/SKILL.md` or `~/.cursor/skills/superpowers/skills/finishing-a-development-branch/SKILL.md`
|
||||
- OpenCode: `~/.agents/skills/superpowers/executing-plans/SKILL.md` or `~/.config/opencode/skills/superpowers/executing-plans/SKILL.md`
|
||||
- OpenCode: `~/.agents/skills/superpowers/using-git-worktrees/SKILL.md` or `~/.config/opencode/skills/superpowers/using-git-worktrees/SKILL.md`
|
||||
- OpenCode: `~/.agents/skills/superpowers/verification-before-completion/SKILL.md` or `~/.config/opencode/skills/superpowers/verification-before-completion/SKILL.md`
|
||||
- OpenCode: `~/.agents/skills/superpowers/finishing-a-development-branch/SKILL.md` or `~/.config/opencode/skills/superpowers/finishing-a-development-branch/SKILL.md`
|
||||
- Cursor: `.cursor/skills/superpowers/skills/executing-plans/SKILL.md`, `~/.cursor/skills/superpowers/skills/executing-plans/SKILL.md`, or the Cursor Superpowers plugin cache
|
||||
- Cursor: `.cursor/skills/superpowers/skills/using-git-worktrees/SKILL.md`, `~/.cursor/skills/superpowers/skills/using-git-worktrees/SKILL.md`, or the Cursor Superpowers plugin cache
|
||||
- Cursor: `.cursor/skills/superpowers/skills/verification-before-completion/SKILL.md`, `~/.cursor/skills/superpowers/skills/verification-before-completion/SKILL.md`, or the Cursor Superpowers plugin cache
|
||||
- Cursor: `.cursor/skills/superpowers/skills/finishing-a-development-branch/SKILL.md`, `~/.cursor/skills/superpowers/skills/finishing-a-development-branch/SKILL.md`, or the Cursor Superpowers plugin cache
|
||||
- Pi: `.pi/skills/superpowers/executing-plans/SKILL.md` or `~/.pi/agent/skills/superpowers/executing-plans/SKILL.md` or `~/.agents/skills/superpowers/executing-plans/SKILL.md`
|
||||
- Pi: `.pi/skills/superpowers/using-git-worktrees/SKILL.md` or `~/.pi/agent/skills/superpowers/using-git-worktrees/SKILL.md` or `~/.agents/skills/superpowers/using-git-worktrees/SKILL.md`
|
||||
- Pi: `.pi/skills/superpowers/verification-before-completion/SKILL.md` or `~/.pi/agent/skills/superpowers/verification-before-completion/SKILL.md` or `~/.agents/skills/superpowers/verification-before-completion/SKILL.md`
|
||||
@@ -179,7 +186,7 @@ Verify Superpowers execution dependencies exist in your agent skills root:
|
||||
|
||||
After each milestone is implemented and verified, the skill sends it to a second model for review:
|
||||
|
||||
1. **Configure** — user picks a reviewer CLI (`codex`, `claude`, `cursor`, `pi`) and model, or skips
|
||||
1. **Configure** — user picks a reviewer CLI (`codex`, `claude`, `cursor`, `opencode`, `pi`) and model, or skips
|
||||
2. **Prepare** — milestone payload and a bash reviewer command script are written to temp files
|
||||
3. **Run** — the command script is executed through `reviewer-runtime/run-review.sh` when installed
|
||||
4. **Feedback** — reviewer evaluates correctness, acceptance criteria, code quality, test coverage, security, and returns `## Summary`, `## Findings`, and `## Verdict`
|
||||
@@ -233,6 +240,7 @@ ts=<ISO-8601> level=<info|warn|error> state=<running-silent|running-active|in-pr
|
||||
| `codex` | `codex exec -m <model> -s read-only` | Yes (`codex exec resume <id>`) | `-s read-only` |
|
||||
| `claude` | `claude -p --model <model> --strict-mcp-config --setting-sources user` | No (fresh call each round) | `--strict-mcp-config --setting-sources user` |
|
||||
| `cursor` | `cursor-agent -p --mode=ask --model <model> --trust --output-format json` | Yes (`--resume <id>`) | `--mode=ask` |
|
||||
| `opencode` | `opencode run -m <provider>/<model> --agent plan --format json` | Fresh call default; optional `-s <id>` | `--agent plan` |
|
||||
| `pi` | See [PI-COMMON-REVIEWER.md](./PI-COMMON-REVIEWER.md) | No (fresh call each round) | `--tools read,grep,find,ls` |
|
||||
|
||||
For all supported reviewer CLIs, the preferred execution path is:
|
||||
@@ -294,12 +302,13 @@ run-review.sh \
|
||||
|
||||
- Must use OpenCode native skill tool (not Claude/Codex invocation syntax).
|
||||
- Must verify Superpowers skill discovery under:
|
||||
- `~/.agents/skills/superpowers`
|
||||
- `~/.config/opencode/skills/superpowers`
|
||||
- Must explicitly load all four execution sub-skills.
|
||||
|
||||
### Cursor
|
||||
|
||||
- Must use workspace discovery from `.cursor/skills/` (repo-local or `~/.cursor/skills/` global).
|
||||
- Must use Cursor-native discovery from `.cursor/skills/`, `~/.cursor/skills/`, or installed Cursor plugin cache entries.
|
||||
- Must announce skill usage explicitly before invocation.
|
||||
- Must use `--mode=ask` (read-only) and `--trust` when running reviewer non-interactively.
|
||||
- Must not use `--force` or `--mode=agent` for review (reviewer should never write files).
|
||||
|
||||
+9
-1
@@ -65,7 +65,15 @@ When a selected install/update needs Superpowers and none are detected for the t
|
||||
- symlink is recommended because updates to the source checkout are immediately visible
|
||||
- copy is more self-contained but must be updated manually
|
||||
|
||||
For Cursor, the wizard installs Superpowers at `<scope>/superpowers/skills` because Cursor variants expect `superpowers/skills/<skill>/SKILL.md`. Codex commonly reuses the shared `~/.agents/skills/superpowers` convention documented in [CODEX.md](./CODEX.md).
|
||||
The wizard recognizes client-native and plugin-managed Superpowers installs before asking to add another copy:
|
||||
|
||||
- Codex: `~/.agents/skills/superpowers` or `~/.codex/superpowers/skills`
|
||||
- Claude Code: `~/.claude/skills/superpowers` or the enabled `superpowers@claude-plugins-official` plugin cache
|
||||
- Cursor: `.cursor/skills/superpowers/skills`, `~/.cursor/skills/superpowers/skills`, or the Cursor public Superpowers plugin cache
|
||||
- OpenCode: `~/.agents/skills/superpowers` or `~/.config/opencode/skills/superpowers`
|
||||
- Pi: `~/.agents/skills/superpowers`, `~/.pi/agent/skills/superpowers`, or `.pi/skills/superpowers`
|
||||
|
||||
When Cursor has no plugin/cache install, the wizard installs Superpowers at `<scope>/superpowers/skills` because Cursor variants expect `superpowers/skills/<skill>/SKILL.md`. Symlinking is still preferred when the source tree is managed locally. Codex and OpenCode can commonly reuse the shared `~/.agents/skills/superpowers` convention documented in [CODEX.md](./CODEX.md) and [OPENCODE.md](./OPENCODE.md).
|
||||
|
||||
When removing the last repository workflow skill from a client/scope, the wizard asks whether to remove Superpowers for that variant too.
|
||||
|
||||
|
||||
+7
-1
@@ -99,7 +99,12 @@ The package surface intentionally ships:
|
||||
- `pi-package/skills/**`
|
||||
- `skills/reviewer-runtime/pi/**`
|
||||
- `docs/PI*.md`
|
||||
- `scripts/install-pi-package.sh`
|
||||
- `scripts/manage-skills.mjs` and `scripts/manage-skills.sh`
|
||||
- `scripts/sync-pi-package-skills.sh`
|
||||
- `scripts/verify-pi-resources.sh`
|
||||
- `scripts/verify-pi-workflows.sh`
|
||||
- `scripts/verify-reviewer-support.sh`
|
||||
|
||||
It intentionally does not ship `skills/<family>/pi/**` as package-discovered skills.
|
||||
|
||||
@@ -120,7 +125,8 @@ When a source Pi variant changes:
|
||||
|
||||
```bash
|
||||
./scripts/sync-pi-package-skills.sh
|
||||
./scripts/verify-pi-resources.sh
|
||||
npm run verify:pi
|
||||
npm run verify:reviewers
|
||||
npm pack --dry-run --json
|
||||
```
|
||||
|
||||
|
||||
@@ -22,21 +22,24 @@ The helper ships from `skills/reviewer-runtime/` together with `run-review.sh`.
|
||||
|
||||
```bash
|
||||
mkdir -p ~/.codex/skills/reviewer-runtime
|
||||
cp -R skills/reviewer-runtime/* ~/.codex/skills/reviewer-runtime/
|
||||
cp skills/reviewer-runtime/run-review.sh skills/reviewer-runtime/notify-telegram.sh ~/.codex/skills/reviewer-runtime/
|
||||
chmod +x ~/.codex/skills/reviewer-runtime/*.sh
|
||||
```
|
||||
|
||||
### Claude Code
|
||||
|
||||
```bash
|
||||
mkdir -p ~/.claude/skills/reviewer-runtime
|
||||
cp -R skills/reviewer-runtime/* ~/.claude/skills/reviewer-runtime/
|
||||
cp skills/reviewer-runtime/run-review.sh skills/reviewer-runtime/notify-telegram.sh ~/.claude/skills/reviewer-runtime/
|
||||
chmod +x ~/.claude/skills/reviewer-runtime/*.sh
|
||||
```
|
||||
|
||||
### OpenCode
|
||||
|
||||
```bash
|
||||
mkdir -p ~/.config/opencode/skills/reviewer-runtime
|
||||
cp -R skills/reviewer-runtime/* ~/.config/opencode/skills/reviewer-runtime/
|
||||
cp skills/reviewer-runtime/run-review.sh skills/reviewer-runtime/notify-telegram.sh ~/.config/opencode/skills/reviewer-runtime/
|
||||
chmod +x ~/.config/opencode/skills/reviewer-runtime/*.sh
|
||||
```
|
||||
|
||||
### Cursor
|
||||
@@ -45,14 +48,16 @@ Repo-local install:
|
||||
|
||||
```bash
|
||||
mkdir -p .cursor/skills/reviewer-runtime
|
||||
cp -R skills/reviewer-runtime/* .cursor/skills/reviewer-runtime/
|
||||
cp skills/reviewer-runtime/run-review.sh skills/reviewer-runtime/notify-telegram.sh .cursor/skills/reviewer-runtime/
|
||||
chmod +x .cursor/skills/reviewer-runtime/*.sh
|
||||
```
|
||||
|
||||
Global install:
|
||||
|
||||
```bash
|
||||
mkdir -p ~/.cursor/skills/reviewer-runtime
|
||||
cp -R skills/reviewer-runtime/* ~/.cursor/skills/reviewer-runtime/
|
||||
cp skills/reviewer-runtime/run-review.sh skills/reviewer-runtime/notify-telegram.sh ~/.cursor/skills/reviewer-runtime/
|
||||
chmod +x ~/.cursor/skills/reviewer-runtime/*.sh
|
||||
```
|
||||
|
||||
## Verify Installation
|
||||
|
||||
Reference in New Issue
Block a user