Add installable create-plan skills for codex, claude-code, and opencode
This commit is contained in:
60
README.md
60
README.md
@@ -1,3 +1,61 @@
|
||||
# ai-coding-skills
|
||||
|
||||
Cross-agent coding skills for Codex, Claude Code, and OpenCode
|
||||
Cross-agent skill collection for **Codex**, **Claude Code**, and **OpenCode**.
|
||||
|
||||
This repo is organized similarly to `obra/superpowers` and is designed to scale to many skills over time.
|
||||
|
||||
## Goals
|
||||
|
||||
- Keep skills portable across coding agents.
|
||||
- Keep each skill self-contained (`skills/<skill-name>/SKILL.md` + optional resources).
|
||||
- Enforce requirement checks for skills that depend on Superpower skills.
|
||||
|
||||
## Repository Layout
|
||||
|
||||
```text
|
||||
ai-coding-skills/
|
||||
├── README.md
|
||||
├── docs/
|
||||
│ ├── repository-structure.md
|
||||
│ └── requirements-gate.md
|
||||
├── skills/
|
||||
│ ├── _template/
|
||||
│ │ └── SKILL.md
|
||||
│ └── create-plan/
|
||||
│ ├── codex/
|
||||
│ ├── claude-code/
|
||||
│ └── opencode/
|
||||
├── .codex/
|
||||
├── .claude-plugin/
|
||||
├── .opencode/
|
||||
│ └── plugins/
|
||||
├── commands/
|
||||
├── hooks/
|
||||
└── tests/
|
||||
```
|
||||
|
||||
## Skills
|
||||
|
||||
| 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)
|
||||
|
||||
If a skill depends on Superpower skills (`https://github.com/obra/superpowers`), it must include an explicit prerequisite block in `SKILL.md` and fail fast with clear instructions when requirements are missing.
|
||||
|
||||
See: `docs/requirements-gate.md`
|
||||
|
||||
## Compatibility Policy
|
||||
|
||||
Each skill added to this repo should specify support status for:
|
||||
|
||||
- Codex
|
||||
- Claude Code
|
||||
- OpenCode
|
||||
|
||||
Use the template at `skills/_template/SKILL.md`.
|
||||
|
||||
47
docs/install.md
Normal file
47
docs/install.md
Normal file
@@ -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.
|
||||
68
skills/create-plan/claude-code/SKILL.md
Normal file
68
skills/create-plan/claude-code/SKILL.md
Normal file
@@ -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-<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).
|
||||
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-<short-title>/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
|
||||
128
skills/create-plan/claude-code/templates/continuation-runbook.md
Normal file
128
skills/create-plan/claude-code/templates/continuation-runbook.md
Normal file
@@ -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-<short-title>/` 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 <changed-file-1> <changed-file-2>
|
||||
```
|
||||
|
||||
### Typecheck
|
||||
```bash
|
||||
# example: pnpm tsc --noEmit
|
||||
```
|
||||
|
||||
### Tests (target changed scope first)
|
||||
```bash
|
||||
# example: pnpm test -- <related spec/file>
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## File Quick Reference
|
||||
|
||||
| File | Purpose |
|
||||
|------|---------|
|
||||
| `original-plan.md` | Original approved plan |
|
||||
| `final-transcript.md` | Final planning transcript |
|
||||
| `milestone-plan.md` | Full specification |
|
||||
| `story-tracker.md` | Current progress tracker |
|
||||
| `continuation-runbook.md` | This runbook |
|
||||
101
skills/create-plan/claude-code/templates/milestone-plan.md
Normal file
101
skills/create-plan/claude-code/templates/milestone-plan.md
Normal file
@@ -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)
|
||||
66
skills/create-plan/claude-code/templates/story-tracker.md
Normal file
66
skills/create-plan/claude-code/templates/story-tracker.md
Normal file
@@ -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.
|
||||
71
skills/create-plan/codex/SKILL.md
Normal file
71
skills/create-plan/codex/SKILL.md
Normal file
@@ -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-<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).
|
||||
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-<short-title>/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
|
||||
128
skills/create-plan/codex/templates/continuation-runbook.md
Normal file
128
skills/create-plan/codex/templates/continuation-runbook.md
Normal file
@@ -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-<short-title>/` 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 <changed-file-1> <changed-file-2>
|
||||
```
|
||||
|
||||
### Typecheck
|
||||
```bash
|
||||
# example: pnpm tsc --noEmit
|
||||
```
|
||||
|
||||
### Tests (target changed scope first)
|
||||
```bash
|
||||
# example: pnpm test -- <related spec/file>
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## File Quick Reference
|
||||
|
||||
| File | Purpose |
|
||||
|------|---------|
|
||||
| `original-plan.md` | Original approved plan |
|
||||
| `final-transcript.md` | Final planning transcript |
|
||||
| `milestone-plan.md` | Full specification |
|
||||
| `story-tracker.md` | Current progress tracker |
|
||||
| `continuation-runbook.md` | This runbook |
|
||||
101
skills/create-plan/codex/templates/milestone-plan.md
Normal file
101
skills/create-plan/codex/templates/milestone-plan.md
Normal file
@@ -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)
|
||||
66
skills/create-plan/codex/templates/story-tracker.md
Normal file
66
skills/create-plan/codex/templates/story-tracker.md
Normal file
@@ -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.
|
||||
67
skills/create-plan/opencode/SKILL.md
Normal file
67
skills/create-plan/opencode/SKILL.md
Normal file
@@ -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-<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).
|
||||
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-<short-title>/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
|
||||
128
skills/create-plan/opencode/templates/continuation-runbook.md
Normal file
128
skills/create-plan/opencode/templates/continuation-runbook.md
Normal file
@@ -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-<short-title>/` 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 <changed-file-1> <changed-file-2>
|
||||
```
|
||||
|
||||
### Typecheck
|
||||
```bash
|
||||
# example: pnpm tsc --noEmit
|
||||
```
|
||||
|
||||
### Tests (target changed scope first)
|
||||
```bash
|
||||
# example: pnpm test -- <related spec/file>
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## File Quick Reference
|
||||
|
||||
| File | Purpose |
|
||||
|------|---------|
|
||||
| `original-plan.md` | Original approved plan |
|
||||
| `final-transcript.md` | Final planning transcript |
|
||||
| `milestone-plan.md` | Full specification |
|
||||
| `story-tracker.md` | Current progress tracker |
|
||||
| `continuation-runbook.md` | This runbook |
|
||||
101
skills/create-plan/opencode/templates/milestone-plan.md
Normal file
101
skills/create-plan/opencode/templates/milestone-plan.md
Normal file
@@ -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)
|
||||
66
skills/create-plan/opencode/templates/story-tracker.md
Normal file
66
skills/create-plan/opencode/templates/story-tracker.md
Normal file
@@ -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.
|
||||
Reference in New Issue
Block a user