Perform code optimization and document cleanup #1
@@ -1,7 +1,8 @@
|
||||
// markdownlint-cli2 configuration — ai-coding-skills (M1)
|
||||
// markdownlint-cli2 configuration — ai-coding-skills (M2)
|
||||
//
|
||||
// This file controls which files are linted and which are ignored.
|
||||
// The markdownlint *rules* are configured in .markdownlint.jsonc.
|
||||
// The markdownlint *rules* are configured in .markdownlint.jsonc (root) and
|
||||
// skills/.markdownlint.jsonc (agent-facing skill files).
|
||||
//
|
||||
// Scope: README.md, docs/, and canonical SKILL.md files.
|
||||
// Excluded: all node_modules, generated agent-variant directories, pi-package.
|
||||
|
||||
@@ -16,69 +16,36 @@ This repo is organized similarly to `obra/superpowers` and is designed to scale
|
||||
```text
|
||||
ai-coding-skills/
|
||||
├── README.md
|
||||
├── docs/
|
||||
│ ├── README.md
|
||||
│ ├── INSTALLER.md
|
||||
│ ├── CODEX.md
|
||||
│ ├── CLAUDE-CODE.md
|
||||
│ ├── CURSOR.md
|
||||
│ ├── OPENCODE.md
|
||||
│ ├── ATLASSIAN.md
|
||||
│ ├── CREATE-PLAN.md
|
||||
│ ├── DO-TASK.md
|
||||
│ ├── IMPLEMENT-PLAN.md
|
||||
│ ├── PI.md
|
||||
│ ├── PI-COMMON-REVIEWER.md
|
||||
│ ├── PI-RESEARCH.md
|
||||
│ ├── PI-SUPERPOWERS.md
|
||||
│ ├── TELEGRAM-NOTIFICATIONS.md
|
||||
│ └── WEB-AUTOMATION.md
|
||||
├── docs/ — user-facing docs (see docs/README.md)
|
||||
├── skills/
|
||||
│ ├── _template/
|
||||
│ │ └── SKILL.md
|
||||
│ ├── atlassian/
|
||||
│ │ ├── codex/
|
||||
│ │ ├── claude-code/
|
||||
│ │ ├── cursor/
|
||||
│ │ ├── opencode/
|
||||
│ │ ├── pi/
|
||||
│ │ └── shared/
|
||||
│ │ ├── codex/ claude-code/ cursor/ opencode/ pi/ shared/
|
||||
│ ├── create-plan/
|
||||
│ │ ├── codex/
|
||||
│ │ ├── claude-code/
|
||||
│ │ ├── opencode/
|
||||
│ │ ├── cursor/
|
||||
│ │ └── pi/
|
||||
│ │ ├── codex/ claude-code/ cursor/ opencode/ pi/
|
||||
│ ├── do-task/
|
||||
│ │ ├── codex/
|
||||
│ │ ├── claude-code/
|
||||
│ │ ├── opencode/
|
||||
│ │ ├── cursor/
|
||||
│ │ └── pi/
|
||||
│ │ ├── codex/ claude-code/ cursor/ opencode/ pi/
|
||||
│ ├── implement-plan/
|
||||
│ │ ├── codex/
|
||||
│ │ ├── claude-code/
|
||||
│ │ ├── opencode/
|
||||
│ │ ├── cursor/
|
||||
│ │ └── pi/
|
||||
│ │ ├── codex/ claude-code/ cursor/ opencode/ pi/
|
||||
│ ├── reviewer-runtime/
|
||||
│ │ ├── pi/
|
||||
│ │ └── tests/
|
||||
│ │ ├── pi/ — Pi-specific run-review.sh + notify-telegram.sh
|
||||
│ │ └── tests/ — reviewer-runtime smoke tests
|
||||
│ └── web-automation/
|
||||
│ ├── codex/
|
||||
│ ├── claude-code/
|
||||
│ ├── cursor/
|
||||
│ ├── opencode/
|
||||
│ └── pi/
|
||||
├── .codex/
|
||||
├── .claude-plugin/
|
||||
├── .opencode/
|
||||
│ └── plugins/
|
||||
├── commands/
|
||||
├── hooks/
|
||||
└── tests/
|
||||
│ ├── codex/ claude-code/ cursor/ opencode/ pi/
|
||||
├── pi-package/
|
||||
│ └── skills/ — Pi-facing mirror synced by sync:pi
|
||||
├── scripts/
|
||||
│ ├── lib/ — shared Node helpers + portable.sh
|
||||
│ └── tests/ — Node.js unit tests
|
||||
├── package.json
|
||||
└── pnpm-workspace.yaml
|
||||
```
|
||||
|
||||
## Where to Read Next
|
||||
|
||||
See **[docs/README.md](docs/README.md)** for the full documentation index with
|
||||
ordered reading flow, one-line summaries for every doc, and links to per-agent
|
||||
install guides, skill docs, Pi docs, Telegram setup, and development notes.
|
||||
|
||||
## Skills
|
||||
|
||||
| Skill | Agent Variant | Purpose | Status | Docs |
|
||||
@@ -150,9 +117,11 @@ node scripts/manage-skills.mjs --client pi --scope packageGlobal --pi-package --
|
||||
node scripts/manage-skills.mjs --client pi --scope packageLocal --pi-package --action install --yes
|
||||
```
|
||||
|
||||
The wizard detects Codex, Claude Code, Cursor, OpenCode, and Pi, previews operations, checks Superpowers dependencies for workflow skills, and prints a final operation report.
|
||||
The wizard detects Codex, Claude Code, Cursor, OpenCode, and Pi, previews operations, checks
|
||||
Superpowers dependencies for workflow skills, and prints a final operation report.
|
||||
|
||||
`ai_plan/` is gitignored local planning state used by `create-plan` and `do-task`. The skill manager does not install, sync, or publish `ai_plan/` contents.
|
||||
`ai_plan/` is gitignored local planning state used by `create-plan` and `do-task`. The skill
|
||||
manager does not install, sync, or publish `ai_plan/` contents.
|
||||
|
||||
## Pi Package
|
||||
|
||||
|
||||
+15
-7
@@ -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
|
||||
|
||||
|
||||
@@ -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).
|
||||
|
||||
+52
-26
@@ -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.
|
||||
|
||||
+3
-1
@@ -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
|
||||
|
||||
+59
-13
@@ -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)
|
||||
|
||||
|
||||
+139
-60
@@ -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).
|
||||
|
||||
+70
-31
@@ -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.
|
||||
|
||||
+22
-8
@@ -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.
|
||||
|
||||
@@ -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
|
||||
|
||||
|
||||
+24
-9
@@ -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
|
||||
|
||||
|
||||
@@ -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:
|
||||
|
||||
|
||||
+13
-4
@@ -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:
|
||||
|
||||
|
||||
+59
-26
@@ -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
|
||||
|
||||
|
||||
@@ -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.
|
||||
@@ -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.
|
||||
|
||||
@@ -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:
|
||||
|
||||
|
||||
+2
-1
@@ -47,7 +47,8 @@
|
||||
"lint:fix": "eslint . --fix && prettier --write .",
|
||||
"typecheck": "pnpm run -r --if-present typecheck",
|
||||
"test": "pnpm run test:installer && pnpm run -r --if-present test",
|
||||
"verify:docs": "markdownlint-cli2 ; R1=$?; node scripts/lib/run-link-check.mjs ; R2=$?; [ $((R1+R2)) -eq 0 ]",
|
||||
"verify:docs": "markdownlint-cli2 ; R1=$?; node scripts/lib/run-link-check.mjs ; R2=$?; node scripts/verify-docs-flow.mjs ; R3=$?; [ $((R1+R2+R3)) -eq 0 ]",
|
||||
"verify:docs:online": "markdownlint-cli2 ; R1=$?; node scripts/lib/run-link-check.mjs --online ; R2=$?; node scripts/verify-docs-flow.mjs ; R3=$?; [ $((R1+R2+R3)) -eq 0 ]",
|
||||
"verify:generated": "node -e \"console.log('verify:generated: stub — fleshed out in M3'); process.exit(0)\"",
|
||||
"check": "node scripts/lib/run-check.mjs"
|
||||
},
|
||||
|
||||
@@ -65,15 +65,19 @@ Work from this folder (`ai_plan/YYYY-MM-DD-<short-title>/`) and always follow th
|
||||
## Full Context Reproduction
|
||||
|
||||
### Project Overview
|
||||
|
||||
[What this project/feature is about]
|
||||
|
||||
### User Requirements
|
||||
|
||||
[All gathered requirements]
|
||||
|
||||
### Scope
|
||||
|
||||
[In scope / out of scope]
|
||||
|
||||
### Dependencies
|
||||
|
||||
[External dependencies, prerequisites, related systems]
|
||||
|
||||
---
|
||||
@@ -81,16 +85,19 @@ Work from this folder (`ai_plan/YYYY-MM-DD-<short-title>/`) and always follow th
|
||||
## Key Specifications
|
||||
|
||||
### Type Definitions
|
||||
|
||||
```typescript
|
||||
// Copy-paste ready type definitions
|
||||
```
|
||||
|
||||
### Enums & Constants
|
||||
|
||||
```typescript
|
||||
// All enums/constants needed
|
||||
```
|
||||
|
||||
### API Endpoints
|
||||
|
||||
```typescript
|
||||
// Request/response shapes
|
||||
```
|
||||
@@ -108,16 +115,19 @@ Work from this folder (`ai_plan/YYYY-MM-DD-<short-title>/`) and always follow th
|
||||
## Verification Commands
|
||||
|
||||
### Lint (changed files first)
|
||||
|
||||
```bash
|
||||
# example: pnpm eslint <changed-file-1> <changed-file-2>
|
||||
```
|
||||
|
||||
### Typecheck
|
||||
|
||||
```bash
|
||||
# example: pnpm tsc --noEmit
|
||||
```
|
||||
|
||||
### Tests (target changed scope first)
|
||||
|
||||
```bash
|
||||
# example: pnpm test -- <related spec/file>
|
||||
```
|
||||
|
||||
@@ -1,6 +1,7 @@
|
||||
# [Plan Title]
|
||||
|
||||
## Overview
|
||||
|
||||
- **Goal:** [One sentence describing the end state]
|
||||
- **Created:** YYYY-MM-DD
|
||||
- **Status:** In Progress | Complete
|
||||
@@ -8,37 +9,46 @@
|
||||
## Context
|
||||
|
||||
### Requirements
|
||||
|
||||
[Gathered requirements from user questions]
|
||||
|
||||
### Constraints
|
||||
|
||||
[Technical, business, or timeline constraints]
|
||||
|
||||
### Success Criteria
|
||||
|
||||
[How we know this is complete]
|
||||
|
||||
## Architecture
|
||||
|
||||
### Design Decisions
|
||||
|
||||
[Key architectural choices and rationale]
|
||||
|
||||
### Component Relationships
|
||||
|
||||
[How pieces fit together]
|
||||
|
||||
### Data Flow
|
||||
|
||||
[How data moves through the system]
|
||||
|
||||
## Milestones
|
||||
|
||||
### M1: [Name]
|
||||
|
||||
**Description:** [What this milestone achieves]
|
||||
|
||||
**Acceptance Criteria:**
|
||||
|
||||
- [ ] [Criterion 1]
|
||||
- [ ] [Criterion 2]
|
||||
|
||||
**Stories:** S-101, S-102, S-103...
|
||||
|
||||
**Milestone Completion Rule (MANDATORY):**
|
||||
|
||||
- Run lint/typecheck/tests for changed files.
|
||||
- Commit locally (DO NOT push).
|
||||
- Stop and ask user for feedback.
|
||||
@@ -48,15 +58,18 @@
|
||||
---
|
||||
|
||||
### M2: [Name]
|
||||
|
||||
**Description:** [What this milestone achieves]
|
||||
|
||||
**Acceptance Criteria:**
|
||||
|
||||
- [ ] [Criterion 1]
|
||||
- [ ] [Criterion 2]
|
||||
|
||||
**Stories:** S-201, S-202, S-203...
|
||||
|
||||
**Milestone Completion Rule (MANDATORY):**
|
||||
|
||||
- Run lint/typecheck/tests for changed files.
|
||||
- Commit locally (DO NOT push).
|
||||
- Stop and ask user for feedback.
|
||||
@@ -68,16 +81,19 @@
|
||||
## Technical Specifications
|
||||
|
||||
### Types & Interfaces
|
||||
|
||||
```typescript
|
||||
// Key type definitions
|
||||
```
|
||||
|
||||
### API Contracts
|
||||
|
||||
```typescript
|
||||
// Endpoint signatures, request/response shapes
|
||||
```
|
||||
|
||||
### Constants & Enums
|
||||
|
||||
```typescript
|
||||
// Shared constants
|
||||
```
|
||||
@@ -94,6 +110,7 @@
|
||||
## Related Plan Files
|
||||
|
||||
This file is part of the plan folder under `ai_plan/`:
|
||||
|
||||
- `original-plan.md` - Original approved plan (reference for original intent)
|
||||
- `final-transcript.md` - Final planning transcript (reference for rationale/context)
|
||||
- `milestone-plan.md` - This file (full specification)
|
||||
|
||||
@@ -1,6 +1,7 @@
|
||||
# Story Tracker: [Plan Title]
|
||||
|
||||
## Progress Summary
|
||||
|
||||
- **Current Milestone:** M1
|
||||
- **Stories Complete:** 0/N
|
||||
- **Milestones Approved:** 0/M
|
||||
@@ -46,15 +47,18 @@
|
||||
## Update Instructions (MANDATORY)
|
||||
|
||||
Before starting any story:
|
||||
|
||||
1. Mark story as `in-dev`
|
||||
2. Update "Last Updated"
|
||||
|
||||
After completing any story:
|
||||
|
||||
1. Mark story as `completed`
|
||||
2. Add local commit hash to Notes
|
||||
3. Update "Stories Complete" and "Last Updated"
|
||||
|
||||
At milestone boundary:
|
||||
|
||||
1. Run lint/typecheck/tests for changed files
|
||||
2. Commit (no push)
|
||||
3. Request feedback
|
||||
@@ -63,4 +67,5 @@ At milestone boundary:
|
||||
6. Continue only after approval
|
||||
|
||||
After all milestones approved:
|
||||
|
||||
- Ask permission to push and then mark plan completed.
|
||||
|
||||
@@ -0,0 +1,28 @@
|
||||
#!/usr/bin/env bash
|
||||
# portable.sh — POSIX-safe helper functions for BSD/GNU shell portability
|
||||
#
|
||||
# Source this file in scripts that need cross-platform variants of:
|
||||
# - stat(1) — BSD uses -f, GNU uses -c
|
||||
#
|
||||
# Usage:
|
||||
# source "$(dirname "${BASH_SOURCE[0]}")/portable.sh"
|
||||
# portable_stat_perms "$file" # -> octal permissions string, e.g. "755"
|
||||
#
|
||||
# Supported platforms:
|
||||
# - macOS (BSD stat)
|
||||
# - Linux/Ubuntu (GNU stat)
|
||||
|
||||
# portable_stat_perms <path>
|
||||
# Outputs the file's permission bits as an octal string (e.g. "755").
|
||||
# Exits non-zero if stat fails.
|
||||
portable_stat_perms() {
|
||||
local path="$1"
|
||||
case "$(uname -s)" in
|
||||
Darwin)
|
||||
stat -f '%Lp' "$path"
|
||||
;;
|
||||
*)
|
||||
stat -c '%a' "$path"
|
||||
;;
|
||||
esac
|
||||
}
|
||||
@@ -132,7 +132,7 @@ console.log(`shellcheck: scanning ${files.length} file(s)…`);
|
||||
|
||||
let failures = 0;
|
||||
for (const file of files.sort()) {
|
||||
const result = spawnSync("shellcheck", [file], {
|
||||
const result = spawnSync("shellcheck", ["-x", "--source-path=SCRIPTDIR", file], {
|
||||
encoding: "utf8",
|
||||
stdio: ["ignore", "pipe", "pipe"],
|
||||
});
|
||||
|
||||
@@ -0,0 +1,71 @@
|
||||
/**
|
||||
* verify-docs-flow.test.mjs — unit tests for the docs-flow verifier (M2, S-206)
|
||||
*
|
||||
* Tests the exported functions from scripts/verify-docs-flow.mjs.
|
||||
* Each test is structured as a RED → GREEN cycle: we first verify the function
|
||||
* exists and behaves correctly; any structural violation surfaces as a clear
|
||||
* test failure rather than a cryptic runtime error.
|
||||
*/
|
||||
|
||||
import { test, describe } from "node:test";
|
||||
import assert from "node:assert/strict";
|
||||
import path from "node:path";
|
||||
import { fileURLToPath } from "node:url";
|
||||
|
||||
const __dirname = path.dirname(fileURLToPath(import.meta.url));
|
||||
const REPO_ROOT = path.resolve(__dirname, "../..");
|
||||
|
||||
// ── Helpers ────────────────────────────────────────────────────────────────
|
||||
|
||||
/**
|
||||
* Import the verifier lazily so missing-module errors surface as test
|
||||
* failures rather than crashing the whole suite.
|
||||
*/
|
||||
async function loadVerifier() {
|
||||
const verifierPath = path.join(REPO_ROOT, "scripts", "verify-docs-flow.mjs");
|
||||
return import(verifierPath);
|
||||
}
|
||||
|
||||
// ── S-206 acceptance checks ────────────────────────────────────────────────
|
||||
|
||||
describe("verify-docs-flow.mjs", () => {
|
||||
test("module exists and exports required functions", async () => {
|
||||
const mod = await loadVerifier();
|
||||
assert.equal(typeof mod.checkDocsIndexCoverage, "function",
|
||||
"must export checkDocsIndexCoverage");
|
||||
assert.equal(typeof mod.checkReviewerMatrixConsistency, "function",
|
||||
"must export checkReviewerMatrixConsistency");
|
||||
assert.equal(typeof mod.checkTelegramAgentCoverage, "function",
|
||||
"must export checkTelegramAgentCoverage");
|
||||
assert.equal(typeof mod.checkRepoPathsExist, "function",
|
||||
"must export checkRepoPathsExist");
|
||||
});
|
||||
|
||||
test("checkDocsIndexCoverage: every docs/*.md is linked from docs/README.md", async () => {
|
||||
const { checkDocsIndexCoverage } = await loadVerifier();
|
||||
const errors = await checkDocsIndexCoverage(REPO_ROOT);
|
||||
assert.deepEqual(errors, [],
|
||||
`docs/README.md coverage errors:\n${errors.join("\n")}`);
|
||||
});
|
||||
|
||||
test("checkReviewerMatrixConsistency: reviewer tables consistent across canonical sources", async () => {
|
||||
const { checkReviewerMatrixConsistency } = await loadVerifier();
|
||||
const errors = await checkReviewerMatrixConsistency(REPO_ROOT);
|
||||
assert.deepEqual(errors, [],
|
||||
`Reviewer matrix inconsistency errors:\n${errors.join("\n")}`);
|
||||
});
|
||||
|
||||
test("checkTelegramAgentCoverage: Telegram doc lists all agents with Pi helpers", async () => {
|
||||
const { checkTelegramAgentCoverage } = await loadVerifier();
|
||||
const errors = await checkTelegramAgentCoverage(REPO_ROOT);
|
||||
assert.deepEqual(errors, [],
|
||||
`Telegram coverage errors:\n${errors.join("\n")}`);
|
||||
});
|
||||
|
||||
test("checkRepoPathsExist: all repo-relative paths in README.md and docs/ exist", async () => {
|
||||
const { checkRepoPathsExist } = await loadVerifier();
|
||||
const errors = await checkRepoPathsExist(REPO_ROOT);
|
||||
assert.deepEqual(errors, [],
|
||||
`Broken repo-relative path references:\n${errors.join("\n")}`);
|
||||
});
|
||||
});
|
||||
@@ -0,0 +1,318 @@
|
||||
#!/usr/bin/env node
|
||||
/**
|
||||
* verify-docs-flow.mjs — documentation reading-flow and consistency verifier (M2, S-206)
|
||||
*
|
||||
* Asserts:
|
||||
* (i) every docs/*.md file is linked from docs/README.md
|
||||
* (ii) the reviewer CLI matrix is consistent across the four canonical sources
|
||||
* (iii) the Telegram agent list matches the set of agents with helpers on disk
|
||||
* (iv) all repository-relative paths referenced in README.md and docs/ exist
|
||||
*
|
||||
* Exits 0 when all checks pass; exits 1 with a report when any check fails.
|
||||
*
|
||||
* Usage:
|
||||
* node scripts/verify-docs-flow.mjs
|
||||
* pnpm run verify:docs (wired via package.json)
|
||||
*/
|
||||
|
||||
import fs from "node:fs";
|
||||
import path from "node:path";
|
||||
import { fileURLToPath } from "node:url";
|
||||
|
||||
const __dirname = path.dirname(fileURLToPath(import.meta.url));
|
||||
export const REPO_ROOT = path.resolve(__dirname, "..");
|
||||
|
||||
// ── (i) docs/README.md coverage ───────────────────────────────────────────
|
||||
|
||||
/**
|
||||
* Check that every *.md file under docs/ is linked from docs/README.md.
|
||||
* Returns an array of error strings (empty = pass).
|
||||
*
|
||||
* @param {string} repoRoot
|
||||
* @returns {Promise<string[]>}
|
||||
*/
|
||||
export async function checkDocsIndexCoverage(repoRoot) {
|
||||
const docsDir = path.join(repoRoot, "docs");
|
||||
const readmePath = path.join(docsDir, "README.md");
|
||||
|
||||
if (!fs.existsSync(readmePath)) {
|
||||
return ["docs/README.md is missing"];
|
||||
}
|
||||
|
||||
const readmeContent = fs.readFileSync(readmePath, "utf8");
|
||||
const errors = [];
|
||||
|
||||
// Collect all *.md files under docs/ except README.md itself
|
||||
const mdFiles = fs
|
||||
.readdirSync(docsDir)
|
||||
.filter((f) => f.endsWith(".md") && f !== "README.md");
|
||||
|
||||
for (const file of mdFiles) {
|
||||
// Accept both ./FILE.md and FILE.md link forms
|
||||
const linked =
|
||||
readmeContent.includes(`](${file})`) ||
|
||||
readmeContent.includes(`](./${file})`);
|
||||
if (!linked) {
|
||||
errors.push(`docs/README.md does not link to docs/${file}`);
|
||||
}
|
||||
}
|
||||
|
||||
return errors;
|
||||
}
|
||||
|
||||
// ── (ii) Reviewer matrix consistency ──────────────────────────────────────
|
||||
|
||||
/**
|
||||
* Canonical reviewer CLI names expected in workflow docs.
|
||||
* Order matters for the consistency check.
|
||||
*/
|
||||
const EXPECTED_REVIEWER_CLIS = ["codex", "claude", "cursor", "opencode", "pi"];
|
||||
|
||||
/**
|
||||
* Check that the reviewer CLI matrix is consistent across the four canonical
|
||||
* workflow docs. Returns an array of error strings (empty = pass).
|
||||
*
|
||||
* @param {string} repoRoot
|
||||
* @returns {Promise<string[]>}
|
||||
*/
|
||||
export async function checkReviewerMatrixConsistency(repoRoot) {
|
||||
const canonical = [
|
||||
"docs/CREATE-PLAN.md",
|
||||
"docs/IMPLEMENT-PLAN.md",
|
||||
"docs/DO-TASK.md",
|
||||
"docs/REVIEWERS.md",
|
||||
];
|
||||
|
||||
const errors = [];
|
||||
|
||||
for (const docPath of canonical) {
|
||||
const fullPath = path.join(repoRoot, docPath);
|
||||
if (!fs.existsSync(fullPath)) {
|
||||
errors.push(`${docPath} is missing`);
|
||||
continue;
|
||||
}
|
||||
const content = fs.readFileSync(fullPath, "utf8");
|
||||
// Each canonical doc must reference all five CLIs
|
||||
for (const cli of EXPECTED_REVIEWER_CLIS) {
|
||||
if (!content.includes(`\`${cli}\``)) {
|
||||
errors.push(`${docPath}: does not mention reviewer CLI \`${cli}\``);
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
return errors;
|
||||
}
|
||||
|
||||
// ── (iii) Telegram agent coverage ─────────────────────────────────────────
|
||||
|
||||
/**
|
||||
* Agents that must have helpers on disk in skills/reviewer-runtime/.
|
||||
* Non-Pi agents use the top-level directory; Pi uses the pi/ sub-directory.
|
||||
*/
|
||||
const TELEGRAM_AGENTS = [
|
||||
{
|
||||
id: "codex",
|
||||
helperPath: "skills/reviewer-runtime/notify-telegram.sh",
|
||||
telegramSectionKeyword: "Codex",
|
||||
},
|
||||
{
|
||||
id: "claude-code",
|
||||
helperPath: "skills/reviewer-runtime/notify-telegram.sh",
|
||||
telegramSectionKeyword: "Claude Code",
|
||||
},
|
||||
{
|
||||
id: "opencode",
|
||||
helperPath: "skills/reviewer-runtime/notify-telegram.sh",
|
||||
telegramSectionKeyword: "OpenCode",
|
||||
},
|
||||
{
|
||||
id: "cursor",
|
||||
helperPath: "skills/reviewer-runtime/notify-telegram.sh",
|
||||
telegramSectionKeyword: "Cursor",
|
||||
},
|
||||
{
|
||||
id: "pi",
|
||||
helperPath: "skills/reviewer-runtime/pi/notify-telegram.sh",
|
||||
telegramSectionKeyword: "Pi",
|
||||
},
|
||||
];
|
||||
|
||||
/**
|
||||
* Check that docs/TELEGRAM-NOTIFICATIONS.md documents every agent that has a
|
||||
* notify-telegram.sh helper on disk. Returns an array of error strings.
|
||||
*
|
||||
* @param {string} repoRoot
|
||||
* @returns {Promise<string[]>}
|
||||
*/
|
||||
export async function checkTelegramAgentCoverage(repoRoot) {
|
||||
const telegramDoc = path.join(repoRoot, "docs", "TELEGRAM-NOTIFICATIONS.md");
|
||||
const errors = [];
|
||||
|
||||
if (!fs.existsSync(telegramDoc)) {
|
||||
return ["docs/TELEGRAM-NOTIFICATIONS.md is missing"];
|
||||
}
|
||||
|
||||
const content = fs.readFileSync(telegramDoc, "utf8");
|
||||
|
||||
for (const agent of TELEGRAM_AGENTS) {
|
||||
const helperFullPath = path.join(repoRoot, agent.helperPath);
|
||||
if (!fs.existsSync(helperFullPath)) {
|
||||
errors.push(
|
||||
`Telegram agent ${agent.id}: helper ${agent.helperPath} does not exist on disk`
|
||||
);
|
||||
continue;
|
||||
}
|
||||
// The Telegram doc must mention this agent somewhere
|
||||
if (!content.includes(agent.telegramSectionKeyword)) {
|
||||
errors.push(
|
||||
`docs/TELEGRAM-NOTIFICATIONS.md does not document agent: ${agent.telegramSectionKeyword}`
|
||||
);
|
||||
}
|
||||
}
|
||||
|
||||
// Pi-specific: must link to PI-COMMON-REVIEWER.md
|
||||
if (!content.includes("PI-COMMON-REVIEWER.md")) {
|
||||
errors.push(
|
||||
"docs/TELEGRAM-NOTIFICATIONS.md must link to docs/PI-COMMON-REVIEWER.md"
|
||||
);
|
||||
}
|
||||
|
||||
return errors;
|
||||
}
|
||||
|
||||
// ── (iv) Repo-relative path references ────────────────────────────────────
|
||||
|
||||
/**
|
||||
* Patterns to skip when checking path references — these are URLs and
|
||||
* non-filesystem references that look like repo paths but aren't.
|
||||
*/
|
||||
const PATH_SKIP_PATTERNS = [
|
||||
/^https?:\/\//, // HTTP URLs
|
||||
/^\/tmp\//, // /tmp paths (runtime artifacts)
|
||||
/^\$\{/, // shell variable expansions
|
||||
/^~\//, // home directory paths
|
||||
/^\.\.?\//, // relative ./ or ../ — checked differently
|
||||
/node_modules/, // node_modules
|
||||
/^[A-Z_]+_[A-Z_]+$/, // environment variable names
|
||||
];
|
||||
|
||||
/**
|
||||
* Extract candidate repository-relative paths from markdown text.
|
||||
* Looks for:
|
||||
* - markdown links: [text](path)
|
||||
* - inline code: `path`
|
||||
* - bare paths starting with known top-level directories
|
||||
*
|
||||
* @param {string} content
|
||||
* @returns {string[]} - candidate relative paths
|
||||
*/
|
||||
function extractRepoPaths(content) {
|
||||
const candidates = new Set();
|
||||
|
||||
// Markdown links: [text](path) where path does not start with http/https
|
||||
const linkRe = /\[(?:[^\]]*)\]\(([^)]+)\)/g;
|
||||
let m;
|
||||
while ((m = linkRe.exec(content)) !== null) {
|
||||
const href = m[1].split("#")[0].trim(); // strip anchors
|
||||
if (!href) continue;
|
||||
if (PATH_SKIP_PATTERNS.some((p) => p.test(href))) continue;
|
||||
// Normalize ./ prefix
|
||||
const normalized = href.startsWith("./") ? href.slice(2) : href;
|
||||
if (normalized.startsWith("../")) continue; // skip upward traversals
|
||||
candidates.add(normalized);
|
||||
}
|
||||
|
||||
return [...candidates];
|
||||
}
|
||||
|
||||
/**
|
||||
* Check that all repository-relative paths referenced in README.md and docs/
|
||||
* actually exist in the repository. Returns an array of error strings.
|
||||
*
|
||||
* @param {string} repoRoot
|
||||
* @returns {Promise<string[]>}
|
||||
*/
|
||||
export async function checkRepoPathsExist(repoRoot) {
|
||||
const errors = [];
|
||||
const filesToCheck = [
|
||||
path.join(repoRoot, "README.md"),
|
||||
...fs
|
||||
.readdirSync(path.join(repoRoot, "docs"))
|
||||
.filter((f) => f.endsWith(".md"))
|
||||
.map((f) => path.join(repoRoot, "docs", f)),
|
||||
];
|
||||
|
||||
for (const filePath of filesToCheck) {
|
||||
if (!fs.existsSync(filePath)) continue;
|
||||
const content = fs.readFileSync(filePath, "utf8");
|
||||
const relDoc = path.relative(repoRoot, filePath);
|
||||
const candidates = extractRepoPaths(content);
|
||||
|
||||
for (const candidate of candidates) {
|
||||
// Skip things that obviously aren't repo paths
|
||||
if (!candidate || candidate.length < 3) continue;
|
||||
// Skip paths that look like markdown-only links (heading anchors)
|
||||
if (candidate.startsWith("#")) continue;
|
||||
// For links relative to docs/, resolve relative to docs/
|
||||
let candidatePath;
|
||||
if (relDoc.startsWith("docs/")) {
|
||||
candidatePath = path.join(repoRoot, "docs", candidate);
|
||||
// If not found there, try relative to repo root
|
||||
if (!fs.existsSync(candidatePath)) {
|
||||
candidatePath = path.join(repoRoot, candidate);
|
||||
}
|
||||
} else {
|
||||
candidatePath = path.join(repoRoot, candidate);
|
||||
}
|
||||
|
||||
if (!fs.existsSync(candidatePath)) {
|
||||
errors.push(`${relDoc}: broken repo path reference → ${candidate}`);
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
return errors;
|
||||
}
|
||||
|
||||
// ── Main ───────────────────────────────────────────────────────────────────
|
||||
|
||||
async function main() {
|
||||
const repoRoot = REPO_ROOT;
|
||||
const allErrors = [];
|
||||
const checks = [
|
||||
["docs/README.md coverage", checkDocsIndexCoverage],
|
||||
["reviewer matrix consistency", checkReviewerMatrixConsistency],
|
||||
["Telegram agent coverage", checkTelegramAgentCoverage],
|
||||
["repo-relative path existence", checkRepoPathsExist],
|
||||
];
|
||||
|
||||
for (const [label, fn] of checks) {
|
||||
const errors = await fn(repoRoot);
|
||||
if (errors.length > 0) {
|
||||
console.error(`\n[FAIL] ${label}:`);
|
||||
for (const e of errors) {
|
||||
console.error(` - ${e}`);
|
||||
}
|
||||
allErrors.push(...errors);
|
||||
} else {
|
||||
console.log(`[pass] ${label}`);
|
||||
}
|
||||
}
|
||||
|
||||
if (allErrors.length > 0) {
|
||||
console.error(`\ndocs-flow: ${allErrors.length} error(s) found.`);
|
||||
process.exit(1);
|
||||
} else {
|
||||
console.log("\ndocs-flow: all checks passed.");
|
||||
process.exit(0);
|
||||
}
|
||||
}
|
||||
|
||||
// Run main only when executed directly (not when imported by tests)
|
||||
const isMain = process.argv[1] === fileURLToPath(import.meta.url);
|
||||
if (isMain) {
|
||||
main().catch((err) => {
|
||||
console.error(err);
|
||||
process.exit(1);
|
||||
});
|
||||
}
|
||||
@@ -1,6 +1,9 @@
|
||||
#!/usr/bin/env bash
|
||||
set -euo pipefail
|
||||
|
||||
# shellcheck source=lib/portable.sh
|
||||
source "$(dirname "${BASH_SOURCE[0]}")/lib/portable.sh"
|
||||
|
||||
REQUIRED_FILES=(
|
||||
"docs/PI-RESEARCH.md"
|
||||
"docs/PI.md"
|
||||
@@ -84,7 +87,7 @@ for family in atlassian create-plan do-task implement-plan web-automation; do
|
||||
rel_path=${source_path#"$source_dir"/}
|
||||
mirror_path="${mirror_dir}/${rel_path}"
|
||||
test -e "$mirror_path"
|
||||
test "$(stat -f '%Lp' "$source_path")" = "$(stat -f '%Lp' "$mirror_path")"
|
||||
test "$(portable_stat_perms "$source_path")" = "$(portable_stat_perms "$mirror_path")"
|
||||
done < <(find "$source_dir" \
|
||||
\( -name '.DS_Store' -o -name 'node_modules' \) -prune -o \
|
||||
-mindepth 1 -print0)
|
||||
|
||||
@@ -0,0 +1,20 @@
|
||||
// markdownlint configuration — skills/ (M2)
|
||||
//
|
||||
// Agent-facing SKILL.md files and plan templates contain verbose prose and
|
||||
// long shell commands where a strict line-length limit is counterproductive.
|
||||
// This file inherits the root config and then overrides the two rules that
|
||||
// produce false positives in agent-facing content.
|
||||
{
|
||||
// Inherit root-level rules
|
||||
"extends": "../.markdownlint.jsonc",
|
||||
|
||||
// MD013 — line length: disabled for skill files.
|
||||
// Shell commands, long option lists, and URL references commonly exceed 120
|
||||
// chars and wrapping them would break copy-paste usability.
|
||||
"MD013": false,
|
||||
|
||||
// MD024 — duplicate headings: disabled for skill files.
|
||||
// SKILL.md files intentionally use repeated per-agent section headings
|
||||
// (e.g. "### Claude Code", "### Codex") in separate variant sections.
|
||||
"MD024": false
|
||||
}
|
||||
@@ -12,6 +12,7 @@ Create and maintain a local plan folder under `ai_plan/` at project root.
|
||||
This Claude Code variant depends on Superpowers planning skills and explicit sub-skill invocation.
|
||||
|
||||
Required:
|
||||
|
||||
- Superpowers repo: `https://github.com/obra/superpowers`
|
||||
- `brainstorming` skill
|
||||
- `writing-plans` skill
|
||||
@@ -23,10 +24,12 @@ If any dependency is missing, stop immediately and return:
|
||||
## Process
|
||||
|
||||
### Phase 1: Analyze
|
||||
|
||||
- Explore the codebase with exploration agents.
|
||||
- Understand existing patterns and context.
|
||||
|
||||
### Phase 2: Gather Requirements
|
||||
|
||||
- Ask questions ONE AT A TIME until user says ready.
|
||||
- Cover scope, constraints, success criteria, dependencies.
|
||||
- Summarize before proceeding.
|
||||
@@ -45,7 +48,6 @@ For shorthand `pi/<pi-model-name>`, split only on the first slash when the prefi
|
||||
|
||||
When `REVIEWER_CLI=pi`, the reviewer model is configured independently from the model running this workflow. If the model/provider is unavailable, surface helper stderr/status and use `pi --list-models [search]` to inspect configured models.
|
||||
|
||||
|
||||
If the user has already specified a reviewer CLI and model (e.g., "create a plan, review with codex o4-mini"), use those values. Otherwise, ask:
|
||||
|
||||
1. **Which CLI should review the plan?**
|
||||
@@ -66,11 +68,13 @@ If the user has already specified a reviewer CLI and model (e.g., "create a plan
|
||||
Store the chosen `REVIEWER_CLI`, `REVIEWER_MODEL`, and `MAX_ROUNDS` for Phase 6 (Iterative Plan Review).
|
||||
|
||||
### Phase 4: Design (REQUIRED SUB-SKILL)
|
||||
|
||||
- Invoke `superpowers:brainstorming` explicitly.
|
||||
- Present 2-3 approaches and recommend one.
|
||||
- Validate design in sections.
|
||||
|
||||
### Phase 5: Plan (REQUIRED SUB-SKILL)
|
||||
|
||||
- Invoke `superpowers:writing-plans` explicitly.
|
||||
- Break into milestones and bite-sized stories (2-5 min each).
|
||||
- Story IDs: `S-{milestone}{sequence}`.
|
||||
@@ -88,6 +92,7 @@ REVIEW_ID=$(uuidgen | tr '[:upper:]' '[:lower:]' | head -c 8)
|
||||
```
|
||||
|
||||
Use for temp artifacts:
|
||||
|
||||
- `/tmp/plan-${REVIEW_ID}.md`
|
||||
- `/tmp/plan-review-${REVIEW_ID}.md`
|
||||
- `/tmp/plan-review-${REVIEW_ID}.json` (Cursor only)
|
||||
@@ -143,6 +148,7 @@ VERDICT: APPROVED
|
||||
```
|
||||
|
||||
Rules:
|
||||
|
||||
- Order findings from `P0` to `P3`.
|
||||
- `P0` = total blocker, `P1` = major risk, `P2` = must-fix before approval, `P3` = cosmetic / nice to have.
|
||||
- Use `- None.` when a severity has no findings.
|
||||
@@ -165,7 +171,6 @@ Write the reviewer invocation to `/tmp/plan-review-${REVIEW_ID}.sh` as a bash sc
|
||||
set -euo pipefail
|
||||
```
|
||||
|
||||
|
||||
**If `REVIEWER_CLI` is `pi`:**
|
||||
|
||||
Fresh call every round (Pi reviewer calls do not use session resume):
|
||||
@@ -298,6 +303,7 @@ fi
|
||||
Run the helper in the foreground and watch its live stdout for `state=in-progress` heartbeats. If your agent environment buffers command output until exit, start the helper in the background and poll `/tmp/plan-review-${REVIEW_ID}.status` separately instead of treating heartbeats as post-hoc-only data.
|
||||
|
||||
After the command completes:
|
||||
|
||||
- If `REVIEWER_CLI=cursor`, extract the final review text:
|
||||
|
||||
```bash
|
||||
@@ -323,14 +329,14 @@ Fallback is allowed only when the helper is missing or not executable.
|
||||
- `/tmp/plan-review-${REVIEW_ID}.runner.out`
|
||||
3. Present review to the user:
|
||||
|
||||
```
|
||||
```markdown
|
||||
## Plan Review — Round N (reviewer: ${REVIEWER_CLI} / ${REVIEWER_MODEL})
|
||||
|
||||
[Reviewer feedback]
|
||||
```
|
||||
|
||||
4. While the reviewer is still running, keep waiting as long as fresh `state=in-progress note="In progress N"` heartbeats continue to appear roughly once per minute.
|
||||
5. Check verdict:
|
||||
1. While the reviewer is still running, keep waiting as long as fresh `state=in-progress note="In progress N"` heartbeats continue to appear roughly once per minute.
|
||||
2. Check verdict:
|
||||
- **VERDICT: APPROVED** with no `P0`, `P1`, or `P2` findings → proceed to Phase 7 (Initialize workspace)
|
||||
- **VERDICT: APPROVED** with only `P3` findings → optionally fix the `P3` items if they are cheap and safe, then proceed
|
||||
- **VERDICT: REVISE** or any `P0`, `P1`, or `P2` finding → go to Step 5
|
||||
@@ -345,7 +351,7 @@ Address the reviewer findings in priority order (`P0` → `P1` → `P2`, then `P
|
||||
|
||||
Summarize revisions for the user:
|
||||
|
||||
```
|
||||
```markdown
|
||||
### Revisions (Round N)
|
||||
- [Change and reason, one bullet per issue addressed]
|
||||
```
|
||||
@@ -356,7 +362,6 @@ If a revision contradicts the user's explicit requirements, skip it and note it
|
||||
|
||||
Rewrite `/tmp/plan-review-${REVIEW_ID}.sh` for the next round. The script should contain the reviewer invocation only; do not run it directly.
|
||||
|
||||
|
||||
**If `REVIEWER_CLI` is `pi`:**
|
||||
|
||||
Fresh call with prior-round context (Pi reviewer calls do not use session resume):
|
||||
@@ -440,7 +445,7 @@ Return to Step 4.
|
||||
|
||||
#### Step 7: Present Final Result
|
||||
|
||||
```
|
||||
```markdown
|
||||
## Plan Review — Final (reviewer: ${REVIEWER_CLI} / ${REVIEWER_MODEL})
|
||||
|
||||
**Status:** Approved after N round(s)
|
||||
@@ -467,21 +472,25 @@ If the round failed, produced empty output, or reached operator-decision timeout
|
||||
### Phase 7: Initialize Local Plan Workspace (MANDATORY)
|
||||
|
||||
At project root:
|
||||
|
||||
1. Ensure `ai_plan/` exists. Create it if missing.
|
||||
2. Ensure `.gitignore` contains `/ai_plan/`.
|
||||
3. If `.gitignore` was changed, commit that change immediately (local commit only).
|
||||
|
||||
Recommended commit message:
|
||||
|
||||
- `chore(gitignore): ignore ai_plan local planning artifacts`
|
||||
|
||||
### Phase 8: Generate Plan Files (MANDATORY - DO NOT SKIP)
|
||||
|
||||
**PLAN MODE CHECK:** If currently in plan mode:
|
||||
|
||||
1. Inform user that plan files cannot be written while in plan mode.
|
||||
2. Instruct user to exit plan mode (approve plan or use ExitPlanMode).
|
||||
3. Proceed with file generation only after exiting plan mode.
|
||||
|
||||
Create `ai_plan/YYYY-MM-DD-<short-title>/` with ALL files:
|
||||
|
||||
1. `original-plan.md` - Copy the plan file from `~/.claude/plans/` as-is.
|
||||
2. `final-transcript.md` - Copy of final planning transcript for reference.
|
||||
3. `milestone-plan.md` - Full specification (template-based).
|
||||
@@ -514,6 +523,7 @@ fi
|
||||
```
|
||||
|
||||
Rules:
|
||||
|
||||
- Telegram is the only supported notification path. Do not use desktop notifications, `say`, email, or any other notifier.
|
||||
- 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.
|
||||
@@ -524,12 +534,14 @@ Rules:
|
||||
**ALWAYS update `story-tracker.md` before/after each story. NEVER proceed with stale tracker state.**
|
||||
|
||||
Before starting any story:
|
||||
|
||||
1. Open `story-tracker.md`
|
||||
2. Mark story `in-dev`
|
||||
3. Add notes if relevant
|
||||
4. Then begin implementation
|
||||
|
||||
After completing any story:
|
||||
|
||||
1. Mark story `completed`
|
||||
2. Add commit hash in Notes
|
||||
3. Review pending stories
|
||||
@@ -568,4 +580,5 @@ After completing any story:
|
||||
- [ ] Telegram notification attempted if configured
|
||||
|
||||
## Exit Triggers for Question Phase
|
||||
|
||||
User says: "ready", "done", "let's plan", "proceed", "enough questions"
|
||||
|
||||
@@ -58,15 +58,19 @@ Work from this folder (`ai_plan/YYYY-MM-DD-<short-title>/`) and always follow th
|
||||
## Full Context Reproduction
|
||||
|
||||
### Project Overview
|
||||
|
||||
[What this project/feature is about]
|
||||
|
||||
### User Requirements
|
||||
|
||||
[All gathered requirements]
|
||||
|
||||
### Scope
|
||||
|
||||
[In scope / out of scope]
|
||||
|
||||
### Dependencies
|
||||
|
||||
[External dependencies, prerequisites, related systems]
|
||||
|
||||
---
|
||||
@@ -74,16 +78,19 @@ Work from this folder (`ai_plan/YYYY-MM-DD-<short-title>/`) and always follow th
|
||||
## Key Specifications
|
||||
|
||||
### Type Definitions
|
||||
|
||||
```typescript
|
||||
// Copy-paste ready type definitions
|
||||
```
|
||||
|
||||
### Enums & Constants
|
||||
|
||||
```typescript
|
||||
// All enums/constants needed
|
||||
```
|
||||
|
||||
### API Endpoints
|
||||
|
||||
```typescript
|
||||
// Request/response shapes
|
||||
```
|
||||
@@ -101,16 +108,19 @@ Work from this folder (`ai_plan/YYYY-MM-DD-<short-title>/`) and always follow th
|
||||
## Verification Commands
|
||||
|
||||
### Lint (changed files first)
|
||||
|
||||
```bash
|
||||
# example: pnpm eslint <changed-file-1> <changed-file-2>
|
||||
```
|
||||
|
||||
### Typecheck
|
||||
|
||||
```bash
|
||||
# example: pnpm tsc --noEmit
|
||||
```
|
||||
|
||||
### Tests (target changed scope first)
|
||||
|
||||
```bash
|
||||
# example: pnpm test -- <related spec/file>
|
||||
```
|
||||
|
||||
@@ -1,6 +1,7 @@
|
||||
# [Plan Title]
|
||||
|
||||
## Overview
|
||||
|
||||
- **Goal:** [One sentence describing the end state]
|
||||
- **Created:** YYYY-MM-DD
|
||||
- **Status:** In Progress | Complete
|
||||
@@ -8,37 +9,46 @@
|
||||
## Context
|
||||
|
||||
### Requirements
|
||||
|
||||
[Gathered requirements from user questions]
|
||||
|
||||
### Constraints
|
||||
|
||||
[Technical, business, or timeline constraints]
|
||||
|
||||
### Success Criteria
|
||||
|
||||
[How we know this is complete]
|
||||
|
||||
## Architecture
|
||||
|
||||
### Design Decisions
|
||||
|
||||
[Key architectural choices and rationale]
|
||||
|
||||
### Component Relationships
|
||||
|
||||
[How pieces fit together]
|
||||
|
||||
### Data Flow
|
||||
|
||||
[How data moves through the system]
|
||||
|
||||
## Milestones
|
||||
|
||||
### M1: [Name]
|
||||
|
||||
**Description:** [What this milestone achieves]
|
||||
|
||||
**Acceptance Criteria:**
|
||||
|
||||
- [ ] [Criterion 1]
|
||||
- [ ] [Criterion 2]
|
||||
|
||||
**Stories:** S-101, S-102, S-103...
|
||||
|
||||
**Milestone Completion Rule (MANDATORY):**
|
||||
|
||||
- Run lint/typecheck/tests for changed files.
|
||||
- Commit locally (DO NOT push).
|
||||
- Stop and ask user for feedback.
|
||||
@@ -48,15 +58,18 @@
|
||||
---
|
||||
|
||||
### M2: [Name]
|
||||
|
||||
**Description:** [What this milestone achieves]
|
||||
|
||||
**Acceptance Criteria:**
|
||||
|
||||
- [ ] [Criterion 1]
|
||||
- [ ] [Criterion 2]
|
||||
|
||||
**Stories:** S-201, S-202, S-203...
|
||||
|
||||
**Milestone Completion Rule (MANDATORY):**
|
||||
|
||||
- Run lint/typecheck/tests for changed files.
|
||||
- Commit locally (DO NOT push).
|
||||
- Stop and ask user for feedback.
|
||||
@@ -68,16 +81,19 @@
|
||||
## Technical Specifications
|
||||
|
||||
### Types & Interfaces
|
||||
|
||||
```typescript
|
||||
// Key type definitions
|
||||
```
|
||||
|
||||
### API Contracts
|
||||
|
||||
```typescript
|
||||
// Endpoint signatures, request/response shapes
|
||||
```
|
||||
|
||||
### Constants & Enums
|
||||
|
||||
```typescript
|
||||
// Shared constants
|
||||
```
|
||||
@@ -94,6 +110,7 @@
|
||||
## Related Plan Files
|
||||
|
||||
This file is part of the plan folder under `ai_plan/`:
|
||||
|
||||
- `original-plan.md` - Original approved plan (reference for original intent)
|
||||
- `final-transcript.md` - Final planning transcript (reference for rationale/context)
|
||||
- `milestone-plan.md` - This file (full specification)
|
||||
|
||||
@@ -1,6 +1,7 @@
|
||||
# Story Tracker: [Plan Title]
|
||||
|
||||
## Progress Summary
|
||||
|
||||
- **Current Milestone:** M1
|
||||
- **Stories Complete:** 0/N
|
||||
- **Milestones Approved:** 0/M
|
||||
@@ -46,15 +47,18 @@
|
||||
## Update Instructions (MANDATORY)
|
||||
|
||||
Before starting any story:
|
||||
|
||||
1. Mark story as `in-dev`
|
||||
2. Update "Last Updated"
|
||||
|
||||
After completing any story:
|
||||
|
||||
1. Mark story as `completed`
|
||||
2. Add local commit hash to Notes
|
||||
3. Update "Stories Complete" and "Last Updated"
|
||||
|
||||
At milestone boundary:
|
||||
|
||||
1. Run lint/typecheck/tests for changed files
|
||||
2. Commit (no push)
|
||||
3. Request feedback
|
||||
@@ -63,4 +67,5 @@ At milestone boundary:
|
||||
6. Continue only after approval
|
||||
|
||||
After all milestones approved:
|
||||
|
||||
- Ask permission to push and then mark plan completed.
|
||||
|
||||
@@ -10,6 +10,7 @@ Create and maintain a local plan workspace under `ai_plan/` at project root.
|
||||
## Overview
|
||||
|
||||
This skill wraps the current Superpowers flow for Codex:
|
||||
|
||||
1. Design first with `superpowers:brainstorming`
|
||||
2. Then build an implementation plan with `superpowers:writing-plans`
|
||||
3. Review the plan iteratively with a second model/provider
|
||||
@@ -20,6 +21,7 @@ This skill wraps the current Superpowers flow for Codex:
|
||||
## Prerequisite Check (MANDATORY)
|
||||
|
||||
Required:
|
||||
|
||||
- Superpowers skills symlink: `~/.agents/skills/superpowers -> ~/.codex/superpowers/skills`
|
||||
- `superpowers:brainstorming`
|
||||
- `superpowers:writing-plans`
|
||||
@@ -50,9 +52,11 @@ If any dependency is missing, stop and return:
|
||||
## Process
|
||||
|
||||
### Phase 1: Analyze
|
||||
|
||||
- Explore the codebase and existing patterns.
|
||||
|
||||
### Phase 2: Gather Requirements
|
||||
|
||||
- Ask questions one at a time until user says ready.
|
||||
- Confirm scope, constraints, success criteria, dependencies.
|
||||
|
||||
@@ -70,7 +74,6 @@ For shorthand `pi/<pi-model-name>`, split only on the first slash when the prefi
|
||||
|
||||
When `REVIEWER_CLI=pi`, the reviewer model is configured independently from the model running this workflow. If the model/provider is unavailable, surface helper stderr/status and use `pi --list-models [search]` to inspect configured models.
|
||||
|
||||
|
||||
If the user has already specified a reviewer CLI and model (e.g., "create a plan, review with claude sonnet"), use those values. Otherwise, ask:
|
||||
|
||||
1. **Which CLI should review the plan?**
|
||||
@@ -111,6 +114,7 @@ REVIEW_ID=$(uuidgen | tr '[:upper:]' '[:lower:]' | head -c 8)
|
||||
```
|
||||
|
||||
Use for temp artifacts:
|
||||
|
||||
- `/tmp/plan-${REVIEW_ID}.md` - plan payload
|
||||
- `/tmp/plan-review-${REVIEW_ID}.md` - normalized review text presented to the user
|
||||
- `/tmp/plan-review-${REVIEW_ID}.json` - raw Cursor JSON (only for `cursor`)
|
||||
@@ -166,6 +170,7 @@ VERDICT: APPROVED
|
||||
```
|
||||
|
||||
Rules:
|
||||
|
||||
- Order findings from `P0` to `P3`.
|
||||
- `P0` = total blocker, `P1` = major risk, `P2` = must-fix before approval, `P3` = cosmetic / nice to have.
|
||||
- Use `- None.` when a severity has no findings.
|
||||
@@ -188,7 +193,6 @@ Write the reviewer invocation to `/tmp/plan-review-${REVIEW_ID}.sh` as a bash sc
|
||||
set -euo pipefail
|
||||
```
|
||||
|
||||
|
||||
**If `REVIEWER_CLI` is `pi`:**
|
||||
|
||||
Fresh call every round (Pi reviewer calls do not use session resume):
|
||||
@@ -321,6 +325,7 @@ fi
|
||||
Run the helper in the foreground and watch its live stdout for `state=in-progress` heartbeats. If your agent environment buffers command output until exit, start the helper in the background and poll `/tmp/plan-review-${REVIEW_ID}.status` separately instead of treating heartbeats as post-hoc-only data.
|
||||
|
||||
After the command completes:
|
||||
|
||||
- If `REVIEWER_CLI=cursor`, extract the final review text:
|
||||
|
||||
```bash
|
||||
@@ -346,14 +351,14 @@ Fallback is allowed only when the helper is missing or not executable.
|
||||
- `/tmp/plan-review-${REVIEW_ID}.runner.out`
|
||||
3. Present review to the user:
|
||||
|
||||
```
|
||||
```markdown
|
||||
## Plan Review — Round N (reviewer: ${REVIEWER_CLI} / ${REVIEWER_MODEL})
|
||||
|
||||
[Reviewer feedback]
|
||||
```
|
||||
|
||||
4. While the reviewer is still running, keep waiting as long as fresh `state=in-progress note="In progress N"` heartbeats continue to appear roughly once per minute.
|
||||
5. Check verdict:
|
||||
1. While the reviewer is still running, keep waiting as long as fresh `state=in-progress note="In progress N"` heartbeats continue to appear roughly once per minute.
|
||||
2. Check verdict:
|
||||
- **VERDICT: APPROVED** with no `P0`, `P1`, or `P2` findings → proceed to Phase 7 (Initialize workspace)
|
||||
- **VERDICT: APPROVED** with only `P3` findings → optionally fix the `P3` items if they are cheap and safe, then proceed
|
||||
- **VERDICT: REVISE** or any `P0`, `P1`, or `P2` finding → go to Step 5
|
||||
@@ -368,7 +373,7 @@ Address the reviewer findings in priority order (`P0` → `P1` → `P2`, then `P
|
||||
|
||||
Summarize revisions for the user:
|
||||
|
||||
```
|
||||
```markdown
|
||||
### Revisions (Round N)
|
||||
- [Change and reason, one bullet per issue addressed]
|
||||
```
|
||||
@@ -379,7 +384,6 @@ If a revision contradicts the user's explicit requirements, skip it and note it
|
||||
|
||||
Rewrite `/tmp/plan-review-${REVIEW_ID}.sh` for the next round. The script should contain the reviewer invocation only; do not run it directly.
|
||||
|
||||
|
||||
**If `REVIEWER_CLI` is `pi`:**
|
||||
|
||||
Fresh call with prior-round context (Pi reviewer calls do not use session resume):
|
||||
@@ -463,7 +467,7 @@ Return to Step 4.
|
||||
|
||||
#### Step 7: Present Final Result
|
||||
|
||||
```
|
||||
```markdown
|
||||
## Plan Review — Final (reviewer: ${REVIEWER_CLI} / ${REVIEWER_MODEL})
|
||||
|
||||
**Status:** Approved after N round(s)
|
||||
@@ -490,16 +494,19 @@ If the round failed, produced empty output, or reached operator-decision timeout
|
||||
### Phase 7: Initialize Local Plan Workspace (MANDATORY)
|
||||
|
||||
At project root:
|
||||
|
||||
1. Ensure `ai_plan/` exists. Create it if missing.
|
||||
2. Ensure `.gitignore` contains `/ai_plan/`.
|
||||
3. If `.gitignore` was changed, commit that change immediately (local commit only).
|
||||
|
||||
Recommended commit message:
|
||||
|
||||
- `chore(gitignore): ignore ai_plan local planning artifacts`
|
||||
|
||||
### Phase 8: Generate Plan Files (MANDATORY)
|
||||
|
||||
Create `ai_plan/YYYY-MM-DD-<short-title>/` with all files below:
|
||||
|
||||
1. `original-plan.md` - copy of original planner-generated plan.
|
||||
2. `final-transcript.md` - copy of final planning transcript used to reach approved plan.
|
||||
3. `milestone-plan.md` - full implementation spec (from template).
|
||||
@@ -532,6 +539,7 @@ fi
|
||||
```
|
||||
|
||||
Rules:
|
||||
|
||||
- Telegram is the only supported notification path. Do not use desktop notifications, `say`, email, or any other notifier.
|
||||
- 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.
|
||||
|
||||
@@ -65,15 +65,19 @@ Work from this folder (`ai_plan/YYYY-MM-DD-<short-title>/`) and always follow th
|
||||
## Full Context Reproduction
|
||||
|
||||
### Project Overview
|
||||
|
||||
[What this project/feature is about]
|
||||
|
||||
### User Requirements
|
||||
|
||||
[All gathered requirements]
|
||||
|
||||
### Scope
|
||||
|
||||
[In scope / out of scope]
|
||||
|
||||
### Dependencies
|
||||
|
||||
[External dependencies, prerequisites, related systems]
|
||||
|
||||
---
|
||||
@@ -81,16 +85,19 @@ Work from this folder (`ai_plan/YYYY-MM-DD-<short-title>/`) and always follow th
|
||||
## Key Specifications
|
||||
|
||||
### Type Definitions
|
||||
|
||||
```typescript
|
||||
// Copy-paste ready type definitions
|
||||
```
|
||||
|
||||
### Enums & Constants
|
||||
|
||||
```typescript
|
||||
// All enums/constants needed
|
||||
```
|
||||
|
||||
### API Endpoints
|
||||
|
||||
```typescript
|
||||
// Request/response shapes
|
||||
```
|
||||
@@ -108,16 +115,19 @@ Work from this folder (`ai_plan/YYYY-MM-DD-<short-title>/`) and always follow th
|
||||
## Verification Commands
|
||||
|
||||
### Lint (changed files first)
|
||||
|
||||
```bash
|
||||
# example: <lint-command> <changed-file-1> <changed-file-2>
|
||||
```
|
||||
|
||||
### Typecheck
|
||||
|
||||
```bash
|
||||
# example: <typecheck-command>
|
||||
```
|
||||
|
||||
### Tests (target changed scope first)
|
||||
|
||||
```bash
|
||||
# example: <test-command> <related spec/file>
|
||||
```
|
||||
|
||||
@@ -1,11 +1,13 @@
|
||||
# [Plan Title]
|
||||
|
||||
## Overview
|
||||
|
||||
- **Goal:** [One sentence describing the end state]
|
||||
- **Created:** YYYY-MM-DD
|
||||
- **Status:** In Progress | Complete
|
||||
|
||||
## Planning Guardrails
|
||||
|
||||
- This plan assumes design was validated before implementation planning.
|
||||
- Skills are invoked via native discovery (Codex: `~/.agents/skills/`).
|
||||
- Deprecated CLI wrappers (for example, `superpowers-codex bootstrap` / `use-skill`) are not part of this workflow.
|
||||
@@ -14,37 +16,46 @@
|
||||
## Context
|
||||
|
||||
### Requirements
|
||||
|
||||
[Gathered requirements from user questions]
|
||||
|
||||
### Constraints
|
||||
|
||||
[Technical, business, or timeline constraints]
|
||||
|
||||
### Success Criteria
|
||||
|
||||
[How we know this is complete]
|
||||
|
||||
## Architecture
|
||||
|
||||
### Design Decisions
|
||||
|
||||
[Key architectural choices and rationale]
|
||||
|
||||
### Component Relationships
|
||||
|
||||
[How pieces fit together]
|
||||
|
||||
### Data Flow
|
||||
|
||||
[How data moves through the system]
|
||||
|
||||
## Milestones
|
||||
|
||||
### M1: [Name]
|
||||
|
||||
**Description:** [What this milestone achieves]
|
||||
|
||||
**Acceptance Criteria:**
|
||||
|
||||
- [ ] [Criterion 1]
|
||||
- [ ] [Criterion 2]
|
||||
|
||||
**Stories:** S-101, S-102, S-103...
|
||||
|
||||
**Milestone Completion Rule (MANDATORY):**
|
||||
|
||||
- Run lint/typecheck/tests for changed files.
|
||||
- Commit locally (DO NOT push).
|
||||
- Stop and ask user for feedback.
|
||||
@@ -54,15 +65,18 @@
|
||||
---
|
||||
|
||||
### M2: [Name]
|
||||
|
||||
**Description:** [What this milestone achieves]
|
||||
|
||||
**Acceptance Criteria:**
|
||||
|
||||
- [ ] [Criterion 1]
|
||||
- [ ] [Criterion 2]
|
||||
|
||||
**Stories:** S-201, S-202, S-203...
|
||||
|
||||
**Milestone Completion Rule (MANDATORY):**
|
||||
|
||||
- Run lint/typecheck/tests for changed files.
|
||||
- Commit locally (DO NOT push).
|
||||
- Stop and ask user for feedback.
|
||||
@@ -74,16 +88,19 @@
|
||||
## Technical Specifications
|
||||
|
||||
### Types & Interfaces
|
||||
|
||||
```typescript
|
||||
// Key type definitions (or equivalent language constructs)
|
||||
```
|
||||
|
||||
### API Contracts
|
||||
|
||||
```typescript
|
||||
// Endpoint signatures, request/response shapes (if applicable)
|
||||
```
|
||||
|
||||
### Constants & Enums
|
||||
|
||||
```typescript
|
||||
// Shared constants (if applicable)
|
||||
```
|
||||
@@ -100,6 +117,7 @@
|
||||
## Related Plan Files
|
||||
|
||||
This file is part of the plan folder under `ai_plan/`:
|
||||
|
||||
- `original-plan.md` - Original approved plan (reference for original intent)
|
||||
- `final-transcript.md` - Final planning transcript (reference for rationale/context)
|
||||
- `milestone-plan.md` - This file (full specification)
|
||||
|
||||
@@ -1,12 +1,14 @@
|
||||
# Story Tracker: [Plan Title]
|
||||
|
||||
## Progress Summary
|
||||
|
||||
- **Current Milestone:** M1
|
||||
- **Stories Complete:** 0/N
|
||||
- **Milestones Approved:** 0/M
|
||||
- **Last Updated:** YYYY-MM-DD
|
||||
|
||||
## Tracking Guardrails
|
||||
|
||||
- Update status immediately when work starts (`in-dev`) and when work completes (`completed`).
|
||||
- Require explicit user approval at each milestone boundary before continuing.
|
||||
- Do not push until all milestones are approved and permission is explicitly granted.
|
||||
@@ -52,15 +54,18 @@
|
||||
## Update Instructions (MANDATORY)
|
||||
|
||||
Before starting any story:
|
||||
|
||||
1. Mark story as `in-dev`
|
||||
2. Update "Last Updated"
|
||||
|
||||
After completing any story:
|
||||
|
||||
1. Mark story as `completed`
|
||||
2. Add local commit hash to Notes
|
||||
3. Update "Stories Complete" and "Last Updated"
|
||||
|
||||
At milestone boundary:
|
||||
|
||||
1. Run lint/typecheck/tests for changed files
|
||||
2. Commit (no push)
|
||||
3. Request feedback
|
||||
@@ -69,4 +74,5 @@ At milestone boundary:
|
||||
6. Continue only after approval
|
||||
|
||||
After all milestones approved:
|
||||
|
||||
- Ask permission to push and then mark plan completed.
|
||||
|
||||
@@ -10,6 +10,7 @@ Create and maintain a local plan folder under `ai_plan/` at project root.
|
||||
## Overview
|
||||
|
||||
This skill wraps the current Superpowers flow for the Cursor Agent CLI (`cursor-agent`):
|
||||
|
||||
1. Design first with `superpowers:brainstorming`
|
||||
2. Then build an implementation plan with `superpowers:writing-plans`
|
||||
3. Review the plan iteratively with a second model/provider
|
||||
@@ -20,6 +21,7 @@ This skill wraps the current Superpowers flow for the Cursor Agent CLI (`cursor-
|
||||
## Prerequisite Check (MANDATORY)
|
||||
|
||||
Required:
|
||||
|
||||
- Cursor Agent CLI: `cursor-agent --version` (install via `curl https://cursor.com/install -fsS | bash`). The binary is `cursor-agent` (installed to `~/.local/bin/`). Some environments alias it as `cursor agent` (subcommand of the Cursor IDE CLI) — both forms work, but this skill uses `cursor-agent` throughout.
|
||||
- `jq` (required only if using `cursor` as the reviewer CLI): `jq --version` (install via `brew install jq` or your package manager)
|
||||
- Superpowers repo: `https://github.com/obra/superpowers`
|
||||
@@ -51,9 +53,11 @@ If any dependency is missing, stop and return:
|
||||
## Process
|
||||
|
||||
### Phase 1: Analyze
|
||||
|
||||
- Explore the codebase and existing patterns.
|
||||
|
||||
### Phase 2: Gather Requirements
|
||||
|
||||
- Ask questions one at a time until user says ready.
|
||||
- Confirm scope, constraints, success criteria, dependencies.
|
||||
|
||||
@@ -71,7 +75,6 @@ For shorthand `pi/<pi-model-name>`, split only on the first slash when the prefi
|
||||
|
||||
When `REVIEWER_CLI=pi`, the reviewer model is configured independently from the model running this workflow. If the model/provider is unavailable, surface helper stderr/status and use `pi --list-models [search]` to inspect configured models.
|
||||
|
||||
|
||||
If the user has already specified a reviewer CLI and model (e.g., "create a plan, review with codex o4-mini"), use those values. Otherwise, ask:
|
||||
|
||||
1. **Which CLI should review the plan?**
|
||||
@@ -113,6 +116,7 @@ REVIEW_ID=$(uuidgen | tr '[:upper:]' '[:lower:]' | head -c 8)
|
||||
```
|
||||
|
||||
Use for temp artifacts:
|
||||
|
||||
- `/tmp/plan-${REVIEW_ID}.md`
|
||||
- `/tmp/plan-review-${REVIEW_ID}.md`
|
||||
- `/tmp/plan-review-${REVIEW_ID}.json` (Cursor only)
|
||||
@@ -172,6 +176,7 @@ VERDICT: APPROVED
|
||||
```
|
||||
|
||||
Rules:
|
||||
|
||||
- Order findings from `P0` to `P3`.
|
||||
- `P0` = total blocker, `P1` = major risk, `P2` = must-fix before approval, `P3` = cosmetic / nice to have.
|
||||
- Use `- None.` when a severity has no findings.
|
||||
@@ -194,7 +199,6 @@ Write the reviewer invocation to `/tmp/plan-review-${REVIEW_ID}.sh` as a bash sc
|
||||
set -euo pipefail
|
||||
```
|
||||
|
||||
|
||||
**If `REVIEWER_CLI` is `pi`:**
|
||||
|
||||
Fresh call every round (Pi reviewer calls do not use session resume):
|
||||
@@ -309,6 +313,7 @@ Rules:
|
||||
For `cursor`, the command script writes raw JSON to `/tmp/plan-review-${REVIEW_ID}.json`. Do not run `jq` extraction until after the helper or fallback execution completes.
|
||||
|
||||
Notes on Cursor flags:
|
||||
|
||||
- `--mode=ask` — read-only mode, no file modifications
|
||||
- `--trust` — trust workspace without prompting (required for non-interactive use)
|
||||
- `-p` / `--print` — non-interactive mode, output to stdout
|
||||
@@ -333,6 +338,7 @@ fi
|
||||
Run the helper in the foreground and watch its live stdout for `state=in-progress` heartbeats. If your agent environment buffers command output until exit, start the helper in the background and poll `/tmp/plan-review-${REVIEW_ID}.status` separately instead of treating heartbeats as post-hoc-only data.
|
||||
|
||||
After the command completes:
|
||||
|
||||
- If `REVIEWER_CLI=cursor`, extract the final review text:
|
||||
|
||||
```bash
|
||||
@@ -356,14 +362,14 @@ cp /tmp/plan-review-${REVIEW_ID}.runner.out /tmp/plan-review-${REVIEW_ID}.md
|
||||
- `/tmp/plan-review-${REVIEW_ID}.runner.out`
|
||||
3. Present review to the user:
|
||||
|
||||
```
|
||||
```markdown
|
||||
## Plan Review — Round N (reviewer: ${REVIEWER_CLI} / ${REVIEWER_MODEL})
|
||||
|
||||
[Reviewer feedback]
|
||||
```
|
||||
|
||||
4. While the reviewer is still running, keep waiting as long as fresh `state=in-progress note="In progress N"` heartbeats continue to appear roughly once per minute.
|
||||
5. Check verdict:
|
||||
1. While the reviewer is still running, keep waiting as long as fresh `state=in-progress note="In progress N"` heartbeats continue to appear roughly once per minute.
|
||||
2. Check verdict:
|
||||
- **VERDICT: APPROVED** with no `P0`, `P1`, or `P2` findings → proceed to Phase 7 (Initialize workspace)
|
||||
- **VERDICT: APPROVED** with only `P3` findings → optionally fix the `P3` items if they are cheap and safe, then proceed
|
||||
- **VERDICT: REVISE** or any `P0`, `P1`, or `P2` finding → go to Step 5
|
||||
@@ -378,7 +384,7 @@ Address the reviewer findings in priority order (`P0` → `P1` → `P2`, then `P
|
||||
|
||||
Summarize revisions for the user:
|
||||
|
||||
```
|
||||
```markdown
|
||||
### Revisions (Round N)
|
||||
- [Change and reason, one bullet per issue addressed]
|
||||
```
|
||||
@@ -389,7 +395,6 @@ If a revision contradicts the user's explicit requirements, skip it and note it
|
||||
|
||||
Rewrite `/tmp/plan-review-${REVIEW_ID}.sh` for the next round. The script should contain the reviewer invocation only; do not run it directly.
|
||||
|
||||
|
||||
**If `REVIEWER_CLI` is `pi`:**
|
||||
|
||||
Fresh call with prior-round context (Pi reviewer calls do not use session resume):
|
||||
@@ -473,7 +478,7 @@ Return to Step 4.
|
||||
|
||||
#### Step 7: Present Final Result
|
||||
|
||||
```
|
||||
```markdown
|
||||
## Plan Review — Final (reviewer: ${REVIEWER_CLI} / ${REVIEWER_MODEL})
|
||||
|
||||
**Status:** Approved after N round(s)
|
||||
@@ -500,16 +505,19 @@ If the round failed, produced empty output, or reached operator-decision timeout
|
||||
### Phase 7: Initialize Local Plan Workspace (MANDATORY)
|
||||
|
||||
At project root:
|
||||
|
||||
1. Ensure `ai_plan/` exists. Create it if missing.
|
||||
2. Ensure `.gitignore` contains `/ai_plan/`.
|
||||
3. If `.gitignore` was changed, commit that change immediately (local commit only).
|
||||
|
||||
Recommended commit message:
|
||||
|
||||
- `chore(gitignore): ignore ai_plan local planning artifacts`
|
||||
|
||||
### Phase 8: Generate Plan Files (MANDATORY)
|
||||
|
||||
Create `ai_plan/YYYY-MM-DD-<short-title>/` with all files below:
|
||||
|
||||
1. `original-plan.md` - copy of original planner-generated plan.
|
||||
2. `final-transcript.md` - copy of final planning transcript used to reach approved plan.
|
||||
3. `milestone-plan.md` - full implementation spec (from template).
|
||||
@@ -546,6 +554,7 @@ fi
|
||||
```
|
||||
|
||||
Rules:
|
||||
|
||||
- Telegram is the only supported notification path. Do not use desktop notifications, `say`, email, or any other notifier.
|
||||
- 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.
|
||||
@@ -569,12 +578,14 @@ Rules:
|
||||
## Tracker Discipline (MANDATORY)
|
||||
|
||||
Before starting any story:
|
||||
|
||||
1. Open `story-tracker.md`
|
||||
2. Mark story `in-dev`
|
||||
3. Add notes if relevant
|
||||
4. Then begin implementation
|
||||
|
||||
After completing any story:
|
||||
|
||||
1. Mark story `completed`
|
||||
2. Add commit hash in Notes
|
||||
3. Review pending stories
|
||||
@@ -634,4 +645,5 @@ After completing any story:
|
||||
- [ ] Telegram notification attempted if configured
|
||||
|
||||
## Exit Triggers for Question Phase
|
||||
|
||||
User says: "ready", "done", "let's plan", "proceed", "enough questions"
|
||||
|
||||
@@ -64,15 +64,19 @@ Work from this folder (`ai_plan/YYYY-MM-DD-<short-title>/`) and always follow th
|
||||
## Full Context Reproduction
|
||||
|
||||
### Project Overview
|
||||
|
||||
[What this project/feature is about]
|
||||
|
||||
### User Requirements
|
||||
|
||||
[All gathered requirements]
|
||||
|
||||
### Scope
|
||||
|
||||
[In scope / out of scope]
|
||||
|
||||
### Dependencies
|
||||
|
||||
[External dependencies, prerequisites, related systems]
|
||||
|
||||
---
|
||||
@@ -80,16 +84,19 @@ Work from this folder (`ai_plan/YYYY-MM-DD-<short-title>/`) and always follow th
|
||||
## Key Specifications
|
||||
|
||||
### Type Definitions
|
||||
|
||||
```typescript
|
||||
// Copy-paste ready type definitions
|
||||
```
|
||||
|
||||
### Enums & Constants
|
||||
|
||||
```typescript
|
||||
// All enums/constants needed
|
||||
```
|
||||
|
||||
### API Endpoints
|
||||
|
||||
```typescript
|
||||
// Request/response shapes
|
||||
```
|
||||
@@ -107,16 +114,19 @@ Work from this folder (`ai_plan/YYYY-MM-DD-<short-title>/`) and always follow th
|
||||
## Verification Commands
|
||||
|
||||
### Lint (changed files first)
|
||||
|
||||
```bash
|
||||
# example: <lint-command> <changed-file-1> <changed-file-2>
|
||||
```
|
||||
|
||||
### Typecheck
|
||||
|
||||
```bash
|
||||
# example: <typecheck-command>
|
||||
```
|
||||
|
||||
### Tests (target changed scope first)
|
||||
|
||||
```bash
|
||||
# example: <test-command> <related spec/file>
|
||||
```
|
||||
|
||||
@@ -1,11 +1,13 @@
|
||||
# [Plan Title]
|
||||
|
||||
## Overview
|
||||
|
||||
- **Goal:** [One sentence describing the end state]
|
||||
- **Created:** YYYY-MM-DD
|
||||
- **Status:** In Progress | Complete
|
||||
|
||||
## Planning Guardrails
|
||||
|
||||
- This plan assumes design was validated before implementation planning.
|
||||
- Skills are invoked via workspace discovery (`.cursor/skills/`).
|
||||
- Milestones require verification + local commits + explicit approval before proceeding.
|
||||
@@ -13,37 +15,46 @@
|
||||
## Context
|
||||
|
||||
### Requirements
|
||||
|
||||
[Gathered requirements from user questions]
|
||||
|
||||
### Constraints
|
||||
|
||||
[Technical, business, or timeline constraints]
|
||||
|
||||
### Success Criteria
|
||||
|
||||
[How we know this is complete]
|
||||
|
||||
## Architecture
|
||||
|
||||
### Design Decisions
|
||||
|
||||
[Key architectural choices and rationale]
|
||||
|
||||
### Component Relationships
|
||||
|
||||
[How pieces fit together]
|
||||
|
||||
### Data Flow
|
||||
|
||||
[How data moves through the system]
|
||||
|
||||
## Milestones
|
||||
|
||||
### M1: [Name]
|
||||
|
||||
**Description:** [What this milestone achieves]
|
||||
|
||||
**Acceptance Criteria:**
|
||||
|
||||
- [ ] [Criterion 1]
|
||||
- [ ] [Criterion 2]
|
||||
|
||||
**Stories:** S-101, S-102, S-103...
|
||||
|
||||
**Milestone Completion Rule (MANDATORY):**
|
||||
|
||||
- Run lint/typecheck/tests for changed files.
|
||||
- Commit locally (DO NOT push).
|
||||
- Stop and ask user for feedback.
|
||||
@@ -53,15 +64,18 @@
|
||||
---
|
||||
|
||||
### M2: [Name]
|
||||
|
||||
**Description:** [What this milestone achieves]
|
||||
|
||||
**Acceptance Criteria:**
|
||||
|
||||
- [ ] [Criterion 1]
|
||||
- [ ] [Criterion 2]
|
||||
|
||||
**Stories:** S-201, S-202, S-203...
|
||||
|
||||
**Milestone Completion Rule (MANDATORY):**
|
||||
|
||||
- Run lint/typecheck/tests for changed files.
|
||||
- Commit locally (DO NOT push).
|
||||
- Stop and ask user for feedback.
|
||||
@@ -73,16 +87,19 @@
|
||||
## Technical Specifications
|
||||
|
||||
### Types & Interfaces
|
||||
|
||||
```typescript
|
||||
// Key type definitions (or equivalent language constructs)
|
||||
```
|
||||
|
||||
### API Contracts
|
||||
|
||||
```typescript
|
||||
// Endpoint signatures, request/response shapes (if applicable)
|
||||
```
|
||||
|
||||
### Constants & Enums
|
||||
|
||||
```typescript
|
||||
// Shared constants (if applicable)
|
||||
```
|
||||
@@ -99,6 +116,7 @@
|
||||
## Related Plan Files
|
||||
|
||||
This file is part of the plan folder under `ai_plan/`:
|
||||
|
||||
- `original-plan.md` - Original approved plan (reference for original intent)
|
||||
- `final-transcript.md` - Final planning transcript (reference for rationale/context)
|
||||
- `milestone-plan.md` - This file (full specification)
|
||||
|
||||
@@ -1,12 +1,14 @@
|
||||
# Story Tracker: [Plan Title]
|
||||
|
||||
## Progress Summary
|
||||
|
||||
- **Current Milestone:** M1
|
||||
- **Stories Complete:** 0/N
|
||||
- **Milestones Approved:** 0/M
|
||||
- **Last Updated:** YYYY-MM-DD
|
||||
|
||||
## Tracking Guardrails
|
||||
|
||||
- Update status immediately when work starts (`in-dev`) and when work completes (`completed`).
|
||||
- Require explicit user approval at each milestone boundary before continuing.
|
||||
- Do not push until all milestones are approved and permission is explicitly granted.
|
||||
@@ -52,15 +54,18 @@
|
||||
## Update Instructions (MANDATORY)
|
||||
|
||||
Before starting any story:
|
||||
|
||||
1. Mark story as `in-dev`
|
||||
2. Update "Last Updated"
|
||||
|
||||
After completing any story:
|
||||
|
||||
1. Mark story as `completed`
|
||||
2. Add local commit hash to Notes
|
||||
3. Update "Stories Complete" and "Last Updated"
|
||||
|
||||
At milestone boundary:
|
||||
|
||||
1. Run lint/typecheck/tests for changed files
|
||||
2. Commit (no push)
|
||||
3. Request feedback
|
||||
@@ -69,4 +74,5 @@ At milestone boundary:
|
||||
6. Continue only after approval
|
||||
|
||||
After all milestones approved:
|
||||
|
||||
- Ask permission to push and then mark plan completed.
|
||||
|
||||
@@ -12,6 +12,7 @@ Create and maintain a local plan folder under `ai_plan/` at project root.
|
||||
This OpenCode variant depends on Superpowers skills being available through OpenCode's native skill system.
|
||||
|
||||
Required:
|
||||
|
||||
- Superpowers repo: `https://github.com/obra/superpowers`
|
||||
- OpenCode Superpowers skills available at `~/.agents/skills/superpowers` or `~/.config/opencode/skills/superpowers`
|
||||
- `superpowers/brainstorming`
|
||||
@@ -33,13 +34,16 @@ If dependencies are missing, stop immediately and return:
|
||||
### Phase 1: Bootstrap Superpowers Context (REQUIRED)
|
||||
|
||||
Use OpenCode's native skill tool:
|
||||
|
||||
- list skills
|
||||
- verify `superpowers/brainstorming` and `superpowers/writing-plans` are discoverable
|
||||
|
||||
### Phase 2: Analyze
|
||||
|
||||
- Explore the codebase and existing patterns.
|
||||
|
||||
### Phase 3: Gather Requirements
|
||||
|
||||
- Ask questions ONE AT A TIME until user says ready.
|
||||
- Cover scope, constraints, success criteria, dependencies.
|
||||
- Summarize before proceeding.
|
||||
@@ -77,10 +81,10 @@ For shorthand `pi/<pi-model-name>`, split only on the first slash when the prefi
|
||||
|
||||
When `REVIEWER_CLI=pi`, the reviewer model is configured independently from the model running this workflow. If the model/provider is unavailable, surface helper stderr/status and use `pi --list-models [search]` to inspect configured models.
|
||||
|
||||
|
||||
### Phase 5: Design (REQUIRED SUB-SKILL)
|
||||
|
||||
Use OpenCode's native skill tool to load:
|
||||
|
||||
- `superpowers/brainstorming`
|
||||
|
||||
Then present 2-3 approaches and recommend one.
|
||||
@@ -88,6 +92,7 @@ Then present 2-3 approaches and recommend one.
|
||||
### Phase 6: Plan (REQUIRED SUB-SKILL)
|
||||
|
||||
Use OpenCode's native skill tool to load:
|
||||
|
||||
- `superpowers/writing-plans`
|
||||
|
||||
Then break into milestones and bite-sized stories (2-5 min each).
|
||||
@@ -106,6 +111,7 @@ REVIEW_ID=$(uuidgen | tr '[:upper:]' '[:lower:]' | head -c 8)
|
||||
```
|
||||
|
||||
Use for temp artifacts:
|
||||
|
||||
- `/tmp/plan-${REVIEW_ID}.md`
|
||||
- `/tmp/plan-review-${REVIEW_ID}.md`
|
||||
- `/tmp/plan-review-${REVIEW_ID}.json` (Cursor only)
|
||||
@@ -131,6 +137,9 @@ case "$REVIEWER_CLI" in
|
||||
cursor)
|
||||
HELPER_SUCCESS_FILE_ARGS+=(--success-file /tmp/plan-review-${REVIEW_ID}.json)
|
||||
;;
|
||||
opencode)
|
||||
HELPER_SUCCESS_FILE_ARGS+=(--success-file /tmp/plan-review-${REVIEW_ID}.md)
|
||||
;;
|
||||
esac
|
||||
```
|
||||
|
||||
@@ -161,6 +170,7 @@ VERDICT: APPROVED
|
||||
```
|
||||
|
||||
Rules:
|
||||
|
||||
- Order findings from `P0` to `P3`.
|
||||
- `P0` = total blocker, `P1` = major risk, `P2` = must-fix before approval, `P3` = cosmetic / nice to have.
|
||||
- Use `- None.` when a severity has no findings.
|
||||
@@ -183,7 +193,6 @@ Write the reviewer invocation to `/tmp/plan-review-${REVIEW_ID}.sh` as a bash sc
|
||||
set -euo pipefail
|
||||
```
|
||||
|
||||
|
||||
**If `REVIEWER_CLI` is `pi`:**
|
||||
|
||||
Fresh call every round (Pi reviewer calls do not use session resume):
|
||||
@@ -297,6 +306,75 @@ Rules:
|
||||
|
||||
For `cursor`, the command script writes raw JSON to `/tmp/plan-review-${REVIEW_ID}.json`. Do not run `jq` extraction until after the helper or fallback execution completes. If `jq` is not installed, inform the user: `brew install jq` (macOS) or equivalent.
|
||||
|
||||
**If `REVIEWER_CLI` is `opencode`:**
|
||||
|
||||
OpenCode uses `--agent plan` for read-oriented review. Fresh call is the recommended default.
|
||||
|
||||
Round 1:
|
||||
|
||||
```bash
|
||||
opencode run \
|
||||
-m ${REVIEWER_MODEL} \
|
||||
--agent plan \
|
||||
--format json \
|
||||
"Read the file /tmp/plan-${REVIEW_ID}.md and review the implementation plan. Focus on:
|
||||
1. Correctness — Will this plan achieve the stated goals?
|
||||
2. Risks — What could go wrong? Edge cases? Data loss?
|
||||
3. Missing steps — Is anything forgotten?
|
||||
4. Alternatives — Is there a simpler or better approach?
|
||||
5. Security — Any security concerns?
|
||||
|
||||
Return exactly these sections in order:
|
||||
## Summary
|
||||
## Findings
|
||||
### P0
|
||||
### P1
|
||||
### P2
|
||||
### P3
|
||||
## Verdict
|
||||
|
||||
Rules:
|
||||
- Order findings from highest severity to lowest.
|
||||
- Use \`- None.\` when a severity has no findings.
|
||||
- \`P0\` = total blocker, \`P1\` = major risk, \`P2\` = must-fix before approval, \`P3\` = cosmetic / nice to have.
|
||||
- End with exactly one verdict line: \`VERDICT: APPROVED\` or \`VERDICT: REVISE\`
|
||||
- \`VERDICT: APPROVED\` is allowed only when there are no \`P0\`, \`P1\`, or \`P2\` findings. \`P3\` findings are non-blocking." \
|
||||
> /tmp/plan-review-${REVIEW_ID}.json
|
||||
```
|
||||
|
||||
Round 2 and later (fresh-call, recommended default):
|
||||
|
||||
```bash
|
||||
opencode run \
|
||||
-m ${REVIEWER_MODEL} \
|
||||
--agent plan \
|
||||
--format json \
|
||||
"You previously reviewed this plan and requested revisions.
|
||||
|
||||
Previous feedback summary: [key points from last review]
|
||||
|
||||
I've revised. Updated payload is in /tmp/plan-${REVIEW_ID}.md.
|
||||
|
||||
Changes made:
|
||||
[List specific changes]
|
||||
|
||||
Re-review using the same ## Summary, ## Findings, and ## Verdict structure as before." \
|
||||
> /tmp/plan-review-${REVIEW_ID}.json
|
||||
```
|
||||
|
||||
Extract the review body:
|
||||
|
||||
```bash
|
||||
jq -r '.[] | select(.type == "message" and .role == "assistant") | .content' \
|
||||
/tmp/plan-review-${REVIEW_ID}.json \
|
||||
> /tmp/plan-review-${REVIEW_ID}.md \
|
||||
|| cp /tmp/plan-review-${REVIEW_ID}.json /tmp/plan-review-${REVIEW_ID}.md
|
||||
```
|
||||
|
||||
If the JSON parse falls through, promote the raw JSON file as the review output. On any opencode
|
||||
CLI or JSON parsing failure, treat this loop round as `completed-empty-output` and follow the
|
||||
helper-failure escalation in Step 4.
|
||||
|
||||
Run the command script through the shared helper when available:
|
||||
|
||||
```bash
|
||||
@@ -316,6 +394,7 @@ fi
|
||||
Run the helper in the foreground and watch its live stdout for `state=in-progress` heartbeats. If your agent environment buffers command output until exit, start the helper in the background and poll `/tmp/plan-review-${REVIEW_ID}.status` separately instead of treating heartbeats as post-hoc-only data.
|
||||
|
||||
After the command completes:
|
||||
|
||||
- If `REVIEWER_CLI=cursor`, extract the final review text:
|
||||
|
||||
```bash
|
||||
@@ -324,6 +403,7 @@ jq -r '.result' /tmp/plan-review-${REVIEW_ID}.json > /tmp/plan-review-${REVIEW_I
|
||||
```
|
||||
|
||||
- If `REVIEWER_CLI=codex`, extract `CODEX_SESSION_ID` from `/tmp/plan-review-${REVIEW_ID}.runner.out` after the helper or fallback run. If the review text is only in `.runner.out`, move or copy the actual review body into `/tmp/plan-review-${REVIEW_ID}.md` before verdict parsing.
|
||||
- If `REVIEWER_CLI=opencode`, the `jq` extraction above covers output capture. If it falls through, copy runner output: `cp /tmp/plan-review-${REVIEW_ID}.runner.out /tmp/plan-review-${REVIEW_ID}.md`. On Round 1, also attempt to capture the session id for optional use in subsequent rounds: `OPENCODE_SESSION_ID=$(jq -r 'if type == "array" then (.[0] | (.id? // .session_id?)) else (.id? // .session_id?) end // empty' /tmp/plan-review-${REVIEW_ID}.json 2>/dev/null || true)`
|
||||
- If `REVIEWER_CLI=claude` or `REVIEWER_CLI=pi`, promote stdout captured by the helper or fallback runner into the markdown review file:
|
||||
|
||||
```bash
|
||||
@@ -339,14 +419,14 @@ cp /tmp/plan-review-${REVIEW_ID}.runner.out /tmp/plan-review-${REVIEW_ID}.md
|
||||
- `/tmp/plan-review-${REVIEW_ID}.runner.out`
|
||||
3. Present review to the user:
|
||||
|
||||
```
|
||||
```markdown
|
||||
## Plan Review — Round N (reviewer: ${REVIEWER_CLI} / ${REVIEWER_MODEL})
|
||||
|
||||
[Reviewer feedback]
|
||||
```
|
||||
|
||||
4. While the reviewer is still running, keep waiting as long as fresh `state=in-progress note="In progress N"` heartbeats continue to appear roughly once per minute.
|
||||
5. Check verdict:
|
||||
1. While the reviewer is still running, keep waiting as long as fresh `state=in-progress note="In progress N"` heartbeats continue to appear roughly once per minute.
|
||||
2. Check verdict:
|
||||
- **VERDICT: APPROVED** with no `P0`, `P1`, or `P2` findings → proceed to Phase 8 (Initialize workspace)
|
||||
- **VERDICT: APPROVED** with only `P3` findings → optionally fix the `P3` items if they are cheap and safe, then proceed
|
||||
- **VERDICT: REVISE** or any `P0`, `P1`, or `P2` finding → go to Step 5
|
||||
@@ -361,7 +441,7 @@ Address the reviewer findings in priority order (`P0` → `P1` → `P2`, then `P
|
||||
|
||||
Summarize revisions for the user:
|
||||
|
||||
```
|
||||
```markdown
|
||||
### Revisions (Round N)
|
||||
- [Change and reason, one bullet per issue addressed]
|
||||
```
|
||||
@@ -372,7 +452,6 @@ If a revision contradicts the user's explicit requirements, skip it and note it
|
||||
|
||||
Rewrite `/tmp/plan-review-${REVIEW_ID}.sh` for the next round. The script should contain the reviewer invocation only; do not run it directly.
|
||||
|
||||
|
||||
**If `REVIEWER_CLI` is `pi`:**
|
||||
|
||||
Fresh call with prior-round context (Pi reviewer calls do not use session resume):
|
||||
@@ -450,13 +529,66 @@ jq -r '.result' /tmp/plan-review-${REVIEW_ID}.json > /tmp/plan-review-${REVIEW_I
|
||||
|
||||
If resume fails, fall back to fresh `cursor-agent -p` with context about prior rounds.
|
||||
|
||||
**If `REVIEWER_CLI` is `opencode`:**
|
||||
|
||||
Fresh call (recommended default — opencode has no guaranteed stable session ID in headless mode):
|
||||
|
||||
```bash
|
||||
opencode run \
|
||||
-m ${REVIEWER_MODEL} \
|
||||
--agent plan \
|
||||
--format json \
|
||||
"You previously reviewed this plan and requested revisions.
|
||||
|
||||
Previous feedback summary: [key points from last review]
|
||||
|
||||
I've revised. Updated payload is in /tmp/plan-${REVIEW_ID}.md.
|
||||
|
||||
Changes made:
|
||||
[List specific changes]
|
||||
|
||||
Re-review using the same \`## Summary\`, \`## Findings\`, and \`## Verdict\` structure as before.
|
||||
Keep findings ordered \`P0\` to \`P3\`, use \`- None.\` when a severity has no findings, and only use \`VERDICT: APPROVED\` when no \`P0\`, \`P1\`, or \`P2\` findings remain. \`P3\` findings are non-blocking." \
|
||||
> /tmp/plan-review-${REVIEW_ID}.json
|
||||
|
||||
jq -r '.[] | select(.type == "message" and .role == "assistant") | .content' \
|
||||
/tmp/plan-review-${REVIEW_ID}.json \
|
||||
> /tmp/plan-review-${REVIEW_ID}.md \
|
||||
|| cp /tmp/plan-review-${REVIEW_ID}.json /tmp/plan-review-${REVIEW_ID}.md
|
||||
```
|
||||
|
||||
Optional session-resume path (only if `OPENCODE_SESSION_ID` was captured on Round 1 and your installed opencode accepts `-s <id>` reliably in headless mode):
|
||||
|
||||
```bash
|
||||
opencode run \
|
||||
-s ${OPENCODE_SESSION_ID} \
|
||||
-m ${REVIEWER_MODEL} \
|
||||
--agent plan \
|
||||
--format json \
|
||||
"I've revised the plan based on your feedback. Updated plan is in /tmp/plan-${REVIEW_ID}.md.
|
||||
|
||||
Changes made:
|
||||
[List specific changes]
|
||||
|
||||
Re-review using the same \`## Summary\`, \`## Findings\`, and \`## Verdict\` structure as before.
|
||||
Keep findings ordered \`P0\` to \`P3\`, use \`- None.\` when a severity has no findings, and only use \`VERDICT: APPROVED\` when no \`P0\`, \`P1\`, or \`P2\` findings remain. \`P3\` findings are non-blocking." \
|
||||
> /tmp/plan-review-${REVIEW_ID}.json
|
||||
|
||||
jq -r '.[] | select(.type == "message" and .role == "assistant") | .content' \
|
||||
/tmp/plan-review-${REVIEW_ID}.json \
|
||||
> /tmp/plan-review-${REVIEW_ID}.md \
|
||||
|| cp /tmp/plan-review-${REVIEW_ID}.json /tmp/plan-review-${REVIEW_ID}.md
|
||||
```
|
||||
|
||||
If session resume fails (session expired or not supported), fall back to the fresh-call path above.
|
||||
|
||||
After updating `/tmp/plan-review-${REVIEW_ID}.sh`, run the same helper/fallback flow from Round 1.
|
||||
|
||||
Return to Step 4.
|
||||
|
||||
#### Step 7: Present Final Result
|
||||
|
||||
```
|
||||
```markdown
|
||||
## Plan Review — Final (reviewer: ${REVIEWER_CLI} / ${REVIEWER_MODEL})
|
||||
|
||||
**Status:** Approved after N round(s)
|
||||
@@ -483,16 +615,19 @@ If the round failed, produced empty output, or reached operator-decision timeout
|
||||
### Phase 8: Initialize Local Plan Workspace (MANDATORY)
|
||||
|
||||
At project root:
|
||||
|
||||
1. Ensure `ai_plan/` exists. Create it if missing.
|
||||
2. Ensure `.gitignore` contains `/ai_plan/`.
|
||||
3. If `.gitignore` was changed, commit that change immediately (local commit only).
|
||||
|
||||
Recommended commit message:
|
||||
|
||||
- `chore(gitignore): ignore ai_plan local planning artifacts`
|
||||
|
||||
### Phase 9: Generate Plan Files (MANDATORY)
|
||||
|
||||
Create `ai_plan/YYYY-MM-DD-<short-title>/` with ALL files:
|
||||
|
||||
1. `original-plan.md` - copy of original planner-generated plan.
|
||||
2. `final-transcript.md` - copy of final planning transcript used to reach approved plan.
|
||||
3. `milestone-plan.md` - full implementation spec (template-based).
|
||||
@@ -523,6 +658,7 @@ fi
|
||||
```
|
||||
|
||||
Rules:
|
||||
|
||||
- Telegram is the only supported notification path. Do not use desktop notifications, `say`, email, or any other notifier.
|
||||
- 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.
|
||||
@@ -531,12 +667,14 @@ Rules:
|
||||
## Tracker Discipline (MANDATORY)
|
||||
|
||||
Before starting any story:
|
||||
|
||||
1. Open `story-tracker.md`
|
||||
2. Mark story `in-dev`
|
||||
3. Add notes if relevant
|
||||
4. Then begin implementation
|
||||
|
||||
After completing any story:
|
||||
|
||||
1. Mark story `completed`
|
||||
2. Add commit hash in Notes
|
||||
3. Review pending stories
|
||||
@@ -575,4 +713,5 @@ After completing any story:
|
||||
- [ ] Telegram notification attempted if configured
|
||||
|
||||
## Exit Triggers for Question Phase
|
||||
|
||||
User says: "ready", "done", "let's plan", "proceed", "enough questions"
|
||||
|
||||
@@ -58,15 +58,19 @@ Work from this folder (`ai_plan/YYYY-MM-DD-<short-title>/`) and always follow th
|
||||
## Full Context Reproduction
|
||||
|
||||
### Project Overview
|
||||
|
||||
[What this project/feature is about]
|
||||
|
||||
### User Requirements
|
||||
|
||||
[All gathered requirements]
|
||||
|
||||
### Scope
|
||||
|
||||
[In scope / out of scope]
|
||||
|
||||
### Dependencies
|
||||
|
||||
[External dependencies, prerequisites, related systems]
|
||||
|
||||
---
|
||||
@@ -74,16 +78,19 @@ Work from this folder (`ai_plan/YYYY-MM-DD-<short-title>/`) and always follow th
|
||||
## Key Specifications
|
||||
|
||||
### Type Definitions
|
||||
|
||||
```typescript
|
||||
// Copy-paste ready type definitions
|
||||
```
|
||||
|
||||
### Enums & Constants
|
||||
|
||||
```typescript
|
||||
// All enums/constants needed
|
||||
```
|
||||
|
||||
### API Endpoints
|
||||
|
||||
```typescript
|
||||
// Request/response shapes
|
||||
```
|
||||
@@ -101,16 +108,19 @@ Work from this folder (`ai_plan/YYYY-MM-DD-<short-title>/`) and always follow th
|
||||
## Verification Commands
|
||||
|
||||
### Lint (changed files first)
|
||||
|
||||
```bash
|
||||
# example: pnpm eslint <changed-file-1> <changed-file-2>
|
||||
```
|
||||
|
||||
### Typecheck
|
||||
|
||||
```bash
|
||||
# example: pnpm tsc --noEmit
|
||||
```
|
||||
|
||||
### Tests (target changed scope first)
|
||||
|
||||
```bash
|
||||
# example: pnpm test -- <related spec/file>
|
||||
```
|
||||
|
||||
@@ -1,6 +1,7 @@
|
||||
# [Plan Title]
|
||||
|
||||
## Overview
|
||||
|
||||
- **Goal:** [One sentence describing the end state]
|
||||
- **Created:** YYYY-MM-DD
|
||||
- **Status:** In Progress | Complete
|
||||
@@ -8,37 +9,46 @@
|
||||
## Context
|
||||
|
||||
### Requirements
|
||||
|
||||
[Gathered requirements from user questions]
|
||||
|
||||
### Constraints
|
||||
|
||||
[Technical, business, or timeline constraints]
|
||||
|
||||
### Success Criteria
|
||||
|
||||
[How we know this is complete]
|
||||
|
||||
## Architecture
|
||||
|
||||
### Design Decisions
|
||||
|
||||
[Key architectural choices and rationale]
|
||||
|
||||
### Component Relationships
|
||||
|
||||
[How pieces fit together]
|
||||
|
||||
### Data Flow
|
||||
|
||||
[How data moves through the system]
|
||||
|
||||
## Milestones
|
||||
|
||||
### M1: [Name]
|
||||
|
||||
**Description:** [What this milestone achieves]
|
||||
|
||||
**Acceptance Criteria:**
|
||||
|
||||
- [ ] [Criterion 1]
|
||||
- [ ] [Criterion 2]
|
||||
|
||||
**Stories:** S-101, S-102, S-103...
|
||||
|
||||
**Milestone Completion Rule (MANDATORY):**
|
||||
|
||||
- Run lint/typecheck/tests for changed files.
|
||||
- Commit locally (DO NOT push).
|
||||
- Stop and ask user for feedback.
|
||||
@@ -48,15 +58,18 @@
|
||||
---
|
||||
|
||||
### M2: [Name]
|
||||
|
||||
**Description:** [What this milestone achieves]
|
||||
|
||||
**Acceptance Criteria:**
|
||||
|
||||
- [ ] [Criterion 1]
|
||||
- [ ] [Criterion 2]
|
||||
|
||||
**Stories:** S-201, S-202, S-203...
|
||||
|
||||
**Milestone Completion Rule (MANDATORY):**
|
||||
|
||||
- Run lint/typecheck/tests for changed files.
|
||||
- Commit locally (DO NOT push).
|
||||
- Stop and ask user for feedback.
|
||||
@@ -68,16 +81,19 @@
|
||||
## Technical Specifications
|
||||
|
||||
### Types & Interfaces
|
||||
|
||||
```typescript
|
||||
// Key type definitions
|
||||
```
|
||||
|
||||
### API Contracts
|
||||
|
||||
```typescript
|
||||
// Endpoint signatures, request/response shapes
|
||||
```
|
||||
|
||||
### Constants & Enums
|
||||
|
||||
```typescript
|
||||
// Shared constants
|
||||
```
|
||||
@@ -94,6 +110,7 @@
|
||||
## Related Plan Files
|
||||
|
||||
This file is part of the plan folder under `ai_plan/`:
|
||||
|
||||
- `original-plan.md` - Original approved plan (reference for original intent)
|
||||
- `final-transcript.md` - Final planning transcript (reference for rationale/context)
|
||||
- `milestone-plan.md` - This file (full specification)
|
||||
|
||||
@@ -1,6 +1,7 @@
|
||||
# Story Tracker: [Plan Title]
|
||||
|
||||
## Progress Summary
|
||||
|
||||
- **Current Milestone:** M1
|
||||
- **Stories Complete:** 0/N
|
||||
- **Milestones Approved:** 0/M
|
||||
@@ -46,15 +47,18 @@
|
||||
## Update Instructions (MANDATORY)
|
||||
|
||||
Before starting any story:
|
||||
|
||||
1. Mark story as `in-dev`
|
||||
2. Update "Last Updated"
|
||||
|
||||
After completing any story:
|
||||
|
||||
1. Mark story as `completed`
|
||||
2. Add local commit hash to Notes
|
||||
3. Update "Stories Complete" and "Last Updated"
|
||||
|
||||
At milestone boundary:
|
||||
|
||||
1. Run lint/typecheck/tests for changed files
|
||||
2. Commit (no push)
|
||||
3. Request feedback
|
||||
@@ -63,4 +67,5 @@ At milestone boundary:
|
||||
6. Continue only after approval
|
||||
|
||||
After all milestones approved:
|
||||
|
||||
- Ask permission to push and then mark plan completed.
|
||||
|
||||
@@ -65,15 +65,19 @@ Work from this folder (`ai_plan/YYYY-MM-DD-<short-title>/`) and always follow th
|
||||
## Full Context Reproduction
|
||||
|
||||
### Project Overview
|
||||
|
||||
[What this project/feature is about]
|
||||
|
||||
### User Requirements
|
||||
|
||||
[All gathered requirements]
|
||||
|
||||
### Scope
|
||||
|
||||
[In scope / out of scope]
|
||||
|
||||
### Dependencies
|
||||
|
||||
[External dependencies, prerequisites, related systems]
|
||||
|
||||
---
|
||||
@@ -81,16 +85,19 @@ Work from this folder (`ai_plan/YYYY-MM-DD-<short-title>/`) and always follow th
|
||||
## Key Specifications
|
||||
|
||||
### Type Definitions
|
||||
|
||||
```typescript
|
||||
// Copy-paste ready type definitions
|
||||
```
|
||||
|
||||
### Enums & Constants
|
||||
|
||||
```typescript
|
||||
// All enums/constants needed
|
||||
```
|
||||
|
||||
### API Endpoints
|
||||
|
||||
```typescript
|
||||
// Request/response shapes
|
||||
```
|
||||
@@ -108,16 +115,19 @@ Work from this folder (`ai_plan/YYYY-MM-DD-<short-title>/`) and always follow th
|
||||
## Verification Commands
|
||||
|
||||
### Lint (changed files first)
|
||||
|
||||
```bash
|
||||
# example: pnpm eslint <changed-file-1> <changed-file-2>
|
||||
```
|
||||
|
||||
### Typecheck
|
||||
|
||||
```bash
|
||||
# example: pnpm tsc --noEmit
|
||||
```
|
||||
|
||||
### Tests (target changed scope first)
|
||||
|
||||
```bash
|
||||
# example: pnpm test -- <related spec/file>
|
||||
```
|
||||
|
||||
@@ -1,6 +1,7 @@
|
||||
# [Plan Title]
|
||||
|
||||
## Overview
|
||||
|
||||
- **Goal:** [One sentence describing the end state]
|
||||
- **Created:** YYYY-MM-DD
|
||||
- **Status:** In Progress | Complete
|
||||
@@ -8,37 +9,46 @@
|
||||
## Context
|
||||
|
||||
### Requirements
|
||||
|
||||
[Gathered requirements from user questions]
|
||||
|
||||
### Constraints
|
||||
|
||||
[Technical, business, or timeline constraints]
|
||||
|
||||
### Success Criteria
|
||||
|
||||
[How we know this is complete]
|
||||
|
||||
## Architecture
|
||||
|
||||
### Design Decisions
|
||||
|
||||
[Key architectural choices and rationale]
|
||||
|
||||
### Component Relationships
|
||||
|
||||
[How pieces fit together]
|
||||
|
||||
### Data Flow
|
||||
|
||||
[How data moves through the system]
|
||||
|
||||
## Milestones
|
||||
|
||||
### M1: [Name]
|
||||
|
||||
**Description:** [What this milestone achieves]
|
||||
|
||||
**Acceptance Criteria:**
|
||||
|
||||
- [ ] [Criterion 1]
|
||||
- [ ] [Criterion 2]
|
||||
|
||||
**Stories:** S-101, S-102, S-103...
|
||||
|
||||
**Milestone Completion Rule (MANDATORY):**
|
||||
|
||||
- Run lint/typecheck/tests for changed files.
|
||||
- Commit locally (DO NOT push).
|
||||
- Stop and ask user for feedback.
|
||||
@@ -48,15 +58,18 @@
|
||||
---
|
||||
|
||||
### M2: [Name]
|
||||
|
||||
**Description:** [What this milestone achieves]
|
||||
|
||||
**Acceptance Criteria:**
|
||||
|
||||
- [ ] [Criterion 1]
|
||||
- [ ] [Criterion 2]
|
||||
|
||||
**Stories:** S-201, S-202, S-203...
|
||||
|
||||
**Milestone Completion Rule (MANDATORY):**
|
||||
|
||||
- Run lint/typecheck/tests for changed files.
|
||||
- Commit locally (DO NOT push).
|
||||
- Stop and ask user for feedback.
|
||||
@@ -68,16 +81,19 @@
|
||||
## Technical Specifications
|
||||
|
||||
### Types & Interfaces
|
||||
|
||||
```typescript
|
||||
// Key type definitions
|
||||
```
|
||||
|
||||
### API Contracts
|
||||
|
||||
```typescript
|
||||
// Endpoint signatures, request/response shapes
|
||||
```
|
||||
|
||||
### Constants & Enums
|
||||
|
||||
```typescript
|
||||
// Shared constants
|
||||
```
|
||||
@@ -94,6 +110,7 @@
|
||||
## Related Plan Files
|
||||
|
||||
This file is part of the plan folder under `ai_plan/`:
|
||||
|
||||
- `original-plan.md` - Original approved plan (reference for original intent)
|
||||
- `final-transcript.md` - Final planning transcript (reference for rationale/context)
|
||||
- `milestone-plan.md` - This file (full specification)
|
||||
|
||||
@@ -1,6 +1,7 @@
|
||||
# Story Tracker: [Plan Title]
|
||||
|
||||
## Progress Summary
|
||||
|
||||
- **Current Milestone:** M1
|
||||
- **Stories Complete:** 0/N
|
||||
- **Milestones Approved:** 0/M
|
||||
@@ -46,15 +47,18 @@
|
||||
## Update Instructions (MANDATORY)
|
||||
|
||||
Before starting any story:
|
||||
|
||||
1. Mark story as `in-dev`
|
||||
2. Update "Last Updated"
|
||||
|
||||
After completing any story:
|
||||
|
||||
1. Mark story as `completed`
|
||||
2. Add local commit hash to Notes
|
||||
3. Update "Stories Complete" and "Last Updated"
|
||||
|
||||
At milestone boundary:
|
||||
|
||||
1. Run lint/typecheck/tests for changed files
|
||||
2. Commit (no push)
|
||||
3. Request feedback
|
||||
@@ -63,4 +67,5 @@ At milestone boundary:
|
||||
6. Continue only after approval
|
||||
|
||||
After all milestones approved:
|
||||
|
||||
- Ask permission to push and then mark plan completed.
|
||||
|
||||
@@ -12,6 +12,7 @@ This is a single-artifact sibling of `create-plan` + `implement-plan`. Unlike `i
|
||||
## Prerequisite Check (MANDATORY)
|
||||
|
||||
Required:
|
||||
|
||||
- Claude Code CLI: `claude --version`
|
||||
- Superpowers repo: `https://github.com/obra/superpowers`
|
||||
- `superpowers:brainstorming`
|
||||
@@ -31,6 +32,7 @@ This variant depends on explicit sub-skill invocation via the `Skill` tool. Do N
|
||||
## Trigger Phrase Detection
|
||||
|
||||
**Binding triggers** (always invoke this skill):
|
||||
|
||||
- `/do-task`
|
||||
- "do this task"
|
||||
- "do task ..."
|
||||
@@ -38,24 +40,29 @@ This variant depends on explicit sub-skill invocation via the `Skill` tool. Do N
|
||||
- "make it so"
|
||||
|
||||
**Hint trigger** (invoke unless context clearly maps to another skill):
|
||||
|
||||
- "just do ..."
|
||||
|
||||
**Escape phrases** (skip the Phase 2 clarifying-question loop):
|
||||
|
||||
- `--no-questions`
|
||||
- `"just do it:"`
|
||||
- `"just do this:"`
|
||||
- `"no questions:"`
|
||||
|
||||
**Excluded** (do NOT trigger `do-task`):
|
||||
|
||||
- "implement this" — reserved for `implement-plan`.
|
||||
|
||||
**Dropped defaults** (explicitly NOT binding triggers):
|
||||
|
||||
- "work on ..."
|
||||
- "handle this"
|
||||
- "take care of ..."
|
||||
- "get this done"
|
||||
|
||||
**Worktree opt-in phrases** (Phase 4 takes the worktree branch):
|
||||
|
||||
- "in a worktree"
|
||||
- "use a worktree"
|
||||
- "on an isolated branch"
|
||||
@@ -113,7 +120,6 @@ Store `REVIEWER_CLI`, `REVIEWER_MODEL`, and `MAX_ROUNDS` for Phases 5 and 8.
|
||||
|
||||
Reviewer CLI: `codex`, `claude`, `cursor`, `opencode`, `pi`, or `skip`.
|
||||
|
||||
|
||||
If `REVIEWER_CLI=pi`, verify the Pi reviewer binary before entering the review loop:
|
||||
|
||||
```bash
|
||||
@@ -127,11 +133,13 @@ When `REVIEWER_CLI=pi`, the reviewer model is configured independently from the
|
||||
### Phase 4: Initialize Plan Workspace
|
||||
|
||||
**PLAN MODE CHECK:** If currently in plan mode:
|
||||
|
||||
1. Inform user that `task-plan.md` cannot be written while in plan mode.
|
||||
2. Instruct user to exit plan mode (approve plan or use `ExitPlanMode`).
|
||||
3. Proceed with file generation only after exiting plan mode.
|
||||
|
||||
Steps:
|
||||
|
||||
1. Compute slug: `YYYY-MM-DD-<slug>` where `<slug>` is a kebab-case hash of the task goal (lowercase, alphanumeric + hyphens only).
|
||||
2. Compute plan folder: `ai_plan/<slug>/`.
|
||||
3. **Resume detection:** If the folder already exists, read `task-plan.md`:
|
||||
@@ -153,7 +161,7 @@ If `REVIEWER_CLI=skip`, present `task-plan.md` to the user and proceed only afte
|
||||
|
||||
Otherwise, invoke the Review Loop (Shared Subroutine) with:
|
||||
|
||||
```
|
||||
```text
|
||||
REVIEW_KIND = plan
|
||||
REVIEW_ID = $(uuidgen | tr '[:upper:]' '[:lower:]' | head -c 8)
|
||||
PAYLOAD_PATH = /tmp/do-task-plan-${REVIEW_ID}.md
|
||||
@@ -191,11 +199,13 @@ Rules:
|
||||
```
|
||||
|
||||
On APPROVED:
|
||||
|
||||
- Set `Status: plan-approved`.
|
||||
- Append APPROVED row to Review History.
|
||||
- Proceed to Phase 6.
|
||||
|
||||
On MAX_ROUNDS:
|
||||
|
||||
- Set `Status: aborted-plan-review`.
|
||||
- Send Telegram summary before stopping.
|
||||
- Ask the user whether to override and proceed, restart, or abort.
|
||||
@@ -221,16 +231,19 @@ Native orchestration — do not invoke `superpowers:executing-plans`.
|
||||
Invoke `superpowers:verification-before-completion` via the `Skill` tool.
|
||||
|
||||
Run the commands listed in the `Verification` section of `task-plan.md`:
|
||||
|
||||
- Lint (changed files first).
|
||||
- Typecheck.
|
||||
- Tests (targeted first, then broader suite if quick).
|
||||
|
||||
All must pass. If a command fails:
|
||||
|
||||
- Fix the issue.
|
||||
- Re-run that command.
|
||||
- Increment `verification_attempts` in Runtime State.
|
||||
|
||||
If `verification_attempts` exceeds 3 without green:
|
||||
|
||||
- Set `Status: aborted-verification`.
|
||||
- Send Telegram summary.
|
||||
- Ask the user whether to retry, override, or abort.
|
||||
@@ -241,7 +254,7 @@ If `REVIEWER_CLI=skip`, present a diff + verification summary to the user and pr
|
||||
|
||||
Otherwise, invoke the Review Loop (Shared Subroutine) with:
|
||||
|
||||
```
|
||||
```text
|
||||
REVIEW_KIND = implementation
|
||||
REVIEW_ID = $(uuidgen | tr '[:upper:]' '[:lower:]' | head -c 8) # distinct from plan-review ID
|
||||
PAYLOAD_PATH = /tmp/do-task-implementation-${REVIEW_ID}.md
|
||||
@@ -297,11 +310,13 @@ Rules:
|
||||
```
|
||||
|
||||
On APPROVED:
|
||||
|
||||
- Set `Status: implementation-approved`.
|
||||
- Append APPROVED row to Review History.
|
||||
- Proceed to Phase 9.
|
||||
|
||||
On MAX_ROUNDS:
|
||||
|
||||
- Set `Status: aborted-impl-review`.
|
||||
- Send Telegram summary.
|
||||
- Ask the user whether to override and commit anyway, restart, or abort.
|
||||
@@ -336,6 +351,7 @@ fi
|
||||
```
|
||||
|
||||
Rules:
|
||||
|
||||
- Telegram is the only supported notification path.
|
||||
- Notification failures are non-blocking but must be surfaced to the user.
|
||||
- Before stopping for any user interaction, approval, or manual decision, send a Telegram summary first if configured.
|
||||
@@ -426,18 +442,19 @@ If `SCAN_MATCHES` is non-empty:
|
||||
1. **Redact the matched text before surfacing** — never echo the raw secret to the user, chat log, terminal scrollback, or any persistent file. Replace each matched substring with a fixed token that preserves only the fact of a match: `[REDACTED:<pattern-label>:<match-length>-chars]`. Example: a matched AWS key becomes `[REDACTED:aws-access-key:20-chars]`. Keep the file path and line number; they are useful for the user and not secret.
|
||||
2. Present the redacted match summary to the user using this exact wording:
|
||||
|
||||
```
|
||||
```text
|
||||
SECRET-SCAN MATCH in outbound reviewer payload (loop: ${REVIEW_KIND}, round: N):
|
||||
<file>:<line>: [REDACTED:<pattern-label>:<match-length>-chars]
|
||||
...
|
||||
Proceed with sending this payload to ${REVIEWER_CLI}? (yes / no / redact)
|
||||
```
|
||||
|
||||
Pattern labels: `aws-access-key`, `gcp-service-account`, `github-token`, `slack-token`, `openai-key`, `anthropic-key`, `pem-private-key`, `dotenv-style`, `jwt`.
|
||||
|
||||
2. Wait for user response.
|
||||
3. On `yes`: record `last_scan_outcome_${REVIEW_KIND}=user-approved-with-matches` in Runtime State, and proceed.
|
||||
4. On `redact`: ask the user to supply redactions, apply them to `PAYLOAD_PATH`, re-scan (this step), record `last_scan_outcome_${REVIEW_KIND}=redacted-and-approved`.
|
||||
5. On `no`: stop the loop, set `Status: failed`, send Telegram, return to the user.
|
||||
3. Wait for user response.
|
||||
4. On `yes`: record `last_scan_outcome_${REVIEW_KIND}=user-approved-with-matches` in Runtime State, and proceed.
|
||||
5. On `redact`: ask the user to supply redactions, apply them to `PAYLOAD_PATH`, re-scan (this step), record `last_scan_outcome_${REVIEW_KIND}=redacted-and-approved`.
|
||||
6. On `no`: stop the loop, set `Status: failed`, send Telegram, return to the user.
|
||||
|
||||
If `SCAN_MATCHES` is empty, record `last_scan_outcome_${REVIEW_KIND}=clean` and proceed.
|
||||
|
||||
@@ -450,7 +467,6 @@ Write the reviewer invocation to `/tmp/do-task-${REVIEW_KIND}-review-${REVIEW_ID
|
||||
set -euo pipefail
|
||||
```
|
||||
|
||||
|
||||
**If `REVIEWER_CLI` is `pi`:**
|
||||
|
||||
Fresh call every round (Pi reviewer calls do not use session resume):
|
||||
@@ -654,15 +670,19 @@ After the command completes:
|
||||
|
||||
- `cursor`: already promoted in Step 2 via `jq -r '.result' ...`. Also capture `session_id` if first round.
|
||||
- `codex`: extract `CODEX_SESSION_ID` from `/tmp/do-task-${REVIEW_KIND}-review-${REVIEW_ID}.runner.out` after the helper or fallback run. If the review text lives only in `.runner.out`, `cp` it into the `.md` file:
|
||||
|
||||
```bash
|
||||
cp /tmp/do-task-${REVIEW_KIND}-review-${REVIEW_ID}.runner.out \
|
||||
/tmp/do-task-${REVIEW_KIND}-review-${REVIEW_ID}.md
|
||||
```
|
||||
|
||||
- `claude` or `pi`: promote `.runner.out` into the `.md` file:
|
||||
|
||||
```bash
|
||||
cp /tmp/do-task-${REVIEW_KIND}-review-${REVIEW_ID}.runner.out \
|
||||
/tmp/do-task-${REVIEW_KIND}-review-${REVIEW_ID}.md
|
||||
```
|
||||
|
||||
- `opencode`: already promoted in Step 2 via `jq` on the JSON stream. If opt-in session-resume is active and the JSON includes a stable session id, capture it and persist to `${SESSION_ID_VAR}`.
|
||||
|
||||
On Round 1, persist the captured session ID (if any) into `task-plan.md`'s Runtime State under `${SESSION_ID_VAR}`.
|
||||
@@ -720,6 +740,7 @@ If the round failed, produced empty output, or reached operator-decision timeout
|
||||
1. Detect existing plan folder by slug at Phase 4.
|
||||
2. Read `task-plan.md` → `Status`.
|
||||
3. Decide next action:
|
||||
|
||||
| Status | Action |
|
||||
|--------|--------|
|
||||
| `draft` | Resume at Phase 5 (plan review) |
|
||||
@@ -728,6 +749,7 @@ If the round failed, produced empty output, or reached operator-decision timeout
|
||||
| `implementation-approved` | Resume at Phase 9 (commit + push ask) |
|
||||
| `pushed` \| `local-only` | Ask user: new suffix, abort, or replay for reference only |
|
||||
| `aborted-*` \| `failed` | Offer new suffix or full restart |
|
||||
|
||||
4. When resuming, read Runtime State for `CODEX_PLAN_SESSION_ID`, `CODEX_IMPL_SESSION_ID`, `CURSOR_PLAN_SESSION_ID`, `CURSOR_IMPL_SESSION_ID`, `OPENCODE_PLAN_SESSION_ID`, `OPENCODE_IMPL_SESSION_ID`, and the round counters. If a session ID is populated, use it for the first revision round in that loop (Round 2) via `codex exec resume`, `cursor-agent --resume`, or `opencode run -s <id>` as applicable.
|
||||
|
||||
---
|
||||
@@ -737,10 +759,12 @@ If the round failed, produced empty output, or reached operator-decision timeout
|
||||
**ALWAYS update `task-plan.md` before/after each phase transition. NEVER proceed with stale state.**
|
||||
|
||||
Before starting any phase:
|
||||
|
||||
1. Update `Status` if it transitions.
|
||||
2. Update `last_phase_entered` in Runtime State.
|
||||
|
||||
After completing any phase:
|
||||
|
||||
1. Update `Status` if it transitions.
|
||||
2. Append notes to the relevant section of `task-plan.md`.
|
||||
|
||||
|
||||
@@ -132,7 +132,6 @@ tdd_used: false
|
||||
- Notes (anything the user should know when revisiting)
|
||||
-->
|
||||
|
||||
|
||||
---
|
||||
|
||||
## Guardrails (do NOT remove)
|
||||
|
||||
@@ -14,6 +14,7 @@ This is a single-artifact sibling of `create-plan` + `implement-plan`. Unlike `i
|
||||
## Prerequisite Check (MANDATORY)
|
||||
|
||||
Required:
|
||||
|
||||
- Codex CLI: `codex --version`
|
||||
- Superpowers repo: `https://github.com/obra/superpowers`
|
||||
- Superpowers skills symlink: `~/.agents/skills/superpowers -> ~/.codex/superpowers/skills`
|
||||
@@ -53,6 +54,7 @@ If any required dependency is missing, stop immediately and return:
|
||||
## Trigger Phrase Detection
|
||||
|
||||
**Binding triggers** (always invoke this skill):
|
||||
|
||||
- `/do-task`
|
||||
- "do this task"
|
||||
- "do task ..."
|
||||
@@ -60,24 +62,29 @@ If any required dependency is missing, stop immediately and return:
|
||||
- "make it so"
|
||||
|
||||
**Hint trigger** (invoke unless context clearly maps to another skill):
|
||||
|
||||
- "just do ..."
|
||||
|
||||
**Escape phrases** (skip the Phase 2 clarifying-question loop):
|
||||
|
||||
- `--no-questions`
|
||||
- `"just do it:"`
|
||||
- `"just do this:"`
|
||||
- `"no questions:"`
|
||||
|
||||
**Excluded** (do NOT trigger `do-task`):
|
||||
|
||||
- "implement this" — reserved for `implement-plan`.
|
||||
|
||||
**Dropped defaults** (explicitly NOT binding triggers):
|
||||
|
||||
- "work on ..."
|
||||
- "handle this"
|
||||
- "take care of ..."
|
||||
- "get this done"
|
||||
|
||||
**Worktree opt-in phrases** (Phase 4 takes the worktree branch):
|
||||
|
||||
- "in a worktree"
|
||||
- "use a worktree"
|
||||
- "on an isolated branch"
|
||||
@@ -135,7 +142,6 @@ Store `REVIEWER_CLI`, `REVIEWER_MODEL`, and `MAX_ROUNDS` for Phases 5 and 8.
|
||||
|
||||
Reviewer CLI: `codex`, `claude`, `cursor`, `opencode`, `pi`, or `skip`.
|
||||
|
||||
|
||||
If `REVIEWER_CLI=pi`, verify the Pi reviewer binary before entering the review loop:
|
||||
|
||||
```bash
|
||||
@@ -151,6 +157,7 @@ When `REVIEWER_CLI=pi`, the reviewer model is configured independently from the
|
||||
Codex has no plan-mode concept; there is no plan-mode guard here.
|
||||
|
||||
Steps:
|
||||
|
||||
1. Compute slug: `YYYY-MM-DD-<slug>` where `<slug>` is a kebab-case hash of the task goal (lowercase, alphanumeric + hyphens only).
|
||||
2. Compute plan folder: `ai_plan/<slug>/`.
|
||||
3. **Resume detection:** If the folder already exists, read `task-plan.md`:
|
||||
@@ -172,7 +179,7 @@ If `REVIEWER_CLI=skip`, present `task-plan.md` to the user and proceed only afte
|
||||
|
||||
Otherwise, invoke the Review Loop (Shared Subroutine) with:
|
||||
|
||||
```
|
||||
```text
|
||||
REVIEW_KIND = plan
|
||||
REVIEW_ID = $(uuidgen | tr '[:upper:]' '[:lower:]' | head -c 8)
|
||||
PAYLOAD_PATH = /tmp/do-task-plan-${REVIEW_ID}.md
|
||||
@@ -210,11 +217,13 @@ Rules:
|
||||
```
|
||||
|
||||
On APPROVED:
|
||||
|
||||
- Set `Status: plan-approved`.
|
||||
- Append APPROVED row to Review History.
|
||||
- Proceed to Phase 6.
|
||||
|
||||
On MAX_ROUNDS:
|
||||
|
||||
- Set `Status: aborted-plan-review`.
|
||||
- Send Telegram summary before stopping.
|
||||
- Ask the user whether to override and proceed, restart, or abort.
|
||||
@@ -240,16 +249,19 @@ Native orchestration — do not invoke `superpowers:executing-plans`.
|
||||
Invoke `superpowers:verification-before-completion` via native discovery.
|
||||
|
||||
Run the commands listed in the `Verification` section of `task-plan.md`:
|
||||
|
||||
- Lint (changed files first).
|
||||
- Typecheck.
|
||||
- Tests (targeted first, then broader suite if quick).
|
||||
|
||||
All must pass. If a command fails:
|
||||
|
||||
- Fix the issue.
|
||||
- Re-run that command.
|
||||
- Increment `verification_attempts` in Runtime State.
|
||||
|
||||
If `verification_attempts` exceeds 3 without green:
|
||||
|
||||
- Set `Status: aborted-verification`.
|
||||
- Send Telegram summary.
|
||||
- Ask the user whether to retry, override, or abort.
|
||||
@@ -260,7 +272,7 @@ If `REVIEWER_CLI=skip`, present a diff + verification summary to the user and pr
|
||||
|
||||
Otherwise, invoke the Review Loop (Shared Subroutine) with:
|
||||
|
||||
```
|
||||
```text
|
||||
REVIEW_KIND = implementation
|
||||
REVIEW_ID = $(uuidgen | tr '[:upper:]' '[:lower:]' | head -c 8) # distinct from plan-review ID
|
||||
PAYLOAD_PATH = /tmp/do-task-implementation-${REVIEW_ID}.md
|
||||
@@ -316,11 +328,13 @@ Rules:
|
||||
```
|
||||
|
||||
On APPROVED:
|
||||
|
||||
- Set `Status: implementation-approved`.
|
||||
- Append APPROVED row to Review History.
|
||||
- Proceed to Phase 9.
|
||||
|
||||
On MAX_ROUNDS:
|
||||
|
||||
- Set `Status: aborted-impl-review`.
|
||||
- Send Telegram summary.
|
||||
- Ask the user whether to override and commit anyway, restart, or abort.
|
||||
@@ -355,6 +369,7 @@ fi
|
||||
```
|
||||
|
||||
Rules:
|
||||
|
||||
- Telegram is the only supported notification path.
|
||||
- Notification failures are non-blocking but must be surfaced to the user.
|
||||
- Before stopping for any user interaction, approval, or manual decision, send a Telegram summary first if configured.
|
||||
@@ -445,18 +460,19 @@ If `SCAN_MATCHES` is non-empty:
|
||||
1. **Redact the matched text before surfacing** — never echo the raw secret to the user, chat log, terminal scrollback, or any persistent file. Replace each matched substring with a fixed token that preserves only the fact of a match: `[REDACTED:<pattern-label>:<match-length>-chars]`. Example: a matched AWS key becomes `[REDACTED:aws-access-key:20-chars]`. Keep the file path and line number; they are useful for the user and not secret.
|
||||
2. Present the redacted match summary to the user using this exact wording:
|
||||
|
||||
```
|
||||
```text
|
||||
SECRET-SCAN MATCH in outbound reviewer payload (loop: ${REVIEW_KIND}, round: N):
|
||||
<file>:<line>: [REDACTED:<pattern-label>:<match-length>-chars]
|
||||
...
|
||||
Proceed with sending this payload to ${REVIEWER_CLI}? (yes / no / redact)
|
||||
```
|
||||
|
||||
Pattern labels: `aws-access-key`, `gcp-service-account`, `github-token`, `slack-token`, `openai-key`, `anthropic-key`, `pem-private-key`, `dotenv-style`, `jwt`.
|
||||
|
||||
2. Wait for user response.
|
||||
3. On `yes`: record `last_scan_outcome_${REVIEW_KIND}=user-approved-with-matches` in Runtime State, and proceed.
|
||||
4. On `redact`: ask the user to supply redactions, apply them to `PAYLOAD_PATH`, re-scan (this step), record `last_scan_outcome_${REVIEW_KIND}=redacted-and-approved`.
|
||||
5. On `no`: stop the loop, set `Status: failed`, send Telegram, return to the user.
|
||||
3. Wait for user response.
|
||||
4. On `yes`: record `last_scan_outcome_${REVIEW_KIND}=user-approved-with-matches` in Runtime State, and proceed.
|
||||
5. On `redact`: ask the user to supply redactions, apply them to `PAYLOAD_PATH`, re-scan (this step), record `last_scan_outcome_${REVIEW_KIND}=redacted-and-approved`.
|
||||
6. On `no`: stop the loop, set `Status: failed`, send Telegram, return to the user.
|
||||
|
||||
If `SCAN_MATCHES` is empty, record `last_scan_outcome_${REVIEW_KIND}=clean` and proceed.
|
||||
|
||||
@@ -469,7 +485,6 @@ Write the reviewer invocation to `/tmp/do-task-${REVIEW_KIND}-review-${REVIEW_ID
|
||||
set -euo pipefail
|
||||
```
|
||||
|
||||
|
||||
**If `REVIEWER_CLI` is `pi`:**
|
||||
|
||||
Fresh call every round (Pi reviewer calls do not use session resume):
|
||||
@@ -673,15 +688,19 @@ After the command completes:
|
||||
|
||||
- `cursor`: already promoted in Step 2 via `jq -r '.result' ...`. Also capture `session_id` if first round.
|
||||
- `codex`: extract `CODEX_SESSION_ID` from `/tmp/do-task-${REVIEW_KIND}-review-${REVIEW_ID}.runner.out` after the helper or fallback run. If the review text lives only in `.runner.out`, `cp` it into the `.md` file:
|
||||
|
||||
```bash
|
||||
cp /tmp/do-task-${REVIEW_KIND}-review-${REVIEW_ID}.runner.out \
|
||||
/tmp/do-task-${REVIEW_KIND}-review-${REVIEW_ID}.md
|
||||
```
|
||||
|
||||
- `claude` or `pi`: promote `.runner.out` into the `.md` file:
|
||||
|
||||
```bash
|
||||
cp /tmp/do-task-${REVIEW_KIND}-review-${REVIEW_ID}.runner.out \
|
||||
/tmp/do-task-${REVIEW_KIND}-review-${REVIEW_ID}.md
|
||||
```
|
||||
|
||||
- `opencode`: already promoted in Step 2 via `jq` on the JSON stream. If opt-in session-resume is active and the JSON includes a stable session id, capture it and persist to `${SESSION_ID_VAR}`.
|
||||
|
||||
On Round 1, persist the captured session ID (if any) into `task-plan.md`'s Runtime State under `${SESSION_ID_VAR}`.
|
||||
@@ -739,6 +758,7 @@ If the round failed, produced empty output, or reached operator-decision timeout
|
||||
1. Detect existing plan folder by slug at Phase 4.
|
||||
2. Read `task-plan.md` → `Status`.
|
||||
3. Decide next action:
|
||||
|
||||
| Status | Action |
|
||||
|--------|--------|
|
||||
| `draft` | Resume at Phase 5 (plan review) |
|
||||
@@ -747,6 +767,7 @@ If the round failed, produced empty output, or reached operator-decision timeout
|
||||
| `implementation-approved` | Resume at Phase 9 (commit + push ask) |
|
||||
| `pushed` \| `local-only` | Ask user: new suffix, abort, or replay for reference only |
|
||||
| `aborted-*` \| `failed` | Offer new suffix or full restart |
|
||||
|
||||
4. When resuming, read Runtime State for `CODEX_PLAN_SESSION_ID`, `CODEX_IMPL_SESSION_ID`, `CURSOR_PLAN_SESSION_ID`, `CURSOR_IMPL_SESSION_ID`, `OPENCODE_PLAN_SESSION_ID`, `OPENCODE_IMPL_SESSION_ID`, and the round counters. If a session ID is populated, use it for the first revision round in that loop (Round 2) via `codex exec resume`, `cursor-agent --resume`, or `opencode run -s <id>` as applicable.
|
||||
|
||||
---
|
||||
@@ -756,10 +777,12 @@ If the round failed, produced empty output, or reached operator-decision timeout
|
||||
**ALWAYS update `task-plan.md` before/after each phase transition. NEVER proceed with stale state.**
|
||||
|
||||
Before starting any phase:
|
||||
|
||||
1. Update `Status` if it transitions.
|
||||
2. Update `last_phase_entered` in Runtime State.
|
||||
|
||||
After completing any phase:
|
||||
|
||||
1. Update `Status` if it transitions.
|
||||
2. Append notes to the relevant section of `task-plan.md`.
|
||||
|
||||
|
||||
@@ -132,7 +132,6 @@ tdd_used: false
|
||||
- Notes (anything the user should know when revisiting)
|
||||
-->
|
||||
|
||||
|
||||
---
|
||||
|
||||
## Guardrails (do NOT remove)
|
||||
|
||||
@@ -14,6 +14,7 @@ This is a single-artifact sibling of `create-plan` + `implement-plan`. Unlike `i
|
||||
## Prerequisite Check (MANDATORY)
|
||||
|
||||
Required:
|
||||
|
||||
- Cursor Agent CLI: `cursor-agent --version` (install via `curl https://cursor.com/install -fsS | bash`). Binary is `cursor-agent`; the alias `cursor agent` also works.
|
||||
- `jq` (**required** — `do-task` always parses JSON output from at least the cursor reviewer branch, and other reviewers may produce JSON). Install via `brew install jq` (macOS) or your package manager. Verify: `jq --version`.
|
||||
- Superpowers repo: `https://github.com/obra/superpowers`
|
||||
@@ -52,6 +53,7 @@ If any required dependency is missing, stop immediately and return:
|
||||
## Trigger Phrase Detection
|
||||
|
||||
**Binding triggers** (always invoke this skill):
|
||||
|
||||
- `/do-task`
|
||||
- "do this task"
|
||||
- "do task ..."
|
||||
@@ -59,24 +61,29 @@ If any required dependency is missing, stop immediately and return:
|
||||
- "make it so"
|
||||
|
||||
**Hint trigger** (invoke unless context clearly maps to another skill):
|
||||
|
||||
- "just do ..."
|
||||
|
||||
**Escape phrases** (skip the Phase 2 clarifying-question loop):
|
||||
|
||||
- `--no-questions`
|
||||
- `"just do it:"`
|
||||
- `"just do this:"`
|
||||
- `"no questions:"`
|
||||
|
||||
**Excluded** (do NOT trigger `do-task`):
|
||||
|
||||
- "implement this" — reserved for `implement-plan`.
|
||||
|
||||
**Dropped defaults** (explicitly NOT binding triggers):
|
||||
|
||||
- "work on ..."
|
||||
- "handle this"
|
||||
- "take care of ..."
|
||||
- "get this done"
|
||||
|
||||
**Worktree opt-in phrases** (Phase 4 takes the worktree branch):
|
||||
|
||||
- "in a worktree"
|
||||
- "use a worktree"
|
||||
- "on an isolated branch"
|
||||
@@ -134,7 +141,6 @@ Store `REVIEWER_CLI`, `REVIEWER_MODEL`, and `MAX_ROUNDS` for Phases 5 and 8.
|
||||
|
||||
Reviewer CLI: `codex`, `claude`, `cursor`, `opencode`, `pi`, or `skip`.
|
||||
|
||||
|
||||
If `REVIEWER_CLI=pi`, verify the Pi reviewer binary before entering the review loop:
|
||||
|
||||
```bash
|
||||
@@ -150,6 +156,7 @@ When `REVIEWER_CLI=pi`, the reviewer model is configured independently from the
|
||||
Cursor Agent CLI has no plan-mode concept; there is no plan-mode guard here.
|
||||
|
||||
Steps:
|
||||
|
||||
1. Compute slug: `YYYY-MM-DD-<slug>` where `<slug>` is a kebab-case hash of the task goal (lowercase, alphanumeric + hyphens only).
|
||||
2. Compute plan folder: `ai_plan/<slug>/`.
|
||||
3. **Resume detection:** If the folder already exists, read `task-plan.md`:
|
||||
@@ -171,7 +178,7 @@ If `REVIEWER_CLI=skip`, present `task-plan.md` to the user and proceed only afte
|
||||
|
||||
Otherwise, invoke the Review Loop (Shared Subroutine) with:
|
||||
|
||||
```
|
||||
```text
|
||||
REVIEW_KIND = plan
|
||||
REVIEW_ID = $(uuidgen | tr '[:upper:]' '[:lower:]' | head -c 8)
|
||||
PAYLOAD_PATH = /tmp/do-task-plan-${REVIEW_ID}.md
|
||||
@@ -209,11 +216,13 @@ Rules:
|
||||
```
|
||||
|
||||
On APPROVED:
|
||||
|
||||
- Set `Status: plan-approved`.
|
||||
- Append APPROVED row to Review History.
|
||||
- Proceed to Phase 6.
|
||||
|
||||
On MAX_ROUNDS:
|
||||
|
||||
- Set `Status: aborted-plan-review`.
|
||||
- Send Telegram summary before stopping.
|
||||
- Ask the user whether to override and proceed, restart, or abort.
|
||||
@@ -239,16 +248,19 @@ Native orchestration — do not invoke `superpowers:executing-plans`.
|
||||
Invoke `superpowers:verification-before-completion` via Cursor-native discovery.
|
||||
|
||||
Run the commands listed in the `Verification` section of `task-plan.md`:
|
||||
|
||||
- Lint (changed files first).
|
||||
- Typecheck.
|
||||
- Tests (targeted first, then broader suite if quick).
|
||||
|
||||
All must pass. If a command fails:
|
||||
|
||||
- Fix the issue.
|
||||
- Re-run that command.
|
||||
- Increment `verification_attempts` in Runtime State.
|
||||
|
||||
If `verification_attempts` exceeds 3 without green:
|
||||
|
||||
- Set `Status: aborted-verification`.
|
||||
- Send Telegram summary.
|
||||
- Ask the user whether to retry, override, or abort.
|
||||
@@ -259,7 +271,7 @@ If `REVIEWER_CLI=skip`, present a diff + verification summary to the user and pr
|
||||
|
||||
Otherwise, invoke the Review Loop (Shared Subroutine) with:
|
||||
|
||||
```
|
||||
```text
|
||||
REVIEW_KIND = implementation
|
||||
REVIEW_ID = $(uuidgen | tr '[:upper:]' '[:lower:]' | head -c 8) # distinct from plan-review ID
|
||||
PAYLOAD_PATH = /tmp/do-task-implementation-${REVIEW_ID}.md
|
||||
@@ -315,11 +327,13 @@ Rules:
|
||||
```
|
||||
|
||||
On APPROVED:
|
||||
|
||||
- Set `Status: implementation-approved`.
|
||||
- Append APPROVED row to Review History.
|
||||
- Proceed to Phase 9.
|
||||
|
||||
On MAX_ROUNDS:
|
||||
|
||||
- Set `Status: aborted-impl-review`.
|
||||
- Send Telegram summary.
|
||||
- Ask the user whether to override and commit anyway, restart, or abort.
|
||||
@@ -358,6 +372,7 @@ fi
|
||||
```
|
||||
|
||||
Rules:
|
||||
|
||||
- Telegram is the only supported notification path.
|
||||
- Notification failures are non-blocking but must be surfaced to the user.
|
||||
- Before stopping for any user interaction, approval, or manual decision, send a Telegram summary first if configured.
|
||||
@@ -452,18 +467,19 @@ If `SCAN_MATCHES` is non-empty:
|
||||
1. **Redact the matched text before surfacing** — never echo the raw secret to the user, chat log, terminal scrollback, or any persistent file. Replace each matched substring with a fixed token that preserves only the fact of a match: `[REDACTED:<pattern-label>:<match-length>-chars]`. Example: a matched AWS key becomes `[REDACTED:aws-access-key:20-chars]`. Keep the file path and line number; they are useful for the user and not secret.
|
||||
2. Present the redacted match summary to the user using this exact wording:
|
||||
|
||||
```
|
||||
```text
|
||||
SECRET-SCAN MATCH in outbound reviewer payload (loop: ${REVIEW_KIND}, round: N):
|
||||
<file>:<line>: [REDACTED:<pattern-label>:<match-length>-chars]
|
||||
...
|
||||
Proceed with sending this payload to ${REVIEWER_CLI}? (yes / no / redact)
|
||||
```
|
||||
|
||||
Pattern labels: `aws-access-key`, `gcp-service-account`, `github-token`, `slack-token`, `openai-key`, `anthropic-key`, `pem-private-key`, `dotenv-style`, `jwt`.
|
||||
|
||||
2. Wait for user response.
|
||||
3. On `yes`: record `last_scan_outcome_${REVIEW_KIND}=user-approved-with-matches` in Runtime State, and proceed.
|
||||
4. On `redact`: ask the user to supply redactions, apply them to `PAYLOAD_PATH`, re-scan (this step), record `last_scan_outcome_${REVIEW_KIND}=redacted-and-approved`.
|
||||
5. On `no`: stop the loop, set `Status: failed`, send Telegram, return to the user.
|
||||
3. Wait for user response.
|
||||
4. On `yes`: record `last_scan_outcome_${REVIEW_KIND}=user-approved-with-matches` in Runtime State, and proceed.
|
||||
5. On `redact`: ask the user to supply redactions, apply them to `PAYLOAD_PATH`, re-scan (this step), record `last_scan_outcome_${REVIEW_KIND}=redacted-and-approved`.
|
||||
6. On `no`: stop the loop, set `Status: failed`, send Telegram, return to the user.
|
||||
|
||||
If `SCAN_MATCHES` is empty, record `last_scan_outcome_${REVIEW_KIND}=clean` and proceed.
|
||||
|
||||
@@ -476,7 +492,6 @@ Write the reviewer invocation to `/tmp/do-task-${REVIEW_KIND}-review-${REVIEW_ID
|
||||
set -euo pipefail
|
||||
```
|
||||
|
||||
|
||||
**If `REVIEWER_CLI` is `pi`:**
|
||||
|
||||
Fresh call every round (Pi reviewer calls do not use session resume):
|
||||
@@ -680,15 +695,19 @@ After the command completes:
|
||||
|
||||
- `cursor`: already promoted in Step 2 via `jq -r '.result' ...`. Also capture `session_id` if first round.
|
||||
- `codex`: extract `CODEX_SESSION_ID` from `/tmp/do-task-${REVIEW_KIND}-review-${REVIEW_ID}.runner.out` after the helper or fallback run. If the review text lives only in `.runner.out`, `cp` it into the `.md` file:
|
||||
|
||||
```bash
|
||||
cp /tmp/do-task-${REVIEW_KIND}-review-${REVIEW_ID}.runner.out \
|
||||
/tmp/do-task-${REVIEW_KIND}-review-${REVIEW_ID}.md
|
||||
```
|
||||
|
||||
- `claude` or `pi`: promote `.runner.out` into the `.md` file:
|
||||
|
||||
```bash
|
||||
cp /tmp/do-task-${REVIEW_KIND}-review-${REVIEW_ID}.runner.out \
|
||||
/tmp/do-task-${REVIEW_KIND}-review-${REVIEW_ID}.md
|
||||
```
|
||||
|
||||
- `opencode`: already promoted in Step 2 via `jq` on the JSON stream. If opt-in session-resume is active and the JSON includes a stable session id, capture it and persist to `${SESSION_ID_VAR}`.
|
||||
|
||||
On Round 1, persist the captured session ID (if any) into `task-plan.md`'s Runtime State under `${SESSION_ID_VAR}`.
|
||||
@@ -746,6 +765,7 @@ If the round failed, produced empty output, or reached operator-decision timeout
|
||||
1. Detect existing plan folder by slug at Phase 4.
|
||||
2. Read `task-plan.md` → `Status`.
|
||||
3. Decide next action:
|
||||
|
||||
| Status | Action |
|
||||
|--------|--------|
|
||||
| `draft` | Resume at Phase 5 (plan review) |
|
||||
@@ -754,6 +774,7 @@ If the round failed, produced empty output, or reached operator-decision timeout
|
||||
| `implementation-approved` | Resume at Phase 9 (commit + push ask) |
|
||||
| `pushed` \| `local-only` | Ask user: new suffix, abort, or replay for reference only |
|
||||
| `aborted-*` \| `failed` | Offer new suffix or full restart |
|
||||
|
||||
4. When resuming, read Runtime State for `CODEX_PLAN_SESSION_ID`, `CODEX_IMPL_SESSION_ID`, `CURSOR_PLAN_SESSION_ID`, `CURSOR_IMPL_SESSION_ID`, `OPENCODE_PLAN_SESSION_ID`, `OPENCODE_IMPL_SESSION_ID`, and the round counters. If a session ID is populated, use it for the first revision round in that loop (Round 2) via `codex exec resume`, `cursor-agent --resume`, or `opencode run -s <id>` as applicable.
|
||||
|
||||
---
|
||||
@@ -763,10 +784,12 @@ If the round failed, produced empty output, or reached operator-decision timeout
|
||||
**ALWAYS update `task-plan.md` before/after each phase transition. NEVER proceed with stale state.**
|
||||
|
||||
Before starting any phase:
|
||||
|
||||
1. Update `Status` if it transitions.
|
||||
2. Update `last_phase_entered` in Runtime State.
|
||||
|
||||
After completing any phase:
|
||||
|
||||
1. Update `Status` if it transitions.
|
||||
2. Append notes to the relevant section of `task-plan.md`.
|
||||
|
||||
|
||||
@@ -132,7 +132,6 @@ tdd_used: false
|
||||
- Notes (anything the user should know when revisiting)
|
||||
-->
|
||||
|
||||
|
||||
---
|
||||
|
||||
## Guardrails (do NOT remove)
|
||||
|
||||
@@ -14,6 +14,7 @@ This is a single-artifact sibling of `create-plan` + `implement-plan`. Unlike `i
|
||||
## Prerequisite Check (MANDATORY)
|
||||
|
||||
Required:
|
||||
|
||||
- OpenCode CLI: `opencode --version` (install via your package manager or `brew install opencode`).
|
||||
- Superpowers repo: `https://github.com/obra/superpowers`
|
||||
- OpenCode Superpowers skills available at `~/.agents/skills/superpowers` or `~/.config/opencode/skills/superpowers`
|
||||
@@ -50,6 +51,7 @@ If any required dependency is missing, stop immediately and return:
|
||||
## Trigger Phrase Detection
|
||||
|
||||
**Binding triggers** (always invoke this skill):
|
||||
|
||||
- `/do-task`
|
||||
- "do this task"
|
||||
- "do task ..."
|
||||
@@ -57,24 +59,29 @@ If any required dependency is missing, stop immediately and return:
|
||||
- "make it so"
|
||||
|
||||
**Hint trigger** (invoke unless context clearly maps to another skill):
|
||||
|
||||
- "just do ..."
|
||||
|
||||
**Escape phrases** (skip the Phase 2 clarifying-question loop):
|
||||
|
||||
- `--no-questions`
|
||||
- `"just do it:"`
|
||||
- `"just do this:"`
|
||||
- `"no questions:"`
|
||||
|
||||
**Excluded** (do NOT trigger `do-task`):
|
||||
|
||||
- "implement this" — reserved for `implement-plan`.
|
||||
|
||||
**Dropped defaults** (explicitly NOT binding triggers):
|
||||
|
||||
- "work on ..."
|
||||
- "handle this"
|
||||
- "take care of ..."
|
||||
- "get this done"
|
||||
|
||||
**Worktree opt-in phrases** (Phase 4 takes the worktree branch):
|
||||
|
||||
- "in a worktree"
|
||||
- "use a worktree"
|
||||
- "on an isolated branch"
|
||||
@@ -133,7 +140,6 @@ Store `REVIEWER_CLI`, `REVIEWER_MODEL`, and `MAX_ROUNDS` for Phases 5 and 8.
|
||||
|
||||
Reviewer CLI: `codex`, `claude`, `cursor`, `opencode`, `pi`, or `skip`.
|
||||
|
||||
|
||||
If `REVIEWER_CLI=pi`, verify the Pi reviewer binary before entering the review loop:
|
||||
|
||||
```bash
|
||||
@@ -149,6 +155,7 @@ When `REVIEWER_CLI=pi`, the reviewer model is configured independently from the
|
||||
OpenCode has no plan-mode concept; there is no plan-mode guard here.
|
||||
|
||||
Steps:
|
||||
|
||||
1. Compute slug: `YYYY-MM-DD-<slug>` where `<slug>` is a kebab-case hash of the task goal (lowercase, alphanumeric + hyphens only).
|
||||
2. Compute plan folder: `ai_plan/<slug>/`.
|
||||
3. **Resume detection:** If the folder already exists, read `task-plan.md`:
|
||||
@@ -170,7 +177,7 @@ If `REVIEWER_CLI=skip`, present `task-plan.md` to the user and proceed only afte
|
||||
|
||||
Otherwise, invoke the Review Loop (Shared Subroutine) with:
|
||||
|
||||
```
|
||||
```text
|
||||
REVIEW_KIND = plan
|
||||
REVIEW_ID = $(uuidgen | tr '[:upper:]' '[:lower:]' | head -c 8)
|
||||
PAYLOAD_PATH = /tmp/do-task-plan-${REVIEW_ID}.md
|
||||
@@ -208,11 +215,13 @@ Rules:
|
||||
```
|
||||
|
||||
On APPROVED:
|
||||
|
||||
- Set `Status: plan-approved`.
|
||||
- Append APPROVED row to Review History.
|
||||
- Proceed to Phase 6.
|
||||
|
||||
On MAX_ROUNDS:
|
||||
|
||||
- Set `Status: aborted-plan-review`.
|
||||
- Send Telegram summary before stopping.
|
||||
- Ask the user whether to override and proceed, restart, or abort.
|
||||
@@ -238,16 +247,19 @@ Native orchestration — do not invoke `superpowers:executing-plans`.
|
||||
Invoke `superpowers/verification-before-completion` via OpenCode's native skill tool.
|
||||
|
||||
Run the commands listed in the `Verification` section of `task-plan.md`:
|
||||
|
||||
- Lint (changed files first).
|
||||
- Typecheck.
|
||||
- Tests (targeted first, then broader suite if quick).
|
||||
|
||||
All must pass. If a command fails:
|
||||
|
||||
- Fix the issue.
|
||||
- Re-run that command.
|
||||
- Increment `verification_attempts` in Runtime State.
|
||||
|
||||
If `verification_attempts` exceeds 3 without green:
|
||||
|
||||
- Set `Status: aborted-verification`.
|
||||
- Send Telegram summary.
|
||||
- Ask the user whether to retry, override, or abort.
|
||||
@@ -258,7 +270,7 @@ If `REVIEWER_CLI=skip`, present a diff + verification summary to the user and pr
|
||||
|
||||
Otherwise, invoke the Review Loop (Shared Subroutine) with:
|
||||
|
||||
```
|
||||
```text
|
||||
REVIEW_KIND = implementation
|
||||
REVIEW_ID = $(uuidgen | tr '[:upper:]' '[:lower:]' | head -c 8) # distinct from plan-review ID
|
||||
PAYLOAD_PATH = /tmp/do-task-implementation-${REVIEW_ID}.md
|
||||
@@ -314,11 +326,13 @@ Rules:
|
||||
```
|
||||
|
||||
On APPROVED:
|
||||
|
||||
- Set `Status: implementation-approved`.
|
||||
- Append APPROVED row to Review History.
|
||||
- Proceed to Phase 9.
|
||||
|
||||
On MAX_ROUNDS:
|
||||
|
||||
- Set `Status: aborted-impl-review`.
|
||||
- Send Telegram summary.
|
||||
- Ask the user whether to override and commit anyway, restart, or abort.
|
||||
@@ -353,6 +367,7 @@ fi
|
||||
```
|
||||
|
||||
Rules:
|
||||
|
||||
- Telegram is the only supported notification path.
|
||||
- Notification failures are non-blocking but must be surfaced to the user.
|
||||
- Before stopping for any user interaction, approval, or manual decision, send a Telegram summary first if configured.
|
||||
@@ -443,18 +458,19 @@ If `SCAN_MATCHES` is non-empty:
|
||||
1. **Redact the matched text before surfacing** — never echo the raw secret to the user, chat log, terminal scrollback, or any persistent file. Replace each matched substring with a fixed token that preserves only the fact of a match: `[REDACTED:<pattern-label>:<match-length>-chars]`. Example: a matched AWS key becomes `[REDACTED:aws-access-key:20-chars]`. Keep the file path and line number; they are useful for the user and not secret.
|
||||
2. Present the redacted match summary to the user using this exact wording:
|
||||
|
||||
```
|
||||
```text
|
||||
SECRET-SCAN MATCH in outbound reviewer payload (loop: ${REVIEW_KIND}, round: N):
|
||||
<file>:<line>: [REDACTED:<pattern-label>:<match-length>-chars]
|
||||
...
|
||||
Proceed with sending this payload to ${REVIEWER_CLI}? (yes / no / redact)
|
||||
```
|
||||
|
||||
Pattern labels: `aws-access-key`, `gcp-service-account`, `github-token`, `slack-token`, `openai-key`, `anthropic-key`, `pem-private-key`, `dotenv-style`, `jwt`.
|
||||
|
||||
2. Wait for user response.
|
||||
3. On `yes`: record `last_scan_outcome_${REVIEW_KIND}=user-approved-with-matches` in Runtime State, and proceed.
|
||||
4. On `redact`: ask the user to supply redactions, apply them to `PAYLOAD_PATH`, re-scan (this step), record `last_scan_outcome_${REVIEW_KIND}=redacted-and-approved`.
|
||||
5. On `no`: stop the loop, set `Status: failed`, send Telegram, return to the user.
|
||||
3. Wait for user response.
|
||||
4. On `yes`: record `last_scan_outcome_${REVIEW_KIND}=user-approved-with-matches` in Runtime State, and proceed.
|
||||
5. On `redact`: ask the user to supply redactions, apply them to `PAYLOAD_PATH`, re-scan (this step), record `last_scan_outcome_${REVIEW_KIND}=redacted-and-approved`.
|
||||
6. On `no`: stop the loop, set `Status: failed`, send Telegram, return to the user.
|
||||
|
||||
If `SCAN_MATCHES` is empty, record `last_scan_outcome_${REVIEW_KIND}=clean` and proceed.
|
||||
|
||||
@@ -467,7 +483,6 @@ Write the reviewer invocation to `/tmp/do-task-${REVIEW_KIND}-review-${REVIEW_ID
|
||||
set -euo pipefail
|
||||
```
|
||||
|
||||
|
||||
**If `REVIEWER_CLI` is `pi`:**
|
||||
|
||||
Fresh call every round (Pi reviewer calls do not use session resume):
|
||||
@@ -671,15 +686,19 @@ After the command completes:
|
||||
|
||||
- `cursor`: already promoted in Step 2 via `jq -r '.result' ...`. Also capture `session_id` if first round.
|
||||
- `codex`: extract `CODEX_SESSION_ID` from `/tmp/do-task-${REVIEW_KIND}-review-${REVIEW_ID}.runner.out` after the helper or fallback run. If the review text lives only in `.runner.out`, `cp` it into the `.md` file:
|
||||
|
||||
```bash
|
||||
cp /tmp/do-task-${REVIEW_KIND}-review-${REVIEW_ID}.runner.out \
|
||||
/tmp/do-task-${REVIEW_KIND}-review-${REVIEW_ID}.md
|
||||
```
|
||||
|
||||
- `claude` or `pi`: promote `.runner.out` into the `.md` file:
|
||||
|
||||
```bash
|
||||
cp /tmp/do-task-${REVIEW_KIND}-review-${REVIEW_ID}.runner.out \
|
||||
/tmp/do-task-${REVIEW_KIND}-review-${REVIEW_ID}.md
|
||||
```
|
||||
|
||||
- `opencode`: already promoted in Step 2 via `jq` on the JSON stream. If opt-in session-resume is active and the JSON includes a stable session id, capture it and persist to `${SESSION_ID_VAR}`.
|
||||
|
||||
On Round 1, persist the captured session ID (if any) into `task-plan.md`'s Runtime State under `${SESSION_ID_VAR}`.
|
||||
@@ -737,6 +756,7 @@ If the round failed, produced empty output, or reached operator-decision timeout
|
||||
1. Detect existing plan folder by slug at Phase 4.
|
||||
2. Read `task-plan.md` → `Status`.
|
||||
3. Decide next action:
|
||||
|
||||
| Status | Action |
|
||||
|--------|--------|
|
||||
| `draft` | Resume at Phase 5 (plan review) |
|
||||
@@ -745,6 +765,7 @@ If the round failed, produced empty output, or reached operator-decision timeout
|
||||
| `implementation-approved` | Resume at Phase 9 (commit + push ask) |
|
||||
| `pushed` \| `local-only` | Ask user: new suffix, abort, or replay for reference only |
|
||||
| `aborted-*` \| `failed` | Offer new suffix or full restart |
|
||||
|
||||
4. When resuming, read Runtime State for `CODEX_PLAN_SESSION_ID`, `CODEX_IMPL_SESSION_ID`, `CURSOR_PLAN_SESSION_ID`, `CURSOR_IMPL_SESSION_ID`, `OPENCODE_PLAN_SESSION_ID`, `OPENCODE_IMPL_SESSION_ID`, and the round counters. If a session ID is populated, use it for the first revision round in that loop (Round 2) via `codex exec resume`, `cursor-agent --resume`, or `opencode run -s <id>` as applicable.
|
||||
|
||||
---
|
||||
@@ -754,10 +775,12 @@ If the round failed, produced empty output, or reached operator-decision timeout
|
||||
**ALWAYS update `task-plan.md` before/after each phase transition. NEVER proceed with stale state.**
|
||||
|
||||
Before starting any phase:
|
||||
|
||||
1. Update `Status` if it transitions.
|
||||
2. Update `last_phase_entered` in Runtime State.
|
||||
|
||||
After completing any phase:
|
||||
|
||||
1. Update `Status` if it transitions.
|
||||
2. Append notes to the relevant section of `task-plan.md`.
|
||||
|
||||
|
||||
@@ -132,7 +132,6 @@ tdd_used: false
|
||||
- Notes (anything the user should know when revisiting)
|
||||
-->
|
||||
|
||||
|
||||
---
|
||||
|
||||
## Guardrails (do NOT remove)
|
||||
|
||||
@@ -10,6 +10,7 @@ Execute an existing plan (created by `create-plan`) in an isolated git worktree,
|
||||
## Prerequisite Check (MANDATORY)
|
||||
|
||||
Required:
|
||||
|
||||
- Plan folder exists under `ai_plan/` at project root
|
||||
- `continuation-runbook.md` exists in plan folder
|
||||
- `milestone-plan.md` exists in plan folder
|
||||
@@ -63,7 +64,6 @@ Store `REVIEWER_CLI`, `REVIEWER_MODEL`, and `MAX_ROUNDS`. These values are fixed
|
||||
|
||||
Reviewer CLI: `codex`, `claude`, `cursor`, `opencode`, `pi`, or `skip`.
|
||||
|
||||
|
||||
If `REVIEWER_CLI=pi`, verify the Pi reviewer binary before entering the review loop:
|
||||
|
||||
```bash
|
||||
@@ -101,6 +101,7 @@ Mark first story `in-dev` in `story-tracker.md`.
|
||||
#### Step 3: Implement Stories
|
||||
|
||||
Execute each story in order. After completing each story:
|
||||
|
||||
1. Mark `in-dev` -> `completed` in `story-tracker.md`
|
||||
2. Update counts
|
||||
3. Mark next story `in-dev`
|
||||
@@ -135,6 +136,7 @@ git commit -m "feat(<scope>): implement milestone M<N> - <description>"
|
||||
```
|
||||
|
||||
Do NOT push. After committing:
|
||||
|
||||
1. Backfill the commit hash into the Notes column for all stories in this milestone in `story-tracker.md`.
|
||||
2. Mark milestone as `approved` in `story-tracker.md`.
|
||||
3. Move to next milestone.
|
||||
@@ -150,6 +152,7 @@ REVIEW_ID=$(uuidgen | tr '[:upper:]' '[:lower:]' | head -c 8)
|
||||
```
|
||||
|
||||
Use `REVIEW_ID` for all milestone review temp file paths:
|
||||
|
||||
- `/tmp/milestone-${REVIEW_ID}.md`
|
||||
- `/tmp/milestone-review-${REVIEW_ID}.md`
|
||||
- `/tmp/milestone-review-${REVIEW_ID}.json`
|
||||
@@ -226,6 +229,7 @@ VERDICT: APPROVED
|
||||
```
|
||||
|
||||
Rules:
|
||||
|
||||
- Order findings from `P0` to `P3`.
|
||||
- `P0` = total blocker, `P1` = major risk, `P2` = must-fix before approval, `P3` = cosmetic / nice to have.
|
||||
- Use `- None.` when a severity has no findings.
|
||||
@@ -248,7 +252,6 @@ Write the reviewer invocation to `/tmp/milestone-review-${REVIEW_ID}.sh` as a ba
|
||||
set -euo pipefail
|
||||
```
|
||||
|
||||
|
||||
**If `REVIEWER_CLI` is `pi`:**
|
||||
|
||||
Fresh call every round (Pi reviewer calls do not use session resume):
|
||||
@@ -389,6 +392,7 @@ fi
|
||||
Run the helper in the foreground and watch its live stdout for `state=in-progress` heartbeats. If your agent environment buffers command output until exit, start the helper in the background and poll `/tmp/milestone-review-${REVIEW_ID}.status` separately instead of treating heartbeats as post-hoc-only data.
|
||||
|
||||
After the command completes:
|
||||
|
||||
- If `REVIEWER_CLI=cursor`, extract the final review text:
|
||||
|
||||
```bash
|
||||
@@ -414,14 +418,14 @@ Fallback is allowed only when the helper is missing or not executable.
|
||||
- `/tmp/milestone-review-${REVIEW_ID}.runner.out`
|
||||
3. Present review to the user:
|
||||
|
||||
```
|
||||
```markdown
|
||||
## Milestone Review — Round N (reviewer: ${REVIEWER_CLI} / ${REVIEWER_MODEL})
|
||||
|
||||
[Reviewer feedback]
|
||||
```
|
||||
|
||||
4. While the reviewer is still running, keep waiting as long as fresh `state=in-progress note="In progress N"` heartbeats continue to appear roughly once per minute.
|
||||
5. Check verdict:
|
||||
1. While the reviewer is still running, keep waiting as long as fresh `state=in-progress note="In progress N"` heartbeats continue to appear roughly once per minute.
|
||||
2. Check verdict:
|
||||
- **VERDICT: APPROVED** with no `P0`, `P1`, or `P2` findings -> proceed to Phase 4 Step 6 (commit & approve)
|
||||
- **VERDICT: APPROVED** with only `P3` findings -> optionally fix the `P3` items if they are cheap and safe, then proceed
|
||||
- **VERDICT: REVISE** or any `P0`, `P1`, or `P2` finding -> go to Step 5
|
||||
@@ -438,7 +442,7 @@ Fallback is allowed only when the helper is missing or not executable.
|
||||
|
||||
Summarize revisions for the user:
|
||||
|
||||
```
|
||||
```markdown
|
||||
### Revisions (Round N)
|
||||
- [Change and reason, one bullet per issue addressed]
|
||||
```
|
||||
@@ -449,7 +453,6 @@ If a revision contradicts the user's explicit requirements, skip it and note it
|
||||
|
||||
Rewrite `/tmp/milestone-review-${REVIEW_ID}.sh` for the next round. The script should contain the reviewer invocation only; do not run it directly.
|
||||
|
||||
|
||||
**If `REVIEWER_CLI` is `pi`:**
|
||||
|
||||
Fresh call with prior-round context (Pi reviewer calls do not use session resume):
|
||||
@@ -559,20 +562,20 @@ After all milestones are approved and committed:
|
||||
git merge implement/<plan-folder-name>
|
||||
```
|
||||
|
||||
4. Delete the worktree and its branch:
|
||||
1. Delete the worktree and its branch:
|
||||
|
||||
```bash
|
||||
git worktree remove <worktree-path>
|
||||
git branch -d implement/<plan-folder-name>
|
||||
```
|
||||
|
||||
5. Mark plan status as `completed` in `story-tracker.md`.
|
||||
1. Mark plan status as `completed` in `story-tracker.md`.
|
||||
|
||||
### Phase 7: Final Report
|
||||
|
||||
Present summary:
|
||||
|
||||
```
|
||||
```markdown
|
||||
## Implementation Complete
|
||||
|
||||
**Plan:** <plan-folder-name>
|
||||
@@ -598,6 +601,7 @@ fi
|
||||
```
|
||||
|
||||
Rules:
|
||||
|
||||
- Telegram is the only supported notification path. Do not use desktop notifications, `say`, email, or any other notifier.
|
||||
- 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.
|
||||
@@ -608,12 +612,14 @@ Rules:
|
||||
**ALWAYS update `story-tracker.md` before/after each story. NEVER proceed with stale tracker state.**
|
||||
|
||||
Before starting any story:
|
||||
|
||||
1. Open `story-tracker.md`
|
||||
2. Mark story `in-dev`
|
||||
3. Add notes if relevant
|
||||
4. Then begin implementation
|
||||
|
||||
After completing any story:
|
||||
|
||||
1. Mark story `completed`
|
||||
2. Review pending stories
|
||||
3. Update Last Updated and Stories Complete counts
|
||||
|
||||
@@ -10,6 +10,7 @@ Execute an existing plan (created by `create-plan`) in an isolated git worktree,
|
||||
## Overview
|
||||
|
||||
This skill wraps the Superpowers execution flow for Codex:
|
||||
|
||||
1. Locate plan files under `ai_plan/`
|
||||
2. Set up an isolated git worktree
|
||||
3. Execute milestones one-by-one with lint/typecheck/test gates
|
||||
@@ -21,6 +22,7 @@ This skill wraps the Superpowers execution flow for Codex:
|
||||
## Prerequisite Check (MANDATORY)
|
||||
|
||||
Required:
|
||||
|
||||
- Plan folder exists under `ai_plan/` at project root
|
||||
- `continuation-runbook.md` exists in plan folder
|
||||
- `milestone-plan.md` exists in plan folder
|
||||
@@ -96,7 +98,6 @@ Store `REVIEWER_CLI`, `REVIEWER_MODEL`, and `MAX_ROUNDS`. These values are fixed
|
||||
|
||||
Reviewer CLI: `codex`, `claude`, `cursor`, `opencode`, `pi`, or `skip`.
|
||||
|
||||
|
||||
If `REVIEWER_CLI=pi`, verify the Pi reviewer binary before entering the review loop:
|
||||
|
||||
```bash
|
||||
@@ -134,6 +135,7 @@ Mark first story `in-dev` in `story-tracker.md`.
|
||||
#### Step 3: Implement Stories
|
||||
|
||||
Execute each story in order. After completing each story:
|
||||
|
||||
1. Mark `in-dev` -> `completed` in `story-tracker.md`
|
||||
2. Update counts
|
||||
3. Mark next story `in-dev`
|
||||
@@ -168,6 +170,7 @@ git commit -m "feat(<scope>): implement milestone M<N> - <description>"
|
||||
```
|
||||
|
||||
Do NOT push. After committing:
|
||||
|
||||
1. Backfill the commit hash into the Notes column for all stories in this milestone in `story-tracker.md`.
|
||||
2. Mark milestone as `approved` in `story-tracker.md`.
|
||||
3. Move to next milestone.
|
||||
@@ -183,6 +186,7 @@ REVIEW_ID=$(uuidgen | tr '[:upper:]' '[:lower:]' | head -c 8)
|
||||
```
|
||||
|
||||
Use `REVIEW_ID` for all milestone review temp file paths:
|
||||
|
||||
- `/tmp/milestone-${REVIEW_ID}.md`
|
||||
- `/tmp/milestone-review-${REVIEW_ID}.md`
|
||||
- `/tmp/milestone-review-${REVIEW_ID}.json`
|
||||
@@ -259,6 +263,7 @@ VERDICT: APPROVED
|
||||
```
|
||||
|
||||
Rules:
|
||||
|
||||
- Order findings from `P0` to `P3`.
|
||||
- `P0` = total blocker, `P1` = major risk, `P2` = must-fix before approval, `P3` = cosmetic / nice to have.
|
||||
- Use `- None.` when a severity has no findings.
|
||||
@@ -281,7 +286,6 @@ Write the reviewer invocation to `/tmp/milestone-review-${REVIEW_ID}.sh` as a ba
|
||||
set -euo pipefail
|
||||
```
|
||||
|
||||
|
||||
**If `REVIEWER_CLI` is `pi`:**
|
||||
|
||||
Fresh call every round (Pi reviewer calls do not use session resume):
|
||||
@@ -422,6 +426,7 @@ fi
|
||||
Run the helper in the foreground and watch its live stdout for `state=in-progress` heartbeats. If your agent environment buffers command output until exit, start the helper in the background and poll `/tmp/milestone-review-${REVIEW_ID}.status` separately instead of treating heartbeats as post-hoc-only data.
|
||||
|
||||
After the command completes:
|
||||
|
||||
- If `REVIEWER_CLI=cursor`, extract the final review text:
|
||||
|
||||
```bash
|
||||
@@ -447,14 +452,14 @@ Fallback is allowed only when the helper is missing or not executable.
|
||||
- `/tmp/milestone-review-${REVIEW_ID}.runner.out`
|
||||
3. Present review to the user:
|
||||
|
||||
```
|
||||
```markdown
|
||||
## Milestone Review — Round N (reviewer: ${REVIEWER_CLI} / ${REVIEWER_MODEL})
|
||||
|
||||
[Reviewer feedback]
|
||||
```
|
||||
|
||||
4. While the reviewer is still running, keep waiting as long as fresh `state=in-progress note="In progress N"` heartbeats continue to appear roughly once per minute.
|
||||
5. Check verdict:
|
||||
1. While the reviewer is still running, keep waiting as long as fresh `state=in-progress note="In progress N"` heartbeats continue to appear roughly once per minute.
|
||||
2. Check verdict:
|
||||
- **VERDICT: APPROVED** with no `P0`, `P1`, or `P2` findings -> proceed to Phase 4 Step 6 (commit & approve)
|
||||
- **VERDICT: APPROVED** with only `P3` findings -> optionally fix the `P3` items if they are cheap and safe, then proceed
|
||||
- **VERDICT: REVISE** or any `P0`, `P1`, or `P2` finding -> go to Step 5
|
||||
@@ -471,7 +476,7 @@ Fallback is allowed only when the helper is missing or not executable.
|
||||
|
||||
Summarize revisions for the user:
|
||||
|
||||
```
|
||||
```markdown
|
||||
### Revisions (Round N)
|
||||
- [Change and reason, one bullet per issue addressed]
|
||||
```
|
||||
@@ -482,7 +487,6 @@ If a revision contradicts the user's explicit requirements, skip it and note it
|
||||
|
||||
Rewrite `/tmp/milestone-review-${REVIEW_ID}.sh` for the next round. The script should contain the reviewer invocation only; do not run it directly.
|
||||
|
||||
|
||||
**If `REVIEWER_CLI` is `pi`:**
|
||||
|
||||
Fresh call with prior-round context (Pi reviewer calls do not use session resume):
|
||||
@@ -592,20 +596,20 @@ After all milestones are approved and committed:
|
||||
git merge implement/<plan-folder-name>
|
||||
```
|
||||
|
||||
4. Delete the worktree and its branch:
|
||||
1. Delete the worktree and its branch:
|
||||
|
||||
```bash
|
||||
git worktree remove <worktree-path>
|
||||
git branch -d implement/<plan-folder-name>
|
||||
```
|
||||
|
||||
5. Mark plan status as `completed` in `story-tracker.md`.
|
||||
1. Mark plan status as `completed` in `story-tracker.md`.
|
||||
|
||||
### Phase 7: Final Report
|
||||
|
||||
Present summary:
|
||||
|
||||
```
|
||||
```markdown
|
||||
## Implementation Complete
|
||||
|
||||
**Plan:** <plan-folder-name>
|
||||
@@ -631,6 +635,7 @@ fi
|
||||
```
|
||||
|
||||
Rules:
|
||||
|
||||
- Telegram is the only supported notification path. Do not use desktop notifications, `say`, email, or any other notifier.
|
||||
- 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.
|
||||
@@ -654,12 +659,14 @@ Rules:
|
||||
**ALWAYS update `story-tracker.md` before/after each story. NEVER proceed with stale tracker state.**
|
||||
|
||||
Before starting any story:
|
||||
|
||||
1. Open `story-tracker.md`
|
||||
2. Mark story `in-dev`
|
||||
3. Add notes if relevant
|
||||
4. Then begin implementation
|
||||
|
||||
After completing any story:
|
||||
|
||||
1. Mark story `completed`
|
||||
2. Review pending stories
|
||||
3. Update Last Updated and Stories Complete counts
|
||||
|
||||
@@ -10,6 +10,7 @@ Execute an existing plan (created by `create-plan`) in an isolated git worktree,
|
||||
## Overview
|
||||
|
||||
This skill wraps the Superpowers execution flow for the Cursor Agent CLI (`cursor-agent`):
|
||||
|
||||
1. Locate plan files under `ai_plan/`
|
||||
2. Set up an isolated git worktree
|
||||
3. Execute milestones one-by-one with lint/typecheck/test gates
|
||||
@@ -21,6 +22,7 @@ This skill wraps the Superpowers execution flow for the Cursor Agent CLI (`curso
|
||||
## Prerequisite Check (MANDATORY)
|
||||
|
||||
Required:
|
||||
|
||||
- Cursor Agent CLI: `cursor-agent --version` (install via `curl https://cursor.com/install -fsS | bash`). The binary is `cursor-agent` (installed to `~/.local/bin/`). Some environments alias it as `cursor agent` (subcommand of the Cursor IDE CLI) — both forms work, but this skill uses `cursor-agent` throughout.
|
||||
- `jq` (required only if using `cursor` as the reviewer CLI): `jq --version` (install via `brew install jq` or your package manager)
|
||||
- Plan folder exists under `ai_plan/` at project root
|
||||
@@ -96,7 +98,6 @@ Store `REVIEWER_CLI`, `REVIEWER_MODEL`, and `MAX_ROUNDS`. These values are fixed
|
||||
|
||||
Reviewer CLI: `codex`, `claude`, `cursor`, `opencode`, `pi`, or `skip`.
|
||||
|
||||
|
||||
If `REVIEWER_CLI=pi`, verify the Pi reviewer binary before entering the review loop:
|
||||
|
||||
```bash
|
||||
@@ -134,6 +135,7 @@ Mark first story `in-dev` in `story-tracker.md`.
|
||||
#### Step 3: Implement Stories
|
||||
|
||||
Execute each story in order. After completing each story:
|
||||
|
||||
1. Mark `in-dev` -> `completed` in `story-tracker.md`
|
||||
2. Update counts
|
||||
3. Mark next story `in-dev`
|
||||
@@ -168,6 +170,7 @@ git commit -m "feat(<scope>): implement milestone M<N> - <description>"
|
||||
```
|
||||
|
||||
Do NOT push. After committing:
|
||||
|
||||
1. Backfill the commit hash into the Notes column for all stories in this milestone in `story-tracker.md`.
|
||||
2. Mark milestone as `approved` in `story-tracker.md`.
|
||||
3. Move to next milestone.
|
||||
@@ -183,6 +186,7 @@ REVIEW_ID=$(uuidgen | tr '[:upper:]' '[:lower:]' | head -c 8)
|
||||
```
|
||||
|
||||
Use `REVIEW_ID` for all milestone review temp file paths:
|
||||
|
||||
- `/tmp/milestone-${REVIEW_ID}.md`
|
||||
- `/tmp/milestone-review-${REVIEW_ID}.md`
|
||||
- `/tmp/milestone-review-${REVIEW_ID}.json`
|
||||
@@ -263,6 +267,7 @@ VERDICT: APPROVED
|
||||
```
|
||||
|
||||
Rules:
|
||||
|
||||
- Order findings from `P0` to `P3`.
|
||||
- `P0` = total blocker, `P1` = major risk, `P2` = must-fix before approval, `P3` = cosmetic / nice to have.
|
||||
- Use `- None.` when a severity has no findings.
|
||||
@@ -285,7 +290,6 @@ Write the reviewer invocation to `/tmp/milestone-review-${REVIEW_ID}.sh` as a ba
|
||||
set -euo pipefail
|
||||
```
|
||||
|
||||
|
||||
**If `REVIEWER_CLI` is `pi`:**
|
||||
|
||||
Fresh call every round (Pi reviewer calls do not use session resume):
|
||||
@@ -408,6 +412,7 @@ Rules:
|
||||
For `cursor`, the command script writes raw JSON to `/tmp/milestone-review-${REVIEW_ID}.json`. Do not run `jq` extraction until after the helper or fallback execution completes.
|
||||
|
||||
Notes on Cursor flags:
|
||||
|
||||
- `--mode=ask` — read-only mode, no file modifications
|
||||
- `--trust` — trust workspace without prompting (required for non-interactive use)
|
||||
- `-p` / `--print` — non-interactive mode, output to stdout
|
||||
@@ -432,6 +437,7 @@ fi
|
||||
Run the helper in the foreground and watch its live stdout for `state=in-progress` heartbeats. If your agent environment buffers command output until exit, start the helper in the background and poll `/tmp/milestone-review-${REVIEW_ID}.status` separately instead of treating heartbeats as post-hoc-only data.
|
||||
|
||||
After the command completes:
|
||||
|
||||
- If `REVIEWER_CLI=cursor`, extract the final review text:
|
||||
|
||||
```bash
|
||||
@@ -457,14 +463,14 @@ Fallback is allowed only when the helper is missing or not executable.
|
||||
- `/tmp/milestone-review-${REVIEW_ID}.runner.out`
|
||||
3. Present review to the user:
|
||||
|
||||
```
|
||||
```markdown
|
||||
## Milestone Review — Round N (reviewer: ${REVIEWER_CLI} / ${REVIEWER_MODEL})
|
||||
|
||||
[Reviewer feedback]
|
||||
```
|
||||
|
||||
4. While the reviewer is still running, keep waiting as long as fresh `state=in-progress note="In progress N"` heartbeats continue to appear roughly once per minute.
|
||||
5. Check verdict:
|
||||
1. While the reviewer is still running, keep waiting as long as fresh `state=in-progress note="In progress N"` heartbeats continue to appear roughly once per minute.
|
||||
2. Check verdict:
|
||||
- **VERDICT: APPROVED** with no `P0`, `P1`, or `P2` findings -> proceed to Phase 4 Step 6 (commit & approve)
|
||||
- **VERDICT: APPROVED** with only `P3` findings -> optionally fix the `P3` items if they are cheap and safe, then proceed
|
||||
- **VERDICT: REVISE** or any `P0`, `P1`, or `P2` finding -> go to Step 5
|
||||
@@ -481,7 +487,7 @@ Fallback is allowed only when the helper is missing or not executable.
|
||||
|
||||
Summarize revisions for the user:
|
||||
|
||||
```
|
||||
```markdown
|
||||
### Revisions (Round N)
|
||||
- [Change and reason, one bullet per issue addressed]
|
||||
```
|
||||
@@ -492,7 +498,6 @@ If a revision contradicts the user's explicit requirements, skip it and note it
|
||||
|
||||
Rewrite `/tmp/milestone-review-${REVIEW_ID}.sh` for the next round. The script should contain the reviewer invocation only; do not run it directly.
|
||||
|
||||
|
||||
**If `REVIEWER_CLI` is `pi`:**
|
||||
|
||||
Fresh call with prior-round context (Pi reviewer calls do not use session resume):
|
||||
@@ -602,20 +607,20 @@ After all milestones are approved and committed:
|
||||
git merge implement/<plan-folder-name>
|
||||
```
|
||||
|
||||
4. Delete the worktree and its branch:
|
||||
1. Delete the worktree and its branch:
|
||||
|
||||
```bash
|
||||
git worktree remove <worktree-path>
|
||||
git branch -d implement/<plan-folder-name>
|
||||
```
|
||||
|
||||
5. Mark plan status as `completed` in `story-tracker.md`.
|
||||
1. Mark plan status as `completed` in `story-tracker.md`.
|
||||
|
||||
### Phase 7: Final Report
|
||||
|
||||
Present summary:
|
||||
|
||||
```
|
||||
```markdown
|
||||
## Implementation Complete
|
||||
|
||||
**Plan:** <plan-folder-name>
|
||||
@@ -645,6 +650,7 @@ fi
|
||||
```
|
||||
|
||||
Rules:
|
||||
|
||||
- Telegram is the only supported notification path. Do not use desktop notifications, `say`, email, or any other notifier.
|
||||
- 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.
|
||||
@@ -666,12 +672,14 @@ Rules:
|
||||
## Tracker Discipline (MANDATORY)
|
||||
|
||||
Before starting any story:
|
||||
|
||||
1. Open `story-tracker.md`
|
||||
2. Mark story `in-dev`
|
||||
3. Add notes if relevant
|
||||
4. Then begin implementation
|
||||
|
||||
After completing any story:
|
||||
|
||||
1. Mark story `completed`
|
||||
2. Review pending stories
|
||||
3. Update Last Updated and Stories Complete counts
|
||||
|
||||
@@ -12,6 +12,7 @@ Execute an existing plan (created by `create-plan`) in an isolated git worktree,
|
||||
This OpenCode variant depends on Superpowers execution skills being installed via OpenCode's native skill system.
|
||||
|
||||
Required:
|
||||
|
||||
- Plan folder exists under `ai_plan/` at project root
|
||||
- `continuation-runbook.md` exists in plan folder
|
||||
- `milestone-plan.md` exists in plan folder
|
||||
@@ -46,6 +47,7 @@ If no plan folder exists:
|
||||
### Phase 1: Bootstrap Superpowers Context (REQUIRED)
|
||||
|
||||
Use OpenCode's native skill tool:
|
||||
|
||||
- list skills
|
||||
- verify `superpowers/executing-plans`, `superpowers/using-git-worktrees`, `superpowers/verification-before-completion`, and `superpowers/finishing-a-development-branch` are discoverable
|
||||
|
||||
@@ -81,7 +83,6 @@ Store `REVIEWER_CLI`, `REVIEWER_MODEL`, and `MAX_ROUNDS`. These values are fixed
|
||||
|
||||
Reviewer CLI: `codex`, `claude`, `cursor`, `opencode`, `pi`, or `skip`.
|
||||
|
||||
|
||||
If `REVIEWER_CLI=pi`, verify the Pi reviewer binary before entering the review loop:
|
||||
|
||||
```bash
|
||||
@@ -95,9 +96,11 @@ When `REVIEWER_CLI=pi`, the reviewer model is configured independently from the
|
||||
### Phase 4: Set Up Worktree (REQUIRED SUB-SKILL)
|
||||
|
||||
Use OpenCode's native skill tool to load:
|
||||
|
||||
- `superpowers/using-git-worktrees`
|
||||
|
||||
Then:
|
||||
|
||||
1. Branch naming: `implement/<plan-folder-name>` (e.g., `implement/2026-03-04-auth-system`).
|
||||
2. Follow worktree skill's directory priority: `.worktrees/` > `worktrees/` > CLAUDE.md > ask user.
|
||||
3. Verify `.gitignore` covers worktree directory.
|
||||
@@ -121,6 +124,7 @@ Mark first story `in-dev` in `story-tracker.md`.
|
||||
#### Step 3: Implement Stories
|
||||
|
||||
Execute each story in order. After completing each story:
|
||||
|
||||
1. Mark `in-dev` -> `completed` in `story-tracker.md`
|
||||
2. Update counts
|
||||
3. Mark next story `in-dev`
|
||||
@@ -130,6 +134,7 @@ Commit hashes are not available yet — they are backfilled in Step 6 after the
|
||||
#### Step 4: Verify Milestone (REQUIRED SUB-SKILL)
|
||||
|
||||
Use OpenCode's native skill tool to load:
|
||||
|
||||
- `superpowers/verification-before-completion`
|
||||
|
||||
```bash
|
||||
@@ -156,6 +161,7 @@ git commit -m "feat(<scope>): implement milestone M<N> - <description>"
|
||||
```
|
||||
|
||||
Do NOT push. After committing:
|
||||
|
||||
1. Backfill the commit hash into the Notes column for all stories in this milestone in `story-tracker.md`.
|
||||
2. Mark milestone as `approved` in `story-tracker.md`.
|
||||
3. Move to next milestone.
|
||||
@@ -171,6 +177,7 @@ REVIEW_ID=$(uuidgen | tr '[:upper:]' '[:lower:]' | head -c 8)
|
||||
```
|
||||
|
||||
Use `REVIEW_ID` for all milestone review temp file paths:
|
||||
|
||||
- `/tmp/milestone-${REVIEW_ID}.md`
|
||||
- `/tmp/milestone-review-${REVIEW_ID}.md`
|
||||
- `/tmp/milestone-review-${REVIEW_ID}.json`
|
||||
@@ -196,6 +203,9 @@ case "$REVIEWER_CLI" in
|
||||
cursor)
|
||||
HELPER_SUCCESS_FILE_ARGS+=(--success-file /tmp/milestone-review-${REVIEW_ID}.json)
|
||||
;;
|
||||
opencode)
|
||||
HELPER_SUCCESS_FILE_ARGS+=(--success-file /tmp/milestone-review-${REVIEW_ID}.md)
|
||||
;;
|
||||
esac
|
||||
```
|
||||
|
||||
@@ -247,6 +257,7 @@ VERDICT: APPROVED
|
||||
```
|
||||
|
||||
Rules:
|
||||
|
||||
- Order findings from `P0` to `P3`.
|
||||
- `P0` = total blocker, `P1` = major risk, `P2` = must-fix before approval, `P3` = cosmetic / nice to have.
|
||||
- Use `- None.` when a severity has no findings.
|
||||
@@ -269,7 +280,6 @@ Write the reviewer invocation to `/tmp/milestone-review-${REVIEW_ID}.sh` as a ba
|
||||
set -euo pipefail
|
||||
```
|
||||
|
||||
|
||||
**If `REVIEWER_CLI` is `pi`:**
|
||||
|
||||
Fresh call every round (Pi reviewer calls do not use session resume):
|
||||
@@ -391,6 +401,77 @@ Rules:
|
||||
|
||||
For `cursor`, the command script writes raw JSON to `/tmp/milestone-review-${REVIEW_ID}.json`. Do not run `jq` extraction until after the helper or fallback execution completes. If `jq` is not installed, inform the user: `brew install jq` (macOS) or equivalent.
|
||||
|
||||
**If `REVIEWER_CLI` is `opencode`:**
|
||||
|
||||
OpenCode uses `--agent plan` for read-oriented review. Fresh call is the recommended default.
|
||||
|
||||
Round 1:
|
||||
|
||||
```bash
|
||||
opencode run \
|
||||
-m ${REVIEWER_MODEL} \
|
||||
--agent plan \
|
||||
--format json \
|
||||
"Read the file /tmp/milestone-${REVIEW_ID}.md and review this milestone implementation.
|
||||
|
||||
Evaluate:
|
||||
1. Correctness — Does the implementation match the milestone spec?
|
||||
2. Acceptance criteria — Are all criteria met?
|
||||
3. Code quality — Clean, maintainable, no obvious issues?
|
||||
4. Test coverage — Are changes adequately tested?
|
||||
5. Security — Any security concerns introduced?
|
||||
|
||||
Return exactly these sections in order:
|
||||
## Summary
|
||||
## Findings
|
||||
### P0
|
||||
### P1
|
||||
### P2
|
||||
### P3
|
||||
## Verdict
|
||||
|
||||
Rules:
|
||||
- Order findings from highest severity to lowest.
|
||||
- Use \`- None.\` when a severity has no findings.
|
||||
- \`P0\` = total blocker, \`P1\` = major risk, \`P2\` = must-fix before approval, \`P3\` = cosmetic / nice to have.
|
||||
- End with exactly one verdict line: \`VERDICT: APPROVED\` or \`VERDICT: REVISE\`
|
||||
- \`VERDICT: APPROVED\` is allowed only when there are no \`P0\`, \`P1\`, or \`P2\` findings. \`P3\` findings are non-blocking." \
|
||||
> /tmp/milestone-review-${REVIEW_ID}.json
|
||||
```
|
||||
|
||||
Round 2 and later (fresh-call, recommended default):
|
||||
|
||||
```bash
|
||||
opencode run \
|
||||
-m ${REVIEWER_MODEL} \
|
||||
--agent plan \
|
||||
--format json \
|
||||
"You previously reviewed this milestone and requested revisions.
|
||||
|
||||
Previous feedback summary: [key points from last review]
|
||||
|
||||
I've revised. Updated milestone payload is in /tmp/milestone-${REVIEW_ID}.md.
|
||||
|
||||
Changes made:
|
||||
[List specific changes]
|
||||
|
||||
Re-review using the same ## Summary, ## Findings, and ## Verdict structure as before." \
|
||||
> /tmp/milestone-review-${REVIEW_ID}.json
|
||||
```
|
||||
|
||||
Extract the review body:
|
||||
|
||||
```bash
|
||||
jq -r '.[] | select(.type == "message" and .role == "assistant") | .content' \
|
||||
/tmp/milestone-review-${REVIEW_ID}.json \
|
||||
> /tmp/milestone-review-${REVIEW_ID}.md \
|
||||
|| cp /tmp/milestone-review-${REVIEW_ID}.json /tmp/milestone-review-${REVIEW_ID}.md
|
||||
```
|
||||
|
||||
If the JSON parse falls through, promote the raw JSON file as the review output. On any opencode
|
||||
CLI or JSON parsing failure, treat this loop round as `completed-empty-output` and follow the
|
||||
helper-failure escalation in Step 4.
|
||||
|
||||
Run the command script through the shared helper when available:
|
||||
|
||||
```bash
|
||||
@@ -410,6 +491,7 @@ fi
|
||||
Run the helper in the foreground and watch its live stdout for `state=in-progress` heartbeats. If your agent environment buffers command output until exit, start the helper in the background and poll `/tmp/milestone-review-${REVIEW_ID}.status` separately instead of treating heartbeats as post-hoc-only data.
|
||||
|
||||
After the command completes:
|
||||
|
||||
- If `REVIEWER_CLI=cursor`, extract the final review text:
|
||||
|
||||
```bash
|
||||
@@ -418,6 +500,7 @@ jq -r '.result' /tmp/milestone-review-${REVIEW_ID}.json > /tmp/milestone-review-
|
||||
```
|
||||
|
||||
- If `REVIEWER_CLI=codex`, extract `CODEX_SESSION_ID` from `/tmp/milestone-review-${REVIEW_ID}.runner.out` after the helper or fallback run. If the review text is only in `.runner.out`, move or copy the actual review body into `/tmp/milestone-review-${REVIEW_ID}.md` before verdict parsing.
|
||||
- If `REVIEWER_CLI=opencode`, the `jq` extraction above covers output capture. If it falls through, copy runner output: `cp /tmp/milestone-review-${REVIEW_ID}.runner.out /tmp/milestone-review-${REVIEW_ID}.md`. On Round 1, also attempt to capture the session id for optional use in subsequent rounds: `OPENCODE_SESSION_ID=$(jq -r 'if type == "array" then (.[0] | (.id? // .session_id?)) else (.id? // .session_id?) end // empty' /tmp/milestone-review-${REVIEW_ID}.json 2>/dev/null || true)`
|
||||
- If `REVIEWER_CLI=claude` or `REVIEWER_CLI=pi`, promote stdout captured by the helper or fallback runner into the markdown review file:
|
||||
|
||||
```bash
|
||||
@@ -435,14 +518,14 @@ Fallback is allowed only when the helper is missing or not executable.
|
||||
- `/tmp/milestone-review-${REVIEW_ID}.runner.out`
|
||||
3. Present review to the user:
|
||||
|
||||
```
|
||||
```markdown
|
||||
## Milestone Review — Round N (reviewer: ${REVIEWER_CLI} / ${REVIEWER_MODEL})
|
||||
|
||||
[Reviewer feedback]
|
||||
```
|
||||
|
||||
4. While the reviewer is still running, keep waiting as long as fresh `state=in-progress note="In progress N"` heartbeats continue to appear roughly once per minute.
|
||||
5. Check verdict:
|
||||
1. While the reviewer is still running, keep waiting as long as fresh `state=in-progress note="In progress N"` heartbeats continue to appear roughly once per minute.
|
||||
2. Check verdict:
|
||||
- **VERDICT: APPROVED** with no `P0`, `P1`, or `P2` findings -> proceed to Phase 5 Step 6 (commit & approve)
|
||||
- **VERDICT: APPROVED** with only `P3` findings -> optionally fix the `P3` items if they are cheap and safe, then proceed
|
||||
- **VERDICT: REVISE** or any `P0`, `P1`, or `P2` finding -> go to Step 5
|
||||
@@ -459,7 +542,7 @@ Fallback is allowed only when the helper is missing or not executable.
|
||||
|
||||
Summarize revisions for the user:
|
||||
|
||||
```
|
||||
```markdown
|
||||
### Revisions (Round N)
|
||||
- [Change and reason, one bullet per issue addressed]
|
||||
```
|
||||
@@ -470,7 +553,6 @@ If a revision contradicts the user's explicit requirements, skip it and note it
|
||||
|
||||
Rewrite `/tmp/milestone-review-${REVIEW_ID}.sh` for the next round. The script should contain the reviewer invocation only; do not run it directly.
|
||||
|
||||
|
||||
**If `REVIEWER_CLI` is `pi`:**
|
||||
|
||||
Fresh call with prior-round context (Pi reviewer calls do not use session resume):
|
||||
@@ -546,6 +628,59 @@ Keep findings ordered `P0` to `P3`, use `- None.` when a severity has no finding
|
||||
|
||||
If resume fails, fall back to fresh `cursor-agent -p` with context about prior rounds.
|
||||
|
||||
**If `REVIEWER_CLI` is `opencode`:**
|
||||
|
||||
Fresh call (recommended default — opencode has no guaranteed stable session ID in headless mode):
|
||||
|
||||
```bash
|
||||
opencode run \
|
||||
-m ${REVIEWER_MODEL} \
|
||||
--agent plan \
|
||||
--format json \
|
||||
"You previously reviewed this milestone and requested revisions.
|
||||
|
||||
Previous feedback summary: [key points from last review]
|
||||
|
||||
I've addressed your feedback. Updated milestone payload is in /tmp/milestone-${REVIEW_ID}.md.
|
||||
|
||||
Changes made:
|
||||
[List specific changes]
|
||||
|
||||
Re-review using the same \`## Summary\`, \`## Findings\`, and \`## Verdict\` structure as before.
|
||||
Keep findings ordered \`P0\` to \`P3\`, use \`- None.\` when a severity has no findings, and only use \`VERDICT: APPROVED\` when no \`P0\`, \`P1\`, or \`P2\` findings remain. \`P3\` findings are non-blocking." \
|
||||
> /tmp/milestone-review-${REVIEW_ID}.json
|
||||
|
||||
jq -r '.[] | select(.type == "message" and .role == "assistant") | .content' \
|
||||
/tmp/milestone-review-${REVIEW_ID}.json \
|
||||
> /tmp/milestone-review-${REVIEW_ID}.md \
|
||||
|| cp /tmp/milestone-review-${REVIEW_ID}.json /tmp/milestone-review-${REVIEW_ID}.md
|
||||
```
|
||||
|
||||
Optional session-resume path (only if `OPENCODE_SESSION_ID` was captured on Round 1 and your installed opencode accepts `-s <id>` reliably in headless mode):
|
||||
|
||||
```bash
|
||||
opencode run \
|
||||
-s ${OPENCODE_SESSION_ID} \
|
||||
-m ${REVIEWER_MODEL} \
|
||||
--agent plan \
|
||||
--format json \
|
||||
"I've addressed your feedback on this milestone. Updated diff and verification output are in /tmp/milestone-${REVIEW_ID}.md.
|
||||
|
||||
Changes made:
|
||||
[List specific changes]
|
||||
|
||||
Re-review using the same \`## Summary\`, \`## Findings\`, and \`## Verdict\` structure as before.
|
||||
Keep findings ordered \`P0\` to \`P3\`, use \`- None.\` when a severity has no findings, and only use \`VERDICT: APPROVED\` when no \`P0\`, \`P1\`, or \`P2\` findings remain. \`P3\` findings are non-blocking." \
|
||||
> /tmp/milestone-review-${REVIEW_ID}.json
|
||||
|
||||
jq -r '.[] | select(.type == "message" and .role == "assistant") | .content' \
|
||||
/tmp/milestone-review-${REVIEW_ID}.json \
|
||||
> /tmp/milestone-review-${REVIEW_ID}.md \
|
||||
|| cp /tmp/milestone-review-${REVIEW_ID}.json /tmp/milestone-review-${REVIEW_ID}.md
|
||||
```
|
||||
|
||||
If session resume fails (session expired or not supported), fall back to the fresh-call path above.
|
||||
|
||||
Do not run `jq` extraction until after the helper or fallback execution completes, then extract `/tmp/milestone-review-${REVIEW_ID}.md` from the JSON response.
|
||||
|
||||
After updating `/tmp/milestone-review-${REVIEW_ID}.sh`, run the same helper/fallback flow from Round 1.
|
||||
@@ -580,20 +715,20 @@ After all milestones are approved and committed:
|
||||
git merge implement/<plan-folder-name>
|
||||
```
|
||||
|
||||
4. Delete the worktree and its branch:
|
||||
1. Delete the worktree and its branch:
|
||||
|
||||
```bash
|
||||
git worktree remove <worktree-path>
|
||||
git branch -d implement/<plan-folder-name>
|
||||
```
|
||||
|
||||
5. Mark plan status as `completed` in `story-tracker.md`.
|
||||
1. Mark plan status as `completed` in `story-tracker.md`.
|
||||
|
||||
### Phase 8: Final Report
|
||||
|
||||
Present summary:
|
||||
|
||||
```
|
||||
```markdown
|
||||
## Implementation Complete
|
||||
|
||||
**Plan:** <plan-folder-name>
|
||||
@@ -619,6 +754,7 @@ fi
|
||||
```
|
||||
|
||||
Rules:
|
||||
|
||||
- Telegram is the only supported notification path. Do not use desktop notifications, `say`, email, or any other notifier.
|
||||
- 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.
|
||||
@@ -627,12 +763,14 @@ Rules:
|
||||
## Tracker Discipline (MANDATORY)
|
||||
|
||||
Before starting any story:
|
||||
|
||||
1. Open `story-tracker.md`
|
||||
2. Mark story `in-dev`
|
||||
3. Add notes if relevant
|
||||
4. Then begin implementation
|
||||
|
||||
After completing any story:
|
||||
|
||||
1. Mark story `completed`
|
||||
2. Review pending stories
|
||||
3. Update Last Updated and Stories Complete counts
|
||||
|
||||
Reference in New Issue
Block a user