Home/ai-coding-skills
2
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: align skill workflow documentation

Browse Source
This commit is contained in:
Stefano Fiorini
2026-04-24 02:44:32 -05:00
parent 193cd45db8
commit 2deab1c1b4
14 changed files with 122 additions and 77 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/IMPLEMENT-PLAN.md
+25 -16
View File
@@ -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).