From dc60cb833c04605ae15448981529d644b1f102da Mon Sep 17 00:00:00 2001 From: Luke Date: Mon, 9 Feb 2026 04:20:40 +0000 Subject: [PATCH] Add installable create-plan skills for codex, claude-code, and opencode --- README.md | 18 ++- docs/install.md | 47 +++++++ skills/create-plan/claude-code/SKILL.md | 68 ++++++++++ .../templates/continuation-runbook.md | 128 ++++++++++++++++++ .../claude-code/templates/milestone-plan.md | 101 ++++++++++++++ .../claude-code/templates/story-tracker.md | 66 +++++++++ skills/create-plan/codex/SKILL.md | 71 ++++++++++ .../codex/templates/continuation-runbook.md | 128 ++++++++++++++++++ .../codex/templates/milestone-plan.md | 101 ++++++++++++++ .../codex/templates/story-tracker.md | 66 +++++++++ skills/create-plan/opencode/SKILL.md | 67 +++++++++ .../templates/continuation-runbook.md | 128 ++++++++++++++++++ .../opencode/templates/milestone-plan.md | 101 ++++++++++++++ .../opencode/templates/story-tracker.md | 66 +++++++++ 14 files changed, 1151 insertions(+), 5 deletions(-) create mode 100644 docs/install.md create mode 100644 skills/create-plan/claude-code/SKILL.md create mode 100644 skills/create-plan/claude-code/templates/continuation-runbook.md create mode 100644 skills/create-plan/claude-code/templates/milestone-plan.md create mode 100644 skills/create-plan/claude-code/templates/story-tracker.md create mode 100644 skills/create-plan/codex/SKILL.md create mode 100644 skills/create-plan/codex/templates/continuation-runbook.md create mode 100644 skills/create-plan/codex/templates/milestone-plan.md create mode 100644 skills/create-plan/codex/templates/story-tracker.md create mode 100644 skills/create-plan/opencode/SKILL.md create mode 100644 skills/create-plan/opencode/templates/continuation-runbook.md create mode 100644 skills/create-plan/opencode/templates/milestone-plan.md create mode 100644 skills/create-plan/opencode/templates/story-tracker.md diff --git a/README.md b/README.md index 1d2ce44..c8a0d07 100644 --- a/README.md +++ b/README.md @@ -19,8 +19,12 @@ ai-coding-skills/ │ ├── repository-structure.md │ └── requirements-gate.md ├── skills/ -│ └── _template/ -│ └── SKILL.md +│ ├── _template/ +│ │ └── SKILL.md +│ └── create-plan/ +│ ├── codex/ +│ ├── claude-code/ +│ └── opencode/ ├── .codex/ ├── .claude-plugin/ ├── .opencode/ @@ -32,9 +36,13 @@ ai-coding-skills/ ## Skills -| Skill | Purpose | Status | -|---|---|---| -| _TBD_ | Waiting for your custom skill content | Planned | +| Skill | Agent Variant | Purpose | Status | +|---|---|---|---| +| create-plan | codex | Structured planning with milestones + runbook-first execution workflow | Ready | +| create-plan | claude-code | Structured planning with milestones + runbook-first execution workflow | Ready | +| create-plan | opencode | Structured planning with milestones + runbook-first execution workflow | Ready | + +See install instructions: `docs/install.md` ## Requirement Gate (Superpowers dependency) diff --git a/docs/install.md b/docs/install.md new file mode 100644 index 0000000..86f6aee --- /dev/null +++ b/docs/install.md @@ -0,0 +1,47 @@ +# Installation + +Install from this repo similarly to superpowers: clone once, then copy/symlink agent-specific skills. + +## 1) Clone + +```bash +git clone https://git.fiorinis.com/Home/ai-coding-skills.git +cd ai-coding-skills +``` + +## 2) Install `create-plan` + +### Codex + +```bash +mkdir -p ~/.codex/skills/create-plan +cp -R skills/create-plan/codex/* ~/.codex/skills/create-plan/ +``` + +### Claude Code + +```bash +mkdir -p ~/.claude/skills/create-plan +cp -R skills/create-plan/claude-code/* ~/.claude/skills/create-plan/ +``` + +### OpenCode + +Use your OpenCode skills/plugin path and copy the opencode variant. + +```bash +# Example path (adjust for your environment) +mkdir -p ~/.opencode/skills/create-plan +cp -R skills/create-plan/opencode/* ~/.opencode/skills/create-plan/ +``` + +## 3) Verify + +- Ensure `SKILL.md` exists in the destination folder. +- Ensure `templates/` files are present. +- Start a new agent session and ask: "create a plan for ..." to verify trigger behavior. + +## Notes + +- `docs/plans` / `docs/plan` can be gitignored by design. +- Plan artifacts are intentionally local. diff --git a/skills/create-plan/claude-code/SKILL.md b/skills/create-plan/claude-code/SKILL.md new file mode 100644 index 0000000..e382a80 --- /dev/null +++ b/skills/create-plan/claude-code/SKILL.md @@ -0,0 +1,68 @@ +--- +name: create-plan +description: Use when starting a new feature, project, or complex task that needs structured planning with milestones, bite-sized stories, and resumable execution context. Trigger for "create a plan", "make a plan", "plan this", "start planning", and similar requests. +--- + +# Create Plan (Claude Code) + +Create and maintain a local plan folder under `docs/plans/` (or `docs/plan/` if that repository convention is already in use). + +## 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. + +### Phase 3: Design +- Invoke `superpowers:brainstorming`. +- Propose 2-3 approaches and recommend one. + +### Phase 4: Plan +- Invoke `superpowers:writing-plans`. +- Break into milestones and bite-sized stories. + +### Phase 5: Generate Plan Files (MANDATORY) + +Create `docs/plans/YYYY-MM-DD-/` 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). +4. `story-tracker.md` - story/milestone status tracker (from template). +5. `continuation-runbook.md` - execution instructions and context (from template). + +Use templates from this skill's `templates/` folder. + +### Phase 6: Handoff + +Always instruct the executing agent: +> Read `docs/plans/YYYY-MM-DD-/continuation-runbook.md` first, then execute from that folder. + +Do not rely on planner-private files during implementation. + +## Execution Rules to Include in Plan (MANDATORY) + +- Run lint/typecheck/tests after each milestone. +- Prefer linting changed files only for speed. +- Commit locally after each completed milestone (**do not push**). +- Stop and ask user for feedback. +- Apply feedback, rerun checks, and commit again. +- Move to next milestone only after user approval. +- After all milestones are completed and approved, ask permission to push. +- Only after approved push: mark plan as completed. + +## Gitignore Note + +If `docs/plans` or `docs/plan` is gitignored, this is expected. Do not treat inability to commit plan-file updates as a problem. These files are local to the user. + +## Verification Checklist + +- [ ] Plan directory created under `docs/plans/` (or repo-standard `docs/plan/`) +- [ ] `original-plan.md` present +- [ ] `final-transcript.md` present +- [ ] `milestone-plan.md` present +- [ ] `story-tracker.md` present +- [ ] `continuation-runbook.md` present +- [ ] Handoff explicitly says to read runbook first and execute from plan folder diff --git a/skills/create-plan/claude-code/templates/continuation-runbook.md b/skills/create-plan/claude-code/templates/continuation-runbook.md new file mode 100644 index 0000000..42587c3 --- /dev/null +++ b/skills/create-plan/claude-code/templates/continuation-runbook.md @@ -0,0 +1,128 @@ +# Continuation Runbook: [Plan Title] + +## Reference Files (START HERE) + +Upon resumption, these files in this folder are the ONLY source of truth: + +| File | Purpose | When to Use | +|------|---------|-------------| +| `continuation-runbook.md` | Full context reproduction + execution workflow | Read FIRST | +| `story-tracker.md` | Current progress and status | Check/update BEFORE and AFTER every story | +| `milestone-plan.md` | Complete plan with specifications | Reference implementation details | +| `original-plan.md` | Original approved plan | Reference original intent | +| `final-transcript.md` | Final planning transcript | Reference reasoning/context | + +Do NOT reference planner-private files during implementation. + +--- + +## Quick Resume Instructions + +1. Read this runbook completely. +2. Check `story-tracker.md`. +3. Find next `pending` story and mark as `in-dev` before starting. +4. Implement the story. +5. Update tracker immediately after each change. + +--- + +## Mandatory Execution Workflow + +Work from this folder (`docs/plans/YYYY-MM-DD-/` or repo-specific `docs/plan/...`) and always follow this order: + +1. Read `continuation-runbook.md` first. +2. Execute stories milestone by milestone. +3. After completing a milestone: + - Run lint/typecheck/tests, prioritizing changed files for speed. + - Commit locally (**DO NOT PUSH**). + - Stop and ask user for feedback. +4. If feedback is provided: + - Apply feedback changes. + - Re-run checks for changed files. + - Commit locally again. + - Ask for milestone approval. +5. Only move to next milestone after explicit approval. +6. After all milestones are completed and approved: + - Ask permission to push. + - If approved, push. + - Mark plan status as `completed`. + +--- + +## Git Note + +If `docs/plan` or `docs/plans` is gitignored, that is expected and acceptable. Do not treat inability to commit plan-file updates as an error. These files are local planning artifacts. + +--- + +## Full Context Reproduction + +### Project Overview +[What this project/feature is about] + +### User Requirements +[All gathered requirements] + +### Scope +[In scope / out of scope] + +### Dependencies +[External dependencies, prerequisites, related systems] + +--- + +## Key Specifications + +### Type Definitions +```typescript +// Copy-paste ready type definitions +``` + +### Enums & Constants +```typescript +// All enums/constants needed +``` + +### API Endpoints +```typescript +// Request/response shapes +``` + +--- + +## Critical Design Decisions + +| Decision | Chosen Approach | Alternatives Rejected | Rationale | +|----------|-----------------|----------------------|-----------| +| [Topic] | [What we chose] | [Other options] | [Why] | + +--- + +## Verification Commands + +### Lint (changed files first) +```bash +# example: pnpm eslint +``` + +### Typecheck +```bash +# example: pnpm tsc --noEmit +``` + +### Tests (target changed scope first) +```bash +# example: pnpm test -- +``` + +--- + +## File Quick Reference + +| File | Purpose | +|------|---------| +| `original-plan.md` | Original approved plan | +| `final-transcript.md` | Final planning transcript | +| `milestone-plan.md` | Full specification | +| `story-tracker.md` | Current progress tracker | +| `continuation-runbook.md` | This runbook | diff --git a/skills/create-plan/claude-code/templates/milestone-plan.md b/skills/create-plan/claude-code/templates/milestone-plan.md new file mode 100644 index 0000000..c87a861 --- /dev/null +++ b/skills/create-plan/claude-code/templates/milestone-plan.md @@ -0,0 +1,101 @@ +# [Plan Title] + +## Overview +- **Goal:** [One sentence describing the end state] +- **Created:** YYYY-MM-DD +- **Status:** In Progress | Complete + +## Context + +### Requirements +[Gathered requirements from user questions] + +### Constraints +[Technical, business, or timeline constraints] + +### Success Criteria +[How we know this is complete] + +## Architecture + +### Design Decisions +[Key architectural choices and rationale] + +### Component Relationships +[How pieces fit together] + +### Data Flow +[How data moves through the system] + +## Milestones + +### M1: [Name] +**Description:** [What this milestone achieves] + +**Acceptance Criteria:** +- [ ] [Criterion 1] +- [ ] [Criterion 2] + +**Stories:** S-101, S-102, S-103... + +**Milestone Completion Rule (MANDATORY):** +- Run lint/typecheck/tests for changed files. +- Commit locally (DO NOT push). +- Stop and ask user for feedback. +- Apply feedback, re-check changed files, commit again. +- Move to next milestone only after user approval. + +--- + +### M2: [Name] +**Description:** [What this milestone achieves] + +**Acceptance Criteria:** +- [ ] [Criterion 1] +- [ ] [Criterion 2] + +**Stories:** S-201, S-202, S-203... + +**Milestone Completion Rule (MANDATORY):** +- Run lint/typecheck/tests for changed files. +- Commit locally (DO NOT push). +- Stop and ask user for feedback. +- Apply feedback, re-check changed files, commit again. +- Move to next milestone only after user approval. + +--- + +## Technical Specifications + +### Types & Interfaces +```typescript +// Key type definitions +``` + +### API Contracts +```typescript +// Endpoint signatures, request/response shapes +``` + +### Constants & Enums +```typescript +// Shared constants +``` + +## Files Inventory + +| File | Purpose | Milestone | +|------|---------|-----------| +| `path/to/file.ts` | [What it does] | M1 | +| `path/to/other.ts` | [What it does] | M2 | + +--- + +## Related Plan Files + +This file is part of the plan folder under `docs/plans/` (or `docs/plan/` if that repo convention is used): +- `original-plan.md` - Original approved plan (reference for original intent) +- `final-transcript.md` - Final planning transcript (reference for rationale/context) +- `milestone-plan.md` - This file (full specification) +- `story-tracker.md` - Status tracking (must be kept up to date) +- `continuation-runbook.md` - Resume/execution context (read first) diff --git a/skills/create-plan/claude-code/templates/story-tracker.md b/skills/create-plan/claude-code/templates/story-tracker.md new file mode 100644 index 0000000..a346cc8 --- /dev/null +++ b/skills/create-plan/claude-code/templates/story-tracker.md @@ -0,0 +1,66 @@ +# Story Tracker: [Plan Title] + +## Progress Summary +- **Current Milestone:** M1 +- **Stories Complete:** 0/N +- **Milestones Approved:** 0/M +- **Last Updated:** YYYY-MM-DD + +--- + +## Milestones + +### M1: [Name] + +| Story | Description | Status | Notes | +|-------|-------------|--------|-------| +| S-101 | [Brief description] | pending | | +| S-102 | [Brief description] | pending | | +| S-103 | [Brief description] | pending | | + +**Approval Status:** pending + +--- + +### M2: [Name] + +| Story | Description | Status | Notes | +|-------|-------------|--------|-------| +| S-201 | [Brief description] | pending | | +| S-202 | [Brief description] | pending | | +| S-203 | [Brief description] | pending | | + +**Approval Status:** pending + +--- + +## Status Legend + +| Status | Meaning | +|--------|---------| +| `pending` | Not started | +| `in-dev` | Currently being worked on | +| `completed` | Done - include commit hash in Notes | +| `deferred` | Postponed - include reason in Notes | + +## Update Instructions (MANDATORY) + +Before starting any story: +1. Mark story as `in-dev` +2. Update "Last Updated" + +After completing any story: +1. Mark story as `completed` +2. Add local commit hash to Notes +3. Update "Stories Complete" and "Last Updated" + +At milestone boundary: +1. Run lint/typecheck/tests for changed files +2. Commit (no push) +3. Request feedback +4. Apply feedback, re-check changed files, commit again +5. Mark milestone **Approval Status: approved** only after user confirms +6. Continue only after approval + +After all milestones approved: +- Ask permission to push and then mark plan completed. diff --git a/skills/create-plan/codex/SKILL.md b/skills/create-plan/codex/SKILL.md new file mode 100644 index 0000000..4b8a50b --- /dev/null +++ b/skills/create-plan/codex/SKILL.md @@ -0,0 +1,71 @@ +--- +name: create-plan +description: Use when starting a new feature, project, or complex task that needs structured planning with milestones, bite-sized stories, and resumable execution context. Trigger for "create a plan", "make a plan", "plan this", "start planning", and similar requests. +--- + +# Create Plan (Codex) + +Create and maintain a local plan folder under `docs/plans/` (or `docs/plan/` if that repository convention is already in use). + +## Process + +### Phase 1: Bootstrap +- Invoke Codex superpowers bootstrap and planning skills when available. + +### Phase 2: Analyze +- Explore the codebase and existing patterns. + +### Phase 3: Gather Requirements +- Ask questions one at a time until user says ready. +- Confirm scope, constraints, success criteria, dependencies. + +### Phase 4: Design +- Use brainstorming workflow. +- Propose 2-3 approaches and recommend one. + +### Phase 5: Plan +- Use writing-plans workflow. +- Break into milestones and bite-sized stories. + +### Phase 6: Generate Plan Files (MANDATORY) + +Create `docs/plans/YYYY-MM-DD-/` 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). +4. `story-tracker.md` - story/milestone status tracker (from template). +5. `continuation-runbook.md` - execution instructions and context (from template). + +Use templates from this skill's `templates/` folder. + +### Phase 7: Handoff + +Always instruct the executing agent: +> Read `docs/plans/YYYY-MM-DD-/continuation-runbook.md` first, then execute from that folder. + +Do not rely on planner-private files during implementation. + +## Execution Rules to Include in Plan (MANDATORY) + +- Run lint/typecheck/tests after each milestone. +- Prefer linting changed files only for speed. +- Commit locally after each completed milestone (**do not push**). +- Stop and ask user for feedback. +- Apply feedback, rerun checks, and commit again. +- Move to next milestone only after user approval. +- After all milestones are completed and approved, ask permission to push. +- Only after approved push: mark plan as completed. + +## Gitignore Note + +If `docs/plans` or `docs/plan` is gitignored, this is expected. Do not treat inability to commit plan-file updates as a problem. These files are local to the user. + +## Verification Checklist + +- [ ] Plan directory created under `docs/plans/` (or repo-standard `docs/plan/`) +- [ ] `original-plan.md` present +- [ ] `final-transcript.md` present +- [ ] `milestone-plan.md` present +- [ ] `story-tracker.md` present +- [ ] `continuation-runbook.md` present +- [ ] Handoff explicitly says to read runbook first and execute from plan folder diff --git a/skills/create-plan/codex/templates/continuation-runbook.md b/skills/create-plan/codex/templates/continuation-runbook.md new file mode 100644 index 0000000..42587c3 --- /dev/null +++ b/skills/create-plan/codex/templates/continuation-runbook.md @@ -0,0 +1,128 @@ +# Continuation Runbook: [Plan Title] + +## Reference Files (START HERE) + +Upon resumption, these files in this folder are the ONLY source of truth: + +| File | Purpose | When to Use | +|------|---------|-------------| +| `continuation-runbook.md` | Full context reproduction + execution workflow | Read FIRST | +| `story-tracker.md` | Current progress and status | Check/update BEFORE and AFTER every story | +| `milestone-plan.md` | Complete plan with specifications | Reference implementation details | +| `original-plan.md` | Original approved plan | Reference original intent | +| `final-transcript.md` | Final planning transcript | Reference reasoning/context | + +Do NOT reference planner-private files during implementation. + +--- + +## Quick Resume Instructions + +1. Read this runbook completely. +2. Check `story-tracker.md`. +3. Find next `pending` story and mark as `in-dev` before starting. +4. Implement the story. +5. Update tracker immediately after each change. + +--- + +## Mandatory Execution Workflow + +Work from this folder (`docs/plans/YYYY-MM-DD-/` or repo-specific `docs/plan/...`) and always follow this order: + +1. Read `continuation-runbook.md` first. +2. Execute stories milestone by milestone. +3. After completing a milestone: + - Run lint/typecheck/tests, prioritizing changed files for speed. + - Commit locally (**DO NOT PUSH**). + - Stop and ask user for feedback. +4. If feedback is provided: + - Apply feedback changes. + - Re-run checks for changed files. + - Commit locally again. + - Ask for milestone approval. +5. Only move to next milestone after explicit approval. +6. After all milestones are completed and approved: + - Ask permission to push. + - If approved, push. + - Mark plan status as `completed`. + +--- + +## Git Note + +If `docs/plan` or `docs/plans` is gitignored, that is expected and acceptable. Do not treat inability to commit plan-file updates as an error. These files are local planning artifacts. + +--- + +## Full Context Reproduction + +### Project Overview +[What this project/feature is about] + +### User Requirements +[All gathered requirements] + +### Scope +[In scope / out of scope] + +### Dependencies +[External dependencies, prerequisites, related systems] + +--- + +## Key Specifications + +### Type Definitions +```typescript +// Copy-paste ready type definitions +``` + +### Enums & Constants +```typescript +// All enums/constants needed +``` + +### API Endpoints +```typescript +// Request/response shapes +``` + +--- + +## Critical Design Decisions + +| Decision | Chosen Approach | Alternatives Rejected | Rationale | +|----------|-----------------|----------------------|-----------| +| [Topic] | [What we chose] | [Other options] | [Why] | + +--- + +## Verification Commands + +### Lint (changed files first) +```bash +# example: pnpm eslint +``` + +### Typecheck +```bash +# example: pnpm tsc --noEmit +``` + +### Tests (target changed scope first) +```bash +# example: pnpm test -- +``` + +--- + +## File Quick Reference + +| File | Purpose | +|------|---------| +| `original-plan.md` | Original approved plan | +| `final-transcript.md` | Final planning transcript | +| `milestone-plan.md` | Full specification | +| `story-tracker.md` | Current progress tracker | +| `continuation-runbook.md` | This runbook | diff --git a/skills/create-plan/codex/templates/milestone-plan.md b/skills/create-plan/codex/templates/milestone-plan.md new file mode 100644 index 0000000..c87a861 --- /dev/null +++ b/skills/create-plan/codex/templates/milestone-plan.md @@ -0,0 +1,101 @@ +# [Plan Title] + +## Overview +- **Goal:** [One sentence describing the end state] +- **Created:** YYYY-MM-DD +- **Status:** In Progress | Complete + +## Context + +### Requirements +[Gathered requirements from user questions] + +### Constraints +[Technical, business, or timeline constraints] + +### Success Criteria +[How we know this is complete] + +## Architecture + +### Design Decisions +[Key architectural choices and rationale] + +### Component Relationships +[How pieces fit together] + +### Data Flow +[How data moves through the system] + +## Milestones + +### M1: [Name] +**Description:** [What this milestone achieves] + +**Acceptance Criteria:** +- [ ] [Criterion 1] +- [ ] [Criterion 2] + +**Stories:** S-101, S-102, S-103... + +**Milestone Completion Rule (MANDATORY):** +- Run lint/typecheck/tests for changed files. +- Commit locally (DO NOT push). +- Stop and ask user for feedback. +- Apply feedback, re-check changed files, commit again. +- Move to next milestone only after user approval. + +--- + +### M2: [Name] +**Description:** [What this milestone achieves] + +**Acceptance Criteria:** +- [ ] [Criterion 1] +- [ ] [Criterion 2] + +**Stories:** S-201, S-202, S-203... + +**Milestone Completion Rule (MANDATORY):** +- Run lint/typecheck/tests for changed files. +- Commit locally (DO NOT push). +- Stop and ask user for feedback. +- Apply feedback, re-check changed files, commit again. +- Move to next milestone only after user approval. + +--- + +## Technical Specifications + +### Types & Interfaces +```typescript +// Key type definitions +``` + +### API Contracts +```typescript +// Endpoint signatures, request/response shapes +``` + +### Constants & Enums +```typescript +// Shared constants +``` + +## Files Inventory + +| File | Purpose | Milestone | +|------|---------|-----------| +| `path/to/file.ts` | [What it does] | M1 | +| `path/to/other.ts` | [What it does] | M2 | + +--- + +## Related Plan Files + +This file is part of the plan folder under `docs/plans/` (or `docs/plan/` if that repo convention is used): +- `original-plan.md` - Original approved plan (reference for original intent) +- `final-transcript.md` - Final planning transcript (reference for rationale/context) +- `milestone-plan.md` - This file (full specification) +- `story-tracker.md` - Status tracking (must be kept up to date) +- `continuation-runbook.md` - Resume/execution context (read first) diff --git a/skills/create-plan/codex/templates/story-tracker.md b/skills/create-plan/codex/templates/story-tracker.md new file mode 100644 index 0000000..a346cc8 --- /dev/null +++ b/skills/create-plan/codex/templates/story-tracker.md @@ -0,0 +1,66 @@ +# Story Tracker: [Plan Title] + +## Progress Summary +- **Current Milestone:** M1 +- **Stories Complete:** 0/N +- **Milestones Approved:** 0/M +- **Last Updated:** YYYY-MM-DD + +--- + +## Milestones + +### M1: [Name] + +| Story | Description | Status | Notes | +|-------|-------------|--------|-------| +| S-101 | [Brief description] | pending | | +| S-102 | [Brief description] | pending | | +| S-103 | [Brief description] | pending | | + +**Approval Status:** pending + +--- + +### M2: [Name] + +| Story | Description | Status | Notes | +|-------|-------------|--------|-------| +| S-201 | [Brief description] | pending | | +| S-202 | [Brief description] | pending | | +| S-203 | [Brief description] | pending | | + +**Approval Status:** pending + +--- + +## Status Legend + +| Status | Meaning | +|--------|---------| +| `pending` | Not started | +| `in-dev` | Currently being worked on | +| `completed` | Done - include commit hash in Notes | +| `deferred` | Postponed - include reason in Notes | + +## Update Instructions (MANDATORY) + +Before starting any story: +1. Mark story as `in-dev` +2. Update "Last Updated" + +After completing any story: +1. Mark story as `completed` +2. Add local commit hash to Notes +3. Update "Stories Complete" and "Last Updated" + +At milestone boundary: +1. Run lint/typecheck/tests for changed files +2. Commit (no push) +3. Request feedback +4. Apply feedback, re-check changed files, commit again +5. Mark milestone **Approval Status: approved** only after user confirms +6. Continue only after approval + +After all milestones approved: +- Ask permission to push and then mark plan completed. diff --git a/skills/create-plan/opencode/SKILL.md b/skills/create-plan/opencode/SKILL.md new file mode 100644 index 0000000..4f3909f --- /dev/null +++ b/skills/create-plan/opencode/SKILL.md @@ -0,0 +1,67 @@ +--- +name: create-plan +description: Use when starting a new feature, project, or complex task that needs structured planning with milestones, bite-sized stories, and resumable execution context in Opencode workflows. Trigger for "create a plan", "make a plan", "plan this", and similar planning requests. +--- + +# Create Plan (Opencode) + +Create and maintain a local plan folder under `docs/plans/` (or `docs/plan/` if that repository convention is already in use). + +## 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. + +### Phase 3: Design +- Use Opencode planning/brainstorming flow. +- Propose 2-3 approaches and recommend one. + +### Phase 4: Plan +- Break into milestones and bite-sized stories. + +### Phase 5: Generate Plan Files (MANDATORY) + +Create `docs/plans/YYYY-MM-DD-/` 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). +4. `story-tracker.md` - story/milestone status tracker (from template). +5. `continuation-runbook.md` - execution instructions and context (from template). + +Use templates from this skill's `templates/` folder. + +### Phase 6: Handoff + +Always instruct the executing agent: +> Read `docs/plans/YYYY-MM-DD-/continuation-runbook.md` first, then execute from that folder. + +Do not rely on planner-private files during implementation. + +## Execution Rules to Include in Plan (MANDATORY) + +- Run lint/typecheck/tests after each milestone. +- Prefer linting changed files only for speed. +- Commit locally after each completed milestone (**do not push**). +- Stop and ask user for feedback. +- Apply feedback, rerun checks, and commit again. +- Move to next milestone only after user approval. +- After all milestones are completed and approved, ask permission to push. +- Only after approved push: mark plan as completed. + +## Gitignore Note + +If `docs/plans` or `docs/plan` is gitignored, this is expected. Do not treat inability to commit plan-file updates as a problem. These files are local to the user. + +## Verification Checklist + +- [ ] Plan directory created under `docs/plans/` (or repo-standard `docs/plan/`) +- [ ] `original-plan.md` present +- [ ] `final-transcript.md` present +- [ ] `milestone-plan.md` present +- [ ] `story-tracker.md` present +- [ ] `continuation-runbook.md` present +- [ ] Handoff explicitly says to read runbook first and execute from plan folder diff --git a/skills/create-plan/opencode/templates/continuation-runbook.md b/skills/create-plan/opencode/templates/continuation-runbook.md new file mode 100644 index 0000000..42587c3 --- /dev/null +++ b/skills/create-plan/opencode/templates/continuation-runbook.md @@ -0,0 +1,128 @@ +# Continuation Runbook: [Plan Title] + +## Reference Files (START HERE) + +Upon resumption, these files in this folder are the ONLY source of truth: + +| File | Purpose | When to Use | +|------|---------|-------------| +| `continuation-runbook.md` | Full context reproduction + execution workflow | Read FIRST | +| `story-tracker.md` | Current progress and status | Check/update BEFORE and AFTER every story | +| `milestone-plan.md` | Complete plan with specifications | Reference implementation details | +| `original-plan.md` | Original approved plan | Reference original intent | +| `final-transcript.md` | Final planning transcript | Reference reasoning/context | + +Do NOT reference planner-private files during implementation. + +--- + +## Quick Resume Instructions + +1. Read this runbook completely. +2. Check `story-tracker.md`. +3. Find next `pending` story and mark as `in-dev` before starting. +4. Implement the story. +5. Update tracker immediately after each change. + +--- + +## Mandatory Execution Workflow + +Work from this folder (`docs/plans/YYYY-MM-DD-/` or repo-specific `docs/plan/...`) and always follow this order: + +1. Read `continuation-runbook.md` first. +2. Execute stories milestone by milestone. +3. After completing a milestone: + - Run lint/typecheck/tests, prioritizing changed files for speed. + - Commit locally (**DO NOT PUSH**). + - Stop and ask user for feedback. +4. If feedback is provided: + - Apply feedback changes. + - Re-run checks for changed files. + - Commit locally again. + - Ask for milestone approval. +5. Only move to next milestone after explicit approval. +6. After all milestones are completed and approved: + - Ask permission to push. + - If approved, push. + - Mark plan status as `completed`. + +--- + +## Git Note + +If `docs/plan` or `docs/plans` is gitignored, that is expected and acceptable. Do not treat inability to commit plan-file updates as an error. These files are local planning artifacts. + +--- + +## Full Context Reproduction + +### Project Overview +[What this project/feature is about] + +### User Requirements +[All gathered requirements] + +### Scope +[In scope / out of scope] + +### Dependencies +[External dependencies, prerequisites, related systems] + +--- + +## Key Specifications + +### Type Definitions +```typescript +// Copy-paste ready type definitions +``` + +### Enums & Constants +```typescript +// All enums/constants needed +``` + +### API Endpoints +```typescript +// Request/response shapes +``` + +--- + +## Critical Design Decisions + +| Decision | Chosen Approach | Alternatives Rejected | Rationale | +|----------|-----------------|----------------------|-----------| +| [Topic] | [What we chose] | [Other options] | [Why] | + +--- + +## Verification Commands + +### Lint (changed files first) +```bash +# example: pnpm eslint +``` + +### Typecheck +```bash +# example: pnpm tsc --noEmit +``` + +### Tests (target changed scope first) +```bash +# example: pnpm test -- +``` + +--- + +## File Quick Reference + +| File | Purpose | +|------|---------| +| `original-plan.md` | Original approved plan | +| `final-transcript.md` | Final planning transcript | +| `milestone-plan.md` | Full specification | +| `story-tracker.md` | Current progress tracker | +| `continuation-runbook.md` | This runbook | diff --git a/skills/create-plan/opencode/templates/milestone-plan.md b/skills/create-plan/opencode/templates/milestone-plan.md new file mode 100644 index 0000000..c87a861 --- /dev/null +++ b/skills/create-plan/opencode/templates/milestone-plan.md @@ -0,0 +1,101 @@ +# [Plan Title] + +## Overview +- **Goal:** [One sentence describing the end state] +- **Created:** YYYY-MM-DD +- **Status:** In Progress | Complete + +## Context + +### Requirements +[Gathered requirements from user questions] + +### Constraints +[Technical, business, or timeline constraints] + +### Success Criteria +[How we know this is complete] + +## Architecture + +### Design Decisions +[Key architectural choices and rationale] + +### Component Relationships +[How pieces fit together] + +### Data Flow +[How data moves through the system] + +## Milestones + +### M1: [Name] +**Description:** [What this milestone achieves] + +**Acceptance Criteria:** +- [ ] [Criterion 1] +- [ ] [Criterion 2] + +**Stories:** S-101, S-102, S-103... + +**Milestone Completion Rule (MANDATORY):** +- Run lint/typecheck/tests for changed files. +- Commit locally (DO NOT push). +- Stop and ask user for feedback. +- Apply feedback, re-check changed files, commit again. +- Move to next milestone only after user approval. + +--- + +### M2: [Name] +**Description:** [What this milestone achieves] + +**Acceptance Criteria:** +- [ ] [Criterion 1] +- [ ] [Criterion 2] + +**Stories:** S-201, S-202, S-203... + +**Milestone Completion Rule (MANDATORY):** +- Run lint/typecheck/tests for changed files. +- Commit locally (DO NOT push). +- Stop and ask user for feedback. +- Apply feedback, re-check changed files, commit again. +- Move to next milestone only after user approval. + +--- + +## Technical Specifications + +### Types & Interfaces +```typescript +// Key type definitions +``` + +### API Contracts +```typescript +// Endpoint signatures, request/response shapes +``` + +### Constants & Enums +```typescript +// Shared constants +``` + +## Files Inventory + +| File | Purpose | Milestone | +|------|---------|-----------| +| `path/to/file.ts` | [What it does] | M1 | +| `path/to/other.ts` | [What it does] | M2 | + +--- + +## Related Plan Files + +This file is part of the plan folder under `docs/plans/` (or `docs/plan/` if that repo convention is used): +- `original-plan.md` - Original approved plan (reference for original intent) +- `final-transcript.md` - Final planning transcript (reference for rationale/context) +- `milestone-plan.md` - This file (full specification) +- `story-tracker.md` - Status tracking (must be kept up to date) +- `continuation-runbook.md` - Resume/execution context (read first) diff --git a/skills/create-plan/opencode/templates/story-tracker.md b/skills/create-plan/opencode/templates/story-tracker.md new file mode 100644 index 0000000..a346cc8 --- /dev/null +++ b/skills/create-plan/opencode/templates/story-tracker.md @@ -0,0 +1,66 @@ +# Story Tracker: [Plan Title] + +## Progress Summary +- **Current Milestone:** M1 +- **Stories Complete:** 0/N +- **Milestones Approved:** 0/M +- **Last Updated:** YYYY-MM-DD + +--- + +## Milestones + +### M1: [Name] + +| Story | Description | Status | Notes | +|-------|-------------|--------|-------| +| S-101 | [Brief description] | pending | | +| S-102 | [Brief description] | pending | | +| S-103 | [Brief description] | pending | | + +**Approval Status:** pending + +--- + +### M2: [Name] + +| Story | Description | Status | Notes | +|-------|-------------|--------|-------| +| S-201 | [Brief description] | pending | | +| S-202 | [Brief description] | pending | | +| S-203 | [Brief description] | pending | | + +**Approval Status:** pending + +--- + +## Status Legend + +| Status | Meaning | +|--------|---------| +| `pending` | Not started | +| `in-dev` | Currently being worked on | +| `completed` | Done - include commit hash in Notes | +| `deferred` | Postponed - include reason in Notes | + +## Update Instructions (MANDATORY) + +Before starting any story: +1. Mark story as `in-dev` +2. Update "Last Updated" + +After completing any story: +1. Mark story as `completed` +2. Add local commit hash to Notes +3. Update "Stories Complete" and "Last Updated" + +At milestone boundary: +1. Run lint/typecheck/tests for changed files +2. Commit (no push) +3. Request feedback +4. Apply feedback, re-check changed files, commit again +5. Mark milestone **Approval Status: approved** only after user confirms +6. Continue only after approval + +After all milestones approved: +- Ask permission to push and then mark plan completed.