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

feat(M2): Documentation flow, accuracy, consistency cleanup, and cross-platform shell portability

Browse Source
This commit is contained in:
Stefano Fiorini
2026-05-03 20:14:44 -05:00
parent 0443381aa0
commit be993429c1
59 changed files with 1898 additions and 385 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/ATLASSIAN.md
+15 -7
View File
@@ -2,13 +2,17 @@
## Purpose
Provide a portable Atlassian Cloud skill for Codex, Claude Code, Cursor Agent, OpenCode, and Pi using one shared CLI surface for common Jira and Confluence workflows.
Provide a portable Atlassian Cloud skill for Codex, Claude Code, Cursor Agent, OpenCode, and Pi
using one shared CLI surface for common Jira and Confluence workflows.
## Why This Skill Exists
The repo targets multiple agent environments with uneven MCP availability. This skill packages a consistent CLI contract so the same task-oriented workflows can be used across all supported agents without depending on MCP-specific integrations.
The repo targets multiple agent environments with uneven MCP availability. This skill packages a
consistent CLI contract so the same task-oriented workflows can be used across all supported agents
without depending on MCP-specific integrations.
The canonical runtime lives in `skills/atlassian/shared/scripts/`. Installable per-agent `scripts/` bundles are generated from that source with:
The canonical runtime lives in `skills/atlassian/shared/scripts/`. Installable per-agent
`scripts/` bundles are generated from that source with:
```bash
pnpm --dir skills/atlassian/shared/scripts sync:agents
@@ -23,7 +27,8 @@ pnpm --dir skills/atlassian/shared/scripts sync:agents
- `ATLASSIAN_EMAIL`
- `ATLASSIAN_API_TOKEN`
The `ATLASSIAN_*` values may come from the shell environment or a `.env` file in the installed agent-specific `scripts/` folder.
The `ATLASSIAN_*` values may come from the shell environment or a `.env` file in the installed
agent-specific `scripts/` folder.
Optional:
@@ -52,12 +57,15 @@ Optional:
## Command Notes
- `health` validates local configuration, probes Jira and Confluence separately, and reports one product as unavailable without masking the other.
- `health` validates local configuration, probes Jira and Confluence separately, and reports one
product as unavailable without masking the other.
- `jira-create` requires `--type`, `--summary`, and either `--project` or `ATLASSIAN_DEFAULT_PROJECT`.
- `jira-update` requires `--issue` and at least one of `--summary` or `--description-file`.
- `conf-create` requires `--title`, `--body-file`, and either `--space` or `ATLASSIAN_DEFAULT_SPACE`.
- `conf-update` requires `--page`, `--title`, and `--body-file`; it fetches the current page version before building the update payload.
- `raw --body-file` expects a workspace-scoped JSON file and is limited to validated Atlassian API prefixes.
- `conf-update` requires `--page`, `--title`, and `--body-file`; it fetches the current page
version before building the update payload.
- `raw --body-file` expects a workspace-scoped JSON file and is limited to validated Atlassian
API prefixes.
## Safety Model
docs/CLEANUP-BASELINE.md
+53
View File
@@ -290,3 +290,56 @@ pre-existing and documented in this file.
*This file is generated once (M1) and updated only when a subsequent milestone
changes the baseline status of a check.*
---
## Post-M2 state
Captured: 2026-05-03 · Platform: macOS 15 (arm64) · Node 22.14.0 · pnpm 10.18.1
M2 resolved all `verify:docs` violations and the `verify:pi` portability
issue (`stat -f` BSD-ism in `scripts/verify-pi-resources.sh`).
### `pnpm run check` aggregate (post-M2)
```text
FAIL lint (exit 1) — same 2 ESLint + 7 shellcheck pre-existing violations (§4a, §4b)
PASS typecheck
PASS test
PASS verify:pi
PASS verify:reviewers
PASS verify:docs (was FAIL in M1; now clean)
PASS verify:generated (stub)
```
Overall exit: **1** — only `lint` still fails on pre-existing violations.
`verify:docs` is now green (0 markdownlint errors, offline link-check clean,
docs-flow verifier passes).
### What changed in M2
- `scripts/lib/portable.sh` added with `portable_stat_perms` helper.
- `scripts/verify-pi-resources.sh` updated to use `portable_stat_perms`
(replaces `stat -f '%Lp'` BSD-only call).
- `scripts/lib/run-shellcheck.mjs` updated to pass `-x --source-path=SCRIPTDIR`
so shellcheck follows `source` directives correctly on both platforms.
- `skills/.markdownlint.jsonc` added to disable MD013 and MD024 for
agent-facing SKILL.md files.
- All 1160 M1 markdownlint violations resolved (auto-fix + targeted edits).
- `docs/README.md` reorganized into ordered reading flow.
- `README.md` layout section updated to reflect actual repo tree.
- `docs/REVIEWERS.md` added as canonical reviewer CLI matrix.
- `docs/TELEGRAM-NOTIFICATIONS.md` extended with Pi section.
- `docs/CREATE-PLAN.md`, `docs/IMPLEMENT-PLAN.md`, `docs/DO-TASK.md` updated
with REVIEWERS.md references and unique variant headings.
- OpenCode reviewer branches added to `skills/create-plan/opencode/SKILL.md`
and `skills/implement-plan/opencode/SKILL.md`.
- `scripts/verify-docs-flow.mjs` implemented and wired into `verify:docs`.
- `pnpm run verify:docs:online` added for external link checks.
### Ubuntu smoke note
No Docker/Ubuntu run was available at M2 capture time. The portability
fix (`portable_stat_perms`) replaces the only identified BSD-ism. The
Ubuntu Docker command is documented in
[DEVELOPMENT.md](./DEVELOPMENT.md#cross-platform-shell-support-m2).
docs/CREATE-PLAN.md
+52 -26
View File
@@ -2,7 +2,8 @@
## Purpose
Create structured implementation plans with milestone and story tracking, and optionally review them iteratively with a second model/provider before finalizing.
Create structured implementation plans with milestone and story tracking, and optionally review
them iteratively with a second model/provider before finalizing.
## Requirements
@@ -12,7 +13,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`
- Cursor can use the Cursor Superpowers plugin cache or manual `.cursor/skills/superpowers/skills` / `~/.cursor/skills/superpowers/skills` installs.
- 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}`
@@ -24,11 +26,14 @@ Create structured implementation plans with milestone and story tracking, and op
If dependencies are missing, stop and return:
"Missing dependency: native Superpowers skills are required (`superpowers:brainstorming`, `superpowers:writing-plans`). Install from https://github.com/obra/superpowers, then retry."
"Missing dependency: native Superpowers skills are required (`superpowers:brainstorming`,
`superpowers:writing-plans`). Install from https://github.com/obra/superpowers, then retry."
### Reviewer CLI Requirements (Optional)
To use the iterative plan review feature, one of these CLIs must be installed:
The canonical reviewer CLI support matrix is documented in
[REVIEWERS.md](./REVIEWERS.md). To use the iterative plan review feature, one
of these CLIs must be installed:
| Reviewer CLI | Install | Verify |
|---|---|---|
@@ -38,9 +43,11 @@ To use the iterative plan review feature, one of these CLIs must be installed:
| `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.
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.
**Additional dependency for `cursor` reviewer:** `jq` is required to parse Cursor's JSON output. Install via `brew install jq` (macOS) or your package manager. Verify: `jq --version`.
**Additional dependency for `cursor` reviewer:** `jq` is required to parse Cursor's JSON output.
Install via `brew install jq` (macOS) or your package manager. Verify: `jq --version`.
## Install
@@ -144,8 +151,10 @@ Verify Superpowers dependencies exist in your agent skills root:
- Claude Code: `~/.claude/skills/superpowers/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
- 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`
@@ -156,11 +165,14 @@ Verify Superpowers dependencies exist in your agent skills root:
- Commits `.gitignore` update locally when added.
- Asks which reviewer CLI, model, and max rounds to use (or accepts `skip` for no review).
- Iteratively reviews the plan with the chosen reviewer (default max 10 rounds) before generating files.
- Runs reviewer commands through `reviewer-runtime/run-review.sh` when available, with fallback to direct synchronous execution only if the helper is missing.
- Runs reviewer commands through `reviewer-runtime/run-review.sh` when available, with fallback to
direct synchronous execution only if the helper is missing.
- Waits as long as the reviewer runtime keeps emitting per-minute `In progress N` heartbeats.
- Requires reviewer findings to be ordered `P0` through `P3`, with `P3` explicitly non-blocking.
- Captures reviewer stderr and helper status logs for diagnostics and retains them on failed, empty-output, or operator-decision review rounds.
- Sends completion notifications through Telegram only when the shared setup in [TELEGRAM-NOTIFICATIONS.md](./TELEGRAM-NOTIFICATIONS.md) is installed and configured.
- Captures reviewer stderr and helper status logs for diagnostics and retains them on failed,
empty-output, or operator-decision review rounds.
- Sends completion notifications through Telegram only when the shared setup in
[TELEGRAM-NOTIFICATIONS.md](./TELEGRAM-NOTIFICATIONS.md) is installed and configured.
- Produces:
- `original-plan.md`
- `final-transcript.md`
@@ -172,10 +184,12 @@ 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`, `opencode`, `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`
4. **Feedback** — reviewer evaluates correctness, risks, missing steps, alternatives, security, and
returns `## Summary`, `## Findings`, and `## Verdict`
5. **Prioritize** — findings are ordered `P0`, `P1`, `P2`, `P3`
6. **Revise** — the planning agent addresses findings in priority order and re-submits
7. **Repeat** — up to max rounds until the reviewer returns `VERDICT: APPROVED`
@@ -210,13 +224,17 @@ ts=<ISO-8601> level=<info|warn|error> state=<running-silent|running-active|in-pr
```
`in-progress` is the liveness heartbeat emitted roughly once per minute with `note="In progress N"`.
`stall-warning` is a non-terminal status-log state only. It does not mean the caller should stop waiting if `in-progress` heartbeats continue.
`stall-warning` is a non-terminal status-log state only. It does not mean the caller should stop
waiting if `in-progress` heartbeats continue.
### Failure Handling
- `completed-empty-output` means the reviewer exited without producing review text; surface `.stderr` and `.status`, then retry only after diagnosing the cause.
- `needs-operator-decision` means the helper reached hard-timeout escalation; surface `.status` and decide whether to extend the timeout, abort, or retry with different parameters.
- Successful rounds clean up temp artifacts. Failed, empty-output, and operator-decision rounds should retain `.stderr`, `.status`, and `.runner.out` until diagnosed.
- `completed-empty-output` means the reviewer exited without producing review text; surface
`.stderr` and `.status`, then retry only after diagnosing the cause.
- `needs-operator-decision` means the helper reached hard-timeout escalation; surface `.status` and
decide whether to extend the timeout, abort, or retry with different parameters.
- Successful rounds clean up temp artifacts. Failed, empty-output, and operator-decision rounds
should retain `.stderr`, `.status`, and `.runner.out` until diagnosed.
- As long as fresh `in-progress` heartbeats continue to arrive roughly once per minute, the caller should keep waiting.
### Supported Reviewer CLIs
@@ -235,15 +253,20 @@ For all supported reviewer CLIs, the preferred execution path is:
2. run that script through `reviewer-runtime/run-review.sh`
3. fall back to direct synchronous execution only if the helper is missing or not executable
## Pi Reviewer Support
All workflow variants can use Pi itself as a reviewer CLI. Use `pi/<pi-model-name>` shorthand, for example `pi/claude-opus-4-7`; this means `REVIEWER_CLI=pi` and `REVIEWER_MODEL=claude-opus-4-7`. Provider-qualified or multi-slash Pi model IDs are preserved after the first `pi/` prefix, for example `pi/anthropic/claude-opus-4-7`.
All workflow variants can use Pi itself as a reviewer CLI. Use `pi/<pi-model-name>` shorthand, for
example `pi/claude-opus-4-7`; this means `REVIEWER_CLI=pi` and `REVIEWER_MODEL=claude-opus-4-7`.
Provider-qualified or multi-slash Pi model IDs are preserved after the first `pi/` prefix, for
example `pi/anthropic/claude-opus-4-7`.
The canonical isolated read-only Pi reviewer flag contract lives in [PI-COMMON-REVIEWER.md](./PI-COMMON-REVIEWER.md). This workflow passes the plan review payload at `/tmp/plan-${REVIEW_ID}.md` and expects the standard `## Summary`, `## Findings`, and `## Verdict` response. Pi reviewer output is captured as markdown stdout, not JSON.
The canonical isolated read-only Pi reviewer flag contract lives in
[PI-COMMON-REVIEWER.md](./PI-COMMON-REVIEWER.md). This workflow passes the plan review payload at
`/tmp/plan-${REVIEW_ID}.md` and expects the standard `## Summary`, `## Findings`, and `## Verdict`
response. Pi reviewer output is captured as markdown stdout, not JSON.
If the Pi reviewer model or provider is unavailable, surface the helper stderr/status and use `pi --list-models [search]` to inspect configured models.
If the Pi reviewer model or provider is unavailable, surface the helper stderr/status and use
`pi --list-models [search]` to inspect configured models.
## Notifications
@@ -257,17 +280,20 @@ If the Pi reviewer model or provider is unavailable, surface the helper stderr/s
All plan templates now include guardrail sections that enforce:
**Planning Guardrails** (`milestone-plan.md`):
- Design validation before implementation planning
- Native skill discovery (no deprecated CLI wrappers)
- Milestone verification + local commits + explicit approval
**Tracking Guardrails** (`story-tracker.md`):
- Immediate status updates when work starts/completes
- Explicit user approval at each milestone boundary
- No pushes until all milestones approved
- Synchronization between tracker and plan files
**Skill Workflow Guardrails** (`continuation-runbook.md`):
- Native skill invocation before action
- Explicit skill announcements
- Checklist tracking for driven skills
@@ -275,7 +301,7 @@ All plan templates now include guardrail sections that enforce:
## Variant Hardening Notes
### Claude Code
### Claude Code Hardening
- Must invoke explicit required sub-skills:
- `superpowers:brainstorming`
@@ -284,7 +310,7 @@ All plan templates now include guardrail sections that enforce:
- if in plan mode, instruct user to exit plan mode before generating files
- Must copy `original-plan.md` from `~/.claude/plans/` when available.
### Codex
### Codex Hardening
- Must use native skill discovery from `~/.agents/skills/` (no CLI wrappers).
- Must verify Superpowers skills symlink: `~/.agents/skills/superpowers -> ~/.codex/superpowers/skills`
@@ -294,7 +320,7 @@ All plan templates now include guardrail sections that enforce:
- Must track checklist-driven skills with `update_plan` todos.
- Deprecated CLI commands (`superpowers-codex bootstrap`, `use-skill`) must NOT be used.
### OpenCode
### OpenCode Hardening
- Must use OpenCode native skill tool (not Claude/Codex invocation syntax).
- Must verify Superpowers skill discovery under:
@@ -304,7 +330,7 @@ All plan templates now include guardrail sections that enforce:
- `superpowers/brainstorming`
- `superpowers/writing-plans`
### Cursor
### Cursor Hardening
- Must use Cursor-native discovery from `.cursor/skills/`, `~/.cursor/skills/`, or installed Cursor plugin cache entries.
- Must announce skill usage explicitly before invocation.
docs/CURSOR.md
+3 -1
View File
@@ -54,7 +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
docs/DEVELOPMENT.md
+59 -13
View File
@@ -40,7 +40,8 @@ pnpm run check
| `pnpm run lint:fix` | Auto-fix ESLint + Prettier (do not run on pre-existing code until M2) |
| `pnpm run typecheck` | TypeScript `tsc --noEmit` in workspace packages |
| `pnpm run test` | Run all tests (root + workspace packages) |
| `pnpm run verify:docs` | markdownlint + offline link-check |
| `pnpm run verify:docs` | markdownlint + offline link-check + docs-flow verifier |
| `pnpm run verify:docs:online` | Same as `verify:docs` but with full external link checking |
| `pnpm run verify:generated` | Assert generated output freshness (stub; fleshed out in M3) |
| `pnpm run check` | Aggregate: run every gate above and report a summary |
@@ -100,6 +101,59 @@ agent-variant directories) and runs shellcheck on each.
The wrapper exits with code **2** (not 1) when shellcheck is missing, so CI
can distinguish "shellcheck absent" from "shellcheck found violations".
## Cross-platform shell support (M2)
All shell scripts under `scripts/` and `skills/reviewer-runtime/` that are
exercised by `verify:pi`, `verify:reviewers`, `sync:pi`, and `test:installer`
must work on both **macOS** (BSD userland) and **Ubuntu/Debian** (GNU
userland) without modification.
### BSD vs GNU differences encountered
| Feature | macOS (BSD) | Linux (GNU) | Portable form |
|---------|-------------|-------------|---------------|
| `stat` permissions | `stat -f '%Lp' <path>` | `stat -c '%a' <path>` | `portable_stat_perms` helper |
| herestrings (`<<<`) | supported (bash) | supported (bash) | OK (scripts use `#!/usr/bin/env bash`) |
| `find -E` (extended regex) | macOS-only | not available | use `grep` or POSIX `-name` |
| `sed -i ''` | macOS form | use `sed -i` on Linux | detect or avoid in-place sed |
| `date -j` (date arithmetic) | macOS-only | use `date -d` on Linux | Node helper or `date +%s` |
| `readlink -f` | not on macOS by default | GNU standard | `realpath` or `cd && pwd` |
### `scripts/lib/portable.sh`
A shared helper that abstracts the two known BSD/GNU divergences hit in
this repo:
```bash
# Source from any script that needs portable stat
# shellcheck source=lib/portable.sh
source "$(dirname "${BASH_SOURCE[0]}")/lib/portable.sh"
# Returns octal permission string: e.g. "755"
portable_stat_perms "$path"
```
The `shellcheck` wrapper passes `-x --source-path=SCRIPTDIR` so source
directives resolve relative to the script file, not the working directory.
### How to run the Ubuntu smoke test locally
```bash
# Requires Docker
docker run --rm \
-v "$PWD:/w" \
-w /w \
node:20-bookworm \
bash -lc 'apt-get update -q && apt-get install -y -q shellcheck ripgrep python3 \
&& corepack enable \
&& pnpm install --frozen-lockfile \
&& pnpm run check'
```
This runs the full `pnpm run check` suite (lint, typecheck, test, verify:pi,
verify:reviewers, verify:docs, verify:generated) inside a clean Debian Bookworm
container with Node 20.
## Transitional `check` contract (M1)
`pnpm run check` may exit non-zero in M1. This is expected. The contract is:
@@ -108,18 +162,10 @@ can distinguish "shellcheck absent" from "shellcheck found violations".
> `docs/CLEANUP-BASELINE.md`. Previously-green checks remain green. No
> violations are introduced by M1's own changes.
The current baseline failures are:
1. `lint` — 2 ESLint violations in existing root scripts; 7 shellcheck
findings in existing `.sh` files.
2. `verify:docs` — 1160 markdownlint violations in pre-existing docs and
`SKILL.md` files.
All other checks (`typecheck`, `test`, `verify:pi`, `verify:reviewers`,
`verify:generated`) pass with EXIT 0.
Once later milestones fix the baseline violations, `pnpm run check` will
reach EXIT 0 and the transitional contract expires.
**M2 update:** `verify:docs` is now green. `lint` still fails on the same
2 pre-existing ESLint violations and 7 pre-existing shellcheck findings
documented in `docs/CLEANUP-BASELINE.md`. Those will be fixed in a dedicated
cleanup pass. No violations were introduced by M2.
## pnpm workspace policy (M1 exclusion-only)
docs/DO-TASK.md
+139 -60
View File
@@ -2,13 +2,19 @@
## Purpose
Execute a single user-supplied prompt end-to-end with **two reviewer loops** (plan review + implementation review), with TDD-first execution, a pre-implementation verification gate, and a single task commit — all in one run of the skill. `do-task` is scoped to small-to-medium ad-hoc tasks; for multi-milestone work use `create-plan` + `implement-plan` instead.
Execute a single user-supplied prompt end-to-end with **two reviewer loops** (plan review +
implementation review), with TDD-first execution, a pre-implementation verification gate, and a
single task commit — all in one run of the skill. `do-task` is scoped to small-to-medium ad-hoc
tasks; for multi-milestone work use `create-plan` + `implement-plan` instead.
`do-task` persists one plan artifact per run: `ai_plan/YYYY-MM-DD-<slug>/task-plan.md`. The folder is kept as a record after success (not deleted). Resume is supported via the `Status` enum and Runtime State fields.
`do-task` persists one plan artifact per run: `ai_plan/YYYY-MM-DD-<slug>/task-plan.md`. The
folder is kept as a record after success (not deleted). Resume is supported via the `Status` enum
and Runtime State fields.
## Requirements
- Git repo with `/ai_plan/` entry in `.gitignore` (the skill adds the entry automatically if missing and commits it as a separate infra commit).
- Git repo with `/ai_plan/` entry in `.gitignore` (the skill adds the entry automatically if
missing and commits it as a separate infra commit).
- Superpowers skills installed from: https://github.com/obra/superpowers
- Required dependencies (vary by variant; see Install below):
- `superpowers:brainstorming` (or `superpowers/brainstorming` for OpenCode)
@@ -18,32 +24,50 @@ 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`
- 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.
- 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:
- 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}`
- OpenCode: `~/.config/opencode/skills/reviewer-runtime/{run-review.sh,notify-telegram.sh}`
- Cursor: `.cursor/skills/reviewer-runtime/{run-review.sh,notify-telegram.sh}` (repo-local, preferred) or `~/.cursor/skills/reviewer-runtime/{run-review.sh,notify-telegram.sh}` (global fallback)
- Pi: `.pi/skills/reviewer-runtime/pi/{run-review.sh,notify-telegram.sh}` (repo-local) or `~/.pi/agent/skills/reviewer-runtime/pi/{run-review.sh,notify-telegram.sh}` (global)
- Cursor: `.cursor/skills/reviewer-runtime/{run-review.sh,notify-telegram.sh}` (repo-local,
preferred) or `~/.cursor/skills/reviewer-runtime/{run-review.sh,notify-telegram.sh}`
(global fallback)
- Pi: `.pi/skills/reviewer-runtime/pi/{run-review.sh,notify-telegram.sh}` (repo-local) or
`~/.pi/agent/skills/reviewer-runtime/pi/{run-review.sh,notify-telegram.sh}` (global)
- 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 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.
- **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 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.`
- **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 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.`
### Reviewer CLI Requirements
One of these CLIs must be installed to drive either of the two review loops:
The canonical reviewer CLI support matrix is documented in
[REVIEWERS.md](./REVIEWERS.md). One of these CLIs must be installed to drive either of the two
review loops:
| Reviewer CLI | Install | Verify | Read-Only Mode | Session Resume |
|---|---|---|---|---|
@@ -53,9 +77,12 @@ One of these CLIs must be installed to drive either of the two review loops:
| `opencode` | `brew install opencode` or your package manager | `opencode --version` | `--agent plan` | Opt-in (`-s <id>`; fresh call is the default) |
| `pi` | Install Pi coding agent | `pi --version`; list models with `pi --list-models [search]` | `--tools read,grep,find,ls` | No (fresh call each round) |
The reviewer CLI is independent of which agent is running the skill — e.g., Claude Code can send both the plan and the implementation to Codex for review.
The reviewer CLI is independent of which agent is running the skill — e.g., Claude Code can send
both the plan and the implementation to Codex for review.
**Additional dependency for `cursor` reviewer:** `jq` is required to parse Cursor's JSON output. Install via `brew install jq` (macOS) or your package manager. Verify: `jq --version`. The cursor variant of `do-task` makes `jq` a hard prerequisite regardless of which reviewer CLI is selected.
**Additional dependency for `cursor` reviewer:** `jq` is required to parse Cursor's JSON output.
Install via `brew install jq` (macOS) or your package manager. Verify: `jq --version`. The cursor
variant of `do-task` makes `jq` a hard prerequisite regardless of which reviewer CLI is selected.
## Install
@@ -138,9 +165,11 @@ Pi workflow skills also require Superpowers. See [PI-SUPERPOWERS.md](./PI-SUPERP
## Verify Installation
Run the per-variant checks for everything the corresponding `SKILL.md` enforces. Each check is structured: (1) CLI binary version, (2) skill file presence, (3) reviewer-runtime + notifier helper presence, (4) Superpowers sub-skill discovery, (5) variant-specific extras.
Run the per-variant checks for everything the corresponding `SKILL.md` enforces. Each check is
structured: (1) CLI binary version, (2) skill file presence, (3) reviewer-runtime + notifier
helper presence, (4) Superpowers sub-skill discovery, (5) variant-specific extras.
### Codex
### Codex Verify
```bash
codex --version
@@ -154,7 +183,7 @@ test -f ~/.agents/skills/superpowers/verification-before-completion/SKILL.md
test -f ~/.agents/skills/superpowers/finishing-a-development-branch/SKILL.md
```
### Claude Code
### Claude Code Verify
```bash
claude --version
@@ -167,7 +196,7 @@ test -f ~/.claude/skills/superpowers/verification-before-completion/SKILL.md
test -f ~/.claude/skills/superpowers/finishing-a-development-branch/SKILL.md
```
### OpenCode
### OpenCode Verify
```bash
opencode --version
@@ -180,7 +209,7 @@ test -f ~/.agents/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
### Cursor Verify
```bash
cursor-agent --version
@@ -194,7 +223,7 @@ test -f .cursor/skills/superpowers/skills/verification-before-completion/SKILL.m
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
### Pi Verify
```bash
pi --version
@@ -210,26 +239,44 @@ test -f .pi/skills/superpowers/finishing-a-development-branch/SKILL.md || test -
## Key Behavior
- Creates one persistent plan artifact at `ai_plan/YYYY-MM-DD-<slug>/task-plan.md`.
- Ensures `/ai_plan/` is in `.gitignore`. If missing, adds it and creates a separate `chore(gitignore): ignore ai_plan local planning artifacts` commit.
- Parses the user prompt, detects the trigger phrase, and asks 1-3 clarifying questions unless the prompt already has a concrete target + outcome + unambiguous scope + resolvable identifiers.
- Invokes `superpowers:brainstorming` for any behavior-changing task (feature creation, non-trivial bug fix, refactor, design decision). The only skip conditions are `pure-documentation` and `pure-comment-whitespace-rename`.
- Asks which reviewer CLI, model, and max rounds to use (or accepts `skip` for no review). "Use defaults" maps to `codex / gpt-5.4 / MAX_ROUNDS=10`.
- Runs the plan review loop (Phase 5) before implementation, iterating up to `MAX_ROUNDS` (default 10) or until the reviewer returns `VERDICT: APPROVED`.
- Executes with TDD-first (Phase 6) via `superpowers:test-driven-development`. Auto-skip permitted only for `pure-documentation` and `pure-comment-whitespace-rename`; all other skips (including config-file additions) require explicit user approval, recorded in the TDD Approach section with an ISO-8601 timestamp.
- Ensures `/ai_plan/` is in `.gitignore`. If missing, adds it and creates a separate
`chore(gitignore): ignore ai_plan local planning artifacts` commit.
- Parses the user prompt, detects the trigger phrase, and asks 1-3 clarifying questions unless
the prompt already has a concrete target + outcome + unambiguous scope + resolvable identifiers.
- Invokes `superpowers:brainstorming` for any behavior-changing task (feature creation,
non-trivial bug fix, refactor, design decision). The only skip conditions are
`pure-documentation` and `pure-comment-whitespace-rename`.
- Asks which reviewer CLI, model, and max rounds to use (or accepts `skip` for no review).
"Use defaults" maps to `codex / gpt-5.4 / MAX_ROUNDS=10`.
- Runs the plan review loop (Phase 5) before implementation, iterating up to `MAX_ROUNDS`
(default 10) or until the reviewer returns `VERDICT: APPROVED`.
- Executes with TDD-first (Phase 6) via `superpowers:test-driven-development`. Auto-skip
permitted only for `pure-documentation` and `pure-comment-whitespace-rename`; all other skips
(including config-file additions) require explicit user approval, recorded in the TDD Approach
section with an ISO-8601 timestamp.
- Runs lint/typecheck/tests as a **verification gate** (Phase 7) before the implementation review loop.
- Runs the implementation review loop (Phase 8) against the diff + verification output, iterating up to `MAX_ROUNDS` or until `APPROVED`.
- Runs the implementation review loop (Phase 8) against the diff + verification output,
iterating up to `MAX_ROUNDS` or until `APPROVED`.
- Scans every outbound reviewer payload for secrets (subroutine step 1a). Per-payload, no caching.
- Creates a **single commit** after the implementation review approves. Does NOT push. Asks the user for explicit `yes` before any push.
- Defaults to the **current branch**. Worktree only on explicit opt-in (`"in a worktree"`, `"use a worktree"`, `"on an isolated branch"`, `"on a new branch called X"`).
- Creates a **single commit** after the implementation review approves. Does NOT push. Asks the
user for explicit `yes` before any push.
- Defaults to the **current branch**. Worktree only on explicit opt-in (`"in a worktree"`,
`"use a worktree"`, `"on an isolated branch"`, `"on a new branch called X"`).
- Supports resume: detects existing folder by slug and uses `Status` + Runtime State to decide how to re-enter.
- Sends completion notifications through Telegram only when the shared setup in [TELEGRAM-NOTIFICATIONS.md](./TELEGRAM-NOTIFICATIONS.md) is installed and configured.
- Sends completion notifications through Telegram only when the shared setup in
[TELEGRAM-NOTIFICATIONS.md](./TELEGRAM-NOTIFICATIONS.md) is installed and configured.
## Dual Review Loops
`do-task` runs the reviewer twice per successful run, with separate session IDs so reviewer context never leaks across loops.
1. **Plan review loop (Phase 5)** — payload is the current `task-plan.md` with `Runtime State` and `Review History` stripped. The reviewer evaluates whether the plan matches the prompt, whether assumptions are surfaced, whether acceptance criteria are testable, whether the TDD approach is appropriate, and whether there are missing files/risks/security concerns.
2. **Implementation review loop (Phase 8)** — payload is the approved task plan (without Runtime State) + `git diff` (unstaged + staged) + verification output (lint, typecheck, tests). The reviewer evaluates correctness, code quality, test coverage, security, and regression risk.
1. **Plan review loop (Phase 5)** — payload is the current `task-plan.md` with `Runtime State`
and `Review History` stripped. The reviewer evaluates whether the plan matches the prompt,
whether assumptions are surfaced, whether acceptance criteria are testable, whether the TDD
approach is appropriate, and whether there are missing files/risks/security concerns.
2. **Implementation review loop (Phase 8)** — payload is the approved task plan (without Runtime
State) + `git diff` (unstaged + staged) + verification output (lint, typecheck, tests). The
reviewer evaluates correctness, code quality, test coverage, security, and regression risk.
Both loops share the same 9-step subroutine and the same `MAX_ROUNDS` counter (default 10).
@@ -239,7 +286,10 @@ Both loops share the same 9-step subroutine and the same `MAX_ROUNDS` counter (d
2. **Secret scan (step 1a)** — per-payload, no caching. See Secret Scan section below.
3. Generate reviewer command script at `/tmp/do-task-<kind>-review-<REVIEW_ID>.sh`.
4. Run via `reviewer-runtime/run-review.sh`.
5. Promote reviewer output and capture the session ID on Round 1; persist it to `task-plan.md` Runtime State under the loop-specific variable (`CODEX_PLAN_SESSION_ID`, `CODEX_IMPL_SESSION_ID`, `CURSOR_PLAN_SESSION_ID`, `CURSOR_IMPL_SESSION_ID`, `OPENCODE_PLAN_SESSION_ID`, or `OPENCODE_IMPL_SESSION_ID`).
5. Promote reviewer output and capture the session ID on Round 1; persist it to `task-plan.md`
Runtime State under the loop-specific variable (`CODEX_PLAN_SESSION_ID`,
`CODEX_IMPL_SESSION_ID`, `CURSOR_PLAN_SESSION_ID`, `CURSOR_IMPL_SESSION_ID`,
`OPENCODE_PLAN_SESSION_ID`, or `OPENCODE_IMPL_SESSION_ID`).
6. Parse verdict; append an entry to Review History; bump the round counter.
7. Branch: `APPROVED` → exit, `REVISE` → caller revises and re-enters, `MAX_ROUNDS` → caller decides.
8. Liveness contract: wait while `In progress N` heartbeats arrive from the runner.
@@ -274,7 +324,8 @@ ts=<ISO-8601> level=<info|warn|error> state=<running-silent|running-active|in-pr
```
`in-progress` is the liveness heartbeat emitted roughly once per minute with `note="In progress N"`.
`stall-warning` is a non-terminal status-log state only. It does not mean the caller should stop waiting if `in-progress` heartbeats continue.
`stall-warning` is a non-terminal status-log state only. It does not mean the caller should
stop waiting if `in-progress` heartbeats continue.
### Persistent Artifact
@@ -295,19 +346,25 @@ The one file kept across runs is `ai_plan/<slug>/task-plan.md`. Its `Status` enu
## Failure Handling
- `completed-empty-output` — the reviewer exited without producing review text; surface `.stderr` and `.status`, then retry only after diagnosing the cause.
- `needs-operator-decision` — the helper reached hard-timeout escalation; surface `.status` and decide whether to extend the timeout, abort, or retry with different parameters.
- Successful rounds clean up temp artifacts. Failed, empty-output, and operator-decision rounds retain `.stderr`, `.status`, and `.runner.out` until diagnosed.
- Verification gate (Phase 7) retries up to 3 times. On exhaustion, `Status` becomes `aborted-verification` and the user is asked whether to retry, override, or abort.
- `completed-empty-output` — the reviewer exited without producing review text; surface
`.stderr` and `.status`, then retry only after diagnosing the cause.
- `needs-operator-decision` — the helper reached hard-timeout escalation; surface `.status`
and decide whether to extend the timeout, abort, or retry with different parameters.
- Successful rounds clean up temp artifacts. Failed, empty-output, and operator-decision rounds
retain `.stderr`, `.status`, and `.runner.out` until diagnosed.
- Verification gate (Phase 7) retries up to 3 times. On exhaustion, `Status` becomes
`aborted-verification` and the user is asked whether to retry, override, or abort.
- As long as fresh `in-progress` heartbeats continue to arrive roughly once per minute, the caller keeps waiting.
## Secret Scan (subroutine step 1a; per-payload; no caching)
Every outbound reviewer payload is scanned **before** being sent to the reviewer CLI. This scan runs on every round of both loops. No results are cached, because the Phase 8 payload includes newly-introduced diff content that earlier rounds never saw.
Every outbound reviewer payload is scanned **before** being sent to the reviewer CLI. This scan
runs on every round of both loops. No results are cached, because the Phase 8 payload includes
newly-introduced diff content that earlier rounds never saw.
Canonical anchored regex list (10 patterns):
```
```text
AWS access key: AKIA[0-9A-Z]{16}
GCP service-acct: "type"\s*:\s*"service_account"
GitHub tokens: (ghp|gho|ghs|ghu|ghr)_[A-Za-z0-9]{36,}
@@ -320,9 +377,14 @@ PEM private keys: -----BEGIN [A-Z ]+ PRIVATE KEY-----
JWT: eyJ[A-Za-z0-9_-]+\.eyJ[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+
```
If a match is found, the skill **redacts the matched text before showing it to the user** using the fixed token `[REDACTED:<pattern-label>:<match-length>-chars]` (pattern labels: `aws-access-key`, `gcp-service-account`, `github-token`, `slack-token`, `openai-key`, `anthropic-key`, `pem-private-key`, `dotenv-style`, `jwt`). File paths and line numbers are kept. Raw match text is never echoed to terminal, chat log, or any persistent file.
If a match is found, the skill **redacts the matched text before showing it to the user** using
the fixed token `[REDACTED:<pattern-label>:<match-length>-chars]` (pattern labels:
`aws-access-key`, `gcp-service-account`, `github-token`, `slack-token`, `openai-key`,
`anthropic-key`, `pem-private-key`, `dotenv-style`, `jwt`). File paths and line numbers are kept.
Raw match text is never echoed to terminal, chat log, or any persistent file.
The user answers `yes` / `no` / `redact`:
- `yes` — proceed; Runtime State records `last_scan_outcome_<kind>=user-approved-with-matches`.
- `redact` — the user supplies redactions, the skill applies them, and re-scans before sending. Runtime State records `last_scan_outcome_<kind>=redacted-and-approved`.
- `no` — stop the loop, set `Status: failed`, send Telegram summary.
@@ -343,15 +405,21 @@ For all supported reviewer CLIs, the preferred execution path is:
2. Run that script through `reviewer-runtime/run-review.sh`.
3. Fall back to direct synchronous execution only if the helper is missing or not executable.
## Pi Reviewer Support
All workflow variants can use Pi itself as a reviewer CLI. Use `pi/<pi-model-name>` shorthand, for example `pi/claude-opus-4-7`; this means `REVIEWER_CLI=pi` and `REVIEWER_MODEL=claude-opus-4-7`. Provider-qualified or multi-slash Pi model IDs are preserved after the first `pi/` prefix, for example `pi/anthropic/claude-opus-4-7`.
All workflow variants can use Pi itself as a reviewer CLI. Use `pi/<pi-model-name>` shorthand,
for example `pi/claude-opus-4-7`; this means `REVIEWER_CLI=pi` and
`REVIEWER_MODEL=claude-opus-4-7`. Provider-qualified or multi-slash Pi model IDs are preserved
after the first `pi/` prefix, for example `pi/anthropic/claude-opus-4-7`.
The canonical isolated read-only Pi reviewer flag contract lives in [PI-COMMON-REVIEWER.md](./PI-COMMON-REVIEWER.md). This workflow passes the plan and implementation review payload at `/tmp/do-task-${REVIEW_KIND}-${REVIEW_ID}.md` and expects the standard `## Summary`, `## Findings`, and `## Verdict` response. Pi reviewer output is captured as markdown stdout, not JSON.
The canonical isolated read-only Pi reviewer flag contract lives in
[PI-COMMON-REVIEWER.md](./PI-COMMON-REVIEWER.md). This workflow passes the plan and
implementation review payload at `/tmp/do-task-${REVIEW_KIND}-${REVIEW_ID}.md` and expects the
standard `## Summary`, `## Findings`, and `## Verdict` response. Pi reviewer output is captured
as markdown stdout, not JSON.
If the Pi reviewer model or provider is unavailable, surface the helper stderr/status and use `pi --list-models [search]` to inspect configured models.
If the Pi reviewer model or provider is unavailable, surface the helper stderr/status and use
`pi --list-models [search]` to inspect configured models.
## Notifications
@@ -359,7 +427,8 @@ If the Pi reviewer model or provider is unavailable, surface the helper stderr/s
- Shared setup: [TELEGRAM-NOTIFICATIONS.md](./TELEGRAM-NOTIFICATIONS.md)
- Notification failures are non-blocking, but they must be surfaced to the user.
- Before stopping for any user interaction, approval, or manual decision, the skill sends a Telegram summary first if configured.
- Terminal outcomes that trigger Telegram: `pushed`, `local-only`, `aborted-plan-review`, `aborted-impl-review`, `aborted-verification`, `failed`.
- Terminal outcomes that trigger Telegram: `pushed`, `local-only`, `aborted-plan-review`,
`aborted-impl-review`, `aborted-verification`, `failed`.
The reviewer-runtime helper also supports manual override flags for diagnostics:
@@ -377,7 +446,9 @@ run-review.sh \
## Template Guardrails
All four `templates/task-plan.md` files share identical core sections (14 `## `-level headings) and identical Status enum (10 values). Variant-specific guardrail language is permitted in the leading blockquote and in the `Runtime` field of the Metadata table.
All four `templates/task-plan.md` files share identical core sections (14 `##`-level headings)
and identical Status enum (10 values). Variant-specific guardrail language is permitted in the
leading blockquote and in the `Runtime` field of the Metadata table.
**Core sections** (appear in every variant, same order):
@@ -396,11 +467,15 @@ All four `templates/task-plan.md` files share identical core sections (14 `## `-
13. Final Status
14. Guardrails (do NOT remove)
**Runtime State keys** (same across all variants): `plan_review_round`, `implementation_review_round`, `CODEX_PLAN_SESSION_ID`, `CODEX_IMPL_SESSION_ID`, `CURSOR_PLAN_SESSION_ID`, `CURSOR_IMPL_SESSION_ID`, `OPENCODE_PLAN_SESSION_ID`, `OPENCODE_IMPL_SESSION_ID`, `last_phase_entered`, `last_round_ts`, `last_scan_outcome_plan`, `last_scan_outcome_impl`, `verification_attempts`, `tests_added_count`, `tdd_used`.
**Runtime State keys** (same across all variants): `plan_review_round`,
`implementation_review_round`, `CODEX_PLAN_SESSION_ID`, `CODEX_IMPL_SESSION_ID`,
`CURSOR_PLAN_SESSION_ID`, `CURSOR_IMPL_SESSION_ID`, `OPENCODE_PLAN_SESSION_ID`,
`OPENCODE_IMPL_SESSION_ID`, `last_phase_entered`, `last_round_ts`, `last_scan_outcome_plan`,
`last_scan_outcome_impl`, `verification_attempts`, `tests_added_count`, `tdd_used`.
## Variant Hardening Notes
### Claude Code
### Claude Code Hardening
- Must invoke explicit required sub-skills via the `Skill` tool:
- `superpowers:brainstorming`
@@ -411,7 +486,7 @@ All four `templates/task-plan.md` files share identical core sections (14 `## `-
- Must enforce plan-mode file-write guard in Phase 4:
- If currently in plan mode, instruct user to exit plan mode before writing `task-plan.md`.
### Codex
### Codex Hardening
- Must use native skill discovery from `~/.agents/skills/` (no CLI wrappers).
- Must verify Superpowers skills symlink: `~/.agents/skills/superpowers -> ~/.codex/superpowers/skills`
@@ -422,22 +497,25 @@ All four `templates/task-plan.md` files share identical core sections (14 `## `-
- Helper paths: `~/.codex/skills/reviewer-runtime/...`.
- No plan-mode guard (Codex has no plan-mode concept).
### OpenCode
### OpenCode Hardening
- 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 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 `~/.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
### Cursor Hardening
- 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.
- Reviewer invocations MUST use `--mode=ask --trust --output-format json`. Never `--mode=agent`, never `--force`, never write-capable modes for reviewer calls.
- Reviewer invocations MUST use `--mode=ask --trust --output-format json`. Never `--mode=agent`,
never `--force`, never write-capable modes for reviewer calls.
- No plan-mode guard (Cursor has no plan-mode concept).
## Execution Workflow Rules
@@ -447,7 +525,8 @@ All four `templates/task-plan.md` files share identical core sections (14 `## `-
- Plan review completes before any implementation starts.
- Phase 7 verification gate must pass before the implementation review starts.
- The task commit is a single commit created in Phase 9.
- The `.gitignore` infra commit (Phase 1) is explicitly separate from the task commit and is allowed even when the final task ends up `aborted` or `failed`.
- The `.gitignore` infra commit (Phase 1) is explicitly separate from the task commit and is
allowed even when the final task ends up `aborted` or `failed`.
- No push without explicit `yes` from the user.
- Secret scan runs per-payload with no caching.
- `MAX_ROUNDS=10` is shared across both loops (single mental model).
docs/IMPLEMENT-PLAN.md
+70 -31
View File
@@ -2,7 +2,10 @@
## Purpose
Execute an existing plan (created by `create-plan`) in an isolated git worktree, with iterative cross-model review at each milestone boundary. Milestones are implemented one-by-one with lint/typecheck/test gates, reviewed by a second model/provider, and committed locally until all are approved.
Execute an existing plan (created by `create-plan`) in an isolated git worktree, with iterative
cross-model review at each milestone boundary. Milestones are implemented one-by-one with
lint/typecheck/test gates, reviewed by a second model/provider, and committed locally until all
are approved.
## Requirements
@@ -19,7 +22,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`
- Cursor can use the Cursor Superpowers plugin cache or manual `.cursor/skills/superpowers/skills` / `~/.cursor/skills/superpowers/skills` installs.
- 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}`
@@ -35,7 +39,9 @@ If dependencies are missing, stop and return:
### Reviewer CLI Requirements (Optional)
To use the iterative milestone review feature, one of these CLIs must be installed:
The canonical reviewer CLI support matrix is documented in
[REVIEWERS.md](./REVIEWERS.md). To use the iterative milestone review feature, one of these CLIs
must be installed:
| Reviewer CLI | Install | Verify |
|---|---|---|
@@ -45,9 +51,11 @@ To use the iterative milestone review feature, one of these CLIs must be install
| `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.
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.
**Additional dependency for `cursor` reviewer:** `jq` is required to parse Cursor's JSON output. Install via `brew install jq` (macOS) or your package manager. Verify: `jq --version`.
**Additional dependency for `cursor` reviewer:** `jq` is required to parse Cursor's JSON output.
Install via `brew install jq` (macOS) or your package manager. Verify: `jq --version`.
## Install
@@ -124,7 +132,8 @@ cp -R skills/reviewer-runtime/pi/* .pi/skills/reviewer-runtime/pi/
chmod +x .pi/skills/reviewer-runtime/pi/*.sh
```
Global manual installs use `~/.pi/agent/skills/implement-plan/` and `~/.pi/agent/skills/reviewer-runtime/pi/` instead of `.pi/skills/...`.
Global manual installs use `~/.pi/agent/skills/implement-plan/` and
`~/.pi/agent/skills/reviewer-runtime/pi/` instead of `.pi/skills/...`.
Pi workflow skills also require Superpowers. See [PI-SUPERPOWERS.md](./PI-SUPERPOWERS.md) and [PI-COMMON-REVIEWER.md](./PI-COMMON-REVIEWER.md).
@@ -157,14 +166,30 @@ Verify Superpowers execution dependencies exist in your agent skills root:
- 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`
- Pi: `.pi/skills/superpowers/finishing-a-development-branch/SKILL.md` or `~/.pi/agent/skills/superpowers/finishing-a-development-branch/SKILL.md` or `~/.agents/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`
- Pi: `.pi/skills/superpowers/finishing-a-development-branch/SKILL.md` or
`~/.pi/agent/skills/superpowers/finishing-a-development-branch/SKILL.md` or
`~/.agents/skills/superpowers/finishing-a-development-branch/SKILL.md`
## Key Behavior
@@ -173,14 +198,17 @@ Verify Superpowers execution dependencies exist in your agent skills root:
- Executes milestones one-by-one, tracking stories in `story-tracker.md`.
- Runs lint/typecheck/tests as a gate before each milestone review.
- Sends each milestone to a reviewer CLI for approval (max rounds configurable, default 10).
- Runs reviewer commands through `reviewer-runtime/run-review.sh` when available, with fallback to direct synchronous execution only if the helper is missing.
- Runs reviewer commands through `reviewer-runtime/run-review.sh` when available, with fallback to
direct synchronous execution only if the helper is missing.
- Waits as long as the reviewer runtime keeps emitting per-minute `In progress N` heartbeats.
- Requires reviewer findings to be ordered `P0` through `P3`, with `P3` explicitly non-blocking.
- Captures reviewer stderr and helper status logs for diagnostics and retains them on failed, empty-output, or operator-decision review rounds.
- Captures reviewer stderr and helper status logs for diagnostics and retains them on failed,
empty-output, or operator-decision review rounds.
- Commits each milestone locally only after reviewer approval (does not push).
- After all milestones approved, merges worktree branch to parent and deletes worktree.
- Supports resume: detects existing worktree and `in-dev`/`completed` stories.
- Sends completion notifications through Telegram only when the shared setup in [TELEGRAM-NOTIFICATIONS.md](./TELEGRAM-NOTIFICATIONS.md) is installed and configured.
- Sends completion notifications through Telegram only when the shared setup in
[TELEGRAM-NOTIFICATIONS.md](./TELEGRAM-NOTIFICATIONS.md) is installed and configured.
## Milestone Review Loop
@@ -189,7 +217,8 @@ After each milestone is implemented and verified, the skill sends it to a second
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`
4. **Feedback** — reviewer evaluates correctness, acceptance criteria, code quality, test coverage,
security, and returns `## Summary`, `## Findings`, and `## Verdict`
5. **Prioritize** — findings are ordered `P0`, `P1`, `P2`, `P3`
6. **Revise** — the implementing agent addresses findings in priority order, re-verifies, and re-submits
7. **Repeat** — up to max rounds (default 10) until the reviewer returns `VERDICT: APPROVED`
@@ -224,13 +253,17 @@ ts=<ISO-8601> level=<info|warn|error> state=<running-silent|running-active|in-pr
```
`in-progress` is the liveness heartbeat emitted roughly once per minute with `note="In progress N"`.
`stall-warning` is a non-terminal status-log state only. It does not mean the caller should stop waiting if `in-progress` heartbeats continue.
`stall-warning` is a non-terminal status-log state only. It does not mean the caller should stop
waiting if `in-progress` heartbeats continue.
### Failure Handling
- `completed-empty-output` means the reviewer exited without producing review text; surface `.stderr` and `.status`, then retry only after diagnosing the cause.
- `needs-operator-decision` means the helper reached hard-timeout escalation; surface `.status` and decide whether to extend the timeout, abort, or retry with different parameters.
- Successful rounds clean up temp artifacts. Failed, empty-output, and operator-decision rounds should retain `.stderr`, `.status`, and `.runner.out` until diagnosed.
- `completed-empty-output` means the reviewer exited without producing review text; surface
`.stderr` and `.status`, then retry only after diagnosing the cause.
- `needs-operator-decision` means the helper reached hard-timeout escalation; surface `.status`
and decide whether to extend the timeout, abort, or retry with different parameters.
- Successful rounds clean up temp artifacts. Failed, empty-output, and operator-decision rounds
should retain `.stderr`, `.status`, and `.runner.out` until diagnosed.
- As long as fresh `in-progress` heartbeats continue to arrive roughly once per minute, the caller should keep waiting.
### Supported Reviewer CLIs
@@ -249,15 +282,21 @@ For all supported reviewer CLIs, the preferred execution path is:
2. run that script through `reviewer-runtime/run-review.sh`
3. fall back to direct synchronous execution only if the helper is missing or not executable
## Pi Reviewer Support
All workflow variants can use Pi itself as a reviewer CLI. Use `pi/<pi-model-name>` shorthand, for example `pi/claude-opus-4-7`; this means `REVIEWER_CLI=pi` and `REVIEWER_MODEL=claude-opus-4-7`. Provider-qualified or multi-slash Pi model IDs are preserved after the first `pi/` prefix, for example `pi/anthropic/claude-opus-4-7`.
All workflow variants can use Pi itself as a reviewer CLI. Use `pi/<pi-model-name>` shorthand, for
example `pi/claude-opus-4-7`; this means `REVIEWER_CLI=pi` and `REVIEWER_MODEL=claude-opus-4-7`.
Provider-qualified or multi-slash Pi model IDs are preserved after the first `pi/` prefix, for
example `pi/anthropic/claude-opus-4-7`.
The canonical isolated read-only Pi reviewer flag contract lives in [PI-COMMON-REVIEWER.md](./PI-COMMON-REVIEWER.md). This workflow passes the milestone review payload at `/tmp/milestone-${REVIEW_ID}.md` and expects the standard `## Summary`, `## Findings`, and `## Verdict` response. Pi reviewer output is captured as markdown stdout, not JSON.
The canonical isolated read-only Pi reviewer flag contract lives in
[PI-COMMON-REVIEWER.md](./PI-COMMON-REVIEWER.md). This workflow passes the milestone review
payload at `/tmp/milestone-${REVIEW_ID}.md` and expects the standard `## Summary`,
`## Findings`, and `## Verdict` response. Pi reviewer output is captured as markdown stdout,
not JSON.
If the Pi reviewer model or provider is unavailable, surface the helper stderr/status and use `pi --list-models [search]` to inspect configured models.
If the Pi reviewer model or provider is unavailable, surface the helper stderr/status and use
`pi --list-models [search]` to inspect configured models.
## Notifications
@@ -282,7 +321,7 @@ run-review.sh \
## Variant Hardening Notes
### Claude Code
### Claude Code Hardening
- Must invoke explicit required sub-skills:
- `superpowers:executing-plans`
@@ -290,7 +329,7 @@ run-review.sh \
- `superpowers:verification-before-completion`
- `superpowers:finishing-a-development-branch`
### Codex
### Codex Hardening
- Must use native skill discovery from `~/.agents/skills/` (no CLI wrappers).
- Must verify Superpowers skills symlink: `~/.agents/skills/superpowers -> ~/.codex/superpowers/skills`
@@ -298,7 +337,7 @@ run-review.sh \
- Must track checklist-driven skills with `update_plan` todos.
- Deprecated CLI commands (`superpowers-codex bootstrap`, `use-skill`) must NOT be used.
### OpenCode
### OpenCode Hardening
- Must use OpenCode native skill tool (not Claude/Codex invocation syntax).
- Must verify Superpowers skill discovery under:
@@ -306,7 +345,7 @@ run-review.sh \
- `~/.config/opencode/skills/superpowers`
- Must explicitly load all four execution sub-skills.
### Cursor
### Cursor Hardening
- Must use Cursor-native discovery from `.cursor/skills/`, `~/.cursor/skills/`, or installed Cursor plugin cache entries.
- Must announce skill usage explicitly before invocation.
docs/INSTALLER.md
+22 -8
View File
@@ -1,6 +1,7 @@
# Skill Manager Installer
Use the skill manager wizard to install, update/reinstall, or remove skills from this repository for supported local coding clients.
Use the skill manager wizard to install, update/reinstall, or remove skills from this repository
for supported local coding clients.
## Quick Start
@@ -58,9 +59,12 @@ Workflow skills require Obra Superpowers:
- `create-plan`: `brainstorming`, `writing-plans`
- `implement-plan`: `executing-plans`, `using-git-worktrees`, `verification-before-completion`, `finishing-a-development-branch`
- `do-task`: `brainstorming`, `test-driven-development`, `verification-before-completion`, `finishing-a-development-branch` plus conditional `using-git-worktrees`
- `do-task`: `brainstorming`, `test-driven-development`, `verification-before-completion`,
`finishing-a-development-branch` plus conditional `using-git-worktrees`
When a selected install/update needs Superpowers and none are detected for the target client/scope, the wizard asks whether to install them. It asks for an absolute path to an Obra Superpowers `skills` directory and lets you choose symlink or copy:
When a selected install/update needs Superpowers and none are detected for the target client/scope,
the wizard asks whether to install them. It asks for an absolute path to an Obra Superpowers
`skills` directory and lets you choose symlink or copy:
- symlink is recommended because updates to the source checkout are immediately visible
- copy is more self-contained but must be updated manually
@@ -69,13 +73,19 @@ The wizard recognizes client-native and plugin-managed Superpowers installs befo
- 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
- 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 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.
When removing the last repository workflow skill from a client/scope, the wizard asks whether to
remove Superpowers for that variant too.
## Reviewer Runtime Helpers
@@ -87,7 +97,9 @@ Workflow skills install/update the reviewer-runtime helper bundle automatically
## Pi Package Mode
Pi can be managed as a package install or by manual skill copy. Package mode always manages the full Pi bundle; per-skill prompts and `--skill` narrowing are ignored for `packageGlobal` and `packageLocal`.
Pi can be managed as a package install or by manual skill copy. Package mode always manages the
full Pi bundle; per-skill prompts and `--skill` narrowing are ignored for `packageGlobal` and
`packageLocal`.
Package-mode actions:
@@ -148,6 +160,8 @@ The final report uses these columns:
Exit code is non-zero if any selected operation fails.
Dangling symlink warnings are surfaced as `warning` rows. For example, if a previously symlinked Superpowers source has moved or been deleted, the final report keeps the operation non-destructive and shows the dangling symlink target in `details` so you can repair or remove it deliberately.
Dangling symlink warnings are surfaced as `warning` rows. For example, if a previously symlinked
Superpowers source has moved or been deleted, the final report keeps the operation non-destructive
and shows the dangling symlink target in `details` so you can repair or remove it deliberately.
See [PI.md](./PI.md) for Pi package layout details and mirror maintenance.
docs/PI-COMMON-REVIEWER.md
+26 -9
View File
@@ -4,11 +4,15 @@
This document covers the shared reviewer-runtime helpers used by the Pi workflow skills.
It is intentionally separate from [PI-SUPERPOWERS.md](./PI-SUPERPOWERS.md). Superpowers are skill dependencies; reviewer-runtime is helper-script setup.
It is intentionally separate from [PI-SUPERPOWERS.md](./PI-SUPERPOWERS.md). Superpowers are
skill dependencies; reviewer-runtime is helper-script setup.
## Pi As A Reviewer CLI
Pi workflow skills may use `pi` itself as the reviewer CLI, even when the main workflow is already running in pi. In that case, the reviewer model is configured independently from the running agent model. This lets the operator run a workflow with one model while asking another pi-configured model, including provider-qualified model IDs, to review the plan or implementation.
Pi workflow skills may use `pi` itself as the reviewer CLI, even when the main workflow is already
running in pi. In that case, the reviewer model is configured independently from the running agent
model. This lets the operator run a workflow with one model while asking another pi-configured
model, including provider-qualified model IDs, to review the plan or implementation.
The canonical isolated, read-only reviewer command is:
@@ -16,13 +20,16 @@ The canonical isolated, read-only reviewer command is:
pi --no-session --no-skills --no-prompt-templates --no-extensions --no-context-files --model "$REVIEWER_MODEL" --tools read,grep,find,ls -p "Read the review payload and return the requested verdict."
```
Workflow docs should link to this section instead of restating the full flag contract. Each workflow substitutes its own payload path and verdict prompt:
Workflow docs should link to this section instead of restating the full flag contract. Each
workflow substitutes its own payload path and verdict prompt:
- `create-plan`: `/tmp/plan-${REVIEW_ID}.md`
- `implement-plan`: `/tmp/milestone-${REVIEW_ID}.md`
- `do-task`: `/tmp/do-task-${REVIEW_KIND}-${REVIEW_ID}.md`
User-facing shorthand `pi/<pi-model-name>` means `REVIEWER_CLI=pi` and `REVIEWER_MODEL=<pi-model-name>`. Split only on the first slash when the prefix before that slash is exactly `pi`; keep the remainder verbatim. Examples:
User-facing shorthand `pi/<pi-model-name>` means `REVIEWER_CLI=pi` and
`REVIEWER_MODEL=<pi-model-name>`. Split only on the first slash when the prefix before that slash
is exactly `pi`; keep the remainder verbatim. Examples:
- `pi/claude-opus-4-7` -> `claude-opus-4-7`
- `pi/anthropic/claude-opus-4-7` -> `anthropic/claude-opus-4-7`
@@ -31,15 +38,25 @@ User-facing shorthand `pi/<pi-model-name>` means `REVIEWER_CLI=pi` and `REVIEWER
Pi reviewer calls must stay isolated from the main workflow:
- Use `--no-session` so the reviewer does not continue or persist the workflow session.
- Use `--no-skills --no-prompt-templates --no-extensions --no-context-files` so the reviewer does not load workflow skills, project context files, or package extensions that could re-enter `create-plan`, `implement-plan`, or `do-task`.
- Use exactly `--tools read,grep,find,ls` for review. The pi reviewer command MUST NOT include `write`, `edit`, or `bash`; the reviewer reads payloads and diffs but never modifies files or runs commands.
- Use `--no-skills --no-prompt-templates --no-extensions --no-context-files` so the reviewer does
not load workflow skills, project context files, or package extensions that could re-enter
`create-plan`, `implement-plan`, or `do-task`.
- Use exactly `--tools read,grep,find,ls` for review.
The pi reviewer command MUST NOT include `write`, `edit`, or `bash`;
the reviewer reads payloads and diffs but never modifies files or runs commands.
If the reviewer subprocess exits non-zero because the provider, credentials, or model ID are unavailable, surface the captured stderr/status from `run-review.sh`, then ask the user for a configured reviewer model. Use `pi --list-models [search]` to inspect available configured models when needed.
If the reviewer subprocess exits non-zero because the provider, credentials, or model ID are
unavailable, surface the captured stderr/status from `run-review.sh`, then ask the user for a
configured reviewer model. Use `pi --list-models [search]` to inspect available configured models
when needed.
Official references:
- `https://github.com/badlogic/pi-mono/tree/main/packages/coding-agent` documents pi providers, model selection, skills, extensions, and print mode.
- Local `pi --help` for pi `0.70.0` confirms `--model <pattern>` supports `provider/id`, `--print, -p` runs non-interactively, `--tools, -t <tools>` allowlists tools, and the read-only example is `pi --tools read,grep,find,ls -p "Review the code in src/"`.
- `https://github.com/badlogic/pi-mono/tree/main/packages/coding-agent` documents pi providers,
model selection, skills, extensions, and print mode.
- Local `pi --help` for pi `0.70.0` confirms `--model <pattern>` supports `provider/id`,
`--print, -p` runs non-interactively, `--tools, -t <tools>` allowlists tools, and the read-only
example is `pi --tools read,grep,find,ls -p "Review the code in src/"`.
## Required Files
docs/PI-RESEARCH.md
+24 -9
View File
@@ -2,7 +2,8 @@
## Scope
This document records the pi-specific findings that drive the `pi` variants in this repo. It is intentionally source-backed so later skill work does not rely on memory or assumptions.
This document records the pi-specific findings that drive the `pi` variants in this repo. It is
intentionally source-backed so later skill work does not rely on memory or assumptions.
Checked on `2026-04-23`.
@@ -32,11 +33,15 @@ Important discovery details from the skills docs:
- top-level `.md` files are loaded as skills in pi-native roots like `.pi/skills/`
- per the upstream skills docs, top-level `.md` files are ignored in `.agents/skills/`
Implication for this repo: `skills/<skill>/pi/SKILL.md` fits pi's recursive discovery model cleanly for source authoring and manual copies, but it is not clean for package-discovered installs because Pi requires the immediate parent directory of `SKILL.md` to match the skill frontmatter `name`.
Implication for this repo: `skills/<skill>/pi/SKILL.md` fits pi's recursive discovery model
cleanly for source authoring and manual copies, but it is not clean for package-discovered installs
because Pi requires the immediate parent directory of `SKILL.md` to match the skill frontmatter
`name`.
### Package Support
Pi packages are a first-class distribution path. The package docs say pi can load resources through conventional directories like `skills/`, or through explicit `pi` manifest entries in `package.json`.
Pi packages are a first-class distribution path. The package docs say pi can load resources through
conventional directories like `skills/`, or through explicit `pi` manifest entries in `package.json`.
Relevant package behaviors:
@@ -46,11 +51,16 @@ Relevant package behaviors:
- installed pi packages can also ship `extensions/`, `prompts/`, and `themes/`
- when pi installs npm or git packages, it runs `npm install`
Implication for this repo: a single repo-level `package.json` is a viable v1 surface for shipping only the Pi resources, but the package-facing skill directories must be shaped like `<skill-name>/SKILL.md`. That means the repo should preserve `skills/<family>/pi/` for editing and expose a separate mirror such as `pi-package/skills/<skill-name>/` to Pi.
Implication for this repo: a single repo-level `package.json` is a viable v1 surface for shipping
only the Pi resources, but the package-facing skill directories must be shaped like
`<skill-name>/SKILL.md`. That means the repo should preserve `skills/<family>/pi/` for editing and
expose a separate mirror such as `pi-package/skills/<skill-name>/` to Pi.
### Settings And Path Overrides
Pi settings support `packages`, `extensions`, `skills`, `prompts`, and `themes`. In both `~/.pi/agent/settings.json` and `.pi/settings.json`, the `skills` array can point to local files or directories, and the docs explicitly allow absolute paths and `~`.
Pi settings support `packages`, `extensions`, `skills`, `prompts`, and `themes`. In both
`~/.pi/agent/settings.json` and `.pi/settings.json`, the `skills` array can point to local files
or directories, and the docs explicitly allow absolute paths and `~`.
Implication for this repo:
@@ -68,18 +78,23 @@ Pi extensions are TypeScript modules that can:
- add UI interactions and custom components
- persist session state
The coding-agent README explicitly lists advanced behaviors like sub-agents, plan mode, permission gates, MCP integration, and git checkpointing as extension-capable areas.
The coding-agent README explicitly lists advanced behaviors like sub-agents, plan mode, permission
gates, MCP integration, and git checkpointing as extension-capable areas.
Implication for this repo: extensions are a real opportunity for workflow-heavy skills, but they are optional for the initial skill port. The base skill variants should remain usable without any extension dependency.
Implication for this repo: extensions are a real opportunity for workflow-heavy skills, but they
are optional for the initial skill port. The base skill variants should remain usable without any
extension dependency.
### Cross-Harness Compatibility
The pi skills docs explicitly call out `~/.agents/skills/` as a supported global skill root, and describe adding Codex or Claude skill directories through settings when needed.
The pi skills docs explicitly call out `~/.agents/skills/` as a supported global skill root, and
describe adding Codex or Claude skill directories through settings when needed.
Implication for this repo:
- existing Superpowers installs exposed through `~/.agents/skills/` can already be visible to pi
- pi-specific skill variants still need their own instructions because pi does not share Codex's `update_plan`, plan-mode, or worktree assumptions
- pi-specific skill variants still need their own instructions because pi does not share Codex's
`update_plan`, plan-mode, or worktree assumptions
## Decisions Derived From Research
docs/PI-SUPERPOWERS.md
+6 -3
View File
@@ -4,7 +4,8 @@
This document is only about making Obra Superpowers visible to Pi.
If you need the shared reviewer helpers (`run-review.sh`, `notify-telegram.sh`), use [PI-COMMON-REVIEWER.md](./PI-COMMON-REVIEWER.md) instead.
If you need the shared reviewer helpers (`run-review.sh`, `notify-telegram.sh`), use
[PI-COMMON-REVIEWER.md](./PI-COMMON-REVIEWER.md) instead.
## What Pi Needs
@@ -18,7 +19,8 @@ The workflow-heavy Pi skills depend on Superpowers such as:
- `finishing-a-development-branch`
- `using-git-worktrees`
Pi can discover them from shared roots like `~/.agents/skills/`, Pi-native roots like `~/.pi/agent/skills/` or `.pi/skills/`, or settings-defined skill directories.
Pi can discover them from shared roots like `~/.agents/skills/`, Pi-native roots like
`~/.pi/agent/skills/` or `.pi/skills/`, or settings-defined skill directories.
## Verify An Existing Install
@@ -42,7 +44,8 @@ test -f ~/.pi/agent/skills/superpowers/brainstorming/SKILL.md || test -f .pi/ski
## Install Option 1: Reuse A Shared Skills Root
If you already have Superpowers available for another harness, the simplest Pi setup is to expose that same tree through `~/.agents/skills/`.
If you already have Superpowers available for another harness, the simplest Pi setup is to expose
that same tree through `~/.agents/skills/`.
Example:
docs/PI.md
+13 -4
View File
@@ -9,7 +9,8 @@ The Pi support surface has two layers:
- editable source variants in `skills/<family>/pi/`
- a package-facing mirror in `pi-package/skills/<skill>/`
That split is intentional. Pi requires the immediate parent directory of `SKILL.md` to match the skill's frontmatter `name`, so the package cannot point directly at `skills/<family>/pi/`.
That split is intentional. Pi requires the immediate parent directory of `SKILL.md` to match the
skill's frontmatter `name`, so the package cannot point directly at `skills/<family>/pi/`.
Related docs:
@@ -92,7 +93,11 @@ That script:
- fetches the CloakBrowser binary for `web-automation`
- prints `pi list` at the end so the active install is visible immediately
For this cloned-checkout flow, local checkout package install keeps the runtime in `pi-package/skills/<skill>/scripts`. Pi loads the skills from the package mirror in this repo; it does not copy them into `~/.pi/agent/skills/<skill>/` or `.pi/skills/<skill>/` unless you do a manual copy install.
For this cloned-checkout flow,
local checkout package install keeps the runtime in `pi-package/skills/<skill>/scripts`.
Pi loads the skills from the package mirror in this repo;
it does not copy them into `~/.pi/agent/skills/<skill>/` or `.pi/skills/<skill>/`
unless you do a manual copy install.
The package surface intentionally ships:
@@ -110,7 +115,8 @@ It intentionally does not ship `skills/<family>/pi/**` as package-discovered ski
## Single-Skill Copy Install
If you only want one Pi skill without installing the whole package, copy from the package-facing mirror into a Pi skill root:
If you only want one Pi skill without installing the whole package, copy from the package-facing
mirror into a Pi skill root:
```bash
mkdir -p .pi/skills/create-plan
@@ -130,7 +136,10 @@ npm run verify:reviewers
npm pack --dry-run --json
```
The focused `scripts/install-pi-package.sh` installer intentionally does not run sync. It assumes the checked-in `pi-package/skills/*` mirror is already current. The multi-client skill manager plans a sync step before manual Pi skill-copy operations so manual installs use the current package-facing mirror.
The focused `scripts/install-pi-package.sh` installer intentionally does not run sync. It assumes
the checked-in `pi-package/skills/*` mirror is already current. The multi-client skill manager
plans a sync step before manual Pi skill-copy operations so manual installs use the current
package-facing mirror.
The verifier is responsible for catching:
docs/README.md
+59 -26
View File
@@ -1,37 +1,70 @@
# Skills Documentation
This directory contains user-facing docs for each skill.
This directory contains user-facing docs for all skills, agents, and tooling
in the `ai-coding-skills` repository.
## Recommended Reading Flow
## Reading Order
1. Use [INSTALLER.md](./INSTALLER.md) for the guided install/update/remove wizard (`./scripts/manage-skills.sh`).
2. Use the client docs ([CODEX.md](./CODEX.md), [CLAUDE-CODE.md](./CLAUDE-CODE.md), [CURSOR.md](./CURSOR.md), [OPENCODE.md](./OPENCODE.md)) for manual installs, and [PI.md](./PI.md) for Pi overview, package install, and manual single-skill copy.
3. Use the skill docs below for skill-specific requirements, runtime setup, verification, and examples.
4. For Pi workflow skills, also consult [PI-SUPERPOWERS.md](./PI-SUPERPOWERS.md) and [PI-COMMON-REVIEWER.md](./PI-COMMON-REVIEWER.md).
Work through the sections below in order on a first read. Return to individual
sections as needed.
## Index
### 1. Getting Started
- [INSTALLER.md](./INSTALLER.md) — Skill manager wizard for installing, updating/reinstalling, and removing repo skills across supported clients.
- [CODEX.md](./CODEX.md) — Manual install instructions for Codex variants.
- [CLAUDE-CODE.md](./CLAUDE-CODE.md) — Manual install instructions for Claude Code variants.
- [CURSOR.md](./CURSOR.md) — Manual install instructions for Cursor variants.
- [OPENCODE.md](./OPENCODE.md) — Manual install instructions for OpenCode variants.
- [ATLASSIAN.md](./ATLASSIAN.md) — Includes requirements, generated bundle sync, install, auth, safety rules, and usage examples for the Atlassian skill.
- [CREATE-PLAN.md](./CREATE-PLAN.md) — Includes requirements, install, verification, and execution workflow for create-plan.
- [DO-TASK.md](./DO-TASK.md) — Single-prompt end-to-end execution with dual reviewer loops (plan + implementation), TDD-first, single task commit. Sibling of create-plan/implement-plan scoped to ad-hoc tasks.
- [IMPLEMENT-PLAN.md](./IMPLEMENT-PLAN.md) — Includes requirements, install, verification, and milestone review workflow for implement-plan.
- [PI.md](./PI.md) — Pi support overview, source-vs-package layout, install flow, and extension decision.
- [PI-RESEARCH.md](./PI-RESEARCH.md) — Source-backed pi findings that inform the repo's pi variants and packaging choices.
- [PI-SUPERPOWERS.md](./PI-SUPERPOWERS.md) — How to install or verify Obra Superpowers for Pi.
- [PI-COMMON-REVIEWER.md](./PI-COMMON-REVIEWER.md) — How to install or verify the shared reviewer-runtime helpers for Pi workflow skills.
- [TELEGRAM-NOTIFICATIONS.md](./TELEGRAM-NOTIFICATIONS.md) — Shared Telegram notification setup used by reviewer-driven skills.
- [WEB-AUTOMATION.md](./WEB-AUTOMATION.md) — Includes requirements, install, dependency verification, and usage examples for web-automation.
- [INSTALLER.md](./INSTALLER.md) — Guided install/update/remove wizard
(`./scripts/manage-skills.sh`). **Start here** if you want the fastest path
to installed skills.
## Development
### 2. Per-Agent Manual Install
- [DEVELOPMENT.md](./DEVELOPMENT.md) — prerequisites, `pnpm run check`, workspace policy,
and the transitional quality contract.
- [CLEANUP-BASELINE.md](./CLEANUP-BASELINE.md) — as-is quality baseline captured at M1.
Use these guides to install specific skills manually for a single agent:
- [CODEX.md](./CODEX.md) — Manual install for Codex variants.
- [CLAUDE-CODE.md](./CLAUDE-CODE.md) — Manual install for Claude Code variants.
- [CURSOR.md](./CURSOR.md) — Manual install for Cursor variants.
- [OPENCODE.md](./OPENCODE.md) — Manual install for OpenCode variants.
- [PI.md](./PI.md) — Pi overview, source-vs-package layout, and manual install.
### 3. Skill Guides
Reference docs for each skill family:
- [ATLASSIAN.md](./ATLASSIAN.md) — Jira/Confluence CLI: requirements, generated
bundle sync, install, auth, safety rules, and usage examples.
- [CREATE-PLAN.md](./CREATE-PLAN.md) — Structured planning with milestones,
cross-model review, and reviewer CLI requirements.
- [DO-TASK.md](./DO-TASK.md) — Single-prompt end-to-end execution with dual
reviewer loops, TDD-first, single task commit.
- [IMPLEMENT-PLAN.md](./IMPLEMENT-PLAN.md) — Worktree-isolated plan execution
with iterative cross-model milestone review.
- [WEB-AUTOMATION.md](./WEB-AUTOMATION.md) — CloakBrowser-backed browsing,
scraping, auth, and flow automation.
### 4. Pi-Specific Docs
- [PI-RESEARCH.md](./PI-RESEARCH.md) — Source-backed Pi findings that inform
repo Pi variants and packaging choices.
- [PI-SUPERPOWERS.md](./PI-SUPERPOWERS.md) — How to install or verify Obra
Superpowers for Pi.
- [PI-COMMON-REVIEWER.md](./PI-COMMON-REVIEWER.md) — Shared reviewer-runtime
helpers for Pi workflow skills; canonical Pi reviewer flag contract.
### 5. Telegram Notifications
- [TELEGRAM-NOTIFICATIONS.md](./TELEGRAM-NOTIFICATIONS.md) — Shared Telegram
notification setup for Codex, Claude Code, OpenCode, Cursor, and Pi.
### 6. Reviewer Matrix
- [REVIEWERS.md](./REVIEWERS.md) — Canonical reviewer CLI support matrix;
single source of truth for all workflow variants.
### 7. Development
- [DEVELOPMENT.md](./DEVELOPMENT.md) — Prerequisites, `pnpm run check`,
workspace policy, cross-platform shell support, and the transitional quality
contract.
- [CLEANUP-BASELINE.md](./CLEANUP-BASELINE.md) — As-is quality baseline
captured at M1, updated through subsequent milestones.
## Repo Setup
docs/REVIEWERS.md
+81
View File
@@ -0,0 +1,81 @@
# Reviewer CLI Support Matrix
This document is the **single canonical source** for the reviewer CLI support
matrix used by `create-plan`, `implement-plan`, and `do-task`. All workflow
docs and `SKILL.md` variants must refer here and stay in sync.
## Canonical Reviewer CLIs
| CLI | Install | Verify | Read-Only Mode | Session Resume |
|-----|---------|--------|----------------|----------------|
| `codex` | `npm install -g @openai/codex` | `codex --version` | `-s read-only` | Yes (`codex exec resume <id>`) |
| `claude` | `npm install -g @anthropic-ai/claude-code` | `claude --version` | `--strict-mcp-config --setting-sources user` | No (fresh call each round) |
| `cursor` | `curl https://cursor.com/install -fsS \| bash` | `cursor-agent --version` | `--mode=ask` | Yes (`--resume <id>`) |
| `opencode` | `brew install opencode` or your package manager | `opencode --version` | `--agent plan` | Opt-in (`-s <id>`; fresh call is the default) |
| `pi` | Install Pi coding agent | `pi --version`; list models with `pi --list-models [search]` | `--tools read,grep,find,ls` | No (fresh call each round) |
**`skip`** is always a valid value; it bypasses the reviewer loop and requires
explicit user approval instead.
## Notes
- The reviewer CLI is independent of which agent is running the skill. For
example, Claude Code can send plans to Codex for review and vice versa.
- **`cursor` reviewer prerequisite:** `jq` is required to parse Cursor's JSON
output. Install via `brew install jq` (macOS) or your package manager.
Verify: `jq --version`. The Cursor variant of `do-task` makes `jq` a hard
prerequisite regardless of which reviewer CLI is selected.
- **`opencode` reviewer:** Uses `--agent plan` (built-in read-oriented agent)
for review posture. Session resume is opt-in via `-s <id>`; fresh call is the
recommended default for non-interactive headless runs.
- **`pi` reviewer:** Use `pi/<pi-model-name>` shorthand, for example
`pi/claude-opus-4-7`; this means `REVIEWER_CLI=pi` and
`REVIEWER_MODEL=claude-opus-4-7`. Provider-qualified or multi-slash Pi model
IDs are preserved after the first `pi/` prefix, for example
`pi/anthropic/claude-opus-4-7`. The canonical isolated read-only Pi reviewer
flag contract lives in [PI-COMMON-REVIEWER.md](./PI-COMMON-REVIEWER.md).
## Reviewer Output Contract
All reviewer CLIs must return the following structure:
```markdown
## Summary
...
## Findings
### P0
- ...
### P1
- ...
### P2
- ...
### P3
- ...
## Verdict
VERDICT: APPROVED
```
Severity levels:
| Level | Meaning |
|-------|---------|
| `P0` | Total blocker |
| `P1` | Major risk |
| `P2` | Must-fix before approval |
| `P3` | Cosmetic / nice to have (non-blocking) |
Rules:
- `VERDICT: APPROVED` is valid only when no `P0`, `P1`, or `P2` findings remain.
- `P3` findings are non-blocking, but the caller should still try to fix them
when cheap and safe.
- Each severity section uses `- None.` when empty.
## References
- [PI-COMMON-REVIEWER.md](./PI-COMMON-REVIEWER.md) — Canonical Pi reviewer
flag contract and read-only command template.
- [TELEGRAM-NOTIFICATIONS.md](./TELEGRAM-NOTIFICATIONS.md) — Telegram
notification setup used by reviewer-driven workflows.
docs/TELEGRAM-NOTIFICATIONS.md
+72 -13
View File
@@ -2,7 +2,9 @@
## Purpose
Shared setup for Telegram notifications used by reviewer-driven skills such as `create-plan` and `implement-plan`, both for completion and for pauses that need user attention.
Shared setup for Telegram notifications used by reviewer-driven skills such as
`create-plan`, `implement-plan`, and `do-task`, both for completion and for
pauses that need user attention.
## Requirements
@@ -12,17 +14,23 @@ Shared setup for Telegram notifications used by reviewer-driven skills such as `
- Codex: `~/.codex/skills/reviewer-runtime/notify-telegram.sh`
- Claude Code: `~/.claude/skills/reviewer-runtime/notify-telegram.sh`
- OpenCode: `~/.config/opencode/skills/reviewer-runtime/notify-telegram.sh`
- Cursor: `.cursor/skills/reviewer-runtime/notify-telegram.sh` or `~/.cursor/skills/reviewer-runtime/notify-telegram.sh`
- Cursor: `.cursor/skills/reviewer-runtime/notify-telegram.sh`
or `~/.cursor/skills/reviewer-runtime/notify-telegram.sh`
- Pi: `.pi/skills/reviewer-runtime/pi/notify-telegram.sh`
or `~/.pi/agent/skills/reviewer-runtime/pi/notify-telegram.sh`
## Install
The helper ships from `skills/reviewer-runtime/` together with `run-review.sh`.
The helpers ship from `skills/reviewer-runtime/` (non-Pi) and
`skills/reviewer-runtime/pi/` (Pi) together with `run-review.sh`.
### Codex
```bash
mkdir -p ~/.codex/skills/reviewer-runtime
cp skills/reviewer-runtime/run-review.sh skills/reviewer-runtime/notify-telegram.sh ~/.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
```
@@ -30,7 +38,9 @@ chmod +x ~/.codex/skills/reviewer-runtime/*.sh
```bash
mkdir -p ~/.claude/skills/reviewer-runtime
cp skills/reviewer-runtime/run-review.sh skills/reviewer-runtime/notify-telegram.sh ~/.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
```
@@ -38,7 +48,9 @@ chmod +x ~/.claude/skills/reviewer-runtime/*.sh
```bash
mkdir -p ~/.config/opencode/skills/reviewer-runtime
cp skills/reviewer-runtime/run-review.sh skills/reviewer-runtime/notify-telegram.sh ~/.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
```
@@ -48,7 +60,9 @@ Repo-local install:
```bash
mkdir -p .cursor/skills/reviewer-runtime
cp skills/reviewer-runtime/run-review.sh skills/reviewer-runtime/notify-telegram.sh .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
```
@@ -56,22 +70,57 @@ Global install:
```bash
mkdir -p ~/.cursor/skills/reviewer-runtime
cp skills/reviewer-runtime/run-review.sh skills/reviewer-runtime/notify-telegram.sh ~/.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
Pi uses a separate set of helpers from `skills/reviewer-runtime/pi/` that are
optimized for the Pi agent environment. See
[PI-COMMON-REVIEWER.md](./PI-COMMON-REVIEWER.md) for full details.
Global install:
```bash
mkdir -p ~/.pi/agent/skills/reviewer-runtime/pi
cp -R skills/reviewer-runtime/pi/* ~/.pi/agent/skills/reviewer-runtime/pi/
chmod +x ~/.pi/agent/skills/reviewer-runtime/pi/*.sh
```
Repo-local install:
```bash
mkdir -p .pi/skills/reviewer-runtime/pi
cp -R skills/reviewer-runtime/pi/* .pi/skills/reviewer-runtime/pi/
chmod +x .pi/skills/reviewer-runtime/pi/*.sh
```
## Verify Installation
### Verify: Non-Pi agents
```bash
test -x ~/.codex/skills/reviewer-runtime/notify-telegram.sh || true
test -x ~/.claude/skills/reviewer-runtime/notify-telegram.sh || true
test -x ~/.config/opencode/skills/reviewer-runtime/notify-telegram.sh || true
test -x .cursor/skills/reviewer-runtime/notify-telegram.sh || test -x ~/.cursor/skills/reviewer-runtime/notify-telegram.sh || true
test -x .cursor/skills/reviewer-runtime/notify-telegram.sh \
|| test -x ~/.cursor/skills/reviewer-runtime/notify-telegram.sh || true
```
### Verify: Pi
```bash
test -x .pi/skills/reviewer-runtime/pi/notify-telegram.sh \
|| test -x ~/.pi/agent/skills/reviewer-runtime/pi/notify-telegram.sh || true
```
## Configure Telegram
Export the required variables before running a skill that sends Telegram notifications:
Export the required variables before running a skill that sends Telegram
notifications:
```bash
export TELEGRAM_BOT_TOKEN="<bot-token>"
@@ -86,7 +135,7 @@ export TELEGRAM_API_BASE_URL="https://api.telegram.org"
## Test the Helper
Example:
Non-Pi agents example:
```bash
TELEGRAM_BOT_TOKEN="<bot-token>" \
@@ -94,9 +143,19 @@ TELEGRAM_CHAT_ID="<chat-id>" \
skills/reviewer-runtime/notify-telegram.sh --message "Telegram notification test"
```
Pi example:
```bash
TELEGRAM_BOT_TOKEN="<bot-token>" \
TELEGRAM_CHAT_ID="<chat-id>" \
skills/reviewer-runtime/pi/notify-telegram.sh --message "Pi Telegram test"
```
## Rules
- Telegram is the only supported notification path for these skills.
- Notification failures are non-blocking, but they must be surfaced to the user.
- Before stopping for any user interaction, approval, or manual decision, send a Telegram summary first if configured.
- Skills should report when Telegram is not configured instead of silently pretending a notification was sent.
- Before stopping for any user interaction, approval, or manual decision, send a
Telegram summary first if configured.
- Skills should report when Telegram is not configured instead of silently
pretending a notification was sent.
docs/WEB-AUTOMATION.md
+4 -2
View File
@@ -112,7 +112,8 @@ pnpm approve-builds
pnpm rebuild better-sqlite3 esbuild
```
This repo intentionally treats `cloakbrowser` as a refreshable dependency: update to the latest available compatible release, then regenerate the lockfile from that resolved set.
This repo intentionally treats `cloakbrowser` as a refreshable dependency: update to the latest
available compatible release, then regenerate the lockfile from that resolved set.
## Verify Installation & Wiring
@@ -129,7 +130,8 @@ Expected checks:
If the check fails, stop and return:
"Missing dependency/config: web-automation requires `cloakbrowser` and `playwright-core` with CloakBrowser-based scripts. Run setup in this skill, then retry."
"Missing dependency/config: web-automation requires `cloakbrowser` and `playwright-core` with
CloakBrowser-based scripts. Run setup in this skill, then retry."
If runtime later fails with native-binding issues, run: