Perform code optimization and document cleanup (#1)
## Summary - add repository-wide quality tooling and verification scaffolding, including CI workflows, pnpm workspace setup, ESLint/Prettier/markdown checks, and generated-output verification helpers - reorganize skill sources and generation flow by introducing canonical `_source` variants, generator/manifests, reusable helper abstractions, and shared web-automation/browser utilities - clean up and expand documentation so the root README flows into docs and skill docs, with clearer development, reviewer, installer, and workflow guidance ## Notable changes - docs flow and consistency cleanup across `README.md`, `docs/README.md`, and related docs - new scripts for `check`, docs verification, generated-file verification, shell portability, and safe directory replacement - refactors in Atlassian and web-automation skill runtimes to reduce duplication and centralize reusable code - changelog, development documentation, and CI surface updates ## Test Plan - [ ] `pnpm run check` - [ ] review generated/manifests and skill sync outputs - [ ] smoke-check docs flow from `README.md` to `docs/README.md` to skill docs ## Notes - this branch currently includes tracked `skills/web-automation/shared/node_modules` content that should be reviewed carefully as potentially noisy/accidental committed artifacts Co-authored-by: Stefano Fiorini <stefano.fiorini@firsthorizon.com> Reviewed-on: #1
This commit was merged in pull request #1.
This commit is contained in:
+16
-8
@@ -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
|
||||
|
||||
@@ -130,7 +138,7 @@ Recommended full Pi package install:
|
||||
Manual single-skill Pi install from the package mirror:
|
||||
|
||||
```bash
|
||||
./scripts/sync-pi-package-skills.sh
|
||||
pnpm run sync:pi
|
||||
mkdir -p .pi/skills/atlassian
|
||||
cp -R pi-package/skills/atlassian/* .pi/skills/atlassian/
|
||||
cd .pi/skills/atlassian/scripts
|
||||
|
||||
@@ -0,0 +1,558 @@
|
||||
# Cleanup Baseline — ai-coding-skills (M1)
|
||||
|
||||
Captured: 2026-05-03 · Platform: macOS (arm64, Apple Silicon) · Node 22.14.0 · pnpm 10.18.1
|
||||
|
||||
This document records the as-is state of every quality check at the start of
|
||||
the refactor series. All pre-existing failures listed here have since been
|
||||
resolved. As of M5 `pnpm run check` exits **0** on a clean checkout. Any
|
||||
failure now represents a regression and must be fixed before merge.
|
||||
|
||||
---
|
||||
|
||||
## Byte-equivalence assertion
|
||||
|
||||
Before any file was modified in M1, `git status` showed a clean working tree.
|
||||
After all S-101 through S-107 changes were applied, `git status` confirms:
|
||||
|
||||
- **Zero** modifications to any nested `package.json` under `skills/` or `pi-package/`.
|
||||
- **Zero** modifications to any file under `skills/*/{codex,claude-code,cursor,opencode,pi}/`
|
||||
(the generated agent-variant directories).
|
||||
- All changes are confined to new root-level config files, new scripts, updated
|
||||
root `package.json` (devDependencies + scripts), and new docs.
|
||||
|
||||
---
|
||||
|
||||
## 1. Pre-existing root scripts
|
||||
|
||||
### `pnpm run sync:pi`
|
||||
|
||||
```text
|
||||
Synced pi package skill mirror into …/pi-package/skills.
|
||||
EXIT: 0
|
||||
```
|
||||
|
||||
### `pnpm run verify:pi`
|
||||
|
||||
```text
|
||||
package metadata ok
|
||||
pi resources verified
|
||||
pi workflow skill docs verified
|
||||
EXIT: 0
|
||||
```
|
||||
|
||||
### `pnpm run verify:reviewers`
|
||||
|
||||
```text
|
||||
reviewer support verified
|
||||
EXIT: 0
|
||||
```
|
||||
|
||||
### `pnpm run test:installer`
|
||||
|
||||
```text
|
||||
TAP version 13
|
||||
# tests 22
|
||||
# pass 22
|
||||
# fail 0
|
||||
EXIT: 0
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 2. Nested package scripts
|
||||
|
||||
### atlassian/shared/scripts — `test`
|
||||
|
||||
```text
|
||||
TAP version 13
|
||||
# tests 23
|
||||
# pass 23
|
||||
# fail 0
|
||||
EXIT: 0
|
||||
```
|
||||
|
||||
### atlassian/shared/scripts — `typecheck`
|
||||
|
||||
```text
|
||||
EXIT: 0
|
||||
```
|
||||
|
||||
### atlassian/codex/scripts — `typecheck`
|
||||
|
||||
```text
|
||||
EXIT: 0
|
||||
```
|
||||
|
||||
### atlassian/claude-code/scripts — `typecheck`
|
||||
|
||||
```text
|
||||
EXIT: 0
|
||||
```
|
||||
|
||||
### atlassian/cursor/scripts — `typecheck`
|
||||
|
||||
```text
|
||||
EXIT: 0
|
||||
```
|
||||
|
||||
### atlassian/opencode/scripts — `typecheck`
|
||||
|
||||
```text
|
||||
EXIT: 0
|
||||
```
|
||||
|
||||
### atlassian/pi/scripts — `typecheck`
|
||||
|
||||
```text
|
||||
EXIT: 0
|
||||
```
|
||||
|
||||
### web-automation/codex/scripts — `typecheck`
|
||||
|
||||
```text
|
||||
EXIT: 0
|
||||
```
|
||||
|
||||
### web-automation/codex/scripts — `lint`
|
||||
|
||||
```text
|
||||
EXIT: 0
|
||||
```
|
||||
|
||||
### web-automation/claude-code/scripts — `typecheck`
|
||||
|
||||
```text
|
||||
EXIT: 0
|
||||
```
|
||||
|
||||
### web-automation/cursor/scripts — `typecheck`
|
||||
|
||||
```text
|
||||
EXIT: 0
|
||||
```
|
||||
|
||||
### web-automation/opencode/scripts — `typecheck`
|
||||
|
||||
```text
|
||||
EXIT: 0
|
||||
```
|
||||
|
||||
### web-automation/pi/scripts — `typecheck`
|
||||
|
||||
```text
|
||||
EXIT: 0
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 3. reviewer-runtime tests
|
||||
|
||||
All three test scripts under `skills/reviewer-runtime/tests/` passed:
|
||||
|
||||
```text
|
||||
claude-review-template-guard.sh PASS
|
||||
smoke-test.sh PASS
|
||||
telegram-notify-test.sh PASS
|
||||
EXIT: 0 (each)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 4. M1 quality tooling — baseline violations
|
||||
|
||||
### 4a. ESLint (`pnpm run lint` — ESLint stage)
|
||||
|
||||
Exit code: **1** — 2 pre-existing errors (no new errors from M1 additions).
|
||||
|
||||
Files with violations in the existing codebase:
|
||||
|
||||
| File | Line | Rule | Message |
|
||||
|------|------|------|---------|
|
||||
| `scripts/lib/skill-manager-core.mjs` | 282 | `no-useless-assignment` | Value assigned to `entries` is not used |
|
||||
| `scripts/manage-skills.mjs` | 270 | `no-unused-vars` | `client` is assigned a value but never used |
|
||||
|
||||
Action: Fix in a later milestone. Do not suppress with eslint-disable comments
|
||||
unless the code is intentionally dead.
|
||||
|
||||
### 4b. shellcheck (`pnpm run lint` — shellcheck stage)
|
||||
|
||||
Exit code: **1** — 7 files with pre-existing findings (no new violations from M1).
|
||||
|
||||
| File | Finding |
|
||||
|------|---------|
|
||||
| `scripts/verify-pi-resources.sh` | SC2016 (info, ×3): single-quoted backtick strings; SC2251 (info, ×1): `!` outside condition |
|
||||
| `scripts/verify-pi-workflows.sh` | SC2016 (info, ×2): single-quoted backtick strings; SC2251 (info, ×1): `!` outside condition |
|
||||
| `skills/reviewer-runtime/pi/run-review.sh` | SC2329 (info): unused `handle_signal`; SC2034 (warning, ×2): unused variables |
|
||||
| `skills/reviewer-runtime/run-review.sh` | SC2329 (info): unused `handle_signal`; SC2034 (warning, ×2): unused variables |
|
||||
| `skills/reviewer-runtime/tests/claude-review-template-guard.sh` | SC2016 (info, ×1): single-quoted expansion |
|
||||
| `skills/reviewer-runtime/tests/smoke-test.sh` | SC2064 (warning, ×1): `trap` should use single quotes |
|
||||
| `skills/reviewer-runtime/tests/telegram-notify-test.sh` | SC2064 (warning, ×1): `trap` should use single quotes |
|
||||
|
||||
The following files pass shellcheck with EXIT 0:
|
||||
|
||||
- `scripts/install-pi-package.sh`
|
||||
- `scripts/manage-skills.sh`
|
||||
- `scripts/sync-pi-package-skills.sh`
|
||||
- `scripts/verify-reviewer-support.sh`
|
||||
- `skills/reviewer-runtime/notify-telegram.sh`
|
||||
- `skills/reviewer-runtime/pi/notify-telegram.sh`
|
||||
- `skills/web-automation/scripts/sync-variants.sh`
|
||||
|
||||
Action: Fix `SC2064` trap issues and `SC2034` warnings in a later milestone.
|
||||
SC2016 findings are intentional (single-quoted strings containing backticks are
|
||||
used as literal grep patterns to match markdown text).
|
||||
|
||||
### 4c. markdownlint (`pnpm run verify:docs`)
|
||||
|
||||
Exit code: **1** — 1160 errors across 62 files (no new violations from M1 additions).
|
||||
|
||||
markdownlint-cli2 v0.22.1 scanned `README.md`, `docs/**/*.md`, and canonical
|
||||
`SKILL.md` files (excluding node\_modules and generated agent-variant
|
||||
directories).
|
||||
|
||||
Rule breakdown (selected):
|
||||
|
||||
| Rule | Description |
|
||||
|------|-------------|
|
||||
| MD013 | Line length > 120 chars (majority of errors) |
|
||||
| MD012 | Multiple consecutive blank lines |
|
||||
| MD024 | Duplicate headings |
|
||||
| MD029 | Ordered list item prefix |
|
||||
| MD032 | Blanks around lists |
|
||||
| MD038 | Spaces inside code span |
|
||||
| MD040 | Fenced code without language |
|
||||
| MD058 | Blanks around tables |
|
||||
|
||||
Affected files include (non-exhaustive): `docs/ATLASSIAN.md`,
|
||||
`docs/CREATE-PLAN.md`, `docs/DO-TASK.md`, `docs/IMPLEMENT-PLAN.md`,
|
||||
`docs/INSTALLER.md`, `docs/PI-COMMON-REVIEWER.md`, `docs/PI-RESEARCH.md`,
|
||||
`docs/PI-SUPERPOWERS.md`, `docs/PI.md`, `docs/README.md`,
|
||||
`docs/TELEGRAM-NOTIFICATIONS.md`, `docs/WEB-AUTOMATION.md`, `README.md`,
|
||||
and all `skills/*/*/SKILL.md` variants.
|
||||
|
||||
Action: Bulk-fix in a dedicated doc-cleanup milestone. New docs added in M1
|
||||
(`docs/DEVELOPMENT.md`, `docs/CLEANUP-BASELINE.md`) pass all enabled rules.
|
||||
|
||||
### 4d. markdown-link-check (offline, `pnpm run verify:docs`)
|
||||
|
||||
Exit code: **0** — no broken repo-relative or anchor links found.
|
||||
|
||||
53 markdown files scanned (offline mode: external http/https links ignored).
|
||||
All internal links are valid.
|
||||
|
||||
### 4e. `pnpm run typecheck` (workspace aggregate)
|
||||
|
||||
Exit code: **0**.
|
||||
|
||||
Ran `typecheck` in workspace members:
|
||||
|
||||
- `skills/atlassian/shared/scripts` — PASS
|
||||
- `skills/web-automation/codex/scripts` — PASS
|
||||
|
||||
### 4f. `pnpm run test` (workspace aggregate)
|
||||
|
||||
Exit code: **0**.
|
||||
|
||||
Ran:
|
||||
|
||||
- `pnpm run test:installer` (22/22 tests)
|
||||
- `skills/atlassian/shared/scripts test` (23/23 tests)
|
||||
|
||||
### 4g. `pnpm run check` aggregate (M1 transitional state)
|
||||
|
||||
```text
|
||||
FAIL lint (exit 1) — ESLint + shellcheck pre-existing violations (§4a, §4b)
|
||||
PASS typecheck
|
||||
PASS test
|
||||
PASS verify:pi
|
||||
PASS verify:reviewers
|
||||
FAIL verify:docs (exit 1) — markdownlint pre-existing violations (§4c)
|
||||
PASS verify:generated (stub)
|
||||
```
|
||||
|
||||
Overall exit: **1** — expected per transitional contract; all failures are
|
||||
pre-existing and documented in this file.
|
||||
|
||||
---
|
||||
|
||||
## 5. Platform notes
|
||||
|
||||
- Tested on macOS 15 (arm64). No GNU/Linux run available at M1 capture time.
|
||||
- shellcheck 0.11.0 installed via `brew install shellcheck`.
|
||||
- `stat` variant: BSD stat (macOS default). The `scripts/` shell scripts do
|
||||
not call `stat`; this affects only M5 CI configuration.
|
||||
- `rg` (ripgrep) is required by `scripts/verify-pi-workflows.sh`. It is
|
||||
present on the test machine; absent systems should install via
|
||||
`brew install ripgrep` / `apt-get install ripgrep`.
|
||||
|
||||
---
|
||||
|
||||
*This file is generated once (M1) and updated only when a subsequent milestone
|
||||
changes the baseline status of a check.*
|
||||
|
||||
---
|
||||
|
||||
## Post-M3 state
|
||||
|
||||
Captured: 2026-05-03 · Platform: macOS 15 (arm64) · Node 22.14.0 · pnpm 10.18.1
|
||||
|
||||
M3 resolved all remaining pre-existing `lint` violations (2 ESLint errors and
|
||||
7 shellcheck findings). `verify:generated` is now a real implementation
|
||||
(was a stub in M2).
|
||||
|
||||
### `pnpm run check` aggregate (post-M3)
|
||||
|
||||
```text
|
||||
PASS lint (was FAIL in M1/M2; pre-existing violations fixed in M3)
|
||||
PASS typecheck
|
||||
PASS test
|
||||
PASS verify:pi
|
||||
PASS verify:reviewers
|
||||
PASS verify:docs
|
||||
PASS verify:generated (was stub in M2; real implementation in M3)
|
||||
```
|
||||
|
||||
Overall exit: **0** — all checks green for the first time.
|
||||
|
||||
### What changed in M3
|
||||
|
||||
- `scripts/generate-skills.mjs` added (generator for all 31 agent-variant roots).
|
||||
- `scripts/verify-generated.mjs` added (drift detector).
|
||||
- Canonical source directories created: `skills/<skill>/_source/`,
|
||||
`skills/web-automation/shared/`.
|
||||
- All 31 generated roots now carry `.generated-manifest.json` and file-type-aware
|
||||
headers.
|
||||
- `package.json` renames: all generated agent-variant packages renamed to
|
||||
`@ai-coding-skills/<skill>-<agent>` with `"private": true`.
|
||||
- `pnpm-workspace.yaml` updated: M1 negative-glob exclusions replaced by
|
||||
positive includes for all uniquely-named generated variants.
|
||||
- Pre-existing ESLint violations fixed: `skill-manager-core.mjs:282`
|
||||
(`no-useless-assignment`) and `manage-skills.mjs:270` (`no-unused-vars`).
|
||||
- Pre-existing shellcheck findings fixed: SC2034 and SC2329 in
|
||||
`reviewer-runtime/run-review.sh`; SC2064 in test trap statements;
|
||||
SC2016 / SC2251 in verify scripts (suppress intentional patterns).
|
||||
- `pnpm run sync:pi` now calls the generator instead of
|
||||
`sync-pi-package-skills.sh`.
|
||||
- `docs/DEVELOPMENT.md` extended with generation workflow and metadata docs.
|
||||
- `CHANGELOG.md` created with package-metadata change callout.
|
||||
|
||||
### Full byte-equivalence diff (M3 vs pre-M3)
|
||||
|
||||
See `CHANGELOG.md` § "Byte-equivalence diff allow-list" for the complete
|
||||
documented diff between M3-generated output and the pre-M3 variants. The
|
||||
only permitted diffs are headers, `.generated-manifest.json`, `name` rename,
|
||||
and `"private": true`.
|
||||
|
||||
---
|
||||
|
||||
## 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).
|
||||
|
||||
---
|
||||
|
||||
## Post-M4 state
|
||||
|
||||
Captured: 2026-05-03 · Platform: macOS 15 (arm64) · Node 22.14.0 · pnpm 10.18.1
|
||||
|
||||
M4 extracted reusable abstractions, consolidated shared helpers, tightened
|
||||
types, and removed the legacy dead-code path. `pnpm run check` remains fully
|
||||
green.
|
||||
|
||||
### `pnpm run check` aggregate (post-M4)
|
||||
|
||||
```text
|
||||
PASS lint
|
||||
PASS typecheck
|
||||
PASS test
|
||||
PASS verify:pi
|
||||
PASS verify:reviewers
|
||||
PASS verify:docs
|
||||
PASS verify:generated
|
||||
```
|
||||
|
||||
Overall exit: **0** — all checks green (no regressions from M3).
|
||||
|
||||
### What changed in M4
|
||||
|
||||
- **S-401** — `scripts/lib/safe-replace-dir.mjs` added: Node.js helper that
|
||||
validates a target is a strict descendant of a safety root before replacing
|
||||
it. Thin shell wrapper `scripts/lib/safe-replace-dir.sh` provided for
|
||||
sourcing in shell scripts. `scripts/sync-pi-package-skills.sh` updated to
|
||||
use `safe_replace_dir` from the shared helper (inline `replace_dir` removed).
|
||||
|
||||
- **S-402** — `removeTarget(op)` extracted from `executeOperation()` in
|
||||
`scripts/lib/skill-manager-core.mjs` and exported. The helper handles
|
||||
skill, helper, and symlink removal with idempotent semantics.
|
||||
`executeOperation` now delegates to `removeTarget` for all remove branches.
|
||||
|
||||
- **S-403** — `skills/atlassian/shared/scripts/src/command-helpers.ts` added
|
||||
with `dryRunResponse<T>()` and `resolveFormat()` helpers. `confluence.ts`,
|
||||
`jira.ts`, and `raw.ts` consume `dryRunResponse` (8 inline objects removed).
|
||||
`cli.ts` imports `resolveFormat` from `command-helpers` instead of defining
|
||||
it locally. All atlassian agent variants regenerated.
|
||||
|
||||
- **S-404** — `skills/web-automation/shared/lib/browser.ts` created with
|
||||
`getProfilePath`, `launchBrowser`, and `getPage`. `browse.ts` imports and
|
||||
re-exports them. `auth.ts`, `flow.ts`, and `scan-local-app.ts` now import
|
||||
directly from `lib/browser.js`. Generator updated to include `lib/`
|
||||
directory in `scriptFiles` for web-automation variants. `tsconfig.json`
|
||||
updated to include `lib/**/*.ts`.
|
||||
|
||||
- **S-405** — `scan-local-app.ts` `page: any` parameters replaced with
|
||||
`Page` from `playwright-core`. Added `GotoError` discriminated type to
|
||||
narrow the `page.goto().catch()` union type safely.
|
||||
|
||||
- **S-406** — `scripts/sync-pi-package-skills.sh` deleted (retired in M3,
|
||||
inline `replace_dir` migrated to shared helper as part of S-401). Comment
|
||||
in `skill-manager-core.mjs` referencing the deleted file updated.
|
||||
Generator's `clearGeneratedRoot` fixed to preserve `node_modules` at all
|
||||
depths (was only protected at root level, causing pnpm workspace packages
|
||||
inside `scripts/` subdirs to lose their node_modules on regeneration).
|
||||
|
||||
- **S-407** — Tests added:
|
||||
- `scripts/tests/safe-replace-dir.test.mjs` (6 tests for S-401 helper)
|
||||
- `scripts/tests/skill-manager-core-remove.test.mjs` (5 tests for S-402)
|
||||
- `skills/atlassian/shared/scripts/tests/command-helpers.test.ts` (7 tests
|
||||
for S-403 `dryRunResponse` and `resolveFormat`)
|
||||
|
||||
### Test count (post-M4)
|
||||
|
||||
| Suite | Tests |
|
||||
|---|---|
|
||||
| `pnpm run test:installer` (root scripts) | 80 |
|
||||
| `atlassian/shared/scripts` | 29 |
|
||||
| **Total** | **109** |
|
||||
|
||||
---
|
||||
|
||||
## Final state (post-M5) — CLOSED
|
||||
|
||||
Captured: 2026-05-03 · Platform: macOS 15 (arm64) · Node 22.14.0 · pnpm 10.18.1
|
||||
|
||||
M5 added CI configuration, finalised documentation, closed out this baseline
|
||||
report, and locked in a permanently green `pnpm run check` gate. No
|
||||
pre-existing failures remain open.
|
||||
|
||||
### `pnpm run check` aggregate (post-M5 — macOS)
|
||||
|
||||
```text
|
||||
PASS lint
|
||||
PASS typecheck
|
||||
PASS test
|
||||
PASS verify:pi
|
||||
PASS verify:reviewers
|
||||
PASS verify:docs
|
||||
PASS verify:generated
|
||||
|
||||
All checks passed.
|
||||
```
|
||||
|
||||
Overall exit: **0** — all checks green (no regressions from M4).
|
||||
|
||||
### What changed in M5
|
||||
|
||||
- **S-501** — `.github/workflows/check.yml` added: matrix over `ubuntu-latest`
|
||||
and `macos-latest`; installs `shellcheck` (apt/brew), `ripgrep` (apt), pnpm,
|
||||
and Node.js 22; runs `pnpm run check`.
|
||||
- **S-501** — `.github/workflows/check-online.yml` added: weekly schedule +
|
||||
`workflow_dispatch`; runs `verify:docs:online` for full external link checking.
|
||||
- **S-502** — Root `README.md` gained a "Contributing / Development" section
|
||||
naming `pnpm run check` as the single quality gate and linking to
|
||||
`docs/DEVELOPMENT.md`.
|
||||
- **S-503** — `docs/DEVELOPMENT.md` finalised: added "Adding a new agent",
|
||||
"Adding a new skill", and "CI" sections; transitional contract replaced by
|
||||
the permanent M5 contract; baseline links updated.
|
||||
- **S-504** — This file (`docs/CLEANUP-BASELINE.md`) closed out with the
|
||||
"Final state" section.
|
||||
- **S-505** — Root `package.json` `files` list updated: `docs/DEVELOPMENT.md`
|
||||
and `docs/REVIEWERS.md` added.
|
||||
- **S-506** — `CHANGELOG.md` extended with the M5 consolidated entry.
|
||||
- **S-507** — Final `pnpm run check` run confirmed green (output above).
|
||||
|
||||
### Baseline status summary
|
||||
|
||||
Every pre-existing failure recorded in this document is now **resolved**.
|
||||
No waivers are required.
|
||||
|
||||
| Check | M1 status | Final status | Resolution |
|
||||
|-------|-----------|--------------|------------|
|
||||
| `lint` (ESLint) | FAIL — 2 errors | **PASS** | Fixed in M3 (S-302) |
|
||||
| `lint` (shellcheck) | FAIL — 7 findings | **PASS** | Fixed in M3 (S-302) |
|
||||
| `typecheck` | PASS | **PASS** | Never regressed |
|
||||
| `test` | PASS | **PASS** | Never regressed |
|
||||
| `verify:pi` | PASS | **PASS** | Portability hardened in M2 |
|
||||
| `verify:reviewers` | PASS | **PASS** | Never regressed |
|
||||
| `verify:docs` (markdownlint) | FAIL — 1160 errors | **PASS** | Fixed in M2 |
|
||||
| `verify:docs` (link-check) | PASS | **PASS** | Never regressed |
|
||||
| `verify:generated` | PASS (stub) | **PASS** | Real implementation in M3 |
|
||||
|
||||
### Ubuntu smoke test
|
||||
|
||||
The CI workflow (`.github/workflows/check.yml`) runs the same `pnpm run check`
|
||||
command on `ubuntu-latest`. This replaces the Docker one-liner that was the
|
||||
only documented Ubuntu smoke test path in M1–M4.
|
||||
|
||||
For local reproduction on Linux:
|
||||
|
||||
```bash
|
||||
# Requires Docker
|
||||
docker run --rm \
|
||||
-v "$PWD:/w" \
|
||||
-w /w \
|
||||
node:22-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 baseline report is now closed. Future regressions must be caught by CI
|
||||
and fixed before merge; they should NOT reopen this document.*
|
||||
+53
-27
@@ -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
|
||||
|
||||
@@ -109,7 +116,7 @@ Recommended full Pi package install:
|
||||
Manual single-skill Pi install from the package mirror:
|
||||
|
||||
```bash
|
||||
./scripts/sync-pi-package-skills.sh
|
||||
pnpm run sync:pi
|
||||
mkdir -p .pi/skills/create-plan
|
||||
cp -R pi-package/skills/create-plan/* .pi/skills/create-plan/
|
||||
mkdir -p .pi/skills/reviewer-runtime/pi
|
||||
@@ -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
|
||||
|
||||
@@ -0,0 +1,460 @@
|
||||
# Development Guide — ai-coding-skills
|
||||
|
||||
This document covers prerequisites, how to run checks locally, the quality
|
||||
tooling, the workspace policy, and the `pnpm run check` contract.
|
||||
|
||||
## Prerequisites
|
||||
|
||||
| Tool | Minimum version | Install |
|
||||
|------|----------------|---------|
|
||||
| Node.js | 20 | `fnm install 22` or `nvm install 22` |
|
||||
| pnpm | 10 | `npm install -g pnpm` |
|
||||
| `rg` (ripgrep) | any | `brew install ripgrep` / `apt-get install ripgrep` |
|
||||
| **shellcheck** | **any** | `brew install shellcheck` / `apt-get install shellcheck` |
|
||||
| `stat` (BSD or GNU) | any | pre-installed on macOS; GNU variant on Linux |
|
||||
| Python 3 | 3.8+ | pre-installed on most systems |
|
||||
|
||||
**`shellcheck` is required.** The `pnpm run lint` script will exit 2 with a
|
||||
clear error message if `shellcheck` is not on `PATH`. Every contributor must
|
||||
install it before running any quality checks.
|
||||
|
||||
## Quick start
|
||||
|
||||
```bash
|
||||
# Install dependencies (workspace-aware, no nested package.json modifications)
|
||||
pnpm install
|
||||
|
||||
# Run the full quality suite
|
||||
pnpm run check
|
||||
```
|
||||
|
||||
## Individual checks
|
||||
|
||||
| Command | What it does |
|
||||
|---------|-------------|
|
||||
| `pnpm run sync:pi` | Mirror pi skill variants into `pi-package/skills/` |
|
||||
| `pnpm run verify:pi` | Assert pi resource and workflow invariants |
|
||||
| `pnpm run verify:reviewers` | Assert reviewer-runtime skill invariants |
|
||||
| `pnpm run test:installer` | Run root-level Node.js unit tests (22 tests) |
|
||||
| `pnpm run lint` | ESLint on root scripts + shellcheck on all `.sh` files |
|
||||
| `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 + 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 verify:ci` | Assert CI workflow files carry no pnpm version pins (see [pnpm version pinning](#pnpm-version-pinning)) |
|
||||
| `pnpm run check` | Aggregate: run every gate above and report a summary |
|
||||
|
||||
## Quality tooling (added in M1)
|
||||
|
||||
### ESLint
|
||||
|
||||
Root-level flat config in `eslint.config.mjs`. Covers `scripts/**/*.mjs`
|
||||
and `scripts/**/*.js`. Uses `@eslint/js` recommended rules and Node.js
|
||||
globals. Nested workspace packages are responsible for their own ESLint
|
||||
configuration.
|
||||
|
||||
### Prettier
|
||||
|
||||
Config in `.prettierrc.json` (print-width 100, LF line endings). Ignore
|
||||
file at `.prettierignore` excludes generated agent-variant directories and
|
||||
`pnpm-lock.yaml`.
|
||||
|
||||
### markdownlint
|
||||
|
||||
Config in `.markdownlint.jsonc` (rules) and `.markdownlint-cli2.jsonc`
|
||||
(file globs and ignores). Key overrides vs defaults:
|
||||
|
||||
- `MD013` line-length relaxed to 120 chars (code blocks and tables excluded).
|
||||
- `MD033` (inline HTML) disabled.
|
||||
- `MD034` (bare URLs) disabled.
|
||||
- `MD041` (first-line heading) disabled.
|
||||
- `MD060` (table column style) disabled.
|
||||
|
||||
Run `pnpm run verify:docs` to lint all `README.md`, `docs/*.md`, and
|
||||
`skills/**/SKILL.md` files (node\_modules excluded automatically).
|
||||
|
||||
### markdown-link-check
|
||||
|
||||
Two configs:
|
||||
|
||||
- `markdown-link-check.json` — **offline** mode (default): ignores all
|
||||
`http://` and `https://` links. Safe for local dev and CI.
|
||||
- `markdown-link-check.online.json` — **online** mode: checks external links
|
||||
with a 10 s timeout, 2 retries, and retry-on-429. Use `--online` flag on
|
||||
`scripts/lib/run-link-check.mjs`.
|
||||
|
||||
`pnpm run verify:docs` uses the offline config by default.
|
||||
|
||||
### shellcheck
|
||||
|
||||
Wrapper script at `scripts/lib/run-shellcheck.mjs`. Discovers every `*.sh`
|
||||
file under `scripts/` and `skills/` (excluding node\_modules and generated
|
||||
agent-variant directories) and runs shellcheck on each.
|
||||
|
||||
**Installation:**
|
||||
|
||||
- macOS: `brew install shellcheck`
|
||||
- Debian/Ubuntu: `sudo apt-get install shellcheck`
|
||||
- Other: <https://github.com/koalaman/shellcheck#installing>
|
||||
|
||||
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.
|
||||
|
||||
## `check` contract (final — M5)
|
||||
|
||||
`pnpm run check` is **fully green** on a clean checkout with the documented
|
||||
prerequisites installed.
|
||||
|
||||
```text
|
||||
PASS lint
|
||||
PASS typecheck
|
||||
PASS test
|
||||
PASS verify:pi
|
||||
PASS verify:reviewers
|
||||
PASS verify:docs
|
||||
PASS verify:generated
|
||||
PASS verify:ci
|
||||
```
|
||||
|
||||
This is the only acceptable state for merge. Any failure on a check not in
|
||||
`docs/CLEANUP-BASELINE.md` is a regression and must be fixed before merge.
|
||||
|
||||
> **History:** In M1 the contract was transitional and allowed pre-existing
|
||||
> failures recorded in the baseline. M2 fixed `verify:docs`. M3 fixed
|
||||
> `lint` and promoted `verify:generated` from stub to real implementation.
|
||||
> M4 added abstractions without regressions. M5 added CI and finalized docs.
|
||||
> The baseline is now closed out — see `docs/CLEANUP-BASELINE.md`.
|
||||
|
||||
## pnpm workspace policy (updated in M3)
|
||||
|
||||
The `pnpm-workspace.yaml` at the repo root uses a **positive-include** policy
|
||||
introduced in M3. There are no negative-glob exclusions.
|
||||
|
||||
**Canonical source packages** (never generated):
|
||||
|
||||
- `skills/atlassian/shared/scripts` — shared Atlassian TypeScript runtime
|
||||
- `skills/web-automation/shared` — shared web-automation runtime template
|
||||
|
||||
**Generated agent-variant packages** (uniquely named, positively included):
|
||||
|
||||
- `skills/atlassian/{claude-code,codex,cursor,opencode,pi}/scripts`
|
||||
→ names `@ai-coding-skills/atlassian-{claude-code,codex,cursor,opencode,pi}`
|
||||
- `skills/web-automation/{claude-code,codex,cursor,opencode,pi}/scripts`
|
||||
→ names `@ai-coding-skills/web-automation-{claude-code,codex,cursor,opencode,pi}`
|
||||
- `pi-package/skills/atlassian/scripts`
|
||||
→ name `@ai-coding-skills/atlassian-pi-mirror`
|
||||
- `pi-package/skills/web-automation/scripts`
|
||||
→ name `@ai-coding-skills/web-automation-pi-mirror`
|
||||
|
||||
**Why unique names matter:**
|
||||
|
||||
Each package in a pnpm workspace must have a distinct `name` field. In M1 all
|
||||
generated agent-variant packages shared the same non-unique name as their
|
||||
canonical source package. In M3 every package receives a scoped unique name
|
||||
of the form `@ai-coding-skills/<skill>-<agent>`, enabling pnpm to include them
|
||||
alongside canonical source packages without conflicts. The pi-package mirrors
|
||||
use the `-mirror` suffix to distinguish them from the `pi` agent variants.
|
||||
|
||||
All generated packages are `"private": true` and are never published to any
|
||||
registry.
|
||||
|
||||
After `pnpm install`, `git status` should show zero modifications to any
|
||||
package.json file under any generated directory. If it does not, the workspace
|
||||
config or generator is broken.
|
||||
|
||||
## How to interpret the baseline report
|
||||
|
||||
See `docs/CLEANUP-BASELINE.md` for the historical as-is capture from M1. That
|
||||
baseline is now **closed** — all pre-existing failures have been resolved.
|
||||
When a CI run fails on any check it is a regression and must be fixed before
|
||||
merge.
|
||||
|
||||
## How variants are generated (M3)
|
||||
|
||||
Every agent-variant directory under `skills/<skill>/<agent>/` and every
|
||||
`pi-package/skills/<skill>/` mirror is **generator-owned**. Do not edit
|
||||
files inside these directories directly — edit the canonical source instead
|
||||
and run `pnpm run sync:pi` to regenerate.
|
||||
|
||||
### Canonical sources (non-generated)
|
||||
|
||||
These directories are **never** generated and are **never** inside a generated
|
||||
root. They are the single source of truth for all content.
|
||||
|
||||
| Skill | Canonical source |
|
||||
|-------|------------------|
|
||||
| `atlassian` | SKILL.md: `skills/atlassian/_source/<agent>/SKILL.md`; scripts: `skills/atlassian/shared/scripts/` |
|
||||
| `web-automation` | SKILL.md: `skills/web-automation/_source/<agent>/SKILL.md`; scripts: `skills/web-automation/shared/` |
|
||||
| `create-plan` | `skills/create-plan/_source/<agent>/` (SKILL.md + templates) |
|
||||
| `do-task` | `skills/do-task/_source/<agent>/` (SKILL.md + templates) |
|
||||
| `implement-plan` | `skills/implement-plan/_source/<agent>/SKILL.md` |
|
||||
| `reviewer-runtime` (base) | `skills/reviewer-runtime/run-review.sh`, `notify-telegram.sh` |
|
||||
|
||||
The `_source/` directories and `shared/` directories sit under the skill root
|
||||
**outside** every generated root. Stale-file detection (`verify:generated`)
|
||||
never traverses them.
|
||||
|
||||
### Generated roots (authoritative list)
|
||||
|
||||
All paths are relative to the repo root.
|
||||
|
||||
```text
|
||||
skills/atlassian/{claude-code,codex,cursor,opencode,pi}/
|
||||
skills/web-automation/{claude-code,codex,cursor,opencode,pi}/
|
||||
skills/create-plan/{claude-code,codex,cursor,opencode,pi}/
|
||||
skills/do-task/{claude-code,codex,cursor,opencode,pi}/
|
||||
skills/implement-plan/{claude-code,codex,cursor,opencode,pi}/
|
||||
skills/reviewer-runtime/pi/
|
||||
pi-package/skills/{atlassian,create-plan,do-task,implement-plan,web-automation}/
|
||||
```
|
||||
|
||||
### Contributor workflow
|
||||
|
||||
1. **Edit the canonical source** in the appropriate `_source/<agent>/`, `shared/`, or
|
||||
base `skills/reviewer-runtime/` directory.
|
||||
2. **Run the generator:**
|
||||
|
||||
```bash
|
||||
pnpm run sync:pi # regenerates all 31 generated roots
|
||||
```
|
||||
|
||||
3. **Verify no drift:**
|
||||
|
||||
```bash
|
||||
pnpm run verify:generated # must exit 0
|
||||
```
|
||||
|
||||
4. **Stage both the canonical source AND the generated output** in the same commit.
|
||||
Never commit a canonical change without regenerating.
|
||||
|
||||
### File-type-aware header policy
|
||||
|
||||
Every generated file (except JSON and `pnpm-lock.yaml`) receives a header
|
||||
identifying it as generated and pointing to the canonical source. Headers are
|
||||
inserted so they do not break parsers or tools:
|
||||
|
||||
| File type | Header form | Placement |
|
||||
|-----------|-------------|----------|
|
||||
| Markdown (with YAML front matter) | `<!-- ⚠️ GENERATED FILE ... -->` | After closing `---` |
|
||||
| Markdown (no front matter) | `<!-- ⚠️ GENERATED FILE ... -->` | Top of file |
|
||||
| Shell script | `# ⚠️ GENERATED FILE ...` | After `#!` shebang |
|
||||
| TypeScript / JavaScript | `// ⚠️ GENERATED FILE ...` | After `#!` shebang if present, else top |
|
||||
| YAML (non-lockfile) | `# ⚠️ GENERATED FILE ...` | Top of file |
|
||||
| JSON | *(no header — recorded in `.generated-manifest.json`)* | — |
|
||||
| `pnpm-lock.yaml` | *(no header — managed by pnpm)* | — |
|
||||
| JSONC | `// ⚠️ GENERATED FILE ...` | Top of file |
|
||||
|
||||
### `.generated-manifest.json` contract
|
||||
|
||||
Each generated root contains a `.generated-manifest.json` that:
|
||||
|
||||
- Has a `$schema` marker and a `generator` field for identification.
|
||||
- Lists every **other** generator-owned path in that root (relative path,
|
||||
file mode, SHA-256 hash, kind).
|
||||
- **Does NOT list itself** (non-self-referential).
|
||||
- Is scoped to exactly **one** generated root — there is no manifest at
|
||||
`skills/<skill>/`.
|
||||
- Is verified structurally (not byte-for-byte) by `verify:generated`.
|
||||
|
||||
### Package metadata (M3 change)
|
||||
|
||||
Each generated agent-variant `package.json` carries:
|
||||
|
||||
- A **unique private name** in the form `@ai-coding-skills/<skill>-<agent>` (e.g.
|
||||
`@ai-coding-skills/atlassian-claude-code`).
|
||||
- `"private": true` to prevent accidental npm publication.
|
||||
|
||||
The pi-package mirrors (`pi-package/skills/atlassian/scripts` and
|
||||
`pi-package/skills/web-automation/scripts`) use the `-mirror` agent suffix
|
||||
(`@ai-coding-skills/atlassian-pi-mirror`, `@ai-coding-skills/web-automation-pi-mirror`)
|
||||
to distinguish them from the `pi` agent variants in the workspace.
|
||||
|
||||
This replaces the previous non-unique `name` fields (`atlassian-skill-scripts`,
|
||||
`web-automation-scripts`). These packages are private and are never published.
|
||||
See `CHANGELOG.md` for the full rename list.
|
||||
|
||||
## Adding a new agent variant
|
||||
|
||||
To add support for a brand-new agent (e.g. `mynewagent`) across all skills:
|
||||
|
||||
1. **Create canonical source files** for every skill:
|
||||
|
||||
```bash
|
||||
mkdir -p skills/<skill>/_source/mynewagent
|
||||
# Add SKILL.md (copy and adapt from an existing agent variant)
|
||||
```
|
||||
|
||||
2. **Update the generator** (`scripts/generate-skills.mjs`):
|
||||
- Add `"mynewagent"` to the `AGENTS` array (or the per-skill agent list).
|
||||
- Ensure any agent-specific substitution logic is handled.
|
||||
|
||||
3. **Regenerate all variants:**
|
||||
|
||||
```bash
|
||||
pnpm run sync:pi
|
||||
pnpm run verify:generated # must exit 0
|
||||
```
|
||||
|
||||
4. **Update the workspace** (`pnpm-workspace.yaml`):
|
||||
- Add entries for every `skills/<skill>/mynewagent/scripts` package that
|
||||
has a `package.json` (e.g. atlassian and web-automation).
|
||||
|
||||
5. **Update documentation:**
|
||||
- Add a row to the skills table in `README.md`.
|
||||
- Add a row to the reviewer matrix in `docs/REVIEWERS.md` if the agent
|
||||
exposes a reviewer CLI.
|
||||
- Add an install guide at `docs/MYNEWAGENT.md` and link it from
|
||||
`docs/README.md`.
|
||||
- Add the doc file to the `files` list in root `package.json`.
|
||||
|
||||
6. **Verify the full suite:**
|
||||
|
||||
```bash
|
||||
pnpm install
|
||||
pnpm run check
|
||||
```
|
||||
|
||||
## Adding a new skill
|
||||
|
||||
To add an entirely new skill (e.g. `my-skill`):
|
||||
|
||||
1. **Create the canonical source tree:**
|
||||
|
||||
```bash
|
||||
mkdir -p skills/my-skill/_source/{claude-code,codex,cursor,opencode,pi}
|
||||
# Add SKILL.md to each _source/<agent>/ directory
|
||||
```
|
||||
|
||||
2. **Update the generator** (`scripts/generate-skills.mjs`):
|
||||
- Add `"my-skill"` to the `SKILLS` array.
|
||||
- Provide a `getSkillMeta(skill)` entry with agents list, source resolver,
|
||||
and any extra files to copy (templates, scripts, etc.).
|
||||
|
||||
3. **Regenerate:**
|
||||
|
||||
```bash
|
||||
pnpm run sync:pi
|
||||
pnpm run verify:generated
|
||||
```
|
||||
|
||||
4. **Add the pi-package entry** if the skill should be distributed via the
|
||||
Pi package:
|
||||
- Update `package.json` → `pi.skills` with the new path.
|
||||
- Update the `files` array to include the new skill directory.
|
||||
|
||||
5. **Write documentation** in `docs/MY-SKILL.md` and link from `docs/README.md`
|
||||
and the skills table in `README.md`.
|
||||
|
||||
6. **Run the full suite:** `pnpm run check`.
|
||||
|
||||
## CI
|
||||
|
||||
Two GitHub Actions workflows live in `.github/workflows/`:
|
||||
|
||||
| File | Trigger | Purpose |
|
||||
|------|---------|---------|
|
||||
| `check.yml` | push, pull_request (all branches) | Full `pnpm run check` on `ubuntu-latest` **and** `macos-latest`. Offline link-checking (no network dependency). |
|
||||
| `check-online.yml` | weekly schedule (Mon 09:00 UTC) + `workflow_dispatch` | `pnpm run verify:docs:online` with full external link checking. |
|
||||
|
||||
### What the `check` workflow does
|
||||
|
||||
1. Checks out the repository.
|
||||
2. Installs `shellcheck` via `apt-get` (Ubuntu) or `brew` (macOS).
|
||||
3. Installs `ripgrep` via `apt-get` (Ubuntu only; pre-installed on macOS runners).
|
||||
4. Installs Node.js 22 via `actions/setup-node`.
|
||||
5. Installs pnpm via `pnpm/action-setup@v4` — **no `version:` key is set**; the action reads the version from
|
||||
`package.json#packageManager` (currently `pnpm@10.18.1+sha512…`), which is the single source of truth.
|
||||
6. Runs `pnpm install --frozen-lockfile`.
|
||||
7. Runs `pnpm run check` (the same command contributors run locally).
|
||||
|
||||
The matrix runs both `ubuntu-latest` and `macos-latest` to guard against
|
||||
platform-specific regressions. Because M2 made all shell scripts portable
|
||||
across BSD and GNU coreutils, both runners should stay green.
|
||||
|
||||
### pnpm version pinning
|
||||
|
||||
The pnpm version is pinned **exclusively** in `package.json#packageManager`:
|
||||
|
||||
```json
|
||||
"packageManager": "pnpm@10.18.1+sha512.77a884a..."
|
||||
```
|
||||
|
||||
This field carries an exact version *and* an integrity hash, giving stronger
|
||||
reproducibility than a floating major like `version: "10"`. The
|
||||
`pnpm/action-setup@v4` step in `check.yml` reads this field automatically;
|
||||
do **not** add a `with.version` key to that step.
|
||||
|
||||
`pnpm run verify:ci` (backed by `scripts/lib/assert-no-pnpm-version-pin.mjs`)
|
||||
greps every `.github/workflows/*.yml` for `pnpm/action-setup` blocks that
|
||||
carry a `version:` key and fails if any are found. This prevents
|
||||
reintroduction of the conflict that caused `pnpm/action-setup@v4` to error.
|
||||
|
||||
### Adding new prerequisites to CI
|
||||
|
||||
If a new tool is required (e.g. a new binary called by a verify script),
|
||||
add the install step to **both** OS branches in `check.yml`. Document the
|
||||
new prerequisite in the Prerequisites table at the top of this file.
|
||||
|
||||
## Links
|
||||
|
||||
- [CLEANUP-BASELINE.md](./CLEANUP-BASELINE.md) — as-is quality baseline
|
||||
- [README.md](../README.md) — project overview
|
||||
- [docs/README.md](./README.md) — documentation index
|
||||
- [CHANGELOG.md](../CHANGELOG.md) — milestone-by-milestone change record
|
||||
- [.github/workflows/check.yml](../.github/workflows/check.yml) — CI workflow
|
||||
- [.github/workflows/check-online.yml](../.github/workflows/check-online.yml) — weekly online link check
|
||||
+140
-61
@@ -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
|
||||
|
||||
@@ -124,7 +151,7 @@ Recommended full Pi package install:
|
||||
Manual single-skill Pi install from the package mirror:
|
||||
|
||||
```bash
|
||||
./scripts/sync-pi-package-skills.sh
|
||||
pnpm run sync:pi
|
||||
mkdir -p .pi/skills/do-task
|
||||
cp -R pi-package/skills/do-task/* .pi/skills/do-task/
|
||||
mkdir -p .pi/skills/reviewer-runtime/pi
|
||||
@@ -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).
|
||||
|
||||
+71
-32
@@ -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
|
||||
|
||||
@@ -116,7 +124,7 @@ Recommended full Pi package install:
|
||||
Manual single-skill Pi install from the package mirror:
|
||||
|
||||
```bash
|
||||
./scripts/sync-pi-package-skills.sh
|
||||
pnpm run sync:pi
|
||||
mkdir -p .pi/skills/implement-plan
|
||||
cp -R pi-package/skills/implement-plan/* .pi/skills/implement-plan/
|
||||
mkdir -p .pi/skills/reviewer-runtime/pi
|
||||
@@ -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:
|
||||
|
||||
|
||||
+28
-14
@@ -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:
|
||||
|
||||
@@ -21,15 +22,18 @@ Related docs:
|
||||
|
||||
### Source Of Truth
|
||||
|
||||
Author Pi variants under:
|
||||
Edit the **canonical sources** under:
|
||||
|
||||
- `skills/atlassian/pi/`
|
||||
- `skills/create-plan/pi/`
|
||||
- `skills/do-task/pi/`
|
||||
- `skills/implement-plan/pi/`
|
||||
- `skills/web-automation/pi/`
|
||||
- `skills/atlassian/_source/pi/SKILL.md`
|
||||
- `skills/create-plan/_source/pi/` (SKILL.md + templates)
|
||||
- `skills/do-task/_source/pi/` (SKILL.md + templates)
|
||||
- `skills/implement-plan/_source/pi/SKILL.md`
|
||||
- `skills/web-automation/_source/pi/SKILL.md`
|
||||
|
||||
These are the directories to edit by hand.
|
||||
After editing a canonical source, run `pnpm run sync:pi` to regenerate all
|
||||
agent-variant directories including `skills/<family>/pi/` and the package mirrors.
|
||||
Do not edit the generated `skills/<family>/pi/` directories directly — they are
|
||||
overwritten by the generator.
|
||||
|
||||
### Package Mirror
|
||||
|
||||
@@ -41,7 +45,9 @@ The package exposes:
|
||||
- `pi-package/skills/implement-plan/`
|
||||
- `pi-package/skills/web-automation/`
|
||||
|
||||
Those directories are generated from the source variants by [`scripts/sync-pi-package-skills.sh`](../scripts/sync-pi-package-skills.sh).
|
||||
Those directories are generated from the canonical sources by
|
||||
[`scripts/generate-skills.mjs`](../scripts/generate-skills.mjs)
|
||||
(run via `pnpm run sync:pi`).
|
||||
|
||||
### Shared Setup Docs
|
||||
|
||||
@@ -92,7 +98,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:
|
||||
|
||||
@@ -101,7 +111,7 @@ The package surface intentionally ships:
|
||||
- `docs/PI*.md`
|
||||
- `scripts/install-pi-package.sh`
|
||||
- `scripts/manage-skills.mjs` and `scripts/manage-skills.sh`
|
||||
- `scripts/sync-pi-package-skills.sh`
|
||||
- `scripts/generate-skills.mjs`
|
||||
- `scripts/verify-pi-resources.sh`
|
||||
- `scripts/verify-pi-workflows.sh`
|
||||
- `scripts/verify-reviewer-support.sh`
|
||||
@@ -110,7 +120,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
|
||||
@@ -124,13 +135,16 @@ Global installs use `~/.pi/agent/skills/<skill>/` instead of `.pi/skills/<skill>
|
||||
When a source Pi variant changes:
|
||||
|
||||
```bash
|
||||
./scripts/sync-pi-package-skills.sh
|
||||
pnpm run sync:pi
|
||||
npm run verify:pi
|
||||
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:
|
||||
|
||||
|
||||
+63
-22
@@ -1,31 +1,72 @@
|
||||
# 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.
|
||||
|
||||
### 2. Per-Agent Manual Install
|
||||
|
||||
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, generation workflow, cross-platform shell support, and the
|
||||
quality contract.
|
||||
- [CLEANUP-BASELINE.md](./CLEANUP-BASELINE.md) — As-is quality baseline
|
||||
captured at M1, updated through subsequent milestones.
|
||||
- [../CHANGELOG.md](../CHANGELOG.md) — Milestone-by-milestone change record
|
||||
(includes M3 package-metadata rename table).
|
||||
|
||||
## 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.
|
||||
|
||||
@@ -89,7 +89,7 @@ Recommended full Pi package install:
|
||||
Manual single-skill Pi install from the package mirror:
|
||||
|
||||
```bash
|
||||
./scripts/sync-pi-package-skills.sh
|
||||
pnpm run sync:pi
|
||||
mkdir -p .pi/skills/web-automation
|
||||
cp -R pi-package/skills/web-automation/* .pi/skills/web-automation/
|
||||
cd .pi/skills/web-automation/scripts
|
||||
@@ -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:
|
||||
|
||||
|
||||
Reference in New Issue
Block a user