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/DO-TASK.md
+27 -23
View File
@@ -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.