From 2deab1c1b4c13579e94cdadb60d70773ad531158 Mon Sep 17 00:00:00 2001 From: Stefano Fiorini Date: Fri, 24 Apr 2026 02:44:32 -0500 Subject: [PATCH] docs: align skill workflow documentation --- README.md | 4 ++- docs/CLAUDE-CODE.md | 4 +++ docs/CODEX.md | 2 ++ docs/CREATE-PLAN.md | 33 +++++++++++------- docs/CURSOR.md | 6 +--- docs/DO-TASK.md | 50 +++++++++++++++------------ docs/IMPLEMENT-PLAN.md | 41 +++++++++++++--------- docs/INSTALLER.md | 10 +++++- docs/PI.md | 8 ++++- docs/TELEGRAM-NOTIFICATIONS.md | 15 +++++--- skills/create-plan/cursor/SKILL.md | 2 +- skills/do-task/cursor/SKILL.md | 18 +++++----- skills/do-task/opencode/SKILL.md | 4 +-- skills/implement-plan/cursor/SKILL.md | 2 +- 14 files changed, 122 insertions(+), 77 deletions(-) diff --git a/README.md b/README.md index fd45d07..5ebea96 100644 --- a/README.md +++ b/README.md @@ -113,6 +113,7 @@ ai-coding-skills/ - Automated install/update/remove wizard: `docs/INSTALLER.md` - Manual install by client: `docs/CODEX.md`, `docs/CLAUDE-CODE.md`, `docs/CURSOR.md`, `docs/OPENCODE.md`, `docs/PI.md` - Skill guides: `docs/ATLASSIAN.md`, `docs/CREATE-PLAN.md`, `docs/DO-TASK.md`, `docs/IMPLEMENT-PLAN.md`, `docs/WEB-AUTOMATION.md` +- Shared workflow setup: `docs/TELEGRAM-NOTIFICATIONS.md`, `docs/PI-SUPERPOWERS.md`, `docs/PI-COMMON-REVIEWER.md` ## Compatibility Policy @@ -190,7 +191,8 @@ Before publishing or sharing a tarball, run: ```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 ``` diff --git a/docs/CLAUDE-CODE.md b/docs/CLAUDE-CODE.md index 820cbb9..8680cdf 100644 --- a/docs/CLAUDE-CODE.md +++ b/docs/CLAUDE-CODE.md @@ -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 diff --git a/docs/CODEX.md b/docs/CODEX.md index 306b761..8ea18aa 100644 --- a/docs/CODEX.md +++ b/docs/CODEX.md @@ -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 diff --git a/docs/CREATE-PLAN.md b/docs/CREATE-PLAN.md index 5077d8e..2f9109e 100644 --- a/docs/CREATE-PLAN.md +++ b/docs/CREATE-PLAN.md @@ -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= level= state= -s read-only` | Yes (`codex exec resume `) | `-s read-only` | | `claude` | `claude -p --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 --trust --output-format json` | Yes (`--resume `) | `--mode=ask` | +| `opencode` | `opencode run -m / --agent plan --format json` | Fresh call default; optional `-s ` | `--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). diff --git a/docs/CURSOR.md b/docs/CURSOR.md index d50e7d1..720182a 100644 --- a/docs/CURSOR.md +++ b/docs/CURSOR.md @@ -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//skills//SKILL.md ~/.cursor/plugins/cache/cursor-public/superpowers//skills//SKILL.md .cursor/skills/superpowers/skills//SKILL.md ~/.cursor/skills/superpowers/skills//SKILL.md diff --git a/docs/DO-TASK.md b/docs/DO-TASK.md index 0d3b8d2..65ded60 100644 --- a/docs/DO-TASK.md +++ b/docs/DO-TASK.md @@ -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 / --agent plan --format json "" > ` | Fresh call (default) OR `opencode run -s -m / --agent plan --format json "" > ` (opt-in) | `jq -r '.[] \| select(.type == "message" and .role == "assistant") \| .content' > ` | | `pi` | See [PI-COMMON-REVIEWER.md](./PI-COMMON-REVIEWER.md) | Fresh call | Markdown stdout copied to `` | -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/` 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. diff --git a/docs/IMPLEMENT-PLAN.md b/docs/IMPLEMENT-PLAN.md index 20f8fc1..de54920 100644 --- a/docs/IMPLEMENT-PLAN.md +++ b/docs/IMPLEMENT-PLAN.md @@ -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= level= state= -s read-only` | Yes (`codex exec resume `) | `-s read-only` | | `claude` | `claude -p --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 --trust --output-format json` | Yes (`--resume `) | `--mode=ask` | +| `opencode` | `opencode run -m / --agent plan --format json` | Fresh call default; optional `-s ` | `--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). diff --git a/docs/INSTALLER.md b/docs/INSTALLER.md index 0b06fd4..164781a 100644 --- a/docs/INSTALLER.md +++ b/docs/INSTALLER.md @@ -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 `/superpowers/skills` because Cursor variants expect `superpowers/skills//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 `/superpowers/skills` because Cursor variants expect `superpowers/skills//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. diff --git a/docs/PI.md b/docs/PI.md index 26eebc9..93a398f 100644 --- a/docs/PI.md +++ b/docs/PI.md @@ -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//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 ``` diff --git a/docs/TELEGRAM-NOTIFICATIONS.md b/docs/TELEGRAM-NOTIFICATIONS.md index 31e9ad2..2e8c1b3 100644 --- a/docs/TELEGRAM-NOTIFICATIONS.md +++ b/docs/TELEGRAM-NOTIFICATIONS.md @@ -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 diff --git a/skills/create-plan/cursor/SKILL.md b/skills/create-plan/cursor/SKILL.md index d9c8b8c..f1ac91d 100644 --- a/skills/create-plan/cursor/SKILL.md +++ b/skills/create-plan/cursor/SKILL.md @@ -43,7 +43,7 @@ If any dependency is missing, stop and return: ## Required Skill Invocation Rules -- Invoke relevant skills through workspace discovery (`.cursor/skills/`). +- Invoke relevant skills through Cursor-native discovery (`.cursor/skills/`, `~/.cursor/skills/`, or installed Cursor plugin cache entries). - Announce skill usage explicitly: - `I've read the [Skill Name] skill and I'm using it to [purpose].` - For skills with checklists, track checklist items explicitly in conversation. diff --git a/skills/do-task/cursor/SKILL.md b/skills/do-task/cursor/SKILL.md index b1fdb1c..95d8b42 100644 --- a/skills/do-task/cursor/SKILL.md +++ b/skills/do-task/cursor/SKILL.md @@ -43,7 +43,7 @@ If any required dependency is missing, stop immediately and return: ## Required Skill Invocation Rules -- Invoke relevant skills through workspace discovery (`.cursor/skills/` repo-local or `~/.cursor/skills/` global). +- Invoke relevant skills through Cursor-native discovery (`.cursor/skills/`, `~/.cursor/skills/`, or installed Cursor plugin cache entries). - Announce skill usage explicitly: - `I've read the [Skill Name] skill and I'm using it to [purpose].` - For skills with checklists, track checklist items explicitly in conversation. @@ -91,7 +91,7 @@ If any required dependency is missing, stop immediately and return: - Append `/ai_plan/` to `.gitignore`. - Commit that infra change immediately with message `chore(gitignore): ignore ai_plan local planning artifacts`. - This infra commit is EXPLICITLY separate from the task commit in Phase 9. It may occur even when the final task ends up `aborted` or `failed`. -3. Verify required sub-skills are discoverable under `.cursor/skills/superpowers/skills/` or `~/.cursor/skills/superpowers/skills/`. Announce each sub-skill before invocation using: +3. Verify required sub-skills are discoverable through Cursor-native skill discovery: the Cursor Superpowers plugin cache, `.cursor/skills/superpowers/skills/`, or `~/.cursor/skills/superpowers/skills/`. Announce each sub-skill before invocation using: `I've read the [Skill Name] skill and I'm using it to [purpose].` ### Phase 2: Parse Prompt and Question @@ -107,7 +107,7 @@ If any required dependency is missing, stop immediately and return: - All identifiers in the prompt are resolvable against the codebase. - Otherwise, ask 1-3 clarifying questions, ONE AT A TIME, multiple-choice preferred. - Empty prompt → ask exactly once: "what task?". -5. Invoke `superpowers:brainstorming` via workspace discovery (`.cursor/skills/superpowers/skills/brainstorming/SKILL.md`) for any **behavior-changing** task — feature creation, bug fix with multiple plausible approaches, refactor, design decision. Present 2-3 approaches and recommend one before finalizing the plan. The ONLY skip conditions are the same ones that allow TDD auto-skip: `pure-documentation` and `pure-comment-whitespace-rename`. When skipping, record the skip reason in the Interpretation section of `task-plan.md`. +5. Invoke `superpowers:brainstorming` through Cursor-native skill discovery for any **behavior-changing** task — feature creation, bug fix with multiple plausible approaches, refactor, design decision. Present 2-3 approaches and recommend one before finalizing the plan. The ONLY skip conditions are the same ones that allow TDD auto-skip: `pure-documentation` and `pure-comment-whitespace-rename`. When skipping, record the skip reason in the Interpretation section of `task-plan.md`. ### Phase 3: Configure Reviewer @@ -163,7 +163,7 @@ Steps: - Leave `Runtime State`, `Review History`, `Final Status` empty (skill updates these). 6. Set `Status: draft`. -**Worktree branch:** If the prompt opts in to a worktree (see Trigger Phrase Detection), invoke `superpowers:using-git-worktrees` via workspace discovery before proceeding. Otherwise continue on the current branch. +**Worktree branch:** If the prompt opts in to a worktree (see Trigger Phrase Detection), invoke `superpowers:using-git-worktrees` via Cursor-native discovery before proceeding. Otherwise continue on the current branch. ### Phase 5: Plan Review Loop @@ -224,7 +224,7 @@ Native orchestration — do not invoke `superpowers:executing-plans`. 1. Set `Status: implementation-in-progress`. 2. For every behavior-changing file edit: - - Invoke `superpowers:test-driven-development` via workspace discovery. + - Invoke `superpowers:test-driven-development` via Cursor-native discovery. - Write the failing test first. Run it. Confirm it fails. - Implement the minimal code to make it pass. Run the test. Confirm green. - Do NOT commit yet — a single task commit happens in Phase 9. @@ -236,7 +236,7 @@ Native orchestration — do not invoke `superpowers:executing-plans`. ### Phase 7: Verification Gate -Invoke `superpowers:verification-before-completion` via workspace discovery. +Invoke `superpowers:verification-before-completion` via Cursor-native discovery. Run the commands listed in the `Verification` section of `task-plan.md`: - Lint (changed files first). @@ -326,7 +326,7 @@ On MAX_ROUNDS: ### Phase 9: Commit + Push Ask -Invoke `superpowers:finishing-a-development-branch` via workspace discovery. +Invoke `superpowers:finishing-a-development-branch` via Cursor-native discovery. 1. Stage all changed files explicitly (avoid `git add -A`). 2. Single commit with message derived from the task goal: @@ -803,11 +803,11 @@ Review History is append-only. ## Variant Hardening Notes — 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. - Reviewer invocation MUST use `--mode=ask --trust --output-format json`. Never `--mode=agent`, never `--force`, never write-capable modes for reviewer calls. - `jq` is a hard prerequisite because the cursor reviewer branch always returns JSON that must be parsed for `session_id` and `result`. - Helper paths are `.cursor/skills/reviewer-runtime/...` preferred, with `~/.cursor/skills/reviewer-runtime/...` as the fallback path. -- Sub-skills are invoked through workspace discovery with explicit announcement — Cursor does not expose a `Skill` tool. +- Sub-skills are invoked through Cursor-native discovery with explicit announcement — Cursor does not expose a `Skill` tool. - `cursor-agent --version` must succeed as part of the prerequisite check. The binary is `cursor-agent`; the alias `cursor agent` is equivalent. - No plan-mode guard (Cursor Agent CLI has no plan-mode concept). diff --git a/skills/do-task/opencode/SKILL.md b/skills/do-task/opencode/SKILL.md index a07cf09..60f6a57 100644 --- a/skills/do-task/opencode/SKILL.md +++ b/skills/do-task/opencode/SKILL.md @@ -9,7 +9,7 @@ Execute an ad-hoc user prompt end-to-end: parse → clarify → plan (with revie This is a single-artifact sibling of `create-plan` + `implement-plan`. Unlike `implement-plan`, `do-task` operates on one persistent `task-plan.md` (not a full milestone plan) and defaults to the **current branch** (not a worktree). -**Core principle:** OpenCode loads skills through its native skill tool. Local skills live under `~/.config/opencode/skills/`, and OpenCode can also expose shared agent skills from `~/.agents/skills/`. Sub-skill invocations use OpenCode's native mechanism — not Claude's `Skill` tool, not Cursor's workspace discovery. +**Core principle:** OpenCode loads skills through its native skill tool. Local skills live under `~/.config/opencode/skills/`, and OpenCode can also expose shared agent skills from `~/.agents/skills/`. Sub-skill invocations use OpenCode's native mechanism — not Claude's `Skill` tool, not Cursor's discovery mechanism. ## Prerequisite Check (MANDATORY) @@ -45,7 +45,7 @@ If any required dependency is missing, stop immediately and return: - Announce skill usage explicitly: - `I've read the [Skill Name] skill and I'm using it to [purpose].` - For skills with checklists, track checklist items explicitly in conversation. -- Do NOT use Claude's `Skill` tool syntax or Cursor's workspace discovery. OpenCode's skill system may expose shared files from `~/.agents/skills/`, but invocation still goes through OpenCode's native skill mechanism. +- Do NOT use Claude's `Skill` tool syntax or Cursor's discovery mechanism. OpenCode's skill system may expose shared files from `~/.agents/skills/`, but invocation still goes through OpenCode's native skill mechanism. ## Trigger Phrase Detection diff --git a/skills/implement-plan/cursor/SKILL.md b/skills/implement-plan/cursor/SKILL.md index 9500f6f..7803d45 100644 --- a/skills/implement-plan/cursor/SKILL.md +++ b/skills/implement-plan/cursor/SKILL.md @@ -57,7 +57,7 @@ If no plan folder exists: ## Required Skill Invocation Rules -- Invoke relevant skills through workspace discovery (`.cursor/skills/`). +- Invoke relevant skills through Cursor-native discovery (`.cursor/skills/`, `~/.cursor/skills/`, or installed Cursor plugin cache entries). - Announce skill usage explicitly: - `I've read the [Skill Name] skill and I'm using it to [purpose].` - For skills with checklists, track checklist items explicitly in conversation.