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/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.