Perform code optimization and document cleanup (#1)
check / check (ubuntu-latest) (push) Successful in 2m5s
check / check (macos-latest) (push) Has been cancelled
check-online / check-online (ubuntu-latest) (push) Successful in 1m53s

## 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:
2026-05-04 04:41:34 +00:00
parent 2deab1c1b4
commit 251148c3ff
373 changed files with 28504 additions and 1281 deletions
@@ -0,0 +1,717 @@
---
name: create-plan
description: Use when starting a new feature, project, or complex task that needs structured planning with milestones, bite-sized stories, and resumable execution context in Opencode workflows. ALWAYS invoke when user says "create a plan", "make a plan", "plan this", "start planning", or similar planning requests.
---
# Create Plan (OpenCode)
Create and maintain a local plan folder under `ai_plan/` at project root.
## Prerequisite Check (MANDATORY)
This OpenCode variant depends on Superpowers skills being available through OpenCode's native skill system.
Required:
- Superpowers repo: `https://github.com/obra/superpowers`
- OpenCode Superpowers skills available at `~/.agents/skills/superpowers` or `~/.config/opencode/skills/superpowers`
- `superpowers/brainstorming`
- `superpowers/writing-plans`
Verify before proceeding:
```bash
test -f ~/.agents/skills/superpowers/brainstorming/SKILL.md || test -f ~/.config/opencode/skills/superpowers/brainstorming/SKILL.md
test -f ~/.agents/skills/superpowers/writing-plans/SKILL.md || test -f ~/.config/opencode/skills/superpowers/writing-plans/SKILL.md
```
If dependencies are missing, stop immediately and return:
"Missing dependency: OpenCode Superpowers skills are required (`superpowers/brainstorming`, `superpowers/writing-plans`). Install from https://github.com/obra/superpowers (OpenCode setup), then retry."
## Process
### Phase 1: Bootstrap Superpowers Context (REQUIRED)
Use OpenCode's native skill tool:
- list skills
- verify `superpowers/brainstorming` and `superpowers/writing-plans` are discoverable
### Phase 2: Analyze
- Explore the codebase and existing patterns.
### Phase 3: Gather Requirements
- Ask questions ONE AT A TIME until user says ready.
- Cover scope, constraints, success criteria, dependencies.
- Summarize before proceeding.
### Phase 4: Configure Reviewer
If the user has already specified a reviewer CLI and model (e.g., "create a plan, review with codex o4-mini"), use those values. Otherwise, ask:
1. **Which CLI should review the plan?**
- `codex` — OpenAI Codex CLI (`codex exec`)
- `claude` — Claude Code CLI (`claude -p`)
- `cursor` — Cursor Agent CLI (`cursor-agent -p`)
- `skip` — No external review, proceed directly to file generation
2. **Which model?** (only if a CLI was chosen)
- For `codex`: default `o4-mini`, alternatives: `gpt-5.3-codex`, `o3`
- For `claude`: default `sonnet`, alternatives: `opus`, `haiku`
- For `cursor`: **run `cursor-agent models` first** to see your account's available models (availability varies by subscription)
- Accept any model string the user provides
3. **Max review rounds for the plan?** (default: 10)
- If the user does not provide a value, set `MAX_ROUNDS=10`.
Store the chosen `REVIEWER_CLI`, `REVIEWER_MODEL`, and `MAX_ROUNDS` for Phase 7 (Iterative Plan Review).
Reviewer CLI: `codex`, `claude`, `cursor`, `opencode`, `pi`, or `skip`.
If `REVIEWER_CLI=pi`, verify the Pi reviewer binary before entering the review loop:
```bash
pi --version
```
For shorthand `pi/<pi-model-name>`, split only on the first slash when the prefix is exactly `pi`; store the complete remainder in `REVIEWER_MODEL`. Examples: `pi/claude-opus-4-7` -> `claude-opus-4-7`, `pi/anthropic/claude-opus-4-7` -> `anthropic/claude-opus-4-7`, and `pi/openrouter/anthropic/claude-opus-4-7` -> `openrouter/anthropic/claude-opus-4-7`.
When `REVIEWER_CLI=pi`, the reviewer model is configured independently from the model running this workflow. If the model/provider is unavailable, surface helper stderr/status and use `pi --list-models [search]` to inspect configured models.
### Phase 5: Design (REQUIRED SUB-SKILL)
Use OpenCode's native skill tool to load:
- `superpowers/brainstorming`
Then present 2-3 approaches and recommend one.
### Phase 6: Plan (REQUIRED SUB-SKILL)
Use OpenCode's native skill tool to load:
- `superpowers/writing-plans`
Then break into milestones and bite-sized stories (2-5 min each).
Story IDs: `S-{milestone}{sequence}`.
### Phase 7: Iterative Plan Review
Send the plan to the configured reviewer CLI for feedback. Revise and re-submit until approved (default max 10 rounds).
**Skip this phase entirely if reviewer was set to `skip`.**
#### Step 1: Generate Session ID
```bash
REVIEW_ID=$(uuidgen | tr '[:upper:]' '[:lower:]' | head -c 8)
```
Use for temp artifacts:
- `/tmp/plan-${REVIEW_ID}.md`
- `/tmp/plan-review-${REVIEW_ID}.md`
- `/tmp/plan-review-${REVIEW_ID}.json` (Cursor only)
- `/tmp/plan-review-${REVIEW_ID}.stderr`
- `/tmp/plan-review-${REVIEW_ID}.status`
- `/tmp/plan-review-${REVIEW_ID}.runner.out`
- `/tmp/plan-review-${REVIEW_ID}.sh`
Resolve the shared reviewer helper from the installed OpenCode skills directory:
```bash
REVIEWER_RUNTIME=~/.config/opencode/skills/reviewer-runtime/run-review.sh
```
Set helper success-artifact args before writing the command script:
```bash
HELPER_SUCCESS_FILE_ARGS=()
case "$REVIEWER_CLI" in
codex)
HELPER_SUCCESS_FILE_ARGS+=(--success-file /tmp/plan-review-${REVIEW_ID}.md)
;;
cursor)
HELPER_SUCCESS_FILE_ARGS+=(--success-file /tmp/plan-review-${REVIEW_ID}.json)
;;
opencode)
HELPER_SUCCESS_FILE_ARGS+=(--success-file /tmp/plan-review-${REVIEW_ID}.md)
;;
esac
```
#### Step 2: Write Plan to Temp File
Write the complete plan (milestones, stories, design decisions, specs) to `/tmp/plan-${REVIEW_ID}.md`.
#### Review Contract (Applies to Every Round)
The reviewer response must use this structure:
```text
## Summary
...
## Findings
### P0
- ...
### P1
- ...
### P2
- ...
### P3
- ...
## Verdict
VERDICT: APPROVED
```
Rules:
- Order findings from `P0` to `P3`.
- `P0` = total blocker, `P1` = major risk, `P2` = must-fix before approval, `P3` = cosmetic / nice to have.
- Use `- None.` when a severity has no findings.
- `VERDICT: APPROVED` is allowed only when no `P0`, `P1`, or `P2` findings remain. `P3` findings are non-blocking.
- The calling agent should still try to fix `P3` findings when they are cheap and safe.
#### Liveness Contract (Applies While Review Is Running)
- The shared reviewer runtime emits `state=in-progress note="In progress N"` heartbeats every 60 seconds while the reviewer child is alive.
- The calling agent must keep waiting as long as a fresh `In progress N` heartbeat keeps arriving roughly once per minute.
- Do not abort just because the review is slow, a soft timeout fired, or a `stall-warning` line appears, as long as the `In progress N` heartbeat continues.
- Treat missing heartbeats, `state=failed`, `state=completed-empty-output`, and `state=needs-operator-decision` as escalation signals.
#### Step 3: Submit to Reviewer (Round 1)
Write the reviewer invocation to `/tmp/plan-review-${REVIEW_ID}.sh` as a bash script:
```bash
#!/usr/bin/env bash
set -euo pipefail
```
**If `REVIEWER_CLI` is `pi`:**
Fresh call every round (Pi reviewer calls do not use session resume):
```bash
pi --no-session --no-skills --no-prompt-templates --no-extensions --no-context-files \
--model "$REVIEWER_MODEL" \
--tools read,grep,find,ls \
-p "Read the file /tmp/plan-${REVIEW_ID}.md and review. Return exactly the required ## Summary, ## Findings, and ## Verdict structure."
```
**If `REVIEWER_CLI` is `codex`:**
```bash
codex exec \
-m ${REVIEWER_MODEL} \
-s read-only \
-o /tmp/plan-review-${REVIEW_ID}.md \
"Review the implementation plan in /tmp/plan-${REVIEW_ID}.md. Focus on:
1. Correctness — Will this plan achieve the stated goals?
2. Risks — What could go wrong? Edge cases? Data loss?
3. Missing steps — Is anything forgotten?
4. Alternatives — Is there a simpler or better approach?
5. Security — Any security concerns?
Return exactly these sections in order:
## Summary
## Findings
### P0
### P1
### P2
### P3
## Verdict
Rules:
- Order findings from highest severity to lowest.
- Use `- None.` when a severity has no findings.
- `P0` = total blocker, `P1` = major risk, `P2` = must-fix before approval, `P3` = cosmetic / nice to have.
- End with exactly one verdict line: `VERDICT: APPROVED` or `VERDICT: REVISE`
- `VERDICT: APPROVED` is allowed only when there are no `P0`, `P1`, or `P2` findings. `P3` findings are non-blocking."
```
Do not try to capture the Codex session ID yet. When using the helper, extract it from `/tmp/plan-review-${REVIEW_ID}.runner.out` after the command completes (look for `session id: <uuid>`), then store it as `CODEX_SESSION_ID` for resume in subsequent rounds.
**If `REVIEWER_CLI` is `claude`:**
```bash
claude -p \
"Review the implementation plan below. Focus on:
$(cat /tmp/plan-${REVIEW_ID}.md)
1. Correctness — Will this plan achieve the stated goals?
2. Risks — What could go wrong? Edge cases? Data loss?
3. Missing steps — Is anything forgotten?
4. Alternatives — Is there a simpler or better approach?
5. Security — Any security concerns?
Return exactly these sections in order:
## Summary
## Findings
### P0
### P1
### P2
### P3
## Verdict
Rules:
- Order findings from highest severity to lowest.
- Use `- None.` when a severity has no findings.
- `P0` = total blocker, `P1` = major risk, `P2` = must-fix before approval, `P3` = cosmetic / nice to have.
- End with exactly one verdict line: `VERDICT: APPROVED` or `VERDICT: REVISE`
- `VERDICT: APPROVED` is allowed only when there are no `P0`, `P1`, or `P2` findings. `P3` findings are non-blocking." \
--model ${REVIEWER_MODEL} \
--strict-mcp-config \
--setting-sources user
```
**If `REVIEWER_CLI` is `cursor`:**
```bash
cursor-agent -p \
--mode=ask \
--model ${REVIEWER_MODEL} \
--trust \
--output-format json \
"Read the file /tmp/plan-${REVIEW_ID}.md and review the implementation plan. Focus on:
1. Correctness — Will this plan achieve the stated goals?
2. Risks — What could go wrong? Edge cases? Data loss?
3. Missing steps — Is anything forgotten?
4. Alternatives — Is there a simpler or better approach?
5. Security — Any security concerns?
Return exactly these sections in order:
## Summary
## Findings
### P0
### P1
### P2
### P3
## Verdict
Rules:
- Order findings from highest severity to lowest.
- Use `- None.` when a severity has no findings.
- `P0` = total blocker, `P1` = major risk, `P2` = must-fix before approval, `P3` = cosmetic / nice to have.
- End with exactly one verdict line: `VERDICT: APPROVED` or `VERDICT: REVISE`
- `VERDICT: APPROVED` is allowed only when there are no `P0`, `P1`, or `P2` findings. `P3` findings are non-blocking." \
> /tmp/plan-review-${REVIEW_ID}.json
```
For `cursor`, the command script writes raw JSON to `/tmp/plan-review-${REVIEW_ID}.json`. Do not run `jq` extraction until after the helper or fallback execution completes. If `jq` is not installed, inform the user: `brew install jq` (macOS) or equivalent.
**If `REVIEWER_CLI` is `opencode`:**
OpenCode uses `--agent plan` for read-oriented review. Fresh call is the recommended default.
Round 1:
```bash
opencode run \
-m ${REVIEWER_MODEL} \
--agent plan \
--format json \
"Read the file /tmp/plan-${REVIEW_ID}.md and review the implementation plan. Focus on:
1. Correctness — Will this plan achieve the stated goals?
2. Risks — What could go wrong? Edge cases? Data loss?
3. Missing steps — Is anything forgotten?
4. Alternatives — Is there a simpler or better approach?
5. Security — Any security concerns?
Return exactly these sections in order:
## Summary
## Findings
### P0
### P1
### P2
### P3
## Verdict
Rules:
- Order findings from highest severity to lowest.
- Use \`- None.\` when a severity has no findings.
- \`P0\` = total blocker, \`P1\` = major risk, \`P2\` = must-fix before approval, \`P3\` = cosmetic / nice to have.
- End with exactly one verdict line: \`VERDICT: APPROVED\` or \`VERDICT: REVISE\`
- \`VERDICT: APPROVED\` is allowed only when there are no \`P0\`, \`P1\`, or \`P2\` findings. \`P3\` findings are non-blocking." \
> /tmp/plan-review-${REVIEW_ID}.json
```
Round 2 and later (fresh-call, recommended default):
```bash
opencode run \
-m ${REVIEWER_MODEL} \
--agent plan \
--format json \
"You previously reviewed this plan and requested revisions.
Previous feedback summary: [key points from last review]
I've revised. Updated payload is in /tmp/plan-${REVIEW_ID}.md.
Changes made:
[List specific changes]
Re-review using the same ## Summary, ## Findings, and ## Verdict structure as before." \
> /tmp/plan-review-${REVIEW_ID}.json
```
Extract the review body:
```bash
jq -r '.[] | select(.type == "message" and .role == "assistant") | .content' \
/tmp/plan-review-${REVIEW_ID}.json \
> /tmp/plan-review-${REVIEW_ID}.md \
|| cp /tmp/plan-review-${REVIEW_ID}.json /tmp/plan-review-${REVIEW_ID}.md
```
If the JSON parse falls through, promote the raw JSON file as the review output. On any opencode
CLI or JSON parsing failure, treat this loop round as `completed-empty-output` and follow the
helper-failure escalation in Step 4.
Run the command script through the shared helper when available:
```bash
if [ -x "$REVIEWER_RUNTIME" ]; then
"$REVIEWER_RUNTIME" \
--command-file /tmp/plan-review-${REVIEW_ID}.sh \
--stdout-file /tmp/plan-review-${REVIEW_ID}.runner.out \
--stderr-file /tmp/plan-review-${REVIEW_ID}.stderr \
--status-file /tmp/plan-review-${REVIEW_ID}.status \
"${HELPER_SUCCESS_FILE_ARGS[@]}"
else
echo "Warning: reviewer runtime helper not found at $REVIEWER_RUNTIME; falling back to direct synchronous review." >&2
bash /tmp/plan-review-${REVIEW_ID}.sh >/tmp/plan-review-${REVIEW_ID}.runner.out 2>/tmp/plan-review-${REVIEW_ID}.stderr
fi
```
Run the helper in the foreground and watch its live stdout for `state=in-progress` heartbeats. If your agent environment buffers command output until exit, start the helper in the background and poll `/tmp/plan-review-${REVIEW_ID}.status` separately instead of treating heartbeats as post-hoc-only data.
After the command completes:
- If `REVIEWER_CLI=cursor`, extract the final review text:
```bash
CURSOR_SESSION_ID=$(jq -r '.session_id' /tmp/plan-review-${REVIEW_ID}.json)
jq -r '.result' /tmp/plan-review-${REVIEW_ID}.json > /tmp/plan-review-${REVIEW_ID}.md
```
- If `REVIEWER_CLI=codex`, extract `CODEX_SESSION_ID` from `/tmp/plan-review-${REVIEW_ID}.runner.out` after the helper or fallback run. If the review text is only in `.runner.out`, move or copy the actual review body into `/tmp/plan-review-${REVIEW_ID}.md` before verdict parsing.
- If `REVIEWER_CLI=opencode`, the `jq` extraction above covers output capture. If it falls through, copy runner output: `cp /tmp/plan-review-${REVIEW_ID}.runner.out /tmp/plan-review-${REVIEW_ID}.md`. On Round 1, also attempt to capture the session id for optional use in subsequent rounds: `OPENCODE_SESSION_ID=$(jq -r 'if type == "array" then (.[0] | (.id? // .session_id?)) else (.id? // .session_id?) end // empty' /tmp/plan-review-${REVIEW_ID}.json 2>/dev/null || true)`
- If `REVIEWER_CLI=claude` or `REVIEWER_CLI=pi`, promote stdout captured by the helper or fallback runner into the markdown review file:
```bash
cp /tmp/plan-review-${REVIEW_ID}.runner.out /tmp/plan-review-${REVIEW_ID}.md
```
#### Step 4: Read Review & Check Verdict
1. Read `/tmp/plan-review-${REVIEW_ID}.md`
2. If the review failed, produced empty output, or reached helper timeout, also read:
- `/tmp/plan-review-${REVIEW_ID}.stderr`
- `/tmp/plan-review-${REVIEW_ID}.status`
- `/tmp/plan-review-${REVIEW_ID}.runner.out`
3. Present review to the user:
```markdown
## Plan Review — Round N (reviewer: ${REVIEWER_CLI} / ${REVIEWER_MODEL})
[Reviewer feedback]
```
1. While the reviewer is still running, keep waiting as long as fresh `state=in-progress note="In progress N"` heartbeats continue to appear roughly once per minute.
2. Check verdict:
- **VERDICT: APPROVED** with no `P0`, `P1`, or `P2` findings → proceed to Phase 8 (Initialize workspace)
- **VERDICT: APPROVED** with only `P3` findings → optionally fix the `P3` items if they are cheap and safe, then proceed
- **VERDICT: REVISE** or any `P0`, `P1`, or `P2` finding → go to Step 5
- No clear verdict but `P0`, `P1`, and `P2` are all `- None.` → treat as approved
- Helper state `completed-empty-output` → treat as failed review attempt, surface stderr/status, fix invocation or prompt handling, then retry
- Helper state `needs-operator-decision` → surface status log and decide whether to extend the timeout, abort, or retry with different helper parameters
- Max rounds (`MAX_ROUNDS`) reached → present the outcome to the user for a manual decision (proceed or stop)
#### Step 5: Revise the Plan
Address the reviewer findings in priority order (`P0``P1``P2`, then `P3` when practical). Update the plan in conversation context and rewrite `/tmp/plan-${REVIEW_ID}.md`.
Summarize revisions for the user:
```markdown
### Revisions (Round N)
- [Change and reason, one bullet per issue addressed]
```
If a revision contradicts the user's explicit requirements, skip it and note it for the user.
#### Step 6: Re-submit to Reviewer (Rounds 2-N)
Rewrite `/tmp/plan-review-${REVIEW_ID}.sh` for the next round. The script should contain the reviewer invocation only; do not run it directly.
**If `REVIEWER_CLI` is `pi`:**
Fresh call with prior-round context (Pi reviewer calls do not use session resume):
```bash
pi --no-session --no-skills --no-prompt-templates --no-extensions --no-context-files \
--model "$REVIEWER_MODEL" \
--tools read,grep,find,ls \
-p "You previously reviewed this plan and requested revisions. Read the updated payload at /tmp/plan-${REVIEW_ID}.md and re-review using the same ## Summary, ## Findings, and ## Verdict structure."
```
**If `REVIEWER_CLI` is `codex`:**
Resume the existing session:
```bash
codex exec resume ${CODEX_SESSION_ID} \
-o /tmp/plan-review-${REVIEW_ID}.md \
"I've revised the plan based on your feedback. Updated plan is in /tmp/plan-${REVIEW_ID}.md.
Changes made:
[List specific changes]
Re-review using the same `## Summary`, `## Findings`, and `## Verdict` structure as before.
Keep findings ordered `P0` to `P3`, use `- None.` when a severity has no findings, and only use `VERDICT: APPROVED` when no `P0`, `P1`, or `P2` findings remain. `P3` findings are non-blocking."
```
If resume fails (session expired), fall back to fresh `codex exec` with context about prior rounds.
**If `REVIEWER_CLI` is `claude`:**
Fresh call with accumulated context (Claude CLI has no session resume):
```bash
claude -p \
"You previously reviewed an implementation plan and requested revisions.
Previous feedback summary: [key points from last review]
I've revised the plan. Updated version is below.
$(cat /tmp/plan-${REVIEW_ID}.md)
Changes made:
[List specific changes]
Re-review the full plan using the same `## Summary`, `## Findings`, and `## Verdict` structure as before.
Keep findings ordered `P0` to `P3`, use `- None.` when a severity has no findings, and only use `VERDICT: APPROVED` when no `P0`, `P1`, or `P2` findings remain. `P3` findings are non-blocking." \
--model ${REVIEWER_MODEL} \
--strict-mcp-config \
--setting-sources user
```
**If `REVIEWER_CLI` is `cursor`:**
Resume the existing session:
```bash
cursor-agent --resume ${CURSOR_SESSION_ID} -p \
--mode=ask \
--model ${REVIEWER_MODEL} \
--trust \
--output-format json \
"I've revised the plan based on your feedback. Updated plan is in /tmp/plan-${REVIEW_ID}.md.
Changes made:
[List specific changes]
Re-review using the same `## Summary`, `## Findings`, and `## Verdict` structure as before.
Keep findings ordered `P0` to `P3`, use `- None.` when a severity has no findings, and only use `VERDICT: APPROVED` when no `P0`, `P1`, or `P2` findings remain. `P3` findings are non-blocking." \
> /tmp/plan-review-${REVIEW_ID}.json
jq -r '.result' /tmp/plan-review-${REVIEW_ID}.json > /tmp/plan-review-${REVIEW_ID}.md
```
If resume fails, fall back to fresh `cursor-agent -p` with context about prior rounds.
**If `REVIEWER_CLI` is `opencode`:**
Fresh call (recommended default — opencode has no guaranteed stable session ID in headless mode):
```bash
opencode run \
-m ${REVIEWER_MODEL} \
--agent plan \
--format json \
"You previously reviewed this plan and requested revisions.
Previous feedback summary: [key points from last review]
I've revised. Updated payload is in /tmp/plan-${REVIEW_ID}.md.
Changes made:
[List specific changes]
Re-review using the same \`## Summary\`, \`## Findings\`, and \`## Verdict\` structure as before.
Keep findings ordered \`P0\` to \`P3\`, use \`- None.\` when a severity has no findings, and only use \`VERDICT: APPROVED\` when no \`P0\`, \`P1\`, or \`P2\` findings remain. \`P3\` findings are non-blocking." \
> /tmp/plan-review-${REVIEW_ID}.json
jq -r '.[] | select(.type == "message" and .role == "assistant") | .content' \
/tmp/plan-review-${REVIEW_ID}.json \
> /tmp/plan-review-${REVIEW_ID}.md \
|| cp /tmp/plan-review-${REVIEW_ID}.json /tmp/plan-review-${REVIEW_ID}.md
```
Optional session-resume path (only if `OPENCODE_SESSION_ID` was captured on Round 1 and your installed opencode accepts `-s <id>` reliably in headless mode):
```bash
opencode run \
-s ${OPENCODE_SESSION_ID} \
-m ${REVIEWER_MODEL} \
--agent plan \
--format json \
"I've revised the plan based on your feedback. Updated plan is in /tmp/plan-${REVIEW_ID}.md.
Changes made:
[List specific changes]
Re-review using the same \`## Summary\`, \`## Findings\`, and \`## Verdict\` structure as before.
Keep findings ordered \`P0\` to \`P3\`, use \`- None.\` when a severity has no findings, and only use \`VERDICT: APPROVED\` when no \`P0\`, \`P1\`, or \`P2\` findings remain. \`P3\` findings are non-blocking." \
> /tmp/plan-review-${REVIEW_ID}.json
jq -r '.[] | select(.type == "message" and .role == "assistant") | .content' \
/tmp/plan-review-${REVIEW_ID}.json \
> /tmp/plan-review-${REVIEW_ID}.md \
|| cp /tmp/plan-review-${REVIEW_ID}.json /tmp/plan-review-${REVIEW_ID}.md
```
If session resume fails (session expired or not supported), fall back to the fresh-call path above.
After updating `/tmp/plan-review-${REVIEW_ID}.sh`, run the same helper/fallback flow from Round 1.
Return to Step 4.
#### Step 7: Present Final Result
```markdown
## Plan Review — Final (reviewer: ${REVIEWER_CLI} / ${REVIEWER_MODEL})
**Status:** Approved after N round(s)
[or]
**Status:** Max rounds (`MAX_ROUNDS`) reached — not fully approved
[Final feedback / remaining concerns]
```
#### Step 8: Cleanup
```bash
rm -f /tmp/plan-${REVIEW_ID}.md \
/tmp/plan-review-${REVIEW_ID}.md \
/tmp/plan-review-${REVIEW_ID}.json \
/tmp/plan-review-${REVIEW_ID}.stderr \
/tmp/plan-review-${REVIEW_ID}.status \
/tmp/plan-review-${REVIEW_ID}.runner.out \
/tmp/plan-review-${REVIEW_ID}.sh
```
If the round failed, produced empty output, or reached operator-decision timeout, keep `.stderr`, `.status`, and `.runner.out` until the issue is diagnosed instead of deleting them immediately.
### Phase 8: Initialize Local Plan Workspace (MANDATORY)
At project root:
1. Ensure `ai_plan/` exists. Create it if missing.
2. Ensure `.gitignore` contains `/ai_plan/`.
3. If `.gitignore` was changed, commit that change immediately (local commit only).
Recommended commit message:
- `chore(gitignore): ignore ai_plan local planning artifacts`
### Phase 9: Generate Plan Files (MANDATORY)
Create `ai_plan/YYYY-MM-DD-<short-title>/` with ALL files:
1. `original-plan.md` - copy of original planner-generated plan.
2. `final-transcript.md` - copy of final planning transcript used to reach approved plan.
3. `milestone-plan.md` - full implementation spec (template-based).
4. `story-tracker.md` - status tracking (template-based, all stories start as `pending`).
5. `continuation-runbook.md` - resume context and execution protocol (template-based).
Use templates from this skill's `templates/` folder.
### Phase 10: Handoff
Always instruct the executing agent:
> Read `ai_plan/YYYY-MM-DD-<short-title>/continuation-runbook.md` first, then execute from `ai_plan` files only.
### Phase 11: Telegram Notification (MANDATORY)
Resolve the Telegram notifier helper from the installed OpenCode skills directory:
```bash
TELEGRAM_NOTIFY_RUNTIME=~/.config/opencode/skills/reviewer-runtime/notify-telegram.sh
```
On every terminal outcome for the create-plan run (approved, max rounds reached, skipped reviewer, or failure), send a Telegram summary if the helper exists and both `TELEGRAM_BOT_TOKEN` and `TELEGRAM_CHAT_ID` are configured:
```bash
if [ -x "$TELEGRAM_NOTIFY_RUNTIME" ] && [ -n "${TELEGRAM_BOT_TOKEN:-}" ] && [ -n "${TELEGRAM_CHAT_ID:-}" ]; then
"$TELEGRAM_NOTIFY_RUNTIME" --message "create-plan completed for <plan-folder-name>: <status summary>"
fi
```
Rules:
- Telegram is the only supported notification path. Do not use desktop notifications, `say`, email, or any other notifier.
- Notification failures are non-blocking, but they must be surfaced to the user.
- Before stopping for any user interaction, approval, or manual decision, send a Telegram summary first if configured.
- If Telegram is not configured, state that no Telegram notification was sent.
## Tracker Discipline (MANDATORY)
Before starting any story:
1. Open `story-tracker.md`
2. Mark story `in-dev`
3. Add notes if relevant
4. Then begin implementation
After completing any story:
1. Mark story `completed`
2. Add commit hash in Notes
3. Review pending stories
4. Update Last Updated and Stories Complete counts
## Execution Rules to Include in Plan (MANDATORY)
- Run lint/typecheck/tests after each milestone.
- Prefer linting changed files only for speed.
- Commit locally after each completed milestone (**do not push**).
- Stop and ask user for feedback.
- Apply feedback, rerun checks, and commit again.
- Move to next milestone only after user approval.
- After all milestones are completed and approved, ask permission to push.
- Only after approved push: mark plan as completed.
## Gitignore Note
`ai_plan/` is intentionally local and must stay gitignored. Do not treat inability to commit plan-file updates in `ai_plan/` as a problem.
## Verification Checklist
- [ ] `ai_plan/` exists at project root
- [ ] `.gitignore` includes `/ai_plan/`
- [ ] `.gitignore` ignore-rule commit was created if needed
- [ ] Plan directory created under `ai_plan/YYYY-MM-DD-<short-title>/`
- [ ] Reviewer configured or explicitly skipped
- [ ] Max review rounds confirmed (default: 10)
- [ ] Plan review completed (approved or max rounds) — or skipped
- [ ] `original-plan.md` present
- [ ] `final-transcript.md` present
- [ ] `milestone-plan.md` present
- [ ] `story-tracker.md` created with all stories as `pending`
- [ ] `continuation-runbook.md` present
- [ ] Handoff explicitly says to read runbook first and execute from plan folder
- [ ] Telegram notification attempted if configured
## Exit Triggers for Question Phase
User says: "ready", "done", "let's plan", "proceed", "enough questions"
@@ -0,0 +1,138 @@
# Continuation Runbook: [Plan Title]
## Reference Files (START HERE)
Upon resumption, these files in this folder are the ONLY source of truth:
| File | Purpose | When to Use |
|------|---------|-------------|
| `continuation-runbook.md` | Full context reproduction + execution workflow | Read FIRST |
| `story-tracker.md` | Current progress and status | Check/update BEFORE and AFTER every story |
| `milestone-plan.md` | Complete plan with specifications | Reference implementation details |
| `original-plan.md` | Original approved plan | Reference original intent |
| `final-transcript.md` | Final planning transcript | Reference reasoning/context |
Do NOT reference planner-private files during implementation.
---
## Quick Resume Instructions
1. Read this runbook completely.
2. Check `story-tracker.md`.
3. Find next `pending` story and mark as `in-dev` before starting.
4. Implement the story.
5. Update tracker immediately after each change.
---
## Mandatory Execution Workflow
Work from this folder (`ai_plan/YYYY-MM-DD-<short-title>/`) and always follow this order:
1. Read `continuation-runbook.md` first.
2. Execute stories milestone by milestone.
3. After completing a milestone:
- Run lint/typecheck/tests, prioritizing changed files for speed.
- Commit locally (**DO NOT PUSH**).
- Stop and ask user for feedback.
4. If feedback is provided:
- Apply feedback changes.
- Re-run checks for changed files.
- Commit locally again.
- Ask for milestone approval.
5. Only move to next milestone after explicit approval.
6. After all milestones are completed and approved:
- Ask permission to push.
- If approved, push.
- Mark plan status as `completed`.
---
## Git Note
`ai_plan/` is intentionally local and must stay gitignored. Do not treat inability to commit plan-file updates inside `ai_plan/` as an error.
---
## Full Context Reproduction
### Project Overview
[What this project/feature is about]
### User Requirements
[All gathered requirements]
### Scope
[In scope / out of scope]
### Dependencies
[External dependencies, prerequisites, related systems]
---
## Key Specifications
### Type Definitions
```typescript
// Copy-paste ready type definitions
```
### Enums & Constants
```typescript
// All enums/constants needed
```
### API Endpoints
```typescript
// Request/response shapes
```
---
## Critical Design Decisions
| Decision | Chosen Approach | Alternatives Rejected | Rationale |
|----------|-----------------|----------------------|-----------|
| [Topic] | [What we chose] | [Other options] | [Why] |
---
## Verification Commands
### Lint (changed files first)
```bash
# example: pnpm eslint <changed-file-1> <changed-file-2>
```
### Typecheck
```bash
# example: pnpm tsc --noEmit
```
### Tests (target changed scope first)
```bash
# example: pnpm test -- <related spec/file>
```
---
## File Quick Reference
| File | Purpose |
|------|---------|
| `original-plan.md` | Original approved plan |
| `final-transcript.md` | Final planning transcript |
| `milestone-plan.md` | Full specification |
| `story-tracker.md` | Current progress tracker |
| `continuation-runbook.md` | This runbook |
@@ -0,0 +1,118 @@
# [Plan Title]
## Overview
- **Goal:** [One sentence describing the end state]
- **Created:** YYYY-MM-DD
- **Status:** In Progress | Complete
## Context
### Requirements
[Gathered requirements from user questions]
### Constraints
[Technical, business, or timeline constraints]
### Success Criteria
[How we know this is complete]
## Architecture
### Design Decisions
[Key architectural choices and rationale]
### Component Relationships
[How pieces fit together]
### Data Flow
[How data moves through the system]
## Milestones
### M1: [Name]
**Description:** [What this milestone achieves]
**Acceptance Criteria:**
- [ ] [Criterion 1]
- [ ] [Criterion 2]
**Stories:** S-101, S-102, S-103...
**Milestone Completion Rule (MANDATORY):**
- Run lint/typecheck/tests for changed files.
- Commit locally (DO NOT push).
- Stop and ask user for feedback.
- Apply feedback, re-check changed files, commit again.
- Move to next milestone only after user approval.
---
### M2: [Name]
**Description:** [What this milestone achieves]
**Acceptance Criteria:**
- [ ] [Criterion 1]
- [ ] [Criterion 2]
**Stories:** S-201, S-202, S-203...
**Milestone Completion Rule (MANDATORY):**
- Run lint/typecheck/tests for changed files.
- Commit locally (DO NOT push).
- Stop and ask user for feedback.
- Apply feedback, re-check changed files, commit again.
- Move to next milestone only after user approval.
---
## Technical Specifications
### Types & Interfaces
```typescript
// Key type definitions
```
### API Contracts
```typescript
// Endpoint signatures, request/response shapes
```
### Constants & Enums
```typescript
// Shared constants
```
## Files Inventory
| File | Purpose | Milestone |
|------|---------|-----------|
| `path/to/file.ts` | [What it does] | M1 |
| `path/to/other.ts` | [What it does] | M2 |
---
## Related Plan Files
This file is part of the plan folder under `ai_plan/`:
- `original-plan.md` - Original approved plan (reference for original intent)
- `final-transcript.md` - Final planning transcript (reference for rationale/context)
- `milestone-plan.md` - This file (full specification)
- `story-tracker.md` - Status tracking (must be kept up to date)
- `continuation-runbook.md` - Resume/execution context (read first)
@@ -0,0 +1,71 @@
# Story Tracker: [Plan Title]
## Progress Summary
- **Current Milestone:** M1
- **Stories Complete:** 0/N
- **Milestones Approved:** 0/M
- **Last Updated:** YYYY-MM-DD
---
## Milestones
### M1: [Name]
| Story | Description | Status | Notes |
|-------|-------------|--------|-------|
| S-101 | [Brief description] | pending | |
| S-102 | [Brief description] | pending | |
| S-103 | [Brief description] | pending | |
**Approval Status:** pending
---
### M2: [Name]
| Story | Description | Status | Notes |
|-------|-------------|--------|-------|
| S-201 | [Brief description] | pending | |
| S-202 | [Brief description] | pending | |
| S-203 | [Brief description] | pending | |
**Approval Status:** pending
---
## Status Legend
| Status | Meaning |
|--------|---------|
| `pending` | Not started |
| `in-dev` | Currently being worked on |
| `completed` | Done - include commit hash in Notes |
| `deferred` | Postponed - include reason in Notes |
## Update Instructions (MANDATORY)
Before starting any story:
1. Mark story as `in-dev`
2. Update "Last Updated"
After completing any story:
1. Mark story as `completed`
2. Add local commit hash to Notes
3. Update "Stories Complete" and "Last Updated"
At milestone boundary:
1. Run lint/typecheck/tests for changed files
2. Commit (no push)
3. Request feedback
4. Apply feedback, re-check changed files, commit again
5. Mark milestone **Approval Status: approved** only after user confirms
6. Continue only after approval
After all milestones approved:
- Ask permission to push and then mark plan completed.