feat(M2): Documentation flow, accuracy, consistency cleanup, and cross-platform shell portability
This commit is contained in:
Stefano Fiorini
@@ -0,0 +1,20 @@
|
||||
// markdownlint configuration — skills/ (M2)
|
||||
//
|
||||
// Agent-facing SKILL.md files and plan templates contain verbose prose and
|
||||
// long shell commands where a strict line-length limit is counterproductive.
|
||||
// This file inherits the root config and then overrides the two rules that
|
||||
// produce false positives in agent-facing content.
|
||||
{
|
||||
// Inherit root-level rules
|
||||
"extends": "../.markdownlint.jsonc",
|
||||
|
||||
// MD013 — line length: disabled for skill files.
|
||||
// Shell commands, long option lists, and URL references commonly exceed 120
|
||||
// chars and wrapping them would break copy-paste usability.
|
||||
"MD013": false,
|
||||
|
||||
// MD024 — duplicate headings: disabled for skill files.
|
||||
// SKILL.md files intentionally use repeated per-agent section headings
|
||||
// (e.g. "### Claude Code", "### Codex") in separate variant sections.
|
||||
"MD024": false
|
||||
}
|
||||
@@ -12,6 +12,7 @@ Create and maintain a local plan folder under `ai_plan/` at project root.
|
||||
This Claude Code variant depends on Superpowers planning skills and explicit sub-skill invocation.
|
||||
|
||||
Required:
|
||||
|
||||
- Superpowers repo: `https://github.com/obra/superpowers`
|
||||
- `brainstorming` skill
|
||||
- `writing-plans` skill
|
||||
@@ -23,10 +24,12 @@ If any dependency is missing, stop immediately and return:
|
||||
## Process
|
||||
|
||||
### Phase 1: Analyze
|
||||
|
||||
- Explore the codebase with exploration agents.
|
||||
- Understand existing patterns and context.
|
||||
|
||||
### Phase 2: Gather Requirements
|
||||
|
||||
- Ask questions ONE AT A TIME until user says ready.
|
||||
- Cover scope, constraints, success criteria, dependencies.
|
||||
- Summarize before proceeding.
|
||||
@@ -45,7 +48,6 @@ For shorthand `pi/<pi-model-name>`, split only on the first slash when the prefi
|
||||
|
||||
When `REVIEWER_CLI=pi`, the reviewer model is configured independently from the model running this workflow. If the model/provider is unavailable, surface helper stderr/status and use `pi --list-models [search]` to inspect configured models.
|
||||
|
||||
|
||||
If the user has already specified a reviewer CLI and model (e.g., "create a plan, review with codex o4-mini"), use those values. Otherwise, ask:
|
||||
|
||||
1. **Which CLI should review the plan?**
|
||||
@@ -66,11 +68,13 @@ If the user has already specified a reviewer CLI and model (e.g., "create a plan
|
||||
Store the chosen `REVIEWER_CLI`, `REVIEWER_MODEL`, and `MAX_ROUNDS` for Phase 6 (Iterative Plan Review).
|
||||
|
||||
### Phase 4: Design (REQUIRED SUB-SKILL)
|
||||
|
||||
- Invoke `superpowers:brainstorming` explicitly.
|
||||
- Present 2-3 approaches and recommend one.
|
||||
- Validate design in sections.
|
||||
|
||||
### Phase 5: Plan (REQUIRED SUB-SKILL)
|
||||
|
||||
- Invoke `superpowers:writing-plans` explicitly.
|
||||
- Break into milestones and bite-sized stories (2-5 min each).
|
||||
- Story IDs: `S-{milestone}{sequence}`.
|
||||
@@ -88,6 +92,7 @@ REVIEW_ID=$(uuidgen | tr '[:upper:]' '[:lower:]' | head -c 8)
|
||||
```
|
||||
|
||||
Use for temp artifacts:
|
||||
|
||||
- `/tmp/plan-${REVIEW_ID}.md`
|
||||
- `/tmp/plan-review-${REVIEW_ID}.md`
|
||||
- `/tmp/plan-review-${REVIEW_ID}.json` (Cursor only)
|
||||
@@ -143,6 +148,7 @@ VERDICT: APPROVED
|
||||
```
|
||||
|
||||
Rules:
|
||||
|
||||
- Order findings from `P0` to `P3`.
|
||||
- `P0` = total blocker, `P1` = major risk, `P2` = must-fix before approval, `P3` = cosmetic / nice to have.
|
||||
- Use `- None.` when a severity has no findings.
|
||||
@@ -165,7 +171,6 @@ Write the reviewer invocation to `/tmp/plan-review-${REVIEW_ID}.sh` as a bash sc
|
||||
set -euo pipefail
|
||||
```
|
||||
|
||||
|
||||
**If `REVIEWER_CLI` is `pi`:**
|
||||
|
||||
Fresh call every round (Pi reviewer calls do not use session resume):
|
||||
@@ -298,6 +303,7 @@ fi
|
||||
Run the helper in the foreground and watch its live stdout for `state=in-progress` heartbeats. If your agent environment buffers command output until exit, start the helper in the background and poll `/tmp/plan-review-${REVIEW_ID}.status` separately instead of treating heartbeats as post-hoc-only data.
|
||||
|
||||
After the command completes:
|
||||
|
||||
- If `REVIEWER_CLI=cursor`, extract the final review text:
|
||||
|
||||
```bash
|
||||
@@ -323,14 +329,14 @@ Fallback is allowed only when the helper is missing or not executable.
|
||||
- `/tmp/plan-review-${REVIEW_ID}.runner.out`
|
||||
3. Present review to the user:
|
||||
|
||||
```
|
||||
```markdown
|
||||
## Plan Review — Round N (reviewer: ${REVIEWER_CLI} / ${REVIEWER_MODEL})
|
||||
|
||||
[Reviewer feedback]
|
||||
```
|
||||
|
||||
4. While the reviewer is still running, keep waiting as long as fresh `state=in-progress note="In progress N"` heartbeats continue to appear roughly once per minute.
|
||||
5. Check verdict:
|
||||
1. While the reviewer is still running, keep waiting as long as fresh `state=in-progress note="In progress N"` heartbeats continue to appear roughly once per minute.
|
||||
2. Check verdict:
|
||||
- **VERDICT: APPROVED** with no `P0`, `P1`, or `P2` findings → proceed to Phase 7 (Initialize workspace)
|
||||
- **VERDICT: APPROVED** with only `P3` findings → optionally fix the `P3` items if they are cheap and safe, then proceed
|
||||
- **VERDICT: REVISE** or any `P0`, `P1`, or `P2` finding → go to Step 5
|
||||
@@ -345,7 +351,7 @@ Address the reviewer findings in priority order (`P0` → `P1` → `P2`, then `P
|
||||
|
||||
Summarize revisions for the user:
|
||||
|
||||
```
|
||||
```markdown
|
||||
### Revisions (Round N)
|
||||
- [Change and reason, one bullet per issue addressed]
|
||||
```
|
||||
@@ -356,7 +362,6 @@ If a revision contradicts the user's explicit requirements, skip it and note it
|
||||
|
||||
Rewrite `/tmp/plan-review-${REVIEW_ID}.sh` for the next round. The script should contain the reviewer invocation only; do not run it directly.
|
||||
|
||||
|
||||
**If `REVIEWER_CLI` is `pi`:**
|
||||
|
||||
Fresh call with prior-round context (Pi reviewer calls do not use session resume):
|
||||
@@ -440,7 +445,7 @@ Return to Step 4.
|
||||
|
||||
#### Step 7: Present Final Result
|
||||
|
||||
```
|
||||
```markdown
|
||||
## Plan Review — Final (reviewer: ${REVIEWER_CLI} / ${REVIEWER_MODEL})
|
||||
|
||||
**Status:** Approved after N round(s)
|
||||
@@ -467,21 +472,25 @@ If the round failed, produced empty output, or reached operator-decision timeout
|
||||
### Phase 7: Initialize Local Plan Workspace (MANDATORY)
|
||||
|
||||
At project root:
|
||||
|
||||
1. Ensure `ai_plan/` exists. Create it if missing.
|
||||
2. Ensure `.gitignore` contains `/ai_plan/`.
|
||||
3. If `.gitignore` was changed, commit that change immediately (local commit only).
|
||||
|
||||
Recommended commit message:
|
||||
|
||||
- `chore(gitignore): ignore ai_plan local planning artifacts`
|
||||
|
||||
### Phase 8: Generate Plan Files (MANDATORY - DO NOT SKIP)
|
||||
|
||||
**PLAN MODE CHECK:** If currently in plan mode:
|
||||
|
||||
1. Inform user that plan files cannot be written while in plan mode.
|
||||
2. Instruct user to exit plan mode (approve plan or use ExitPlanMode).
|
||||
3. Proceed with file generation only after exiting plan mode.
|
||||
|
||||
Create `ai_plan/YYYY-MM-DD-<short-title>/` with ALL files:
|
||||
|
||||
1. `original-plan.md` - Copy the plan file from `~/.claude/plans/` as-is.
|
||||
2. `final-transcript.md` - Copy of final planning transcript for reference.
|
||||
3. `milestone-plan.md` - Full specification (template-based).
|
||||
@@ -514,6 +523,7 @@ fi
|
||||
```
|
||||
|
||||
Rules:
|
||||
|
||||
- Telegram is the only supported notification path. Do not use desktop notifications, `say`, email, or any other notifier.
|
||||
- Notification failures are non-blocking, but they must be surfaced to the user.
|
||||
- Before stopping for any user interaction, approval, or manual decision, send a Telegram summary first if configured.
|
||||
@@ -524,12 +534,14 @@ Rules:
|
||||
**ALWAYS update `story-tracker.md` before/after each story. NEVER proceed with stale tracker state.**
|
||||
|
||||
Before starting any story:
|
||||
|
||||
1. Open `story-tracker.md`
|
||||
2. Mark story `in-dev`
|
||||
3. Add notes if relevant
|
||||
4. Then begin implementation
|
||||
|
||||
After completing any story:
|
||||
|
||||
1. Mark story `completed`
|
||||
2. Add commit hash in Notes
|
||||
3. Review pending stories
|
||||
@@ -568,4 +580,5 @@ After completing any story:
|
||||
- [ ] Telegram notification attempted if configured
|
||||
|
||||
## Exit Triggers for Question Phase
|
||||
|
||||
User says: "ready", "done", "let's plan", "proceed", "enough questions"
|
||||
|
||||
@@ -58,15 +58,19 @@ Work from this folder (`ai_plan/YYYY-MM-DD-<short-title>/`) and always follow th
|
||||
## Full Context Reproduction
|
||||
|
||||
### Project Overview
|
||||
|
||||
[What this project/feature is about]
|
||||
|
||||
### User Requirements
|
||||
|
||||
[All gathered requirements]
|
||||
|
||||
### Scope
|
||||
|
||||
[In scope / out of scope]
|
||||
|
||||
### Dependencies
|
||||
|
||||
[External dependencies, prerequisites, related systems]
|
||||
|
||||
---
|
||||
@@ -74,16 +78,19 @@ Work from this folder (`ai_plan/YYYY-MM-DD-<short-title>/`) and always follow th
|
||||
## Key Specifications
|
||||
|
||||
### Type Definitions
|
||||
|
||||
```typescript
|
||||
// Copy-paste ready type definitions
|
||||
```
|
||||
|
||||
### Enums & Constants
|
||||
|
||||
```typescript
|
||||
// All enums/constants needed
|
||||
```
|
||||
|
||||
### API Endpoints
|
||||
|
||||
```typescript
|
||||
// Request/response shapes
|
||||
```
|
||||
@@ -101,16 +108,19 @@ Work from this folder (`ai_plan/YYYY-MM-DD-<short-title>/`) and always follow th
|
||||
## Verification Commands
|
||||
|
||||
### Lint (changed files first)
|
||||
|
||||
```bash
|
||||
# example: pnpm eslint <changed-file-1> <changed-file-2>
|
||||
```
|
||||
|
||||
### Typecheck
|
||||
|
||||
```bash
|
||||
# example: pnpm tsc --noEmit
|
||||
```
|
||||
|
||||
### Tests (target changed scope first)
|
||||
|
||||
```bash
|
||||
# example: pnpm test -- <related spec/file>
|
||||
```
|
||||
|
||||
@@ -1,6 +1,7 @@
|
||||
# [Plan Title]
|
||||
|
||||
## Overview
|
||||
|
||||
- **Goal:** [One sentence describing the end state]
|
||||
- **Created:** YYYY-MM-DD
|
||||
- **Status:** In Progress | Complete
|
||||
@@ -8,37 +9,46 @@
|
||||
## Context
|
||||
|
||||
### Requirements
|
||||
|
||||
[Gathered requirements from user questions]
|
||||
|
||||
### Constraints
|
||||
|
||||
[Technical, business, or timeline constraints]
|
||||
|
||||
### Success Criteria
|
||||
|
||||
[How we know this is complete]
|
||||
|
||||
## Architecture
|
||||
|
||||
### Design Decisions
|
||||
|
||||
[Key architectural choices and rationale]
|
||||
|
||||
### Component Relationships
|
||||
|
||||
[How pieces fit together]
|
||||
|
||||
### Data Flow
|
||||
|
||||
[How data moves through the system]
|
||||
|
||||
## Milestones
|
||||
|
||||
### M1: [Name]
|
||||
|
||||
**Description:** [What this milestone achieves]
|
||||
|
||||
**Acceptance Criteria:**
|
||||
|
||||
- [ ] [Criterion 1]
|
||||
- [ ] [Criterion 2]
|
||||
|
||||
**Stories:** S-101, S-102, S-103...
|
||||
|
||||
**Milestone Completion Rule (MANDATORY):**
|
||||
|
||||
- Run lint/typecheck/tests for changed files.
|
||||
- Commit locally (DO NOT push).
|
||||
- Stop and ask user for feedback.
|
||||
@@ -48,15 +58,18 @@
|
||||
---
|
||||
|
||||
### M2: [Name]
|
||||
|
||||
**Description:** [What this milestone achieves]
|
||||
|
||||
**Acceptance Criteria:**
|
||||
|
||||
- [ ] [Criterion 1]
|
||||
- [ ] [Criterion 2]
|
||||
|
||||
**Stories:** S-201, S-202, S-203...
|
||||
|
||||
**Milestone Completion Rule (MANDATORY):**
|
||||
|
||||
- Run lint/typecheck/tests for changed files.
|
||||
- Commit locally (DO NOT push).
|
||||
- Stop and ask user for feedback.
|
||||
@@ -68,16 +81,19 @@
|
||||
## Technical Specifications
|
||||
|
||||
### Types & Interfaces
|
||||
|
||||
```typescript
|
||||
// Key type definitions
|
||||
```
|
||||
|
||||
### API Contracts
|
||||
|
||||
```typescript
|
||||
// Endpoint signatures, request/response shapes
|
||||
```
|
||||
|
||||
### Constants & Enums
|
||||
|
||||
```typescript
|
||||
// Shared constants
|
||||
```
|
||||
@@ -94,6 +110,7 @@
|
||||
## Related Plan Files
|
||||
|
||||
This file is part of the plan folder under `ai_plan/`:
|
||||
|
||||
- `original-plan.md` - Original approved plan (reference for original intent)
|
||||
- `final-transcript.md` - Final planning transcript (reference for rationale/context)
|
||||
- `milestone-plan.md` - This file (full specification)
|
||||
|
||||
@@ -1,6 +1,7 @@
|
||||
# Story Tracker: [Plan Title]
|
||||
|
||||
## Progress Summary
|
||||
|
||||
- **Current Milestone:** M1
|
||||
- **Stories Complete:** 0/N
|
||||
- **Milestones Approved:** 0/M
|
||||
@@ -46,15 +47,18 @@
|
||||
## Update Instructions (MANDATORY)
|
||||
|
||||
Before starting any story:
|
||||
|
||||
1. Mark story as `in-dev`
|
||||
2. Update "Last Updated"
|
||||
|
||||
After completing any story:
|
||||
|
||||
1. Mark story as `completed`
|
||||
2. Add local commit hash to Notes
|
||||
3. Update "Stories Complete" and "Last Updated"
|
||||
|
||||
At milestone boundary:
|
||||
|
||||
1. Run lint/typecheck/tests for changed files
|
||||
2. Commit (no push)
|
||||
3. Request feedback
|
||||
@@ -63,4 +67,5 @@ At milestone boundary:
|
||||
6. Continue only after approval
|
||||
|
||||
After all milestones approved:
|
||||
|
||||
- Ask permission to push and then mark plan completed.
|
||||
|
||||
@@ -10,6 +10,7 @@ Create and maintain a local plan workspace under `ai_plan/` at project root.
|
||||
## Overview
|
||||
|
||||
This skill wraps the current Superpowers flow for Codex:
|
||||
|
||||
1. Design first with `superpowers:brainstorming`
|
||||
2. Then build an implementation plan with `superpowers:writing-plans`
|
||||
3. Review the plan iteratively with a second model/provider
|
||||
@@ -20,6 +21,7 @@ This skill wraps the current Superpowers flow for Codex:
|
||||
## Prerequisite Check (MANDATORY)
|
||||
|
||||
Required:
|
||||
|
||||
- Superpowers skills symlink: `~/.agents/skills/superpowers -> ~/.codex/superpowers/skills`
|
||||
- `superpowers:brainstorming`
|
||||
- `superpowers:writing-plans`
|
||||
@@ -50,9 +52,11 @@ If any dependency is missing, stop and return:
|
||||
## Process
|
||||
|
||||
### Phase 1: Analyze
|
||||
|
||||
- Explore the codebase and existing patterns.
|
||||
|
||||
### Phase 2: Gather Requirements
|
||||
|
||||
- Ask questions one at a time until user says ready.
|
||||
- Confirm scope, constraints, success criteria, dependencies.
|
||||
|
||||
@@ -70,7 +74,6 @@ For shorthand `pi/<pi-model-name>`, split only on the first slash when the prefi
|
||||
|
||||
When `REVIEWER_CLI=pi`, the reviewer model is configured independently from the model running this workflow. If the model/provider is unavailable, surface helper stderr/status and use `pi --list-models [search]` to inspect configured models.
|
||||
|
||||
|
||||
If the user has already specified a reviewer CLI and model (e.g., "create a plan, review with claude sonnet"), use those values. Otherwise, ask:
|
||||
|
||||
1. **Which CLI should review the plan?**
|
||||
@@ -111,6 +114,7 @@ REVIEW_ID=$(uuidgen | tr '[:upper:]' '[:lower:]' | head -c 8)
|
||||
```
|
||||
|
||||
Use for temp artifacts:
|
||||
|
||||
- `/tmp/plan-${REVIEW_ID}.md` - plan payload
|
||||
- `/tmp/plan-review-${REVIEW_ID}.md` - normalized review text presented to the user
|
||||
- `/tmp/plan-review-${REVIEW_ID}.json` - raw Cursor JSON (only for `cursor`)
|
||||
@@ -166,6 +170,7 @@ VERDICT: APPROVED
|
||||
```
|
||||
|
||||
Rules:
|
||||
|
||||
- Order findings from `P0` to `P3`.
|
||||
- `P0` = total blocker, `P1` = major risk, `P2` = must-fix before approval, `P3` = cosmetic / nice to have.
|
||||
- Use `- None.` when a severity has no findings.
|
||||
@@ -188,7 +193,6 @@ Write the reviewer invocation to `/tmp/plan-review-${REVIEW_ID}.sh` as a bash sc
|
||||
set -euo pipefail
|
||||
```
|
||||
|
||||
|
||||
**If `REVIEWER_CLI` is `pi`:**
|
||||
|
||||
Fresh call every round (Pi reviewer calls do not use session resume):
|
||||
@@ -321,6 +325,7 @@ fi
|
||||
Run the helper in the foreground and watch its live stdout for `state=in-progress` heartbeats. If your agent environment buffers command output until exit, start the helper in the background and poll `/tmp/plan-review-${REVIEW_ID}.status` separately instead of treating heartbeats as post-hoc-only data.
|
||||
|
||||
After the command completes:
|
||||
|
||||
- If `REVIEWER_CLI=cursor`, extract the final review text:
|
||||
|
||||
```bash
|
||||
@@ -346,14 +351,14 @@ Fallback is allowed only when the helper is missing or not executable.
|
||||
- `/tmp/plan-review-${REVIEW_ID}.runner.out`
|
||||
3. Present review to the user:
|
||||
|
||||
```
|
||||
```markdown
|
||||
## Plan Review — Round N (reviewer: ${REVIEWER_CLI} / ${REVIEWER_MODEL})
|
||||
|
||||
[Reviewer feedback]
|
||||
```
|
||||
|
||||
4. While the reviewer is still running, keep waiting as long as fresh `state=in-progress note="In progress N"` heartbeats continue to appear roughly once per minute.
|
||||
5. Check verdict:
|
||||
1. While the reviewer is still running, keep waiting as long as fresh `state=in-progress note="In progress N"` heartbeats continue to appear roughly once per minute.
|
||||
2. Check verdict:
|
||||
- **VERDICT: APPROVED** with no `P0`, `P1`, or `P2` findings → proceed to Phase 7 (Initialize workspace)
|
||||
- **VERDICT: APPROVED** with only `P3` findings → optionally fix the `P3` items if they are cheap and safe, then proceed
|
||||
- **VERDICT: REVISE** or any `P0`, `P1`, or `P2` finding → go to Step 5
|
||||
@@ -368,7 +373,7 @@ Address the reviewer findings in priority order (`P0` → `P1` → `P2`, then `P
|
||||
|
||||
Summarize revisions for the user:
|
||||
|
||||
```
|
||||
```markdown
|
||||
### Revisions (Round N)
|
||||
- [Change and reason, one bullet per issue addressed]
|
||||
```
|
||||
@@ -379,7 +384,6 @@ If a revision contradicts the user's explicit requirements, skip it and note it
|
||||
|
||||
Rewrite `/tmp/plan-review-${REVIEW_ID}.sh` for the next round. The script should contain the reviewer invocation only; do not run it directly.
|
||||
|
||||
|
||||
**If `REVIEWER_CLI` is `pi`:**
|
||||
|
||||
Fresh call with prior-round context (Pi reviewer calls do not use session resume):
|
||||
@@ -463,7 +467,7 @@ Return to Step 4.
|
||||
|
||||
#### Step 7: Present Final Result
|
||||
|
||||
```
|
||||
```markdown
|
||||
## Plan Review — Final (reviewer: ${REVIEWER_CLI} / ${REVIEWER_MODEL})
|
||||
|
||||
**Status:** Approved after N round(s)
|
||||
@@ -490,16 +494,19 @@ If the round failed, produced empty output, or reached operator-decision timeout
|
||||
### Phase 7: Initialize Local Plan Workspace (MANDATORY)
|
||||
|
||||
At project root:
|
||||
|
||||
1. Ensure `ai_plan/` exists. Create it if missing.
|
||||
2. Ensure `.gitignore` contains `/ai_plan/`.
|
||||
3. If `.gitignore` was changed, commit that change immediately (local commit only).
|
||||
|
||||
Recommended commit message:
|
||||
|
||||
- `chore(gitignore): ignore ai_plan local planning artifacts`
|
||||
|
||||
### Phase 8: Generate Plan Files (MANDATORY)
|
||||
|
||||
Create `ai_plan/YYYY-MM-DD-<short-title>/` with all files below:
|
||||
|
||||
1. `original-plan.md` - copy of original planner-generated plan.
|
||||
2. `final-transcript.md` - copy of final planning transcript used to reach approved plan.
|
||||
3. `milestone-plan.md` - full implementation spec (from template).
|
||||
@@ -532,6 +539,7 @@ fi
|
||||
```
|
||||
|
||||
Rules:
|
||||
|
||||
- Telegram is the only supported notification path. Do not use desktop notifications, `say`, email, or any other notifier.
|
||||
- Notification failures are non-blocking, but they must be surfaced to the user.
|
||||
- Before stopping for any user interaction, approval, or manual decision, send a Telegram summary first if configured.
|
||||
|
||||
@@ -65,15 +65,19 @@ Work from this folder (`ai_plan/YYYY-MM-DD-<short-title>/`) and always follow th
|
||||
## Full Context Reproduction
|
||||
|
||||
### Project Overview
|
||||
|
||||
[What this project/feature is about]
|
||||
|
||||
### User Requirements
|
||||
|
||||
[All gathered requirements]
|
||||
|
||||
### Scope
|
||||
|
||||
[In scope / out of scope]
|
||||
|
||||
### Dependencies
|
||||
|
||||
[External dependencies, prerequisites, related systems]
|
||||
|
||||
---
|
||||
@@ -81,16 +85,19 @@ Work from this folder (`ai_plan/YYYY-MM-DD-<short-title>/`) and always follow th
|
||||
## Key Specifications
|
||||
|
||||
### Type Definitions
|
||||
|
||||
```typescript
|
||||
// Copy-paste ready type definitions
|
||||
```
|
||||
|
||||
### Enums & Constants
|
||||
|
||||
```typescript
|
||||
// All enums/constants needed
|
||||
```
|
||||
|
||||
### API Endpoints
|
||||
|
||||
```typescript
|
||||
// Request/response shapes
|
||||
```
|
||||
@@ -108,16 +115,19 @@ Work from this folder (`ai_plan/YYYY-MM-DD-<short-title>/`) and always follow th
|
||||
## Verification Commands
|
||||
|
||||
### Lint (changed files first)
|
||||
|
||||
```bash
|
||||
# example: <lint-command> <changed-file-1> <changed-file-2>
|
||||
```
|
||||
|
||||
### Typecheck
|
||||
|
||||
```bash
|
||||
# example: <typecheck-command>
|
||||
```
|
||||
|
||||
### Tests (target changed scope first)
|
||||
|
||||
```bash
|
||||
# example: <test-command> <related spec/file>
|
||||
```
|
||||
|
||||
@@ -1,11 +1,13 @@
|
||||
# [Plan Title]
|
||||
|
||||
## Overview
|
||||
|
||||
- **Goal:** [One sentence describing the end state]
|
||||
- **Created:** YYYY-MM-DD
|
||||
- **Status:** In Progress | Complete
|
||||
|
||||
## Planning Guardrails
|
||||
|
||||
- This plan assumes design was validated before implementation planning.
|
||||
- Skills are invoked via native discovery (Codex: `~/.agents/skills/`).
|
||||
- Deprecated CLI wrappers (for example, `superpowers-codex bootstrap` / `use-skill`) are not part of this workflow.
|
||||
@@ -14,37 +16,46 @@
|
||||
## Context
|
||||
|
||||
### Requirements
|
||||
|
||||
[Gathered requirements from user questions]
|
||||
|
||||
### Constraints
|
||||
|
||||
[Technical, business, or timeline constraints]
|
||||
|
||||
### Success Criteria
|
||||
|
||||
[How we know this is complete]
|
||||
|
||||
## Architecture
|
||||
|
||||
### Design Decisions
|
||||
|
||||
[Key architectural choices and rationale]
|
||||
|
||||
### Component Relationships
|
||||
|
||||
[How pieces fit together]
|
||||
|
||||
### Data Flow
|
||||
|
||||
[How data moves through the system]
|
||||
|
||||
## Milestones
|
||||
|
||||
### M1: [Name]
|
||||
|
||||
**Description:** [What this milestone achieves]
|
||||
|
||||
**Acceptance Criteria:**
|
||||
|
||||
- [ ] [Criterion 1]
|
||||
- [ ] [Criterion 2]
|
||||
|
||||
**Stories:** S-101, S-102, S-103...
|
||||
|
||||
**Milestone Completion Rule (MANDATORY):**
|
||||
|
||||
- Run lint/typecheck/tests for changed files.
|
||||
- Commit locally (DO NOT push).
|
||||
- Stop and ask user for feedback.
|
||||
@@ -54,15 +65,18 @@
|
||||
---
|
||||
|
||||
### M2: [Name]
|
||||
|
||||
**Description:** [What this milestone achieves]
|
||||
|
||||
**Acceptance Criteria:**
|
||||
|
||||
- [ ] [Criterion 1]
|
||||
- [ ] [Criterion 2]
|
||||
|
||||
**Stories:** S-201, S-202, S-203...
|
||||
|
||||
**Milestone Completion Rule (MANDATORY):**
|
||||
|
||||
- Run lint/typecheck/tests for changed files.
|
||||
- Commit locally (DO NOT push).
|
||||
- Stop and ask user for feedback.
|
||||
@@ -74,16 +88,19 @@
|
||||
## Technical Specifications
|
||||
|
||||
### Types & Interfaces
|
||||
|
||||
```typescript
|
||||
// Key type definitions (or equivalent language constructs)
|
||||
```
|
||||
|
||||
### API Contracts
|
||||
|
||||
```typescript
|
||||
// Endpoint signatures, request/response shapes (if applicable)
|
||||
```
|
||||
|
||||
### Constants & Enums
|
||||
|
||||
```typescript
|
||||
// Shared constants (if applicable)
|
||||
```
|
||||
@@ -100,6 +117,7 @@
|
||||
## Related Plan Files
|
||||
|
||||
This file is part of the plan folder under `ai_plan/`:
|
||||
|
||||
- `original-plan.md` - Original approved plan (reference for original intent)
|
||||
- `final-transcript.md` - Final planning transcript (reference for rationale/context)
|
||||
- `milestone-plan.md` - This file (full specification)
|
||||
|
||||
@@ -1,12 +1,14 @@
|
||||
# Story Tracker: [Plan Title]
|
||||
|
||||
## Progress Summary
|
||||
|
||||
- **Current Milestone:** M1
|
||||
- **Stories Complete:** 0/N
|
||||
- **Milestones Approved:** 0/M
|
||||
- **Last Updated:** YYYY-MM-DD
|
||||
|
||||
## Tracking Guardrails
|
||||
|
||||
- Update status immediately when work starts (`in-dev`) and when work completes (`completed`).
|
||||
- Require explicit user approval at each milestone boundary before continuing.
|
||||
- Do not push until all milestones are approved and permission is explicitly granted.
|
||||
@@ -52,15 +54,18 @@
|
||||
## Update Instructions (MANDATORY)
|
||||
|
||||
Before starting any story:
|
||||
|
||||
1. Mark story as `in-dev`
|
||||
2. Update "Last Updated"
|
||||
|
||||
After completing any story:
|
||||
|
||||
1. Mark story as `completed`
|
||||
2. Add local commit hash to Notes
|
||||
3. Update "Stories Complete" and "Last Updated"
|
||||
|
||||
At milestone boundary:
|
||||
|
||||
1. Run lint/typecheck/tests for changed files
|
||||
2. Commit (no push)
|
||||
3. Request feedback
|
||||
@@ -69,4 +74,5 @@ At milestone boundary:
|
||||
6. Continue only after approval
|
||||
|
||||
After all milestones approved:
|
||||
|
||||
- Ask permission to push and then mark plan completed.
|
||||
|
||||
@@ -10,6 +10,7 @@ Create and maintain a local plan folder under `ai_plan/` at project root.
|
||||
## Overview
|
||||
|
||||
This skill wraps the current Superpowers flow for the Cursor Agent CLI (`cursor-agent`):
|
||||
|
||||
1. Design first with `superpowers:brainstorming`
|
||||
2. Then build an implementation plan with `superpowers:writing-plans`
|
||||
3. Review the plan iteratively with a second model/provider
|
||||
@@ -20,6 +21,7 @@ This skill wraps the current Superpowers flow for the Cursor Agent CLI (`cursor-
|
||||
## Prerequisite Check (MANDATORY)
|
||||
|
||||
Required:
|
||||
|
||||
- Cursor Agent CLI: `cursor-agent --version` (install via `curl https://cursor.com/install -fsS | bash`). The binary is `cursor-agent` (installed to `~/.local/bin/`). Some environments alias it as `cursor agent` (subcommand of the Cursor IDE CLI) — both forms work, but this skill uses `cursor-agent` throughout.
|
||||
- `jq` (required only if using `cursor` as the reviewer CLI): `jq --version` (install via `brew install jq` or your package manager)
|
||||
- Superpowers repo: `https://github.com/obra/superpowers`
|
||||
@@ -51,9 +53,11 @@ If any dependency is missing, stop and return:
|
||||
## Process
|
||||
|
||||
### Phase 1: Analyze
|
||||
|
||||
- Explore the codebase and existing patterns.
|
||||
|
||||
### Phase 2: Gather Requirements
|
||||
|
||||
- Ask questions one at a time until user says ready.
|
||||
- Confirm scope, constraints, success criteria, dependencies.
|
||||
|
||||
@@ -71,7 +75,6 @@ For shorthand `pi/<pi-model-name>`, split only on the first slash when the prefi
|
||||
|
||||
When `REVIEWER_CLI=pi`, the reviewer model is configured independently from the model running this workflow. If the model/provider is unavailable, surface helper stderr/status and use `pi --list-models [search]` to inspect configured models.
|
||||
|
||||
|
||||
If the user has already specified a reviewer CLI and model (e.g., "create a plan, review with codex o4-mini"), use those values. Otherwise, ask:
|
||||
|
||||
1. **Which CLI should review the plan?**
|
||||
@@ -113,6 +116,7 @@ REVIEW_ID=$(uuidgen | tr '[:upper:]' '[:lower:]' | head -c 8)
|
||||
```
|
||||
|
||||
Use for temp artifacts:
|
||||
|
||||
- `/tmp/plan-${REVIEW_ID}.md`
|
||||
- `/tmp/plan-review-${REVIEW_ID}.md`
|
||||
- `/tmp/plan-review-${REVIEW_ID}.json` (Cursor only)
|
||||
@@ -172,6 +176,7 @@ VERDICT: APPROVED
|
||||
```
|
||||
|
||||
Rules:
|
||||
|
||||
- Order findings from `P0` to `P3`.
|
||||
- `P0` = total blocker, `P1` = major risk, `P2` = must-fix before approval, `P3` = cosmetic / nice to have.
|
||||
- Use `- None.` when a severity has no findings.
|
||||
@@ -194,7 +199,6 @@ Write the reviewer invocation to `/tmp/plan-review-${REVIEW_ID}.sh` as a bash sc
|
||||
set -euo pipefail
|
||||
```
|
||||
|
||||
|
||||
**If `REVIEWER_CLI` is `pi`:**
|
||||
|
||||
Fresh call every round (Pi reviewer calls do not use session resume):
|
||||
@@ -309,6 +313,7 @@ Rules:
|
||||
For `cursor`, the command script writes raw JSON to `/tmp/plan-review-${REVIEW_ID}.json`. Do not run `jq` extraction until after the helper or fallback execution completes.
|
||||
|
||||
Notes on Cursor flags:
|
||||
|
||||
- `--mode=ask` — read-only mode, no file modifications
|
||||
- `--trust` — trust workspace without prompting (required for non-interactive use)
|
||||
- `-p` / `--print` — non-interactive mode, output to stdout
|
||||
@@ -333,6 +338,7 @@ fi
|
||||
Run the helper in the foreground and watch its live stdout for `state=in-progress` heartbeats. If your agent environment buffers command output until exit, start the helper in the background and poll `/tmp/plan-review-${REVIEW_ID}.status` separately instead of treating heartbeats as post-hoc-only data.
|
||||
|
||||
After the command completes:
|
||||
|
||||
- If `REVIEWER_CLI=cursor`, extract the final review text:
|
||||
|
||||
```bash
|
||||
@@ -356,14 +362,14 @@ cp /tmp/plan-review-${REVIEW_ID}.runner.out /tmp/plan-review-${REVIEW_ID}.md
|
||||
- `/tmp/plan-review-${REVIEW_ID}.runner.out`
|
||||
3. Present review to the user:
|
||||
|
||||
```
|
||||
```markdown
|
||||
## Plan Review — Round N (reviewer: ${REVIEWER_CLI} / ${REVIEWER_MODEL})
|
||||
|
||||
[Reviewer feedback]
|
||||
```
|
||||
|
||||
4. While the reviewer is still running, keep waiting as long as fresh `state=in-progress note="In progress N"` heartbeats continue to appear roughly once per minute.
|
||||
5. Check verdict:
|
||||
1. While the reviewer is still running, keep waiting as long as fresh `state=in-progress note="In progress N"` heartbeats continue to appear roughly once per minute.
|
||||
2. Check verdict:
|
||||
- **VERDICT: APPROVED** with no `P0`, `P1`, or `P2` findings → proceed to Phase 7 (Initialize workspace)
|
||||
- **VERDICT: APPROVED** with only `P3` findings → optionally fix the `P3` items if they are cheap and safe, then proceed
|
||||
- **VERDICT: REVISE** or any `P0`, `P1`, or `P2` finding → go to Step 5
|
||||
@@ -378,7 +384,7 @@ Address the reviewer findings in priority order (`P0` → `P1` → `P2`, then `P
|
||||
|
||||
Summarize revisions for the user:
|
||||
|
||||
```
|
||||
```markdown
|
||||
### Revisions (Round N)
|
||||
- [Change and reason, one bullet per issue addressed]
|
||||
```
|
||||
@@ -389,7 +395,6 @@ If a revision contradicts the user's explicit requirements, skip it and note it
|
||||
|
||||
Rewrite `/tmp/plan-review-${REVIEW_ID}.sh` for the next round. The script should contain the reviewer invocation only; do not run it directly.
|
||||
|
||||
|
||||
**If `REVIEWER_CLI` is `pi`:**
|
||||
|
||||
Fresh call with prior-round context (Pi reviewer calls do not use session resume):
|
||||
@@ -473,7 +478,7 @@ Return to Step 4.
|
||||
|
||||
#### Step 7: Present Final Result
|
||||
|
||||
```
|
||||
```markdown
|
||||
## Plan Review — Final (reviewer: ${REVIEWER_CLI} / ${REVIEWER_MODEL})
|
||||
|
||||
**Status:** Approved after N round(s)
|
||||
@@ -500,16 +505,19 @@ If the round failed, produced empty output, or reached operator-decision timeout
|
||||
### Phase 7: Initialize Local Plan Workspace (MANDATORY)
|
||||
|
||||
At project root:
|
||||
|
||||
1. Ensure `ai_plan/` exists. Create it if missing.
|
||||
2. Ensure `.gitignore` contains `/ai_plan/`.
|
||||
3. If `.gitignore` was changed, commit that change immediately (local commit only).
|
||||
|
||||
Recommended commit message:
|
||||
|
||||
- `chore(gitignore): ignore ai_plan local planning artifacts`
|
||||
|
||||
### Phase 8: Generate Plan Files (MANDATORY)
|
||||
|
||||
Create `ai_plan/YYYY-MM-DD-<short-title>/` with all files below:
|
||||
|
||||
1. `original-plan.md` - copy of original planner-generated plan.
|
||||
2. `final-transcript.md` - copy of final planning transcript used to reach approved plan.
|
||||
3. `milestone-plan.md` - full implementation spec (from template).
|
||||
@@ -546,6 +554,7 @@ fi
|
||||
```
|
||||
|
||||
Rules:
|
||||
|
||||
- Telegram is the only supported notification path. Do not use desktop notifications, `say`, email, or any other notifier.
|
||||
- Notification failures are non-blocking, but they must be surfaced to the user.
|
||||
- Before stopping for any user interaction, approval, or manual decision, send a Telegram summary first if configured.
|
||||
@@ -569,12 +578,14 @@ Rules:
|
||||
## Tracker Discipline (MANDATORY)
|
||||
|
||||
Before starting any story:
|
||||
|
||||
1. Open `story-tracker.md`
|
||||
2. Mark story `in-dev`
|
||||
3. Add notes if relevant
|
||||
4. Then begin implementation
|
||||
|
||||
After completing any story:
|
||||
|
||||
1. Mark story `completed`
|
||||
2. Add commit hash in Notes
|
||||
3. Review pending stories
|
||||
@@ -634,4 +645,5 @@ After completing any story:
|
||||
- [ ] Telegram notification attempted if configured
|
||||
|
||||
## Exit Triggers for Question Phase
|
||||
|
||||
User says: "ready", "done", "let's plan", "proceed", "enough questions"
|
||||
|
||||
@@ -64,15 +64,19 @@ Work from this folder (`ai_plan/YYYY-MM-DD-<short-title>/`) and always follow th
|
||||
## Full Context Reproduction
|
||||
|
||||
### Project Overview
|
||||
|
||||
[What this project/feature is about]
|
||||
|
||||
### User Requirements
|
||||
|
||||
[All gathered requirements]
|
||||
|
||||
### Scope
|
||||
|
||||
[In scope / out of scope]
|
||||
|
||||
### Dependencies
|
||||
|
||||
[External dependencies, prerequisites, related systems]
|
||||
|
||||
---
|
||||
@@ -80,16 +84,19 @@ Work from this folder (`ai_plan/YYYY-MM-DD-<short-title>/`) and always follow th
|
||||
## Key Specifications
|
||||
|
||||
### Type Definitions
|
||||
|
||||
```typescript
|
||||
// Copy-paste ready type definitions
|
||||
```
|
||||
|
||||
### Enums & Constants
|
||||
|
||||
```typescript
|
||||
// All enums/constants needed
|
||||
```
|
||||
|
||||
### API Endpoints
|
||||
|
||||
```typescript
|
||||
// Request/response shapes
|
||||
```
|
||||
@@ -107,16 +114,19 @@ Work from this folder (`ai_plan/YYYY-MM-DD-<short-title>/`) and always follow th
|
||||
## Verification Commands
|
||||
|
||||
### Lint (changed files first)
|
||||
|
||||
```bash
|
||||
# example: <lint-command> <changed-file-1> <changed-file-2>
|
||||
```
|
||||
|
||||
### Typecheck
|
||||
|
||||
```bash
|
||||
# example: <typecheck-command>
|
||||
```
|
||||
|
||||
### Tests (target changed scope first)
|
||||
|
||||
```bash
|
||||
# example: <test-command> <related spec/file>
|
||||
```
|
||||
|
||||
@@ -1,11 +1,13 @@
|
||||
# [Plan Title]
|
||||
|
||||
## Overview
|
||||
|
||||
- **Goal:** [One sentence describing the end state]
|
||||
- **Created:** YYYY-MM-DD
|
||||
- **Status:** In Progress | Complete
|
||||
|
||||
## Planning Guardrails
|
||||
|
||||
- This plan assumes design was validated before implementation planning.
|
||||
- Skills are invoked via workspace discovery (`.cursor/skills/`).
|
||||
- Milestones require verification + local commits + explicit approval before proceeding.
|
||||
@@ -13,37 +15,46 @@
|
||||
## Context
|
||||
|
||||
### Requirements
|
||||
|
||||
[Gathered requirements from user questions]
|
||||
|
||||
### Constraints
|
||||
|
||||
[Technical, business, or timeline constraints]
|
||||
|
||||
### Success Criteria
|
||||
|
||||
[How we know this is complete]
|
||||
|
||||
## Architecture
|
||||
|
||||
### Design Decisions
|
||||
|
||||
[Key architectural choices and rationale]
|
||||
|
||||
### Component Relationships
|
||||
|
||||
[How pieces fit together]
|
||||
|
||||
### Data Flow
|
||||
|
||||
[How data moves through the system]
|
||||
|
||||
## Milestones
|
||||
|
||||
### M1: [Name]
|
||||
|
||||
**Description:** [What this milestone achieves]
|
||||
|
||||
**Acceptance Criteria:**
|
||||
|
||||
- [ ] [Criterion 1]
|
||||
- [ ] [Criterion 2]
|
||||
|
||||
**Stories:** S-101, S-102, S-103...
|
||||
|
||||
**Milestone Completion Rule (MANDATORY):**
|
||||
|
||||
- Run lint/typecheck/tests for changed files.
|
||||
- Commit locally (DO NOT push).
|
||||
- Stop and ask user for feedback.
|
||||
@@ -53,15 +64,18 @@
|
||||
---
|
||||
|
||||
### M2: [Name]
|
||||
|
||||
**Description:** [What this milestone achieves]
|
||||
|
||||
**Acceptance Criteria:**
|
||||
|
||||
- [ ] [Criterion 1]
|
||||
- [ ] [Criterion 2]
|
||||
|
||||
**Stories:** S-201, S-202, S-203...
|
||||
|
||||
**Milestone Completion Rule (MANDATORY):**
|
||||
|
||||
- Run lint/typecheck/tests for changed files.
|
||||
- Commit locally (DO NOT push).
|
||||
- Stop and ask user for feedback.
|
||||
@@ -73,16 +87,19 @@
|
||||
## Technical Specifications
|
||||
|
||||
### Types & Interfaces
|
||||
|
||||
```typescript
|
||||
// Key type definitions (or equivalent language constructs)
|
||||
```
|
||||
|
||||
### API Contracts
|
||||
|
||||
```typescript
|
||||
// Endpoint signatures, request/response shapes (if applicable)
|
||||
```
|
||||
|
||||
### Constants & Enums
|
||||
|
||||
```typescript
|
||||
// Shared constants (if applicable)
|
||||
```
|
||||
@@ -99,6 +116,7 @@
|
||||
## Related Plan Files
|
||||
|
||||
This file is part of the plan folder under `ai_plan/`:
|
||||
|
||||
- `original-plan.md` - Original approved plan (reference for original intent)
|
||||
- `final-transcript.md` - Final planning transcript (reference for rationale/context)
|
||||
- `milestone-plan.md` - This file (full specification)
|
||||
|
||||
@@ -1,12 +1,14 @@
|
||||
# Story Tracker: [Plan Title]
|
||||
|
||||
## Progress Summary
|
||||
|
||||
- **Current Milestone:** M1
|
||||
- **Stories Complete:** 0/N
|
||||
- **Milestones Approved:** 0/M
|
||||
- **Last Updated:** YYYY-MM-DD
|
||||
|
||||
## Tracking Guardrails
|
||||
|
||||
- Update status immediately when work starts (`in-dev`) and when work completes (`completed`).
|
||||
- Require explicit user approval at each milestone boundary before continuing.
|
||||
- Do not push until all milestones are approved and permission is explicitly granted.
|
||||
@@ -52,15 +54,18 @@
|
||||
## Update Instructions (MANDATORY)
|
||||
|
||||
Before starting any story:
|
||||
|
||||
1. Mark story as `in-dev`
|
||||
2. Update "Last Updated"
|
||||
|
||||
After completing any story:
|
||||
|
||||
1. Mark story as `completed`
|
||||
2. Add local commit hash to Notes
|
||||
3. Update "Stories Complete" and "Last Updated"
|
||||
|
||||
At milestone boundary:
|
||||
|
||||
1. Run lint/typecheck/tests for changed files
|
||||
2. Commit (no push)
|
||||
3. Request feedback
|
||||
@@ -69,4 +74,5 @@ At milestone boundary:
|
||||
6. Continue only after approval
|
||||
|
||||
After all milestones approved:
|
||||
|
||||
- Ask permission to push and then mark plan completed.
|
||||
|
||||
@@ -12,6 +12,7 @@ Create and maintain a local plan folder under `ai_plan/` at project root.
|
||||
This OpenCode variant depends on Superpowers skills being available through OpenCode's native skill system.
|
||||
|
||||
Required:
|
||||
|
||||
- Superpowers repo: `https://github.com/obra/superpowers`
|
||||
- OpenCode Superpowers skills available at `~/.agents/skills/superpowers` or `~/.config/opencode/skills/superpowers`
|
||||
- `superpowers/brainstorming`
|
||||
@@ -33,13 +34,16 @@ If dependencies are missing, stop immediately and return:
|
||||
### Phase 1: Bootstrap Superpowers Context (REQUIRED)
|
||||
|
||||
Use OpenCode's native skill tool:
|
||||
|
||||
- list skills
|
||||
- verify `superpowers/brainstorming` and `superpowers/writing-plans` are discoverable
|
||||
|
||||
### Phase 2: Analyze
|
||||
|
||||
- Explore the codebase and existing patterns.
|
||||
|
||||
### Phase 3: Gather Requirements
|
||||
|
||||
- Ask questions ONE AT A TIME until user says ready.
|
||||
- Cover scope, constraints, success criteria, dependencies.
|
||||
- Summarize before proceeding.
|
||||
@@ -77,10 +81,10 @@ For shorthand `pi/<pi-model-name>`, split only on the first slash when the prefi
|
||||
|
||||
When `REVIEWER_CLI=pi`, the reviewer model is configured independently from the model running this workflow. If the model/provider is unavailable, surface helper stderr/status and use `pi --list-models [search]` to inspect configured models.
|
||||
|
||||
|
||||
### Phase 5: Design (REQUIRED SUB-SKILL)
|
||||
|
||||
Use OpenCode's native skill tool to load:
|
||||
|
||||
- `superpowers/brainstorming`
|
||||
|
||||
Then present 2-3 approaches and recommend one.
|
||||
@@ -88,6 +92,7 @@ Then present 2-3 approaches and recommend one.
|
||||
### Phase 6: Plan (REQUIRED SUB-SKILL)
|
||||
|
||||
Use OpenCode's native skill tool to load:
|
||||
|
||||
- `superpowers/writing-plans`
|
||||
|
||||
Then break into milestones and bite-sized stories (2-5 min each).
|
||||
@@ -106,6 +111,7 @@ REVIEW_ID=$(uuidgen | tr '[:upper:]' '[:lower:]' | head -c 8)
|
||||
```
|
||||
|
||||
Use for temp artifacts:
|
||||
|
||||
- `/tmp/plan-${REVIEW_ID}.md`
|
||||
- `/tmp/plan-review-${REVIEW_ID}.md`
|
||||
- `/tmp/plan-review-${REVIEW_ID}.json` (Cursor only)
|
||||
@@ -131,6 +137,9 @@ case "$REVIEWER_CLI" in
|
||||
cursor)
|
||||
HELPER_SUCCESS_FILE_ARGS+=(--success-file /tmp/plan-review-${REVIEW_ID}.json)
|
||||
;;
|
||||
opencode)
|
||||
HELPER_SUCCESS_FILE_ARGS+=(--success-file /tmp/plan-review-${REVIEW_ID}.md)
|
||||
;;
|
||||
esac
|
||||
```
|
||||
|
||||
@@ -161,6 +170,7 @@ VERDICT: APPROVED
|
||||
```
|
||||
|
||||
Rules:
|
||||
|
||||
- Order findings from `P0` to `P3`.
|
||||
- `P0` = total blocker, `P1` = major risk, `P2` = must-fix before approval, `P3` = cosmetic / nice to have.
|
||||
- Use `- None.` when a severity has no findings.
|
||||
@@ -183,7 +193,6 @@ Write the reviewer invocation to `/tmp/plan-review-${REVIEW_ID}.sh` as a bash sc
|
||||
set -euo pipefail
|
||||
```
|
||||
|
||||
|
||||
**If `REVIEWER_CLI` is `pi`:**
|
||||
|
||||
Fresh call every round (Pi reviewer calls do not use session resume):
|
||||
@@ -297,6 +306,75 @@ Rules:
|
||||
|
||||
For `cursor`, the command script writes raw JSON to `/tmp/plan-review-${REVIEW_ID}.json`. Do not run `jq` extraction until after the helper or fallback execution completes. If `jq` is not installed, inform the user: `brew install jq` (macOS) or equivalent.
|
||||
|
||||
**If `REVIEWER_CLI` is `opencode`:**
|
||||
|
||||
OpenCode uses `--agent plan` for read-oriented review. Fresh call is the recommended default.
|
||||
|
||||
Round 1:
|
||||
|
||||
```bash
|
||||
opencode run \
|
||||
-m ${REVIEWER_MODEL} \
|
||||
--agent plan \
|
||||
--format json \
|
||||
"Read the file /tmp/plan-${REVIEW_ID}.md and review the implementation plan. Focus on:
|
||||
1. Correctness — Will this plan achieve the stated goals?
|
||||
2. Risks — What could go wrong? Edge cases? Data loss?
|
||||
3. Missing steps — Is anything forgotten?
|
||||
4. Alternatives — Is there a simpler or better approach?
|
||||
5. Security — Any security concerns?
|
||||
|
||||
Return exactly these sections in order:
|
||||
## Summary
|
||||
## Findings
|
||||
### P0
|
||||
### P1
|
||||
### P2
|
||||
### P3
|
||||
## Verdict
|
||||
|
||||
Rules:
|
||||
- Order findings from highest severity to lowest.
|
||||
- Use \`- None.\` when a severity has no findings.
|
||||
- \`P0\` = total blocker, \`P1\` = major risk, \`P2\` = must-fix before approval, \`P3\` = cosmetic / nice to have.
|
||||
- End with exactly one verdict line: \`VERDICT: APPROVED\` or \`VERDICT: REVISE\`
|
||||
- \`VERDICT: APPROVED\` is allowed only when there are no \`P0\`, \`P1\`, or \`P2\` findings. \`P3\` findings are non-blocking." \
|
||||
> /tmp/plan-review-${REVIEW_ID}.json
|
||||
```
|
||||
|
||||
Round 2 and later (fresh-call, recommended default):
|
||||
|
||||
```bash
|
||||
opencode run \
|
||||
-m ${REVIEWER_MODEL} \
|
||||
--agent plan \
|
||||
--format json \
|
||||
"You previously reviewed this plan and requested revisions.
|
||||
|
||||
Previous feedback summary: [key points from last review]
|
||||
|
||||
I've revised. Updated payload is in /tmp/plan-${REVIEW_ID}.md.
|
||||
|
||||
Changes made:
|
||||
[List specific changes]
|
||||
|
||||
Re-review using the same ## Summary, ## Findings, and ## Verdict structure as before." \
|
||||
> /tmp/plan-review-${REVIEW_ID}.json
|
||||
```
|
||||
|
||||
Extract the review body:
|
||||
|
||||
```bash
|
||||
jq -r '.[] | select(.type == "message" and .role == "assistant") | .content' \
|
||||
/tmp/plan-review-${REVIEW_ID}.json \
|
||||
> /tmp/plan-review-${REVIEW_ID}.md \
|
||||
|| cp /tmp/plan-review-${REVIEW_ID}.json /tmp/plan-review-${REVIEW_ID}.md
|
||||
```
|
||||
|
||||
If the JSON parse falls through, promote the raw JSON file as the review output. On any opencode
|
||||
CLI or JSON parsing failure, treat this loop round as `completed-empty-output` and follow the
|
||||
helper-failure escalation in Step 4.
|
||||
|
||||
Run the command script through the shared helper when available:
|
||||
|
||||
```bash
|
||||
@@ -316,6 +394,7 @@ fi
|
||||
Run the helper in the foreground and watch its live stdout for `state=in-progress` heartbeats. If your agent environment buffers command output until exit, start the helper in the background and poll `/tmp/plan-review-${REVIEW_ID}.status` separately instead of treating heartbeats as post-hoc-only data.
|
||||
|
||||
After the command completes:
|
||||
|
||||
- If `REVIEWER_CLI=cursor`, extract the final review text:
|
||||
|
||||
```bash
|
||||
@@ -324,6 +403,7 @@ jq -r '.result' /tmp/plan-review-${REVIEW_ID}.json > /tmp/plan-review-${REVIEW_I
|
||||
```
|
||||
|
||||
- If `REVIEWER_CLI=codex`, extract `CODEX_SESSION_ID` from `/tmp/plan-review-${REVIEW_ID}.runner.out` after the helper or fallback run. If the review text is only in `.runner.out`, move or copy the actual review body into `/tmp/plan-review-${REVIEW_ID}.md` before verdict parsing.
|
||||
- If `REVIEWER_CLI=opencode`, the `jq` extraction above covers output capture. If it falls through, copy runner output: `cp /tmp/plan-review-${REVIEW_ID}.runner.out /tmp/plan-review-${REVIEW_ID}.md`. On Round 1, also attempt to capture the session id for optional use in subsequent rounds: `OPENCODE_SESSION_ID=$(jq -r 'if type == "array" then (.[0] | (.id? // .session_id?)) else (.id? // .session_id?) end // empty' /tmp/plan-review-${REVIEW_ID}.json 2>/dev/null || true)`
|
||||
- If `REVIEWER_CLI=claude` or `REVIEWER_CLI=pi`, promote stdout captured by the helper or fallback runner into the markdown review file:
|
||||
|
||||
```bash
|
||||
@@ -339,14 +419,14 @@ cp /tmp/plan-review-${REVIEW_ID}.runner.out /tmp/plan-review-${REVIEW_ID}.md
|
||||
- `/tmp/plan-review-${REVIEW_ID}.runner.out`
|
||||
3. Present review to the user:
|
||||
|
||||
```
|
||||
```markdown
|
||||
## Plan Review — Round N (reviewer: ${REVIEWER_CLI} / ${REVIEWER_MODEL})
|
||||
|
||||
[Reviewer feedback]
|
||||
```
|
||||
|
||||
4. While the reviewer is still running, keep waiting as long as fresh `state=in-progress note="In progress N"` heartbeats continue to appear roughly once per minute.
|
||||
5. Check verdict:
|
||||
1. While the reviewer is still running, keep waiting as long as fresh `state=in-progress note="In progress N"` heartbeats continue to appear roughly once per minute.
|
||||
2. Check verdict:
|
||||
- **VERDICT: APPROVED** with no `P0`, `P1`, or `P2` findings → proceed to Phase 8 (Initialize workspace)
|
||||
- **VERDICT: APPROVED** with only `P3` findings → optionally fix the `P3` items if they are cheap and safe, then proceed
|
||||
- **VERDICT: REVISE** or any `P0`, `P1`, or `P2` finding → go to Step 5
|
||||
@@ -361,7 +441,7 @@ Address the reviewer findings in priority order (`P0` → `P1` → `P2`, then `P
|
||||
|
||||
Summarize revisions for the user:
|
||||
|
||||
```
|
||||
```markdown
|
||||
### Revisions (Round N)
|
||||
- [Change and reason, one bullet per issue addressed]
|
||||
```
|
||||
@@ -372,7 +452,6 @@ If a revision contradicts the user's explicit requirements, skip it and note it
|
||||
|
||||
Rewrite `/tmp/plan-review-${REVIEW_ID}.sh` for the next round. The script should contain the reviewer invocation only; do not run it directly.
|
||||
|
||||
|
||||
**If `REVIEWER_CLI` is `pi`:**
|
||||
|
||||
Fresh call with prior-round context (Pi reviewer calls do not use session resume):
|
||||
@@ -450,13 +529,66 @@ jq -r '.result' /tmp/plan-review-${REVIEW_ID}.json > /tmp/plan-review-${REVIEW_I
|
||||
|
||||
If resume fails, fall back to fresh `cursor-agent -p` with context about prior rounds.
|
||||
|
||||
**If `REVIEWER_CLI` is `opencode`:**
|
||||
|
||||
Fresh call (recommended default — opencode has no guaranteed stable session ID in headless mode):
|
||||
|
||||
```bash
|
||||
opencode run \
|
||||
-m ${REVIEWER_MODEL} \
|
||||
--agent plan \
|
||||
--format json \
|
||||
"You previously reviewed this plan and requested revisions.
|
||||
|
||||
Previous feedback summary: [key points from last review]
|
||||
|
||||
I've revised. Updated payload is in /tmp/plan-${REVIEW_ID}.md.
|
||||
|
||||
Changes made:
|
||||
[List specific changes]
|
||||
|
||||
Re-review using the same \`## Summary\`, \`## Findings\`, and \`## Verdict\` structure as before.
|
||||
Keep findings ordered \`P0\` to \`P3\`, use \`- None.\` when a severity has no findings, and only use \`VERDICT: APPROVED\` when no \`P0\`, \`P1\`, or \`P2\` findings remain. \`P3\` findings are non-blocking." \
|
||||
> /tmp/plan-review-${REVIEW_ID}.json
|
||||
|
||||
jq -r '.[] | select(.type == "message" and .role == "assistant") | .content' \
|
||||
/tmp/plan-review-${REVIEW_ID}.json \
|
||||
> /tmp/plan-review-${REVIEW_ID}.md \
|
||||
|| cp /tmp/plan-review-${REVIEW_ID}.json /tmp/plan-review-${REVIEW_ID}.md
|
||||
```
|
||||
|
||||
Optional session-resume path (only if `OPENCODE_SESSION_ID` was captured on Round 1 and your installed opencode accepts `-s <id>` reliably in headless mode):
|
||||
|
||||
```bash
|
||||
opencode run \
|
||||
-s ${OPENCODE_SESSION_ID} \
|
||||
-m ${REVIEWER_MODEL} \
|
||||
--agent plan \
|
||||
--format json \
|
||||
"I've revised the plan based on your feedback. Updated plan is in /tmp/plan-${REVIEW_ID}.md.
|
||||
|
||||
Changes made:
|
||||
[List specific changes]
|
||||
|
||||
Re-review using the same \`## Summary\`, \`## Findings\`, and \`## Verdict\` structure as before.
|
||||
Keep findings ordered \`P0\` to \`P3\`, use \`- None.\` when a severity has no findings, and only use \`VERDICT: APPROVED\` when no \`P0\`, \`P1\`, or \`P2\` findings remain. \`P3\` findings are non-blocking." \
|
||||
> /tmp/plan-review-${REVIEW_ID}.json
|
||||
|
||||
jq -r '.[] | select(.type == "message" and .role == "assistant") | .content' \
|
||||
/tmp/plan-review-${REVIEW_ID}.json \
|
||||
> /tmp/plan-review-${REVIEW_ID}.md \
|
||||
|| cp /tmp/plan-review-${REVIEW_ID}.json /tmp/plan-review-${REVIEW_ID}.md
|
||||
```
|
||||
|
||||
If session resume fails (session expired or not supported), fall back to the fresh-call path above.
|
||||
|
||||
After updating `/tmp/plan-review-${REVIEW_ID}.sh`, run the same helper/fallback flow from Round 1.
|
||||
|
||||
Return to Step 4.
|
||||
|
||||
#### Step 7: Present Final Result
|
||||
|
||||
```
|
||||
```markdown
|
||||
## Plan Review — Final (reviewer: ${REVIEWER_CLI} / ${REVIEWER_MODEL})
|
||||
|
||||
**Status:** Approved after N round(s)
|
||||
@@ -483,16 +615,19 @@ If the round failed, produced empty output, or reached operator-decision timeout
|
||||
### Phase 8: Initialize Local Plan Workspace (MANDATORY)
|
||||
|
||||
At project root:
|
||||
|
||||
1. Ensure `ai_plan/` exists. Create it if missing.
|
||||
2. Ensure `.gitignore` contains `/ai_plan/`.
|
||||
3. If `.gitignore` was changed, commit that change immediately (local commit only).
|
||||
|
||||
Recommended commit message:
|
||||
|
||||
- `chore(gitignore): ignore ai_plan local planning artifacts`
|
||||
|
||||
### Phase 9: Generate Plan Files (MANDATORY)
|
||||
|
||||
Create `ai_plan/YYYY-MM-DD-<short-title>/` with ALL files:
|
||||
|
||||
1. `original-plan.md` - copy of original planner-generated plan.
|
||||
2. `final-transcript.md` - copy of final planning transcript used to reach approved plan.
|
||||
3. `milestone-plan.md` - full implementation spec (template-based).
|
||||
@@ -523,6 +658,7 @@ fi
|
||||
```
|
||||
|
||||
Rules:
|
||||
|
||||
- Telegram is the only supported notification path. Do not use desktop notifications, `say`, email, or any other notifier.
|
||||
- Notification failures are non-blocking, but they must be surfaced to the user.
|
||||
- Before stopping for any user interaction, approval, or manual decision, send a Telegram summary first if configured.
|
||||
@@ -531,12 +667,14 @@ Rules:
|
||||
## Tracker Discipline (MANDATORY)
|
||||
|
||||
Before starting any story:
|
||||
|
||||
1. Open `story-tracker.md`
|
||||
2. Mark story `in-dev`
|
||||
3. Add notes if relevant
|
||||
4. Then begin implementation
|
||||
|
||||
After completing any story:
|
||||
|
||||
1. Mark story `completed`
|
||||
2. Add commit hash in Notes
|
||||
3. Review pending stories
|
||||
@@ -575,4 +713,5 @@ After completing any story:
|
||||
- [ ] Telegram notification attempted if configured
|
||||
|
||||
## Exit Triggers for Question Phase
|
||||
|
||||
User says: "ready", "done", "let's plan", "proceed", "enough questions"
|
||||
|
||||
@@ -58,15 +58,19 @@ Work from this folder (`ai_plan/YYYY-MM-DD-<short-title>/`) and always follow th
|
||||
## Full Context Reproduction
|
||||
|
||||
### Project Overview
|
||||
|
||||
[What this project/feature is about]
|
||||
|
||||
### User Requirements
|
||||
|
||||
[All gathered requirements]
|
||||
|
||||
### Scope
|
||||
|
||||
[In scope / out of scope]
|
||||
|
||||
### Dependencies
|
||||
|
||||
[External dependencies, prerequisites, related systems]
|
||||
|
||||
---
|
||||
@@ -74,16 +78,19 @@ Work from this folder (`ai_plan/YYYY-MM-DD-<short-title>/`) and always follow th
|
||||
## Key Specifications
|
||||
|
||||
### Type Definitions
|
||||
|
||||
```typescript
|
||||
// Copy-paste ready type definitions
|
||||
```
|
||||
|
||||
### Enums & Constants
|
||||
|
||||
```typescript
|
||||
// All enums/constants needed
|
||||
```
|
||||
|
||||
### API Endpoints
|
||||
|
||||
```typescript
|
||||
// Request/response shapes
|
||||
```
|
||||
@@ -101,16 +108,19 @@ Work from this folder (`ai_plan/YYYY-MM-DD-<short-title>/`) and always follow th
|
||||
## Verification Commands
|
||||
|
||||
### Lint (changed files first)
|
||||
|
||||
```bash
|
||||
# example: pnpm eslint <changed-file-1> <changed-file-2>
|
||||
```
|
||||
|
||||
### Typecheck
|
||||
|
||||
```bash
|
||||
# example: pnpm tsc --noEmit
|
||||
```
|
||||
|
||||
### Tests (target changed scope first)
|
||||
|
||||
```bash
|
||||
# example: pnpm test -- <related spec/file>
|
||||
```
|
||||
|
||||
@@ -1,6 +1,7 @@
|
||||
# [Plan Title]
|
||||
|
||||
## Overview
|
||||
|
||||
- **Goal:** [One sentence describing the end state]
|
||||
- **Created:** YYYY-MM-DD
|
||||
- **Status:** In Progress | Complete
|
||||
@@ -8,37 +9,46 @@
|
||||
## Context
|
||||
|
||||
### Requirements
|
||||
|
||||
[Gathered requirements from user questions]
|
||||
|
||||
### Constraints
|
||||
|
||||
[Technical, business, or timeline constraints]
|
||||
|
||||
### Success Criteria
|
||||
|
||||
[How we know this is complete]
|
||||
|
||||
## Architecture
|
||||
|
||||
### Design Decisions
|
||||
|
||||
[Key architectural choices and rationale]
|
||||
|
||||
### Component Relationships
|
||||
|
||||
[How pieces fit together]
|
||||
|
||||
### Data Flow
|
||||
|
||||
[How data moves through the system]
|
||||
|
||||
## Milestones
|
||||
|
||||
### M1: [Name]
|
||||
|
||||
**Description:** [What this milestone achieves]
|
||||
|
||||
**Acceptance Criteria:**
|
||||
|
||||
- [ ] [Criterion 1]
|
||||
- [ ] [Criterion 2]
|
||||
|
||||
**Stories:** S-101, S-102, S-103...
|
||||
|
||||
**Milestone Completion Rule (MANDATORY):**
|
||||
|
||||
- Run lint/typecheck/tests for changed files.
|
||||
- Commit locally (DO NOT push).
|
||||
- Stop and ask user for feedback.
|
||||
@@ -48,15 +58,18 @@
|
||||
---
|
||||
|
||||
### M2: [Name]
|
||||
|
||||
**Description:** [What this milestone achieves]
|
||||
|
||||
**Acceptance Criteria:**
|
||||
|
||||
- [ ] [Criterion 1]
|
||||
- [ ] [Criterion 2]
|
||||
|
||||
**Stories:** S-201, S-202, S-203...
|
||||
|
||||
**Milestone Completion Rule (MANDATORY):**
|
||||
|
||||
- Run lint/typecheck/tests for changed files.
|
||||
- Commit locally (DO NOT push).
|
||||
- Stop and ask user for feedback.
|
||||
@@ -68,16 +81,19 @@
|
||||
## Technical Specifications
|
||||
|
||||
### Types & Interfaces
|
||||
|
||||
```typescript
|
||||
// Key type definitions
|
||||
```
|
||||
|
||||
### API Contracts
|
||||
|
||||
```typescript
|
||||
// Endpoint signatures, request/response shapes
|
||||
```
|
||||
|
||||
### Constants & Enums
|
||||
|
||||
```typescript
|
||||
// Shared constants
|
||||
```
|
||||
@@ -94,6 +110,7 @@
|
||||
## Related Plan Files
|
||||
|
||||
This file is part of the plan folder under `ai_plan/`:
|
||||
|
||||
- `original-plan.md` - Original approved plan (reference for original intent)
|
||||
- `final-transcript.md` - Final planning transcript (reference for rationale/context)
|
||||
- `milestone-plan.md` - This file (full specification)
|
||||
|
||||
@@ -1,6 +1,7 @@
|
||||
# Story Tracker: [Plan Title]
|
||||
|
||||
## Progress Summary
|
||||
|
||||
- **Current Milestone:** M1
|
||||
- **Stories Complete:** 0/N
|
||||
- **Milestones Approved:** 0/M
|
||||
@@ -46,15 +47,18 @@
|
||||
## Update Instructions (MANDATORY)
|
||||
|
||||
Before starting any story:
|
||||
|
||||
1. Mark story as `in-dev`
|
||||
2. Update "Last Updated"
|
||||
|
||||
After completing any story:
|
||||
|
||||
1. Mark story as `completed`
|
||||
2. Add local commit hash to Notes
|
||||
3. Update "Stories Complete" and "Last Updated"
|
||||
|
||||
At milestone boundary:
|
||||
|
||||
1. Run lint/typecheck/tests for changed files
|
||||
2. Commit (no push)
|
||||
3. Request feedback
|
||||
@@ -63,4 +67,5 @@ At milestone boundary:
|
||||
6. Continue only after approval
|
||||
|
||||
After all milestones approved:
|
||||
|
||||
- Ask permission to push and then mark plan completed.
|
||||
|
||||
@@ -65,15 +65,19 @@ Work from this folder (`ai_plan/YYYY-MM-DD-<short-title>/`) and always follow th
|
||||
## Full Context Reproduction
|
||||
|
||||
### Project Overview
|
||||
|
||||
[What this project/feature is about]
|
||||
|
||||
### User Requirements
|
||||
|
||||
[All gathered requirements]
|
||||
|
||||
### Scope
|
||||
|
||||
[In scope / out of scope]
|
||||
|
||||
### Dependencies
|
||||
|
||||
[External dependencies, prerequisites, related systems]
|
||||
|
||||
---
|
||||
@@ -81,16 +85,19 @@ Work from this folder (`ai_plan/YYYY-MM-DD-<short-title>/`) and always follow th
|
||||
## Key Specifications
|
||||
|
||||
### Type Definitions
|
||||
|
||||
```typescript
|
||||
// Copy-paste ready type definitions
|
||||
```
|
||||
|
||||
### Enums & Constants
|
||||
|
||||
```typescript
|
||||
// All enums/constants needed
|
||||
```
|
||||
|
||||
### API Endpoints
|
||||
|
||||
```typescript
|
||||
// Request/response shapes
|
||||
```
|
||||
@@ -108,16 +115,19 @@ Work from this folder (`ai_plan/YYYY-MM-DD-<short-title>/`) and always follow th
|
||||
## Verification Commands
|
||||
|
||||
### Lint (changed files first)
|
||||
|
||||
```bash
|
||||
# example: pnpm eslint <changed-file-1> <changed-file-2>
|
||||
```
|
||||
|
||||
### Typecheck
|
||||
|
||||
```bash
|
||||
# example: pnpm tsc --noEmit
|
||||
```
|
||||
|
||||
### Tests (target changed scope first)
|
||||
|
||||
```bash
|
||||
# example: pnpm test -- <related spec/file>
|
||||
```
|
||||
|
||||
@@ -1,6 +1,7 @@
|
||||
# [Plan Title]
|
||||
|
||||
## Overview
|
||||
|
||||
- **Goal:** [One sentence describing the end state]
|
||||
- **Created:** YYYY-MM-DD
|
||||
- **Status:** In Progress | Complete
|
||||
@@ -8,37 +9,46 @@
|
||||
## Context
|
||||
|
||||
### Requirements
|
||||
|
||||
[Gathered requirements from user questions]
|
||||
|
||||
### Constraints
|
||||
|
||||
[Technical, business, or timeline constraints]
|
||||
|
||||
### Success Criteria
|
||||
|
||||
[How we know this is complete]
|
||||
|
||||
## Architecture
|
||||
|
||||
### Design Decisions
|
||||
|
||||
[Key architectural choices and rationale]
|
||||
|
||||
### Component Relationships
|
||||
|
||||
[How pieces fit together]
|
||||
|
||||
### Data Flow
|
||||
|
||||
[How data moves through the system]
|
||||
|
||||
## Milestones
|
||||
|
||||
### M1: [Name]
|
||||
|
||||
**Description:** [What this milestone achieves]
|
||||
|
||||
**Acceptance Criteria:**
|
||||
|
||||
- [ ] [Criterion 1]
|
||||
- [ ] [Criterion 2]
|
||||
|
||||
**Stories:** S-101, S-102, S-103...
|
||||
|
||||
**Milestone Completion Rule (MANDATORY):**
|
||||
|
||||
- Run lint/typecheck/tests for changed files.
|
||||
- Commit locally (DO NOT push).
|
||||
- Stop and ask user for feedback.
|
||||
@@ -48,15 +58,18 @@
|
||||
---
|
||||
|
||||
### M2: [Name]
|
||||
|
||||
**Description:** [What this milestone achieves]
|
||||
|
||||
**Acceptance Criteria:**
|
||||
|
||||
- [ ] [Criterion 1]
|
||||
- [ ] [Criterion 2]
|
||||
|
||||
**Stories:** S-201, S-202, S-203...
|
||||
|
||||
**Milestone Completion Rule (MANDATORY):**
|
||||
|
||||
- Run lint/typecheck/tests for changed files.
|
||||
- Commit locally (DO NOT push).
|
||||
- Stop and ask user for feedback.
|
||||
@@ -68,16 +81,19 @@
|
||||
## Technical Specifications
|
||||
|
||||
### Types & Interfaces
|
||||
|
||||
```typescript
|
||||
// Key type definitions
|
||||
```
|
||||
|
||||
### API Contracts
|
||||
|
||||
```typescript
|
||||
// Endpoint signatures, request/response shapes
|
||||
```
|
||||
|
||||
### Constants & Enums
|
||||
|
||||
```typescript
|
||||
// Shared constants
|
||||
```
|
||||
@@ -94,6 +110,7 @@
|
||||
## Related Plan Files
|
||||
|
||||
This file is part of the plan folder under `ai_plan/`:
|
||||
|
||||
- `original-plan.md` - Original approved plan (reference for original intent)
|
||||
- `final-transcript.md` - Final planning transcript (reference for rationale/context)
|
||||
- `milestone-plan.md` - This file (full specification)
|
||||
|
||||
@@ -1,6 +1,7 @@
|
||||
# Story Tracker: [Plan Title]
|
||||
|
||||
## Progress Summary
|
||||
|
||||
- **Current Milestone:** M1
|
||||
- **Stories Complete:** 0/N
|
||||
- **Milestones Approved:** 0/M
|
||||
@@ -46,15 +47,18 @@
|
||||
## Update Instructions (MANDATORY)
|
||||
|
||||
Before starting any story:
|
||||
|
||||
1. Mark story as `in-dev`
|
||||
2. Update "Last Updated"
|
||||
|
||||
After completing any story:
|
||||
|
||||
1. Mark story as `completed`
|
||||
2. Add local commit hash to Notes
|
||||
3. Update "Stories Complete" and "Last Updated"
|
||||
|
||||
At milestone boundary:
|
||||
|
||||
1. Run lint/typecheck/tests for changed files
|
||||
2. Commit (no push)
|
||||
3. Request feedback
|
||||
@@ -63,4 +67,5 @@ At milestone boundary:
|
||||
6. Continue only after approval
|
||||
|
||||
After all milestones approved:
|
||||
|
||||
- Ask permission to push and then mark plan completed.
|
||||
|
||||
@@ -12,6 +12,7 @@ This is a single-artifact sibling of `create-plan` + `implement-plan`. Unlike `i
|
||||
## Prerequisite Check (MANDATORY)
|
||||
|
||||
Required:
|
||||
|
||||
- Claude Code CLI: `claude --version`
|
||||
- Superpowers repo: `https://github.com/obra/superpowers`
|
||||
- `superpowers:brainstorming`
|
||||
@@ -31,6 +32,7 @@ This variant depends on explicit sub-skill invocation via the `Skill` tool. Do N
|
||||
## Trigger Phrase Detection
|
||||
|
||||
**Binding triggers** (always invoke this skill):
|
||||
|
||||
- `/do-task`
|
||||
- "do this task"
|
||||
- "do task ..."
|
||||
@@ -38,24 +40,29 @@ This variant depends on explicit sub-skill invocation via the `Skill` tool. Do N
|
||||
- "make it so"
|
||||
|
||||
**Hint trigger** (invoke unless context clearly maps to another skill):
|
||||
|
||||
- "just do ..."
|
||||
|
||||
**Escape phrases** (skip the Phase 2 clarifying-question loop):
|
||||
|
||||
- `--no-questions`
|
||||
- `"just do it:"`
|
||||
- `"just do this:"`
|
||||
- `"no questions:"`
|
||||
|
||||
**Excluded** (do NOT trigger `do-task`):
|
||||
|
||||
- "implement this" — reserved for `implement-plan`.
|
||||
|
||||
**Dropped defaults** (explicitly NOT binding triggers):
|
||||
|
||||
- "work on ..."
|
||||
- "handle this"
|
||||
- "take care of ..."
|
||||
- "get this done"
|
||||
|
||||
**Worktree opt-in phrases** (Phase 4 takes the worktree branch):
|
||||
|
||||
- "in a worktree"
|
||||
- "use a worktree"
|
||||
- "on an isolated branch"
|
||||
@@ -113,7 +120,6 @@ Store `REVIEWER_CLI`, `REVIEWER_MODEL`, and `MAX_ROUNDS` for Phases 5 and 8.
|
||||
|
||||
Reviewer CLI: `codex`, `claude`, `cursor`, `opencode`, `pi`, or `skip`.
|
||||
|
||||
|
||||
If `REVIEWER_CLI=pi`, verify the Pi reviewer binary before entering the review loop:
|
||||
|
||||
```bash
|
||||
@@ -127,11 +133,13 @@ When `REVIEWER_CLI=pi`, the reviewer model is configured independently from the
|
||||
### Phase 4: Initialize Plan Workspace
|
||||
|
||||
**PLAN MODE CHECK:** If currently in plan mode:
|
||||
|
||||
1. Inform user that `task-plan.md` cannot be written while in plan mode.
|
||||
2. Instruct user to exit plan mode (approve plan or use `ExitPlanMode`).
|
||||
3. Proceed with file generation only after exiting plan mode.
|
||||
|
||||
Steps:
|
||||
|
||||
1. Compute slug: `YYYY-MM-DD-<slug>` where `<slug>` is a kebab-case hash of the task goal (lowercase, alphanumeric + hyphens only).
|
||||
2. Compute plan folder: `ai_plan/<slug>/`.
|
||||
3. **Resume detection:** If the folder already exists, read `task-plan.md`:
|
||||
@@ -153,7 +161,7 @@ If `REVIEWER_CLI=skip`, present `task-plan.md` to the user and proceed only afte
|
||||
|
||||
Otherwise, invoke the Review Loop (Shared Subroutine) with:
|
||||
|
||||
```
|
||||
```text
|
||||
REVIEW_KIND = plan
|
||||
REVIEW_ID = $(uuidgen | tr '[:upper:]' '[:lower:]' | head -c 8)
|
||||
PAYLOAD_PATH = /tmp/do-task-plan-${REVIEW_ID}.md
|
||||
@@ -191,11 +199,13 @@ Rules:
|
||||
```
|
||||
|
||||
On APPROVED:
|
||||
|
||||
- Set `Status: plan-approved`.
|
||||
- Append APPROVED row to Review History.
|
||||
- Proceed to Phase 6.
|
||||
|
||||
On MAX_ROUNDS:
|
||||
|
||||
- Set `Status: aborted-plan-review`.
|
||||
- Send Telegram summary before stopping.
|
||||
- Ask the user whether to override and proceed, restart, or abort.
|
||||
@@ -221,16 +231,19 @@ Native orchestration — do not invoke `superpowers:executing-plans`.
|
||||
Invoke `superpowers:verification-before-completion` via the `Skill` tool.
|
||||
|
||||
Run the commands listed in the `Verification` section of `task-plan.md`:
|
||||
|
||||
- Lint (changed files first).
|
||||
- Typecheck.
|
||||
- Tests (targeted first, then broader suite if quick).
|
||||
|
||||
All must pass. If a command fails:
|
||||
|
||||
- Fix the issue.
|
||||
- Re-run that command.
|
||||
- Increment `verification_attempts` in Runtime State.
|
||||
|
||||
If `verification_attempts` exceeds 3 without green:
|
||||
|
||||
- Set `Status: aborted-verification`.
|
||||
- Send Telegram summary.
|
||||
- Ask the user whether to retry, override, or abort.
|
||||
@@ -241,7 +254,7 @@ If `REVIEWER_CLI=skip`, present a diff + verification summary to the user and pr
|
||||
|
||||
Otherwise, invoke the Review Loop (Shared Subroutine) with:
|
||||
|
||||
```
|
||||
```text
|
||||
REVIEW_KIND = implementation
|
||||
REVIEW_ID = $(uuidgen | tr '[:upper:]' '[:lower:]' | head -c 8) # distinct from plan-review ID
|
||||
PAYLOAD_PATH = /tmp/do-task-implementation-${REVIEW_ID}.md
|
||||
@@ -297,11 +310,13 @@ Rules:
|
||||
```
|
||||
|
||||
On APPROVED:
|
||||
|
||||
- Set `Status: implementation-approved`.
|
||||
- Append APPROVED row to Review History.
|
||||
- Proceed to Phase 9.
|
||||
|
||||
On MAX_ROUNDS:
|
||||
|
||||
- Set `Status: aborted-impl-review`.
|
||||
- Send Telegram summary.
|
||||
- Ask the user whether to override and commit anyway, restart, or abort.
|
||||
@@ -336,6 +351,7 @@ fi
|
||||
```
|
||||
|
||||
Rules:
|
||||
|
||||
- Telegram is the only supported notification path.
|
||||
- Notification failures are non-blocking but must be surfaced to the user.
|
||||
- Before stopping for any user interaction, approval, or manual decision, send a Telegram summary first if configured.
|
||||
@@ -426,18 +442,19 @@ If `SCAN_MATCHES` is non-empty:
|
||||
1. **Redact the matched text before surfacing** — never echo the raw secret to the user, chat log, terminal scrollback, or any persistent file. Replace each matched substring with a fixed token that preserves only the fact of a match: `[REDACTED:<pattern-label>:<match-length>-chars]`. Example: a matched AWS key becomes `[REDACTED:aws-access-key:20-chars]`. Keep the file path and line number; they are useful for the user and not secret.
|
||||
2. Present the redacted match summary to the user using this exact wording:
|
||||
|
||||
```
|
||||
```text
|
||||
SECRET-SCAN MATCH in outbound reviewer payload (loop: ${REVIEW_KIND}, round: N):
|
||||
<file>:<line>: [REDACTED:<pattern-label>:<match-length>-chars]
|
||||
...
|
||||
Proceed with sending this payload to ${REVIEWER_CLI}? (yes / no / redact)
|
||||
```
|
||||
|
||||
Pattern labels: `aws-access-key`, `gcp-service-account`, `github-token`, `slack-token`, `openai-key`, `anthropic-key`, `pem-private-key`, `dotenv-style`, `jwt`.
|
||||
|
||||
2. Wait for user response.
|
||||
3. On `yes`: record `last_scan_outcome_${REVIEW_KIND}=user-approved-with-matches` in Runtime State, and proceed.
|
||||
4. On `redact`: ask the user to supply redactions, apply them to `PAYLOAD_PATH`, re-scan (this step), record `last_scan_outcome_${REVIEW_KIND}=redacted-and-approved`.
|
||||
5. On `no`: stop the loop, set `Status: failed`, send Telegram, return to the user.
|
||||
3. Wait for user response.
|
||||
4. On `yes`: record `last_scan_outcome_${REVIEW_KIND}=user-approved-with-matches` in Runtime State, and proceed.
|
||||
5. On `redact`: ask the user to supply redactions, apply them to `PAYLOAD_PATH`, re-scan (this step), record `last_scan_outcome_${REVIEW_KIND}=redacted-and-approved`.
|
||||
6. On `no`: stop the loop, set `Status: failed`, send Telegram, return to the user.
|
||||
|
||||
If `SCAN_MATCHES` is empty, record `last_scan_outcome_${REVIEW_KIND}=clean` and proceed.
|
||||
|
||||
@@ -450,7 +467,6 @@ Write the reviewer invocation to `/tmp/do-task-${REVIEW_KIND}-review-${REVIEW_ID
|
||||
set -euo pipefail
|
||||
```
|
||||
|
||||
|
||||
**If `REVIEWER_CLI` is `pi`:**
|
||||
|
||||
Fresh call every round (Pi reviewer calls do not use session resume):
|
||||
@@ -654,15 +670,19 @@ After the command completes:
|
||||
|
||||
- `cursor`: already promoted in Step 2 via `jq -r '.result' ...`. Also capture `session_id` if first round.
|
||||
- `codex`: extract `CODEX_SESSION_ID` from `/tmp/do-task-${REVIEW_KIND}-review-${REVIEW_ID}.runner.out` after the helper or fallback run. If the review text lives only in `.runner.out`, `cp` it into the `.md` file:
|
||||
|
||||
```bash
|
||||
cp /tmp/do-task-${REVIEW_KIND}-review-${REVIEW_ID}.runner.out \
|
||||
/tmp/do-task-${REVIEW_KIND}-review-${REVIEW_ID}.md
|
||||
```
|
||||
|
||||
- `claude` or `pi`: promote `.runner.out` into the `.md` file:
|
||||
|
||||
```bash
|
||||
cp /tmp/do-task-${REVIEW_KIND}-review-${REVIEW_ID}.runner.out \
|
||||
/tmp/do-task-${REVIEW_KIND}-review-${REVIEW_ID}.md
|
||||
```
|
||||
|
||||
- `opencode`: already promoted in Step 2 via `jq` on the JSON stream. If opt-in session-resume is active and the JSON includes a stable session id, capture it and persist to `${SESSION_ID_VAR}`.
|
||||
|
||||
On Round 1, persist the captured session ID (if any) into `task-plan.md`'s Runtime State under `${SESSION_ID_VAR}`.
|
||||
@@ -720,6 +740,7 @@ If the round failed, produced empty output, or reached operator-decision timeout
|
||||
1. Detect existing plan folder by slug at Phase 4.
|
||||
2. Read `task-plan.md` → `Status`.
|
||||
3. Decide next action:
|
||||
|
||||
| Status | Action |
|
||||
|--------|--------|
|
||||
| `draft` | Resume at Phase 5 (plan review) |
|
||||
@@ -728,6 +749,7 @@ If the round failed, produced empty output, or reached operator-decision timeout
|
||||
| `implementation-approved` | Resume at Phase 9 (commit + push ask) |
|
||||
| `pushed` \| `local-only` | Ask user: new suffix, abort, or replay for reference only |
|
||||
| `aborted-*` \| `failed` | Offer new suffix or full restart |
|
||||
|
||||
4. When resuming, read Runtime State for `CODEX_PLAN_SESSION_ID`, `CODEX_IMPL_SESSION_ID`, `CURSOR_PLAN_SESSION_ID`, `CURSOR_IMPL_SESSION_ID`, `OPENCODE_PLAN_SESSION_ID`, `OPENCODE_IMPL_SESSION_ID`, and the round counters. If a session ID is populated, use it for the first revision round in that loop (Round 2) via `codex exec resume`, `cursor-agent --resume`, or `opencode run -s <id>` as applicable.
|
||||
|
||||
---
|
||||
@@ -737,10 +759,12 @@ If the round failed, produced empty output, or reached operator-decision timeout
|
||||
**ALWAYS update `task-plan.md` before/after each phase transition. NEVER proceed with stale state.**
|
||||
|
||||
Before starting any phase:
|
||||
|
||||
1. Update `Status` if it transitions.
|
||||
2. Update `last_phase_entered` in Runtime State.
|
||||
|
||||
After completing any phase:
|
||||
|
||||
1. Update `Status` if it transitions.
|
||||
2. Append notes to the relevant section of `task-plan.md`.
|
||||
|
||||
|
||||
@@ -132,7 +132,6 @@ tdd_used: false
|
||||
- Notes (anything the user should know when revisiting)
|
||||
-->
|
||||
|
||||
|
||||
---
|
||||
|
||||
## Guardrails (do NOT remove)
|
||||
|
||||
@@ -14,6 +14,7 @@ This is a single-artifact sibling of `create-plan` + `implement-plan`. Unlike `i
|
||||
## Prerequisite Check (MANDATORY)
|
||||
|
||||
Required:
|
||||
|
||||
- Codex CLI: `codex --version`
|
||||
- Superpowers repo: `https://github.com/obra/superpowers`
|
||||
- Superpowers skills symlink: `~/.agents/skills/superpowers -> ~/.codex/superpowers/skills`
|
||||
@@ -53,6 +54,7 @@ If any required dependency is missing, stop immediately and return:
|
||||
## Trigger Phrase Detection
|
||||
|
||||
**Binding triggers** (always invoke this skill):
|
||||
|
||||
- `/do-task`
|
||||
- "do this task"
|
||||
- "do task ..."
|
||||
@@ -60,24 +62,29 @@ If any required dependency is missing, stop immediately and return:
|
||||
- "make it so"
|
||||
|
||||
**Hint trigger** (invoke unless context clearly maps to another skill):
|
||||
|
||||
- "just do ..."
|
||||
|
||||
**Escape phrases** (skip the Phase 2 clarifying-question loop):
|
||||
|
||||
- `--no-questions`
|
||||
- `"just do it:"`
|
||||
- `"just do this:"`
|
||||
- `"no questions:"`
|
||||
|
||||
**Excluded** (do NOT trigger `do-task`):
|
||||
|
||||
- "implement this" — reserved for `implement-plan`.
|
||||
|
||||
**Dropped defaults** (explicitly NOT binding triggers):
|
||||
|
||||
- "work on ..."
|
||||
- "handle this"
|
||||
- "take care of ..."
|
||||
- "get this done"
|
||||
|
||||
**Worktree opt-in phrases** (Phase 4 takes the worktree branch):
|
||||
|
||||
- "in a worktree"
|
||||
- "use a worktree"
|
||||
- "on an isolated branch"
|
||||
@@ -135,7 +142,6 @@ Store `REVIEWER_CLI`, `REVIEWER_MODEL`, and `MAX_ROUNDS` for Phases 5 and 8.
|
||||
|
||||
Reviewer CLI: `codex`, `claude`, `cursor`, `opencode`, `pi`, or `skip`.
|
||||
|
||||
|
||||
If `REVIEWER_CLI=pi`, verify the Pi reviewer binary before entering the review loop:
|
||||
|
||||
```bash
|
||||
@@ -151,6 +157,7 @@ When `REVIEWER_CLI=pi`, the reviewer model is configured independently from the
|
||||
Codex has no plan-mode concept; there is no plan-mode guard here.
|
||||
|
||||
Steps:
|
||||
|
||||
1. Compute slug: `YYYY-MM-DD-<slug>` where `<slug>` is a kebab-case hash of the task goal (lowercase, alphanumeric + hyphens only).
|
||||
2. Compute plan folder: `ai_plan/<slug>/`.
|
||||
3. **Resume detection:** If the folder already exists, read `task-plan.md`:
|
||||
@@ -172,7 +179,7 @@ If `REVIEWER_CLI=skip`, present `task-plan.md` to the user and proceed only afte
|
||||
|
||||
Otherwise, invoke the Review Loop (Shared Subroutine) with:
|
||||
|
||||
```
|
||||
```text
|
||||
REVIEW_KIND = plan
|
||||
REVIEW_ID = $(uuidgen | tr '[:upper:]' '[:lower:]' | head -c 8)
|
||||
PAYLOAD_PATH = /tmp/do-task-plan-${REVIEW_ID}.md
|
||||
@@ -210,11 +217,13 @@ Rules:
|
||||
```
|
||||
|
||||
On APPROVED:
|
||||
|
||||
- Set `Status: plan-approved`.
|
||||
- Append APPROVED row to Review History.
|
||||
- Proceed to Phase 6.
|
||||
|
||||
On MAX_ROUNDS:
|
||||
|
||||
- Set `Status: aborted-plan-review`.
|
||||
- Send Telegram summary before stopping.
|
||||
- Ask the user whether to override and proceed, restart, or abort.
|
||||
@@ -240,16 +249,19 @@ Native orchestration — do not invoke `superpowers:executing-plans`.
|
||||
Invoke `superpowers:verification-before-completion` via native discovery.
|
||||
|
||||
Run the commands listed in the `Verification` section of `task-plan.md`:
|
||||
|
||||
- Lint (changed files first).
|
||||
- Typecheck.
|
||||
- Tests (targeted first, then broader suite if quick).
|
||||
|
||||
All must pass. If a command fails:
|
||||
|
||||
- Fix the issue.
|
||||
- Re-run that command.
|
||||
- Increment `verification_attempts` in Runtime State.
|
||||
|
||||
If `verification_attempts` exceeds 3 without green:
|
||||
|
||||
- Set `Status: aborted-verification`.
|
||||
- Send Telegram summary.
|
||||
- Ask the user whether to retry, override, or abort.
|
||||
@@ -260,7 +272,7 @@ If `REVIEWER_CLI=skip`, present a diff + verification summary to the user and pr
|
||||
|
||||
Otherwise, invoke the Review Loop (Shared Subroutine) with:
|
||||
|
||||
```
|
||||
```text
|
||||
REVIEW_KIND = implementation
|
||||
REVIEW_ID = $(uuidgen | tr '[:upper:]' '[:lower:]' | head -c 8) # distinct from plan-review ID
|
||||
PAYLOAD_PATH = /tmp/do-task-implementation-${REVIEW_ID}.md
|
||||
@@ -316,11 +328,13 @@ Rules:
|
||||
```
|
||||
|
||||
On APPROVED:
|
||||
|
||||
- Set `Status: implementation-approved`.
|
||||
- Append APPROVED row to Review History.
|
||||
- Proceed to Phase 9.
|
||||
|
||||
On MAX_ROUNDS:
|
||||
|
||||
- Set `Status: aborted-impl-review`.
|
||||
- Send Telegram summary.
|
||||
- Ask the user whether to override and commit anyway, restart, or abort.
|
||||
@@ -355,6 +369,7 @@ fi
|
||||
```
|
||||
|
||||
Rules:
|
||||
|
||||
- Telegram is the only supported notification path.
|
||||
- Notification failures are non-blocking but must be surfaced to the user.
|
||||
- Before stopping for any user interaction, approval, or manual decision, send a Telegram summary first if configured.
|
||||
@@ -445,18 +460,19 @@ If `SCAN_MATCHES` is non-empty:
|
||||
1. **Redact the matched text before surfacing** — never echo the raw secret to the user, chat log, terminal scrollback, or any persistent file. Replace each matched substring with a fixed token that preserves only the fact of a match: `[REDACTED:<pattern-label>:<match-length>-chars]`. Example: a matched AWS key becomes `[REDACTED:aws-access-key:20-chars]`. Keep the file path and line number; they are useful for the user and not secret.
|
||||
2. Present the redacted match summary to the user using this exact wording:
|
||||
|
||||
```
|
||||
```text
|
||||
SECRET-SCAN MATCH in outbound reviewer payload (loop: ${REVIEW_KIND}, round: N):
|
||||
<file>:<line>: [REDACTED:<pattern-label>:<match-length>-chars]
|
||||
...
|
||||
Proceed with sending this payload to ${REVIEWER_CLI}? (yes / no / redact)
|
||||
```
|
||||
|
||||
Pattern labels: `aws-access-key`, `gcp-service-account`, `github-token`, `slack-token`, `openai-key`, `anthropic-key`, `pem-private-key`, `dotenv-style`, `jwt`.
|
||||
|
||||
2. Wait for user response.
|
||||
3. On `yes`: record `last_scan_outcome_${REVIEW_KIND}=user-approved-with-matches` in Runtime State, and proceed.
|
||||
4. On `redact`: ask the user to supply redactions, apply them to `PAYLOAD_PATH`, re-scan (this step), record `last_scan_outcome_${REVIEW_KIND}=redacted-and-approved`.
|
||||
5. On `no`: stop the loop, set `Status: failed`, send Telegram, return to the user.
|
||||
3. Wait for user response.
|
||||
4. On `yes`: record `last_scan_outcome_${REVIEW_KIND}=user-approved-with-matches` in Runtime State, and proceed.
|
||||
5. On `redact`: ask the user to supply redactions, apply them to `PAYLOAD_PATH`, re-scan (this step), record `last_scan_outcome_${REVIEW_KIND}=redacted-and-approved`.
|
||||
6. On `no`: stop the loop, set `Status: failed`, send Telegram, return to the user.
|
||||
|
||||
If `SCAN_MATCHES` is empty, record `last_scan_outcome_${REVIEW_KIND}=clean` and proceed.
|
||||
|
||||
@@ -469,7 +485,6 @@ Write the reviewer invocation to `/tmp/do-task-${REVIEW_KIND}-review-${REVIEW_ID
|
||||
set -euo pipefail
|
||||
```
|
||||
|
||||
|
||||
**If `REVIEWER_CLI` is `pi`:**
|
||||
|
||||
Fresh call every round (Pi reviewer calls do not use session resume):
|
||||
@@ -673,15 +688,19 @@ After the command completes:
|
||||
|
||||
- `cursor`: already promoted in Step 2 via `jq -r '.result' ...`. Also capture `session_id` if first round.
|
||||
- `codex`: extract `CODEX_SESSION_ID` from `/tmp/do-task-${REVIEW_KIND}-review-${REVIEW_ID}.runner.out` after the helper or fallback run. If the review text lives only in `.runner.out`, `cp` it into the `.md` file:
|
||||
|
||||
```bash
|
||||
cp /tmp/do-task-${REVIEW_KIND}-review-${REVIEW_ID}.runner.out \
|
||||
/tmp/do-task-${REVIEW_KIND}-review-${REVIEW_ID}.md
|
||||
```
|
||||
|
||||
- `claude` or `pi`: promote `.runner.out` into the `.md` file:
|
||||
|
||||
```bash
|
||||
cp /tmp/do-task-${REVIEW_KIND}-review-${REVIEW_ID}.runner.out \
|
||||
/tmp/do-task-${REVIEW_KIND}-review-${REVIEW_ID}.md
|
||||
```
|
||||
|
||||
- `opencode`: already promoted in Step 2 via `jq` on the JSON stream. If opt-in session-resume is active and the JSON includes a stable session id, capture it and persist to `${SESSION_ID_VAR}`.
|
||||
|
||||
On Round 1, persist the captured session ID (if any) into `task-plan.md`'s Runtime State under `${SESSION_ID_VAR}`.
|
||||
@@ -739,6 +758,7 @@ If the round failed, produced empty output, or reached operator-decision timeout
|
||||
1. Detect existing plan folder by slug at Phase 4.
|
||||
2. Read `task-plan.md` → `Status`.
|
||||
3. Decide next action:
|
||||
|
||||
| Status | Action |
|
||||
|--------|--------|
|
||||
| `draft` | Resume at Phase 5 (plan review) |
|
||||
@@ -747,6 +767,7 @@ If the round failed, produced empty output, or reached operator-decision timeout
|
||||
| `implementation-approved` | Resume at Phase 9 (commit + push ask) |
|
||||
| `pushed` \| `local-only` | Ask user: new suffix, abort, or replay for reference only |
|
||||
| `aborted-*` \| `failed` | Offer new suffix or full restart |
|
||||
|
||||
4. When resuming, read Runtime State for `CODEX_PLAN_SESSION_ID`, `CODEX_IMPL_SESSION_ID`, `CURSOR_PLAN_SESSION_ID`, `CURSOR_IMPL_SESSION_ID`, `OPENCODE_PLAN_SESSION_ID`, `OPENCODE_IMPL_SESSION_ID`, and the round counters. If a session ID is populated, use it for the first revision round in that loop (Round 2) via `codex exec resume`, `cursor-agent --resume`, or `opencode run -s <id>` as applicable.
|
||||
|
||||
---
|
||||
@@ -756,10 +777,12 @@ If the round failed, produced empty output, or reached operator-decision timeout
|
||||
**ALWAYS update `task-plan.md` before/after each phase transition. NEVER proceed with stale state.**
|
||||
|
||||
Before starting any phase:
|
||||
|
||||
1. Update `Status` if it transitions.
|
||||
2. Update `last_phase_entered` in Runtime State.
|
||||
|
||||
After completing any phase:
|
||||
|
||||
1. Update `Status` if it transitions.
|
||||
2. Append notes to the relevant section of `task-plan.md`.
|
||||
|
||||
|
||||
@@ -132,7 +132,6 @@ tdd_used: false
|
||||
- Notes (anything the user should know when revisiting)
|
||||
-->
|
||||
|
||||
|
||||
---
|
||||
|
||||
## Guardrails (do NOT remove)
|
||||
|
||||
@@ -14,6 +14,7 @@ This is a single-artifact sibling of `create-plan` + `implement-plan`. Unlike `i
|
||||
## Prerequisite Check (MANDATORY)
|
||||
|
||||
Required:
|
||||
|
||||
- Cursor Agent CLI: `cursor-agent --version` (install via `curl https://cursor.com/install -fsS | bash`). Binary is `cursor-agent`; the alias `cursor agent` also works.
|
||||
- `jq` (**required** — `do-task` always parses JSON output from at least the cursor reviewer branch, and other reviewers may produce JSON). Install via `brew install jq` (macOS) or your package manager. Verify: `jq --version`.
|
||||
- Superpowers repo: `https://github.com/obra/superpowers`
|
||||
@@ -52,6 +53,7 @@ If any required dependency is missing, stop immediately and return:
|
||||
## Trigger Phrase Detection
|
||||
|
||||
**Binding triggers** (always invoke this skill):
|
||||
|
||||
- `/do-task`
|
||||
- "do this task"
|
||||
- "do task ..."
|
||||
@@ -59,24 +61,29 @@ If any required dependency is missing, stop immediately and return:
|
||||
- "make it so"
|
||||
|
||||
**Hint trigger** (invoke unless context clearly maps to another skill):
|
||||
|
||||
- "just do ..."
|
||||
|
||||
**Escape phrases** (skip the Phase 2 clarifying-question loop):
|
||||
|
||||
- `--no-questions`
|
||||
- `"just do it:"`
|
||||
- `"just do this:"`
|
||||
- `"no questions:"`
|
||||
|
||||
**Excluded** (do NOT trigger `do-task`):
|
||||
|
||||
- "implement this" — reserved for `implement-plan`.
|
||||
|
||||
**Dropped defaults** (explicitly NOT binding triggers):
|
||||
|
||||
- "work on ..."
|
||||
- "handle this"
|
||||
- "take care of ..."
|
||||
- "get this done"
|
||||
|
||||
**Worktree opt-in phrases** (Phase 4 takes the worktree branch):
|
||||
|
||||
- "in a worktree"
|
||||
- "use a worktree"
|
||||
- "on an isolated branch"
|
||||
@@ -134,7 +141,6 @@ Store `REVIEWER_CLI`, `REVIEWER_MODEL`, and `MAX_ROUNDS` for Phases 5 and 8.
|
||||
|
||||
Reviewer CLI: `codex`, `claude`, `cursor`, `opencode`, `pi`, or `skip`.
|
||||
|
||||
|
||||
If `REVIEWER_CLI=pi`, verify the Pi reviewer binary before entering the review loop:
|
||||
|
||||
```bash
|
||||
@@ -150,6 +156,7 @@ When `REVIEWER_CLI=pi`, the reviewer model is configured independently from the
|
||||
Cursor Agent CLI has no plan-mode concept; there is no plan-mode guard here.
|
||||
|
||||
Steps:
|
||||
|
||||
1. Compute slug: `YYYY-MM-DD-<slug>` where `<slug>` is a kebab-case hash of the task goal (lowercase, alphanumeric + hyphens only).
|
||||
2. Compute plan folder: `ai_plan/<slug>/`.
|
||||
3. **Resume detection:** If the folder already exists, read `task-plan.md`:
|
||||
@@ -171,7 +178,7 @@ If `REVIEWER_CLI=skip`, present `task-plan.md` to the user and proceed only afte
|
||||
|
||||
Otherwise, invoke the Review Loop (Shared Subroutine) with:
|
||||
|
||||
```
|
||||
```text
|
||||
REVIEW_KIND = plan
|
||||
REVIEW_ID = $(uuidgen | tr '[:upper:]' '[:lower:]' | head -c 8)
|
||||
PAYLOAD_PATH = /tmp/do-task-plan-${REVIEW_ID}.md
|
||||
@@ -209,11 +216,13 @@ Rules:
|
||||
```
|
||||
|
||||
On APPROVED:
|
||||
|
||||
- Set `Status: plan-approved`.
|
||||
- Append APPROVED row to Review History.
|
||||
- Proceed to Phase 6.
|
||||
|
||||
On MAX_ROUNDS:
|
||||
|
||||
- Set `Status: aborted-plan-review`.
|
||||
- Send Telegram summary before stopping.
|
||||
- Ask the user whether to override and proceed, restart, or abort.
|
||||
@@ -239,16 +248,19 @@ Native orchestration — do not invoke `superpowers:executing-plans`.
|
||||
Invoke `superpowers:verification-before-completion` via Cursor-native discovery.
|
||||
|
||||
Run the commands listed in the `Verification` section of `task-plan.md`:
|
||||
|
||||
- Lint (changed files first).
|
||||
- Typecheck.
|
||||
- Tests (targeted first, then broader suite if quick).
|
||||
|
||||
All must pass. If a command fails:
|
||||
|
||||
- Fix the issue.
|
||||
- Re-run that command.
|
||||
- Increment `verification_attempts` in Runtime State.
|
||||
|
||||
If `verification_attempts` exceeds 3 without green:
|
||||
|
||||
- Set `Status: aborted-verification`.
|
||||
- Send Telegram summary.
|
||||
- Ask the user whether to retry, override, or abort.
|
||||
@@ -259,7 +271,7 @@ If `REVIEWER_CLI=skip`, present a diff + verification summary to the user and pr
|
||||
|
||||
Otherwise, invoke the Review Loop (Shared Subroutine) with:
|
||||
|
||||
```
|
||||
```text
|
||||
REVIEW_KIND = implementation
|
||||
REVIEW_ID = $(uuidgen | tr '[:upper:]' '[:lower:]' | head -c 8) # distinct from plan-review ID
|
||||
PAYLOAD_PATH = /tmp/do-task-implementation-${REVIEW_ID}.md
|
||||
@@ -315,11 +327,13 @@ Rules:
|
||||
```
|
||||
|
||||
On APPROVED:
|
||||
|
||||
- Set `Status: implementation-approved`.
|
||||
- Append APPROVED row to Review History.
|
||||
- Proceed to Phase 9.
|
||||
|
||||
On MAX_ROUNDS:
|
||||
|
||||
- Set `Status: aborted-impl-review`.
|
||||
- Send Telegram summary.
|
||||
- Ask the user whether to override and commit anyway, restart, or abort.
|
||||
@@ -358,6 +372,7 @@ fi
|
||||
```
|
||||
|
||||
Rules:
|
||||
|
||||
- Telegram is the only supported notification path.
|
||||
- Notification failures are non-blocking but must be surfaced to the user.
|
||||
- Before stopping for any user interaction, approval, or manual decision, send a Telegram summary first if configured.
|
||||
@@ -452,18 +467,19 @@ If `SCAN_MATCHES` is non-empty:
|
||||
1. **Redact the matched text before surfacing** — never echo the raw secret to the user, chat log, terminal scrollback, or any persistent file. Replace each matched substring with a fixed token that preserves only the fact of a match: `[REDACTED:<pattern-label>:<match-length>-chars]`. Example: a matched AWS key becomes `[REDACTED:aws-access-key:20-chars]`. Keep the file path and line number; they are useful for the user and not secret.
|
||||
2. Present the redacted match summary to the user using this exact wording:
|
||||
|
||||
```
|
||||
```text
|
||||
SECRET-SCAN MATCH in outbound reviewer payload (loop: ${REVIEW_KIND}, round: N):
|
||||
<file>:<line>: [REDACTED:<pattern-label>:<match-length>-chars]
|
||||
...
|
||||
Proceed with sending this payload to ${REVIEWER_CLI}? (yes / no / redact)
|
||||
```
|
||||
|
||||
Pattern labels: `aws-access-key`, `gcp-service-account`, `github-token`, `slack-token`, `openai-key`, `anthropic-key`, `pem-private-key`, `dotenv-style`, `jwt`.
|
||||
|
||||
2. Wait for user response.
|
||||
3. On `yes`: record `last_scan_outcome_${REVIEW_KIND}=user-approved-with-matches` in Runtime State, and proceed.
|
||||
4. On `redact`: ask the user to supply redactions, apply them to `PAYLOAD_PATH`, re-scan (this step), record `last_scan_outcome_${REVIEW_KIND}=redacted-and-approved`.
|
||||
5. On `no`: stop the loop, set `Status: failed`, send Telegram, return to the user.
|
||||
3. Wait for user response.
|
||||
4. On `yes`: record `last_scan_outcome_${REVIEW_KIND}=user-approved-with-matches` in Runtime State, and proceed.
|
||||
5. On `redact`: ask the user to supply redactions, apply them to `PAYLOAD_PATH`, re-scan (this step), record `last_scan_outcome_${REVIEW_KIND}=redacted-and-approved`.
|
||||
6. On `no`: stop the loop, set `Status: failed`, send Telegram, return to the user.
|
||||
|
||||
If `SCAN_MATCHES` is empty, record `last_scan_outcome_${REVIEW_KIND}=clean` and proceed.
|
||||
|
||||
@@ -476,7 +492,6 @@ Write the reviewer invocation to `/tmp/do-task-${REVIEW_KIND}-review-${REVIEW_ID
|
||||
set -euo pipefail
|
||||
```
|
||||
|
||||
|
||||
**If `REVIEWER_CLI` is `pi`:**
|
||||
|
||||
Fresh call every round (Pi reviewer calls do not use session resume):
|
||||
@@ -680,15 +695,19 @@ After the command completes:
|
||||
|
||||
- `cursor`: already promoted in Step 2 via `jq -r '.result' ...`. Also capture `session_id` if first round.
|
||||
- `codex`: extract `CODEX_SESSION_ID` from `/tmp/do-task-${REVIEW_KIND}-review-${REVIEW_ID}.runner.out` after the helper or fallback run. If the review text lives only in `.runner.out`, `cp` it into the `.md` file:
|
||||
|
||||
```bash
|
||||
cp /tmp/do-task-${REVIEW_KIND}-review-${REVIEW_ID}.runner.out \
|
||||
/tmp/do-task-${REVIEW_KIND}-review-${REVIEW_ID}.md
|
||||
```
|
||||
|
||||
- `claude` or `pi`: promote `.runner.out` into the `.md` file:
|
||||
|
||||
```bash
|
||||
cp /tmp/do-task-${REVIEW_KIND}-review-${REVIEW_ID}.runner.out \
|
||||
/tmp/do-task-${REVIEW_KIND}-review-${REVIEW_ID}.md
|
||||
```
|
||||
|
||||
- `opencode`: already promoted in Step 2 via `jq` on the JSON stream. If opt-in session-resume is active and the JSON includes a stable session id, capture it and persist to `${SESSION_ID_VAR}`.
|
||||
|
||||
On Round 1, persist the captured session ID (if any) into `task-plan.md`'s Runtime State under `${SESSION_ID_VAR}`.
|
||||
@@ -746,6 +765,7 @@ If the round failed, produced empty output, or reached operator-decision timeout
|
||||
1. Detect existing plan folder by slug at Phase 4.
|
||||
2. Read `task-plan.md` → `Status`.
|
||||
3. Decide next action:
|
||||
|
||||
| Status | Action |
|
||||
|--------|--------|
|
||||
| `draft` | Resume at Phase 5 (plan review) |
|
||||
@@ -754,6 +774,7 @@ If the round failed, produced empty output, or reached operator-decision timeout
|
||||
| `implementation-approved` | Resume at Phase 9 (commit + push ask) |
|
||||
| `pushed` \| `local-only` | Ask user: new suffix, abort, or replay for reference only |
|
||||
| `aborted-*` \| `failed` | Offer new suffix or full restart |
|
||||
|
||||
4. When resuming, read Runtime State for `CODEX_PLAN_SESSION_ID`, `CODEX_IMPL_SESSION_ID`, `CURSOR_PLAN_SESSION_ID`, `CURSOR_IMPL_SESSION_ID`, `OPENCODE_PLAN_SESSION_ID`, `OPENCODE_IMPL_SESSION_ID`, and the round counters. If a session ID is populated, use it for the first revision round in that loop (Round 2) via `codex exec resume`, `cursor-agent --resume`, or `opencode run -s <id>` as applicable.
|
||||
|
||||
---
|
||||
@@ -763,10 +784,12 @@ If the round failed, produced empty output, or reached operator-decision timeout
|
||||
**ALWAYS update `task-plan.md` before/after each phase transition. NEVER proceed with stale state.**
|
||||
|
||||
Before starting any phase:
|
||||
|
||||
1. Update `Status` if it transitions.
|
||||
2. Update `last_phase_entered` in Runtime State.
|
||||
|
||||
After completing any phase:
|
||||
|
||||
1. Update `Status` if it transitions.
|
||||
2. Append notes to the relevant section of `task-plan.md`.
|
||||
|
||||
|
||||
@@ -132,7 +132,6 @@ tdd_used: false
|
||||
- Notes (anything the user should know when revisiting)
|
||||
-->
|
||||
|
||||
|
||||
---
|
||||
|
||||
## Guardrails (do NOT remove)
|
||||
|
||||
@@ -14,6 +14,7 @@ This is a single-artifact sibling of `create-plan` + `implement-plan`. Unlike `i
|
||||
## Prerequisite Check (MANDATORY)
|
||||
|
||||
Required:
|
||||
|
||||
- OpenCode CLI: `opencode --version` (install via your package manager or `brew install opencode`).
|
||||
- Superpowers repo: `https://github.com/obra/superpowers`
|
||||
- OpenCode Superpowers skills available at `~/.agents/skills/superpowers` or `~/.config/opencode/skills/superpowers`
|
||||
@@ -50,6 +51,7 @@ If any required dependency is missing, stop immediately and return:
|
||||
## Trigger Phrase Detection
|
||||
|
||||
**Binding triggers** (always invoke this skill):
|
||||
|
||||
- `/do-task`
|
||||
- "do this task"
|
||||
- "do task ..."
|
||||
@@ -57,24 +59,29 @@ If any required dependency is missing, stop immediately and return:
|
||||
- "make it so"
|
||||
|
||||
**Hint trigger** (invoke unless context clearly maps to another skill):
|
||||
|
||||
- "just do ..."
|
||||
|
||||
**Escape phrases** (skip the Phase 2 clarifying-question loop):
|
||||
|
||||
- `--no-questions`
|
||||
- `"just do it:"`
|
||||
- `"just do this:"`
|
||||
- `"no questions:"`
|
||||
|
||||
**Excluded** (do NOT trigger `do-task`):
|
||||
|
||||
- "implement this" — reserved for `implement-plan`.
|
||||
|
||||
**Dropped defaults** (explicitly NOT binding triggers):
|
||||
|
||||
- "work on ..."
|
||||
- "handle this"
|
||||
- "take care of ..."
|
||||
- "get this done"
|
||||
|
||||
**Worktree opt-in phrases** (Phase 4 takes the worktree branch):
|
||||
|
||||
- "in a worktree"
|
||||
- "use a worktree"
|
||||
- "on an isolated branch"
|
||||
@@ -133,7 +140,6 @@ Store `REVIEWER_CLI`, `REVIEWER_MODEL`, and `MAX_ROUNDS` for Phases 5 and 8.
|
||||
|
||||
Reviewer CLI: `codex`, `claude`, `cursor`, `opencode`, `pi`, or `skip`.
|
||||
|
||||
|
||||
If `REVIEWER_CLI=pi`, verify the Pi reviewer binary before entering the review loop:
|
||||
|
||||
```bash
|
||||
@@ -149,6 +155,7 @@ When `REVIEWER_CLI=pi`, the reviewer model is configured independently from the
|
||||
OpenCode has no plan-mode concept; there is no plan-mode guard here.
|
||||
|
||||
Steps:
|
||||
|
||||
1. Compute slug: `YYYY-MM-DD-<slug>` where `<slug>` is a kebab-case hash of the task goal (lowercase, alphanumeric + hyphens only).
|
||||
2. Compute plan folder: `ai_plan/<slug>/`.
|
||||
3. **Resume detection:** If the folder already exists, read `task-plan.md`:
|
||||
@@ -170,7 +177,7 @@ If `REVIEWER_CLI=skip`, present `task-plan.md` to the user and proceed only afte
|
||||
|
||||
Otherwise, invoke the Review Loop (Shared Subroutine) with:
|
||||
|
||||
```
|
||||
```text
|
||||
REVIEW_KIND = plan
|
||||
REVIEW_ID = $(uuidgen | tr '[:upper:]' '[:lower:]' | head -c 8)
|
||||
PAYLOAD_PATH = /tmp/do-task-plan-${REVIEW_ID}.md
|
||||
@@ -208,11 +215,13 @@ Rules:
|
||||
```
|
||||
|
||||
On APPROVED:
|
||||
|
||||
- Set `Status: plan-approved`.
|
||||
- Append APPROVED row to Review History.
|
||||
- Proceed to Phase 6.
|
||||
|
||||
On MAX_ROUNDS:
|
||||
|
||||
- Set `Status: aborted-plan-review`.
|
||||
- Send Telegram summary before stopping.
|
||||
- Ask the user whether to override and proceed, restart, or abort.
|
||||
@@ -238,16 +247,19 @@ Native orchestration — do not invoke `superpowers:executing-plans`.
|
||||
Invoke `superpowers/verification-before-completion` via OpenCode's native skill tool.
|
||||
|
||||
Run the commands listed in the `Verification` section of `task-plan.md`:
|
||||
|
||||
- Lint (changed files first).
|
||||
- Typecheck.
|
||||
- Tests (targeted first, then broader suite if quick).
|
||||
|
||||
All must pass. If a command fails:
|
||||
|
||||
- Fix the issue.
|
||||
- Re-run that command.
|
||||
- Increment `verification_attempts` in Runtime State.
|
||||
|
||||
If `verification_attempts` exceeds 3 without green:
|
||||
|
||||
- Set `Status: aborted-verification`.
|
||||
- Send Telegram summary.
|
||||
- Ask the user whether to retry, override, or abort.
|
||||
@@ -258,7 +270,7 @@ If `REVIEWER_CLI=skip`, present a diff + verification summary to the user and pr
|
||||
|
||||
Otherwise, invoke the Review Loop (Shared Subroutine) with:
|
||||
|
||||
```
|
||||
```text
|
||||
REVIEW_KIND = implementation
|
||||
REVIEW_ID = $(uuidgen | tr '[:upper:]' '[:lower:]' | head -c 8) # distinct from plan-review ID
|
||||
PAYLOAD_PATH = /tmp/do-task-implementation-${REVIEW_ID}.md
|
||||
@@ -314,11 +326,13 @@ Rules:
|
||||
```
|
||||
|
||||
On APPROVED:
|
||||
|
||||
- Set `Status: implementation-approved`.
|
||||
- Append APPROVED row to Review History.
|
||||
- Proceed to Phase 9.
|
||||
|
||||
On MAX_ROUNDS:
|
||||
|
||||
- Set `Status: aborted-impl-review`.
|
||||
- Send Telegram summary.
|
||||
- Ask the user whether to override and commit anyway, restart, or abort.
|
||||
@@ -353,6 +367,7 @@ fi
|
||||
```
|
||||
|
||||
Rules:
|
||||
|
||||
- Telegram is the only supported notification path.
|
||||
- Notification failures are non-blocking but must be surfaced to the user.
|
||||
- Before stopping for any user interaction, approval, or manual decision, send a Telegram summary first if configured.
|
||||
@@ -443,18 +458,19 @@ If `SCAN_MATCHES` is non-empty:
|
||||
1. **Redact the matched text before surfacing** — never echo the raw secret to the user, chat log, terminal scrollback, or any persistent file. Replace each matched substring with a fixed token that preserves only the fact of a match: `[REDACTED:<pattern-label>:<match-length>-chars]`. Example: a matched AWS key becomes `[REDACTED:aws-access-key:20-chars]`. Keep the file path and line number; they are useful for the user and not secret.
|
||||
2. Present the redacted match summary to the user using this exact wording:
|
||||
|
||||
```
|
||||
```text
|
||||
SECRET-SCAN MATCH in outbound reviewer payload (loop: ${REVIEW_KIND}, round: N):
|
||||
<file>:<line>: [REDACTED:<pattern-label>:<match-length>-chars]
|
||||
...
|
||||
Proceed with sending this payload to ${REVIEWER_CLI}? (yes / no / redact)
|
||||
```
|
||||
|
||||
Pattern labels: `aws-access-key`, `gcp-service-account`, `github-token`, `slack-token`, `openai-key`, `anthropic-key`, `pem-private-key`, `dotenv-style`, `jwt`.
|
||||
|
||||
2. Wait for user response.
|
||||
3. On `yes`: record `last_scan_outcome_${REVIEW_KIND}=user-approved-with-matches` in Runtime State, and proceed.
|
||||
4. On `redact`: ask the user to supply redactions, apply them to `PAYLOAD_PATH`, re-scan (this step), record `last_scan_outcome_${REVIEW_KIND}=redacted-and-approved`.
|
||||
5. On `no`: stop the loop, set `Status: failed`, send Telegram, return to the user.
|
||||
3. Wait for user response.
|
||||
4. On `yes`: record `last_scan_outcome_${REVIEW_KIND}=user-approved-with-matches` in Runtime State, and proceed.
|
||||
5. On `redact`: ask the user to supply redactions, apply them to `PAYLOAD_PATH`, re-scan (this step), record `last_scan_outcome_${REVIEW_KIND}=redacted-and-approved`.
|
||||
6. On `no`: stop the loop, set `Status: failed`, send Telegram, return to the user.
|
||||
|
||||
If `SCAN_MATCHES` is empty, record `last_scan_outcome_${REVIEW_KIND}=clean` and proceed.
|
||||
|
||||
@@ -467,7 +483,6 @@ Write the reviewer invocation to `/tmp/do-task-${REVIEW_KIND}-review-${REVIEW_ID
|
||||
set -euo pipefail
|
||||
```
|
||||
|
||||
|
||||
**If `REVIEWER_CLI` is `pi`:**
|
||||
|
||||
Fresh call every round (Pi reviewer calls do not use session resume):
|
||||
@@ -671,15 +686,19 @@ After the command completes:
|
||||
|
||||
- `cursor`: already promoted in Step 2 via `jq -r '.result' ...`. Also capture `session_id` if first round.
|
||||
- `codex`: extract `CODEX_SESSION_ID` from `/tmp/do-task-${REVIEW_KIND}-review-${REVIEW_ID}.runner.out` after the helper or fallback run. If the review text lives only in `.runner.out`, `cp` it into the `.md` file:
|
||||
|
||||
```bash
|
||||
cp /tmp/do-task-${REVIEW_KIND}-review-${REVIEW_ID}.runner.out \
|
||||
/tmp/do-task-${REVIEW_KIND}-review-${REVIEW_ID}.md
|
||||
```
|
||||
|
||||
- `claude` or `pi`: promote `.runner.out` into the `.md` file:
|
||||
|
||||
```bash
|
||||
cp /tmp/do-task-${REVIEW_KIND}-review-${REVIEW_ID}.runner.out \
|
||||
/tmp/do-task-${REVIEW_KIND}-review-${REVIEW_ID}.md
|
||||
```
|
||||
|
||||
- `opencode`: already promoted in Step 2 via `jq` on the JSON stream. If opt-in session-resume is active and the JSON includes a stable session id, capture it and persist to `${SESSION_ID_VAR}`.
|
||||
|
||||
On Round 1, persist the captured session ID (if any) into `task-plan.md`'s Runtime State under `${SESSION_ID_VAR}`.
|
||||
@@ -737,6 +756,7 @@ If the round failed, produced empty output, or reached operator-decision timeout
|
||||
1. Detect existing plan folder by slug at Phase 4.
|
||||
2. Read `task-plan.md` → `Status`.
|
||||
3. Decide next action:
|
||||
|
||||
| Status | Action |
|
||||
|--------|--------|
|
||||
| `draft` | Resume at Phase 5 (plan review) |
|
||||
@@ -745,6 +765,7 @@ If the round failed, produced empty output, or reached operator-decision timeout
|
||||
| `implementation-approved` | Resume at Phase 9 (commit + push ask) |
|
||||
| `pushed` \| `local-only` | Ask user: new suffix, abort, or replay for reference only |
|
||||
| `aborted-*` \| `failed` | Offer new suffix or full restart |
|
||||
|
||||
4. When resuming, read Runtime State for `CODEX_PLAN_SESSION_ID`, `CODEX_IMPL_SESSION_ID`, `CURSOR_PLAN_SESSION_ID`, `CURSOR_IMPL_SESSION_ID`, `OPENCODE_PLAN_SESSION_ID`, `OPENCODE_IMPL_SESSION_ID`, and the round counters. If a session ID is populated, use it for the first revision round in that loop (Round 2) via `codex exec resume`, `cursor-agent --resume`, or `opencode run -s <id>` as applicable.
|
||||
|
||||
---
|
||||
@@ -754,10 +775,12 @@ If the round failed, produced empty output, or reached operator-decision timeout
|
||||
**ALWAYS update `task-plan.md` before/after each phase transition. NEVER proceed with stale state.**
|
||||
|
||||
Before starting any phase:
|
||||
|
||||
1. Update `Status` if it transitions.
|
||||
2. Update `last_phase_entered` in Runtime State.
|
||||
|
||||
After completing any phase:
|
||||
|
||||
1. Update `Status` if it transitions.
|
||||
2. Append notes to the relevant section of `task-plan.md`.
|
||||
|
||||
|
||||
@@ -132,7 +132,6 @@ tdd_used: false
|
||||
- Notes (anything the user should know when revisiting)
|
||||
-->
|
||||
|
||||
|
||||
---
|
||||
|
||||
## Guardrails (do NOT remove)
|
||||
|
||||
@@ -10,6 +10,7 @@ Execute an existing plan (created by `create-plan`) in an isolated git worktree,
|
||||
## Prerequisite Check (MANDATORY)
|
||||
|
||||
Required:
|
||||
|
||||
- Plan folder exists under `ai_plan/` at project root
|
||||
- `continuation-runbook.md` exists in plan folder
|
||||
- `milestone-plan.md` exists in plan folder
|
||||
@@ -63,7 +64,6 @@ Store `REVIEWER_CLI`, `REVIEWER_MODEL`, and `MAX_ROUNDS`. These values are fixed
|
||||
|
||||
Reviewer CLI: `codex`, `claude`, `cursor`, `opencode`, `pi`, or `skip`.
|
||||
|
||||
|
||||
If `REVIEWER_CLI=pi`, verify the Pi reviewer binary before entering the review loop:
|
||||
|
||||
```bash
|
||||
@@ -101,6 +101,7 @@ Mark first story `in-dev` in `story-tracker.md`.
|
||||
#### Step 3: Implement Stories
|
||||
|
||||
Execute each story in order. After completing each story:
|
||||
|
||||
1. Mark `in-dev` -> `completed` in `story-tracker.md`
|
||||
2. Update counts
|
||||
3. Mark next story `in-dev`
|
||||
@@ -135,6 +136,7 @@ git commit -m "feat(<scope>): implement milestone M<N> - <description>"
|
||||
```
|
||||
|
||||
Do NOT push. After committing:
|
||||
|
||||
1. Backfill the commit hash into the Notes column for all stories in this milestone in `story-tracker.md`.
|
||||
2. Mark milestone as `approved` in `story-tracker.md`.
|
||||
3. Move to next milestone.
|
||||
@@ -150,6 +152,7 @@ REVIEW_ID=$(uuidgen | tr '[:upper:]' '[:lower:]' | head -c 8)
|
||||
```
|
||||
|
||||
Use `REVIEW_ID` for all milestone review temp file paths:
|
||||
|
||||
- `/tmp/milestone-${REVIEW_ID}.md`
|
||||
- `/tmp/milestone-review-${REVIEW_ID}.md`
|
||||
- `/tmp/milestone-review-${REVIEW_ID}.json`
|
||||
@@ -226,6 +229,7 @@ VERDICT: APPROVED
|
||||
```
|
||||
|
||||
Rules:
|
||||
|
||||
- Order findings from `P0` to `P3`.
|
||||
- `P0` = total blocker, `P1` = major risk, `P2` = must-fix before approval, `P3` = cosmetic / nice to have.
|
||||
- Use `- None.` when a severity has no findings.
|
||||
@@ -248,7 +252,6 @@ Write the reviewer invocation to `/tmp/milestone-review-${REVIEW_ID}.sh` as a ba
|
||||
set -euo pipefail
|
||||
```
|
||||
|
||||
|
||||
**If `REVIEWER_CLI` is `pi`:**
|
||||
|
||||
Fresh call every round (Pi reviewer calls do not use session resume):
|
||||
@@ -389,6 +392,7 @@ fi
|
||||
Run the helper in the foreground and watch its live stdout for `state=in-progress` heartbeats. If your agent environment buffers command output until exit, start the helper in the background and poll `/tmp/milestone-review-${REVIEW_ID}.status` separately instead of treating heartbeats as post-hoc-only data.
|
||||
|
||||
After the command completes:
|
||||
|
||||
- If `REVIEWER_CLI=cursor`, extract the final review text:
|
||||
|
||||
```bash
|
||||
@@ -414,14 +418,14 @@ Fallback is allowed only when the helper is missing or not executable.
|
||||
- `/tmp/milestone-review-${REVIEW_ID}.runner.out`
|
||||
3. Present review to the user:
|
||||
|
||||
```
|
||||
```markdown
|
||||
## Milestone Review — Round N (reviewer: ${REVIEWER_CLI} / ${REVIEWER_MODEL})
|
||||
|
||||
[Reviewer feedback]
|
||||
```
|
||||
|
||||
4. While the reviewer is still running, keep waiting as long as fresh `state=in-progress note="In progress N"` heartbeats continue to appear roughly once per minute.
|
||||
5. Check verdict:
|
||||
1. While the reviewer is still running, keep waiting as long as fresh `state=in-progress note="In progress N"` heartbeats continue to appear roughly once per minute.
|
||||
2. Check verdict:
|
||||
- **VERDICT: APPROVED** with no `P0`, `P1`, or `P2` findings -> proceed to Phase 4 Step 6 (commit & approve)
|
||||
- **VERDICT: APPROVED** with only `P3` findings -> optionally fix the `P3` items if they are cheap and safe, then proceed
|
||||
- **VERDICT: REVISE** or any `P0`, `P1`, or `P2` finding -> go to Step 5
|
||||
@@ -438,7 +442,7 @@ Fallback is allowed only when the helper is missing or not executable.
|
||||
|
||||
Summarize revisions for the user:
|
||||
|
||||
```
|
||||
```markdown
|
||||
### Revisions (Round N)
|
||||
- [Change and reason, one bullet per issue addressed]
|
||||
```
|
||||
@@ -449,7 +453,6 @@ If a revision contradicts the user's explicit requirements, skip it and note it
|
||||
|
||||
Rewrite `/tmp/milestone-review-${REVIEW_ID}.sh` for the next round. The script should contain the reviewer invocation only; do not run it directly.
|
||||
|
||||
|
||||
**If `REVIEWER_CLI` is `pi`:**
|
||||
|
||||
Fresh call with prior-round context (Pi reviewer calls do not use session resume):
|
||||
@@ -559,20 +562,20 @@ After all milestones are approved and committed:
|
||||
git merge implement/<plan-folder-name>
|
||||
```
|
||||
|
||||
4. Delete the worktree and its branch:
|
||||
1. Delete the worktree and its branch:
|
||||
|
||||
```bash
|
||||
git worktree remove <worktree-path>
|
||||
git branch -d implement/<plan-folder-name>
|
||||
```
|
||||
|
||||
5. Mark plan status as `completed` in `story-tracker.md`.
|
||||
1. Mark plan status as `completed` in `story-tracker.md`.
|
||||
|
||||
### Phase 7: Final Report
|
||||
|
||||
Present summary:
|
||||
|
||||
```
|
||||
```markdown
|
||||
## Implementation Complete
|
||||
|
||||
**Plan:** <plan-folder-name>
|
||||
@@ -598,6 +601,7 @@ fi
|
||||
```
|
||||
|
||||
Rules:
|
||||
|
||||
- Telegram is the only supported notification path. Do not use desktop notifications, `say`, email, or any other notifier.
|
||||
- Notification failures are non-blocking, but they must be surfaced to the user.
|
||||
- Before stopping for any user interaction, approval, or manual decision, send a Telegram summary first if configured.
|
||||
@@ -608,12 +612,14 @@ Rules:
|
||||
**ALWAYS update `story-tracker.md` before/after each story. NEVER proceed with stale tracker state.**
|
||||
|
||||
Before starting any story:
|
||||
|
||||
1. Open `story-tracker.md`
|
||||
2. Mark story `in-dev`
|
||||
3. Add notes if relevant
|
||||
4. Then begin implementation
|
||||
|
||||
After completing any story:
|
||||
|
||||
1. Mark story `completed`
|
||||
2. Review pending stories
|
||||
3. Update Last Updated and Stories Complete counts
|
||||
|
||||
@@ -10,6 +10,7 @@ Execute an existing plan (created by `create-plan`) in an isolated git worktree,
|
||||
## Overview
|
||||
|
||||
This skill wraps the Superpowers execution flow for Codex:
|
||||
|
||||
1. Locate plan files under `ai_plan/`
|
||||
2. Set up an isolated git worktree
|
||||
3. Execute milestones one-by-one with lint/typecheck/test gates
|
||||
@@ -21,6 +22,7 @@ This skill wraps the Superpowers execution flow for Codex:
|
||||
## Prerequisite Check (MANDATORY)
|
||||
|
||||
Required:
|
||||
|
||||
- Plan folder exists under `ai_plan/` at project root
|
||||
- `continuation-runbook.md` exists in plan folder
|
||||
- `milestone-plan.md` exists in plan folder
|
||||
@@ -96,7 +98,6 @@ Store `REVIEWER_CLI`, `REVIEWER_MODEL`, and `MAX_ROUNDS`. These values are fixed
|
||||
|
||||
Reviewer CLI: `codex`, `claude`, `cursor`, `opencode`, `pi`, or `skip`.
|
||||
|
||||
|
||||
If `REVIEWER_CLI=pi`, verify the Pi reviewer binary before entering the review loop:
|
||||
|
||||
```bash
|
||||
@@ -134,6 +135,7 @@ Mark first story `in-dev` in `story-tracker.md`.
|
||||
#### Step 3: Implement Stories
|
||||
|
||||
Execute each story in order. After completing each story:
|
||||
|
||||
1. Mark `in-dev` -> `completed` in `story-tracker.md`
|
||||
2. Update counts
|
||||
3. Mark next story `in-dev`
|
||||
@@ -168,6 +170,7 @@ git commit -m "feat(<scope>): implement milestone M<N> - <description>"
|
||||
```
|
||||
|
||||
Do NOT push. After committing:
|
||||
|
||||
1. Backfill the commit hash into the Notes column for all stories in this milestone in `story-tracker.md`.
|
||||
2. Mark milestone as `approved` in `story-tracker.md`.
|
||||
3. Move to next milestone.
|
||||
@@ -183,6 +186,7 @@ REVIEW_ID=$(uuidgen | tr '[:upper:]' '[:lower:]' | head -c 8)
|
||||
```
|
||||
|
||||
Use `REVIEW_ID` for all milestone review temp file paths:
|
||||
|
||||
- `/tmp/milestone-${REVIEW_ID}.md`
|
||||
- `/tmp/milestone-review-${REVIEW_ID}.md`
|
||||
- `/tmp/milestone-review-${REVIEW_ID}.json`
|
||||
@@ -259,6 +263,7 @@ VERDICT: APPROVED
|
||||
```
|
||||
|
||||
Rules:
|
||||
|
||||
- Order findings from `P0` to `P3`.
|
||||
- `P0` = total blocker, `P1` = major risk, `P2` = must-fix before approval, `P3` = cosmetic / nice to have.
|
||||
- Use `- None.` when a severity has no findings.
|
||||
@@ -281,7 +286,6 @@ Write the reviewer invocation to `/tmp/milestone-review-${REVIEW_ID}.sh` as a ba
|
||||
set -euo pipefail
|
||||
```
|
||||
|
||||
|
||||
**If `REVIEWER_CLI` is `pi`:**
|
||||
|
||||
Fresh call every round (Pi reviewer calls do not use session resume):
|
||||
@@ -422,6 +426,7 @@ fi
|
||||
Run the helper in the foreground and watch its live stdout for `state=in-progress` heartbeats. If your agent environment buffers command output until exit, start the helper in the background and poll `/tmp/milestone-review-${REVIEW_ID}.status` separately instead of treating heartbeats as post-hoc-only data.
|
||||
|
||||
After the command completes:
|
||||
|
||||
- If `REVIEWER_CLI=cursor`, extract the final review text:
|
||||
|
||||
```bash
|
||||
@@ -447,14 +452,14 @@ Fallback is allowed only when the helper is missing or not executable.
|
||||
- `/tmp/milestone-review-${REVIEW_ID}.runner.out`
|
||||
3. Present review to the user:
|
||||
|
||||
```
|
||||
```markdown
|
||||
## Milestone Review — Round N (reviewer: ${REVIEWER_CLI} / ${REVIEWER_MODEL})
|
||||
|
||||
[Reviewer feedback]
|
||||
```
|
||||
|
||||
4. While the reviewer is still running, keep waiting as long as fresh `state=in-progress note="In progress N"` heartbeats continue to appear roughly once per minute.
|
||||
5. Check verdict:
|
||||
1. While the reviewer is still running, keep waiting as long as fresh `state=in-progress note="In progress N"` heartbeats continue to appear roughly once per minute.
|
||||
2. Check verdict:
|
||||
- **VERDICT: APPROVED** with no `P0`, `P1`, or `P2` findings -> proceed to Phase 4 Step 6 (commit & approve)
|
||||
- **VERDICT: APPROVED** with only `P3` findings -> optionally fix the `P3` items if they are cheap and safe, then proceed
|
||||
- **VERDICT: REVISE** or any `P0`, `P1`, or `P2` finding -> go to Step 5
|
||||
@@ -471,7 +476,7 @@ Fallback is allowed only when the helper is missing or not executable.
|
||||
|
||||
Summarize revisions for the user:
|
||||
|
||||
```
|
||||
```markdown
|
||||
### Revisions (Round N)
|
||||
- [Change and reason, one bullet per issue addressed]
|
||||
```
|
||||
@@ -482,7 +487,6 @@ If a revision contradicts the user's explicit requirements, skip it and note it
|
||||
|
||||
Rewrite `/tmp/milestone-review-${REVIEW_ID}.sh` for the next round. The script should contain the reviewer invocation only; do not run it directly.
|
||||
|
||||
|
||||
**If `REVIEWER_CLI` is `pi`:**
|
||||
|
||||
Fresh call with prior-round context (Pi reviewer calls do not use session resume):
|
||||
@@ -592,20 +596,20 @@ After all milestones are approved and committed:
|
||||
git merge implement/<plan-folder-name>
|
||||
```
|
||||
|
||||
4. Delete the worktree and its branch:
|
||||
1. Delete the worktree and its branch:
|
||||
|
||||
```bash
|
||||
git worktree remove <worktree-path>
|
||||
git branch -d implement/<plan-folder-name>
|
||||
```
|
||||
|
||||
5. Mark plan status as `completed` in `story-tracker.md`.
|
||||
1. Mark plan status as `completed` in `story-tracker.md`.
|
||||
|
||||
### Phase 7: Final Report
|
||||
|
||||
Present summary:
|
||||
|
||||
```
|
||||
```markdown
|
||||
## Implementation Complete
|
||||
|
||||
**Plan:** <plan-folder-name>
|
||||
@@ -631,6 +635,7 @@ fi
|
||||
```
|
||||
|
||||
Rules:
|
||||
|
||||
- Telegram is the only supported notification path. Do not use desktop notifications, `say`, email, or any other notifier.
|
||||
- Notification failures are non-blocking, but they must be surfaced to the user.
|
||||
- Before stopping for any user interaction, approval, or manual decision, send a Telegram summary first if configured.
|
||||
@@ -654,12 +659,14 @@ Rules:
|
||||
**ALWAYS update `story-tracker.md` before/after each story. NEVER proceed with stale tracker state.**
|
||||
|
||||
Before starting any story:
|
||||
|
||||
1. Open `story-tracker.md`
|
||||
2. Mark story `in-dev`
|
||||
3. Add notes if relevant
|
||||
4. Then begin implementation
|
||||
|
||||
After completing any story:
|
||||
|
||||
1. Mark story `completed`
|
||||
2. Review pending stories
|
||||
3. Update Last Updated and Stories Complete counts
|
||||
|
||||
@@ -10,6 +10,7 @@ Execute an existing plan (created by `create-plan`) in an isolated git worktree,
|
||||
## Overview
|
||||
|
||||
This skill wraps the Superpowers execution flow for the Cursor Agent CLI (`cursor-agent`):
|
||||
|
||||
1. Locate plan files under `ai_plan/`
|
||||
2. Set up an isolated git worktree
|
||||
3. Execute milestones one-by-one with lint/typecheck/test gates
|
||||
@@ -21,6 +22,7 @@ This skill wraps the Superpowers execution flow for the Cursor Agent CLI (`curso
|
||||
## Prerequisite Check (MANDATORY)
|
||||
|
||||
Required:
|
||||
|
||||
- Cursor Agent CLI: `cursor-agent --version` (install via `curl https://cursor.com/install -fsS | bash`). The binary is `cursor-agent` (installed to `~/.local/bin/`). Some environments alias it as `cursor agent` (subcommand of the Cursor IDE CLI) — both forms work, but this skill uses `cursor-agent` throughout.
|
||||
- `jq` (required only if using `cursor` as the reviewer CLI): `jq --version` (install via `brew install jq` or your package manager)
|
||||
- Plan folder exists under `ai_plan/` at project root
|
||||
@@ -96,7 +98,6 @@ Store `REVIEWER_CLI`, `REVIEWER_MODEL`, and `MAX_ROUNDS`. These values are fixed
|
||||
|
||||
Reviewer CLI: `codex`, `claude`, `cursor`, `opencode`, `pi`, or `skip`.
|
||||
|
||||
|
||||
If `REVIEWER_CLI=pi`, verify the Pi reviewer binary before entering the review loop:
|
||||
|
||||
```bash
|
||||
@@ -134,6 +135,7 @@ Mark first story `in-dev` in `story-tracker.md`.
|
||||
#### Step 3: Implement Stories
|
||||
|
||||
Execute each story in order. After completing each story:
|
||||
|
||||
1. Mark `in-dev` -> `completed` in `story-tracker.md`
|
||||
2. Update counts
|
||||
3. Mark next story `in-dev`
|
||||
@@ -168,6 +170,7 @@ git commit -m "feat(<scope>): implement milestone M<N> - <description>"
|
||||
```
|
||||
|
||||
Do NOT push. After committing:
|
||||
|
||||
1. Backfill the commit hash into the Notes column for all stories in this milestone in `story-tracker.md`.
|
||||
2. Mark milestone as `approved` in `story-tracker.md`.
|
||||
3. Move to next milestone.
|
||||
@@ -183,6 +186,7 @@ REVIEW_ID=$(uuidgen | tr '[:upper:]' '[:lower:]' | head -c 8)
|
||||
```
|
||||
|
||||
Use `REVIEW_ID` for all milestone review temp file paths:
|
||||
|
||||
- `/tmp/milestone-${REVIEW_ID}.md`
|
||||
- `/tmp/milestone-review-${REVIEW_ID}.md`
|
||||
- `/tmp/milestone-review-${REVIEW_ID}.json`
|
||||
@@ -263,6 +267,7 @@ VERDICT: APPROVED
|
||||
```
|
||||
|
||||
Rules:
|
||||
|
||||
- Order findings from `P0` to `P3`.
|
||||
- `P0` = total blocker, `P1` = major risk, `P2` = must-fix before approval, `P3` = cosmetic / nice to have.
|
||||
- Use `- None.` when a severity has no findings.
|
||||
@@ -285,7 +290,6 @@ Write the reviewer invocation to `/tmp/milestone-review-${REVIEW_ID}.sh` as a ba
|
||||
set -euo pipefail
|
||||
```
|
||||
|
||||
|
||||
**If `REVIEWER_CLI` is `pi`:**
|
||||
|
||||
Fresh call every round (Pi reviewer calls do not use session resume):
|
||||
@@ -408,6 +412,7 @@ Rules:
|
||||
For `cursor`, the command script writes raw JSON to `/tmp/milestone-review-${REVIEW_ID}.json`. Do not run `jq` extraction until after the helper or fallback execution completes.
|
||||
|
||||
Notes on Cursor flags:
|
||||
|
||||
- `--mode=ask` — read-only mode, no file modifications
|
||||
- `--trust` — trust workspace without prompting (required for non-interactive use)
|
||||
- `-p` / `--print` — non-interactive mode, output to stdout
|
||||
@@ -432,6 +437,7 @@ fi
|
||||
Run the helper in the foreground and watch its live stdout for `state=in-progress` heartbeats. If your agent environment buffers command output until exit, start the helper in the background and poll `/tmp/milestone-review-${REVIEW_ID}.status` separately instead of treating heartbeats as post-hoc-only data.
|
||||
|
||||
After the command completes:
|
||||
|
||||
- If `REVIEWER_CLI=cursor`, extract the final review text:
|
||||
|
||||
```bash
|
||||
@@ -457,14 +463,14 @@ Fallback is allowed only when the helper is missing or not executable.
|
||||
- `/tmp/milestone-review-${REVIEW_ID}.runner.out`
|
||||
3. Present review to the user:
|
||||
|
||||
```
|
||||
```markdown
|
||||
## Milestone Review — Round N (reviewer: ${REVIEWER_CLI} / ${REVIEWER_MODEL})
|
||||
|
||||
[Reviewer feedback]
|
||||
```
|
||||
|
||||
4. While the reviewer is still running, keep waiting as long as fresh `state=in-progress note="In progress N"` heartbeats continue to appear roughly once per minute.
|
||||
5. Check verdict:
|
||||
1. While the reviewer is still running, keep waiting as long as fresh `state=in-progress note="In progress N"` heartbeats continue to appear roughly once per minute.
|
||||
2. Check verdict:
|
||||
- **VERDICT: APPROVED** with no `P0`, `P1`, or `P2` findings -> proceed to Phase 4 Step 6 (commit & approve)
|
||||
- **VERDICT: APPROVED** with only `P3` findings -> optionally fix the `P3` items if they are cheap and safe, then proceed
|
||||
- **VERDICT: REVISE** or any `P0`, `P1`, or `P2` finding -> go to Step 5
|
||||
@@ -481,7 +487,7 @@ Fallback is allowed only when the helper is missing or not executable.
|
||||
|
||||
Summarize revisions for the user:
|
||||
|
||||
```
|
||||
```markdown
|
||||
### Revisions (Round N)
|
||||
- [Change and reason, one bullet per issue addressed]
|
||||
```
|
||||
@@ -492,7 +498,6 @@ If a revision contradicts the user's explicit requirements, skip it and note it
|
||||
|
||||
Rewrite `/tmp/milestone-review-${REVIEW_ID}.sh` for the next round. The script should contain the reviewer invocation only; do not run it directly.
|
||||
|
||||
|
||||
**If `REVIEWER_CLI` is `pi`:**
|
||||
|
||||
Fresh call with prior-round context (Pi reviewer calls do not use session resume):
|
||||
@@ -602,20 +607,20 @@ After all milestones are approved and committed:
|
||||
git merge implement/<plan-folder-name>
|
||||
```
|
||||
|
||||
4. Delete the worktree and its branch:
|
||||
1. Delete the worktree and its branch:
|
||||
|
||||
```bash
|
||||
git worktree remove <worktree-path>
|
||||
git branch -d implement/<plan-folder-name>
|
||||
```
|
||||
|
||||
5. Mark plan status as `completed` in `story-tracker.md`.
|
||||
1. Mark plan status as `completed` in `story-tracker.md`.
|
||||
|
||||
### Phase 7: Final Report
|
||||
|
||||
Present summary:
|
||||
|
||||
```
|
||||
```markdown
|
||||
## Implementation Complete
|
||||
|
||||
**Plan:** <plan-folder-name>
|
||||
@@ -645,6 +650,7 @@ fi
|
||||
```
|
||||
|
||||
Rules:
|
||||
|
||||
- Telegram is the only supported notification path. Do not use desktop notifications, `say`, email, or any other notifier.
|
||||
- Notification failures are non-blocking, but they must be surfaced to the user.
|
||||
- Before stopping for any user interaction, approval, or manual decision, send a Telegram summary first if configured.
|
||||
@@ -666,12 +672,14 @@ Rules:
|
||||
## Tracker Discipline (MANDATORY)
|
||||
|
||||
Before starting any story:
|
||||
|
||||
1. Open `story-tracker.md`
|
||||
2. Mark story `in-dev`
|
||||
3. Add notes if relevant
|
||||
4. Then begin implementation
|
||||
|
||||
After completing any story:
|
||||
|
||||
1. Mark story `completed`
|
||||
2. Review pending stories
|
||||
3. Update Last Updated and Stories Complete counts
|
||||
|
||||
@@ -12,6 +12,7 @@ Execute an existing plan (created by `create-plan`) in an isolated git worktree,
|
||||
This OpenCode variant depends on Superpowers execution skills being installed via OpenCode's native skill system.
|
||||
|
||||
Required:
|
||||
|
||||
- Plan folder exists under `ai_plan/` at project root
|
||||
- `continuation-runbook.md` exists in plan folder
|
||||
- `milestone-plan.md` exists in plan folder
|
||||
@@ -46,6 +47,7 @@ If no plan folder exists:
|
||||
### Phase 1: Bootstrap Superpowers Context (REQUIRED)
|
||||
|
||||
Use OpenCode's native skill tool:
|
||||
|
||||
- list skills
|
||||
- verify `superpowers/executing-plans`, `superpowers/using-git-worktrees`, `superpowers/verification-before-completion`, and `superpowers/finishing-a-development-branch` are discoverable
|
||||
|
||||
@@ -81,7 +83,6 @@ Store `REVIEWER_CLI`, `REVIEWER_MODEL`, and `MAX_ROUNDS`. These values are fixed
|
||||
|
||||
Reviewer CLI: `codex`, `claude`, `cursor`, `opencode`, `pi`, or `skip`.
|
||||
|
||||
|
||||
If `REVIEWER_CLI=pi`, verify the Pi reviewer binary before entering the review loop:
|
||||
|
||||
```bash
|
||||
@@ -95,9 +96,11 @@ When `REVIEWER_CLI=pi`, the reviewer model is configured independently from the
|
||||
### Phase 4: Set Up Worktree (REQUIRED SUB-SKILL)
|
||||
|
||||
Use OpenCode's native skill tool to load:
|
||||
|
||||
- `superpowers/using-git-worktrees`
|
||||
|
||||
Then:
|
||||
|
||||
1. Branch naming: `implement/<plan-folder-name>` (e.g., `implement/2026-03-04-auth-system`).
|
||||
2. Follow worktree skill's directory priority: `.worktrees/` > `worktrees/` > CLAUDE.md > ask user.
|
||||
3. Verify `.gitignore` covers worktree directory.
|
||||
@@ -121,6 +124,7 @@ Mark first story `in-dev` in `story-tracker.md`.
|
||||
#### Step 3: Implement Stories
|
||||
|
||||
Execute each story in order. After completing each story:
|
||||
|
||||
1. Mark `in-dev` -> `completed` in `story-tracker.md`
|
||||
2. Update counts
|
||||
3. Mark next story `in-dev`
|
||||
@@ -130,6 +134,7 @@ Commit hashes are not available yet — they are backfilled in Step 6 after the
|
||||
#### Step 4: Verify Milestone (REQUIRED SUB-SKILL)
|
||||
|
||||
Use OpenCode's native skill tool to load:
|
||||
|
||||
- `superpowers/verification-before-completion`
|
||||
|
||||
```bash
|
||||
@@ -156,6 +161,7 @@ git commit -m "feat(<scope>): implement milestone M<N> - <description>"
|
||||
```
|
||||
|
||||
Do NOT push. After committing:
|
||||
|
||||
1. Backfill the commit hash into the Notes column for all stories in this milestone in `story-tracker.md`.
|
||||
2. Mark milestone as `approved` in `story-tracker.md`.
|
||||
3. Move to next milestone.
|
||||
@@ -171,6 +177,7 @@ REVIEW_ID=$(uuidgen | tr '[:upper:]' '[:lower:]' | head -c 8)
|
||||
```
|
||||
|
||||
Use `REVIEW_ID` for all milestone review temp file paths:
|
||||
|
||||
- `/tmp/milestone-${REVIEW_ID}.md`
|
||||
- `/tmp/milestone-review-${REVIEW_ID}.md`
|
||||
- `/tmp/milestone-review-${REVIEW_ID}.json`
|
||||
@@ -196,6 +203,9 @@ case "$REVIEWER_CLI" in
|
||||
cursor)
|
||||
HELPER_SUCCESS_FILE_ARGS+=(--success-file /tmp/milestone-review-${REVIEW_ID}.json)
|
||||
;;
|
||||
opencode)
|
||||
HELPER_SUCCESS_FILE_ARGS+=(--success-file /tmp/milestone-review-${REVIEW_ID}.md)
|
||||
;;
|
||||
esac
|
||||
```
|
||||
|
||||
@@ -247,6 +257,7 @@ VERDICT: APPROVED
|
||||
```
|
||||
|
||||
Rules:
|
||||
|
||||
- Order findings from `P0` to `P3`.
|
||||
- `P0` = total blocker, `P1` = major risk, `P2` = must-fix before approval, `P3` = cosmetic / nice to have.
|
||||
- Use `- None.` when a severity has no findings.
|
||||
@@ -269,7 +280,6 @@ Write the reviewer invocation to `/tmp/milestone-review-${REVIEW_ID}.sh` as a ba
|
||||
set -euo pipefail
|
||||
```
|
||||
|
||||
|
||||
**If `REVIEWER_CLI` is `pi`:**
|
||||
|
||||
Fresh call every round (Pi reviewer calls do not use session resume):
|
||||
@@ -391,6 +401,77 @@ Rules:
|
||||
|
||||
For `cursor`, the command script writes raw JSON to `/tmp/milestone-review-${REVIEW_ID}.json`. Do not run `jq` extraction until after the helper or fallback execution completes. If `jq` is not installed, inform the user: `brew install jq` (macOS) or equivalent.
|
||||
|
||||
**If `REVIEWER_CLI` is `opencode`:**
|
||||
|
||||
OpenCode uses `--agent plan` for read-oriented review. Fresh call is the recommended default.
|
||||
|
||||
Round 1:
|
||||
|
||||
```bash
|
||||
opencode run \
|
||||
-m ${REVIEWER_MODEL} \
|
||||
--agent plan \
|
||||
--format json \
|
||||
"Read the file /tmp/milestone-${REVIEW_ID}.md and review this milestone implementation.
|
||||
|
||||
Evaluate:
|
||||
1. Correctness — Does the implementation match the milestone spec?
|
||||
2. Acceptance criteria — Are all criteria met?
|
||||
3. Code quality — Clean, maintainable, no obvious issues?
|
||||
4. Test coverage — Are changes adequately tested?
|
||||
5. Security — Any security concerns introduced?
|
||||
|
||||
Return exactly these sections in order:
|
||||
## Summary
|
||||
## Findings
|
||||
### P0
|
||||
### P1
|
||||
### P2
|
||||
### P3
|
||||
## Verdict
|
||||
|
||||
Rules:
|
||||
- Order findings from highest severity to lowest.
|
||||
- Use \`- None.\` when a severity has no findings.
|
||||
- \`P0\` = total blocker, \`P1\` = major risk, \`P2\` = must-fix before approval, \`P3\` = cosmetic / nice to have.
|
||||
- End with exactly one verdict line: \`VERDICT: APPROVED\` or \`VERDICT: REVISE\`
|
||||
- \`VERDICT: APPROVED\` is allowed only when there are no \`P0\`, \`P1\`, or \`P2\` findings. \`P3\` findings are non-blocking." \
|
||||
> /tmp/milestone-review-${REVIEW_ID}.json
|
||||
```
|
||||
|
||||
Round 2 and later (fresh-call, recommended default):
|
||||
|
||||
```bash
|
||||
opencode run \
|
||||
-m ${REVIEWER_MODEL} \
|
||||
--agent plan \
|
||||
--format json \
|
||||
"You previously reviewed this milestone and requested revisions.
|
||||
|
||||
Previous feedback summary: [key points from last review]
|
||||
|
||||
I've revised. Updated milestone payload is in /tmp/milestone-${REVIEW_ID}.md.
|
||||
|
||||
Changes made:
|
||||
[List specific changes]
|
||||
|
||||
Re-review using the same ## Summary, ## Findings, and ## Verdict structure as before." \
|
||||
> /tmp/milestone-review-${REVIEW_ID}.json
|
||||
```
|
||||
|
||||
Extract the review body:
|
||||
|
||||
```bash
|
||||
jq -r '.[] | select(.type == "message" and .role == "assistant") | .content' \
|
||||
/tmp/milestone-review-${REVIEW_ID}.json \
|
||||
> /tmp/milestone-review-${REVIEW_ID}.md \
|
||||
|| cp /tmp/milestone-review-${REVIEW_ID}.json /tmp/milestone-review-${REVIEW_ID}.md
|
||||
```
|
||||
|
||||
If the JSON parse falls through, promote the raw JSON file as the review output. On any opencode
|
||||
CLI or JSON parsing failure, treat this loop round as `completed-empty-output` and follow the
|
||||
helper-failure escalation in Step 4.
|
||||
|
||||
Run the command script through the shared helper when available:
|
||||
|
||||
```bash
|
||||
@@ -410,6 +491,7 @@ fi
|
||||
Run the helper in the foreground and watch its live stdout for `state=in-progress` heartbeats. If your agent environment buffers command output until exit, start the helper in the background and poll `/tmp/milestone-review-${REVIEW_ID}.status` separately instead of treating heartbeats as post-hoc-only data.
|
||||
|
||||
After the command completes:
|
||||
|
||||
- If `REVIEWER_CLI=cursor`, extract the final review text:
|
||||
|
||||
```bash
|
||||
@@ -418,6 +500,7 @@ jq -r '.result' /tmp/milestone-review-${REVIEW_ID}.json > /tmp/milestone-review-
|
||||
```
|
||||
|
||||
- If `REVIEWER_CLI=codex`, extract `CODEX_SESSION_ID` from `/tmp/milestone-review-${REVIEW_ID}.runner.out` after the helper or fallback run. If the review text is only in `.runner.out`, move or copy the actual review body into `/tmp/milestone-review-${REVIEW_ID}.md` before verdict parsing.
|
||||
- If `REVIEWER_CLI=opencode`, the `jq` extraction above covers output capture. If it falls through, copy runner output: `cp /tmp/milestone-review-${REVIEW_ID}.runner.out /tmp/milestone-review-${REVIEW_ID}.md`. On Round 1, also attempt to capture the session id for optional use in subsequent rounds: `OPENCODE_SESSION_ID=$(jq -r 'if type == "array" then (.[0] | (.id? // .session_id?)) else (.id? // .session_id?) end // empty' /tmp/milestone-review-${REVIEW_ID}.json 2>/dev/null || true)`
|
||||
- If `REVIEWER_CLI=claude` or `REVIEWER_CLI=pi`, promote stdout captured by the helper or fallback runner into the markdown review file:
|
||||
|
||||
```bash
|
||||
@@ -435,14 +518,14 @@ Fallback is allowed only when the helper is missing or not executable.
|
||||
- `/tmp/milestone-review-${REVIEW_ID}.runner.out`
|
||||
3. Present review to the user:
|
||||
|
||||
```
|
||||
```markdown
|
||||
## Milestone Review — Round N (reviewer: ${REVIEWER_CLI} / ${REVIEWER_MODEL})
|
||||
|
||||
[Reviewer feedback]
|
||||
```
|
||||
|
||||
4. While the reviewer is still running, keep waiting as long as fresh `state=in-progress note="In progress N"` heartbeats continue to appear roughly once per minute.
|
||||
5. Check verdict:
|
||||
1. While the reviewer is still running, keep waiting as long as fresh `state=in-progress note="In progress N"` heartbeats continue to appear roughly once per minute.
|
||||
2. Check verdict:
|
||||
- **VERDICT: APPROVED** with no `P0`, `P1`, or `P2` findings -> proceed to Phase 5 Step 6 (commit & approve)
|
||||
- **VERDICT: APPROVED** with only `P3` findings -> optionally fix the `P3` items if they are cheap and safe, then proceed
|
||||
- **VERDICT: REVISE** or any `P0`, `P1`, or `P2` finding -> go to Step 5
|
||||
@@ -459,7 +542,7 @@ Fallback is allowed only when the helper is missing or not executable.
|
||||
|
||||
Summarize revisions for the user:
|
||||
|
||||
```
|
||||
```markdown
|
||||
### Revisions (Round N)
|
||||
- [Change and reason, one bullet per issue addressed]
|
||||
```
|
||||
@@ -470,7 +553,6 @@ If a revision contradicts the user's explicit requirements, skip it and note it
|
||||
|
||||
Rewrite `/tmp/milestone-review-${REVIEW_ID}.sh` for the next round. The script should contain the reviewer invocation only; do not run it directly.
|
||||
|
||||
|
||||
**If `REVIEWER_CLI` is `pi`:**
|
||||
|
||||
Fresh call with prior-round context (Pi reviewer calls do not use session resume):
|
||||
@@ -546,6 +628,59 @@ Keep findings ordered `P0` to `P3`, use `- None.` when a severity has no finding
|
||||
|
||||
If resume fails, fall back to fresh `cursor-agent -p` with context about prior rounds.
|
||||
|
||||
**If `REVIEWER_CLI` is `opencode`:**
|
||||
|
||||
Fresh call (recommended default — opencode has no guaranteed stable session ID in headless mode):
|
||||
|
||||
```bash
|
||||
opencode run \
|
||||
-m ${REVIEWER_MODEL} \
|
||||
--agent plan \
|
||||
--format json \
|
||||
"You previously reviewed this milestone and requested revisions.
|
||||
|
||||
Previous feedback summary: [key points from last review]
|
||||
|
||||
I've addressed your feedback. Updated milestone payload is in /tmp/milestone-${REVIEW_ID}.md.
|
||||
|
||||
Changes made:
|
||||
[List specific changes]
|
||||
|
||||
Re-review using the same \`## Summary\`, \`## Findings\`, and \`## Verdict\` structure as before.
|
||||
Keep findings ordered \`P0\` to \`P3\`, use \`- None.\` when a severity has no findings, and only use \`VERDICT: APPROVED\` when no \`P0\`, \`P1\`, or \`P2\` findings remain. \`P3\` findings are non-blocking." \
|
||||
> /tmp/milestone-review-${REVIEW_ID}.json
|
||||
|
||||
jq -r '.[] | select(.type == "message" and .role == "assistant") | .content' \
|
||||
/tmp/milestone-review-${REVIEW_ID}.json \
|
||||
> /tmp/milestone-review-${REVIEW_ID}.md \
|
||||
|| cp /tmp/milestone-review-${REVIEW_ID}.json /tmp/milestone-review-${REVIEW_ID}.md
|
||||
```
|
||||
|
||||
Optional session-resume path (only if `OPENCODE_SESSION_ID` was captured on Round 1 and your installed opencode accepts `-s <id>` reliably in headless mode):
|
||||
|
||||
```bash
|
||||
opencode run \
|
||||
-s ${OPENCODE_SESSION_ID} \
|
||||
-m ${REVIEWER_MODEL} \
|
||||
--agent plan \
|
||||
--format json \
|
||||
"I've addressed your feedback on this milestone. Updated diff and verification output are in /tmp/milestone-${REVIEW_ID}.md.
|
||||
|
||||
Changes made:
|
||||
[List specific changes]
|
||||
|
||||
Re-review using the same \`## Summary\`, \`## Findings\`, and \`## Verdict\` structure as before.
|
||||
Keep findings ordered \`P0\` to \`P3\`, use \`- None.\` when a severity has no findings, and only use \`VERDICT: APPROVED\` when no \`P0\`, \`P1\`, or \`P2\` findings remain. \`P3\` findings are non-blocking." \
|
||||
> /tmp/milestone-review-${REVIEW_ID}.json
|
||||
|
||||
jq -r '.[] | select(.type == "message" and .role == "assistant") | .content' \
|
||||
/tmp/milestone-review-${REVIEW_ID}.json \
|
||||
> /tmp/milestone-review-${REVIEW_ID}.md \
|
||||
|| cp /tmp/milestone-review-${REVIEW_ID}.json /tmp/milestone-review-${REVIEW_ID}.md
|
||||
```
|
||||
|
||||
If session resume fails (session expired or not supported), fall back to the fresh-call path above.
|
||||
|
||||
Do not run `jq` extraction until after the helper or fallback execution completes, then extract `/tmp/milestone-review-${REVIEW_ID}.md` from the JSON response.
|
||||
|
||||
After updating `/tmp/milestone-review-${REVIEW_ID}.sh`, run the same helper/fallback flow from Round 1.
|
||||
@@ -580,20 +715,20 @@ After all milestones are approved and committed:
|
||||
git merge implement/<plan-folder-name>
|
||||
```
|
||||
|
||||
4. Delete the worktree and its branch:
|
||||
1. Delete the worktree and its branch:
|
||||
|
||||
```bash
|
||||
git worktree remove <worktree-path>
|
||||
git branch -d implement/<plan-folder-name>
|
||||
```
|
||||
|
||||
5. Mark plan status as `completed` in `story-tracker.md`.
|
||||
1. Mark plan status as `completed` in `story-tracker.md`.
|
||||
|
||||
### Phase 8: Final Report
|
||||
|
||||
Present summary:
|
||||
|
||||
```
|
||||
```markdown
|
||||
## Implementation Complete
|
||||
|
||||
**Plan:** <plan-folder-name>
|
||||
@@ -619,6 +754,7 @@ fi
|
||||
```
|
||||
|
||||
Rules:
|
||||
|
||||
- Telegram is the only supported notification path. Do not use desktop notifications, `say`, email, or any other notifier.
|
||||
- Notification failures are non-blocking, but they must be surfaced to the user.
|
||||
- Before stopping for any user interaction, approval, or manual decision, send a Telegram summary first if configured.
|
||||
@@ -627,12 +763,14 @@ Rules:
|
||||
## Tracker Discipline (MANDATORY)
|
||||
|
||||
Before starting any story:
|
||||
|
||||
1. Open `story-tracker.md`
|
||||
2. Mark story `in-dev`
|
||||
3. Add notes if relevant
|
||||
4. Then begin implementation
|
||||
|
||||
After completing any story:
|
||||
|
||||
1. Mark story `completed`
|
||||
2. Review pending stories
|
||||
3. Update Last Updated and Stories Complete counts
|
||||
|
||||
Reference in New Issue
Block a user