Home/ai-coding-skills
2
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat(M2): Documentation flow, accuracy, consistency cleanup, and cross-platform shell portability

Browse Source
This commit is contained in:
Stefano Fiorini
2026-05-03 20:14:44 -05:00
parent 0443381aa0
commit be993429c1
59 changed files with 1898 additions and 385 deletions
Download Patch File Download Diff File Expand all files Collapse all files
skills/create-plan/claude-code/SKILL.md
+21 -8
View File
@@ -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"
skills/create-plan/claude-code/templates/continuation-runbook.md
+10
View File
@@ -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>
```
skills/create-plan/claude-code/templates/milestone-plan.md
+17
View 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)
skills/create-plan/claude-code/templates/story-tracker.md
+5
View File
@@ -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.
skills/create-plan/codex/SKILL.md
+16 -8
View File
@@ -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.
skills/create-plan/codex/templates/continuation-runbook.md
+10
View File
@@ -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>
```
skills/create-plan/codex/templates/milestone-plan.md
+18
View 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)
skills/create-plan/codex/templates/story-tracker.md
+6
View File
@@ -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.
skills/create-plan/cursor/SKILL.md
+20 -8
View File
@@ -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"
skills/create-plan/cursor/templates/continuation-runbook.md
+10
View File
@@ -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>
```
skills/create-plan/cursor/templates/milestone-plan.md
+18
View 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)
skills/create-plan/cursor/templates/story-tracker.md
+6
View File
@@ -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.
skills/create-plan/opencode/SKILL.md
+147 -8
View File
@@ -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"
skills/create-plan/opencode/templates/continuation-runbook.md
+10
View File
@@ -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>
```
skills/create-plan/opencode/templates/milestone-plan.md
+17
View 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)
skills/create-plan/opencode/templates/story-tracker.md
+5
View File
@@ -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.
skills/create-plan/pi/templates/continuation-runbook.md
+10
View File
@@ -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>
```
skills/create-plan/pi/templates/milestone-plan.md
+17
View 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)
skills/create-plan/pi/templates/story-tracker.md
+5
View File
@@ -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.