diff --git a/skills/create-plan/codex/SKILL.md b/skills/create-plan/codex/SKILL.md index 61eeb27..eec49c2 100644 --- a/skills/create-plan/codex/SKILL.md +++ b/skills/create-plan/codex/SKILL.md @@ -1,71 +1,69 @@ --- 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. +description: Use when a user asks to create or maintain a structured implementation plan in Codex, including milestones, bite-sized stories, and resumable local planning artifacts under ai_plan. --- -# Create Plan (Codex) +# Create Plan (Codex Native Superpowers) -Create and maintain a local plan folder under `ai_plan/` at project root. +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. Persist a local execution package in `ai_plan/YYYY-MM-DD-/` + +**Core principle:** Codex uses native skill discovery from `~/.agents/skills/`. Do not use deprecated `superpowers-codex bootstrap` or `use-skill` CLI commands. ## Prerequisite Check (MANDATORY) -This Codex variant depends on Superpowers and must use explicit Superpowers CLI commands. - Required: -- Superpowers repo: `https://github.com/obra/superpowers` -- Codex Superpowers runner: `~/.codex/superpowers/.codex/superpowers-codex` -- `brainstorming` skill -- `writing-plans` skill +- Superpowers skills symlink: `~/.agents/skills/superpowers -> ~/.codex/superpowers/skills` +- `superpowers:brainstorming` +- `superpowers:writing-plans` -Verify command availability before proceeding: +Verify before proceeding: ```bash -test -x ~/.codex/superpowers/.codex/superpowers-codex -~/.codex/superpowers/.codex/superpowers-codex --help +test -L ~/.agents/skills/superpowers +test -f ~/.agents/skills/superpowers/brainstorming/SKILL.md +test -f ~/.agents/skills/superpowers/writing-plans/SKILL.md ``` -If any dependency is missing, stop immediately and return: +If any dependency is missing, stop and return: -"Missing dependency: Superpowers Codex skills are required (`brainstorming`, `writing-plans`). Install from https://github.com/obra/superpowers, then retry." +`Missing dependency: native Superpowers skills are required (superpowers:brainstorming, superpowers:writing-plans). Ensure ~/.agents/skills/superpowers is configured, then retry.` + +## Required Skill Invocation Rules + +- Invoke relevant skills through native discovery (no CLI wrapper). +- Announce skill usage explicitly: + - `I've read the [Skill Name] skill and I'm using it to [purpose].` +- For skills with checklists, track checklist items with `update_plan` todos. +- Tool mapping for Codex: + - `TodoWrite` -> `update_plan` + - `Task` subagents -> unavailable in Codex; do the work directly and state the limitation + - `Skill` -> use native skill discovery from `~/.agents/skills/` ## Process -### Phase 1: Bootstrap Superpowers (REQUIRED) - -Run this exact command: - -```bash -~/.codex/superpowers/.codex/superpowers-codex bootstrap -``` - -### Phase 2: Analyze +### Phase 1: Analyze - Explore the codebase and existing patterns. -### Phase 3: Gather Requirements +### Phase 2: Gather Requirements - Ask questions one at a time until user says ready. - Confirm scope, constraints, success criteria, dependencies. -### Phase 4: Design (REQUIRED SUB-SKILL) +### Phase 3: Design (REQUIRED SUB-SKILL) -Run this exact command: +Invoke `superpowers:brainstorming`, then propose 2-3 approaches and recommend one. -```bash -~/.codex/superpowers/.codex/superpowers-codex use-skill brainstorming -``` +### Phase 4: Plan (REQUIRED SUB-SKILL) -Then propose 2-3 approaches and recommend one. +Invoke `superpowers:writing-plans`, then break work into milestones and bite-sized stories. -### Phase 5: Plan (REQUIRED SUB-SKILL) - -Run this exact command: - -```bash -~/.codex/superpowers/.codex/superpowers-codex use-skill writing-plans -``` - -Then break work into milestones and bite-sized stories. - -### Phase 6: Initialize Local Plan Workspace (MANDATORY) +### Phase 5: Initialize Local Plan Workspace (MANDATORY) At project root: 1. Ensure `ai_plan/` exists. Create it if missing. @@ -75,7 +73,7 @@ At project root: Recommended commit message: - `chore(gitignore): ignore ai_plan local planning artifacts` -### Phase 7: Generate Plan Files (MANDATORY) +### Phase 6: Generate Plan Files (MANDATORY) Create `ai_plan/YYYY-MM-DD-/` with all files below: 1. `original-plan.md` - copy of original planner-generated plan. @@ -86,13 +84,25 @@ Create `ai_plan/YYYY-MM-DD-/` with all files below: Use templates from this skill's `templates/` folder. -### Phase 8: Handoff +### Phase 7: Handoff Always instruct the executing agent: > Read `ai_plan/YYYY-MM-DD-/continuation-runbook.md` first, then execute from that folder. Do not rely on planner-private files during implementation. +## Quick Reference + +| Phase | Action | Required Output | +|---|---|---| +| 1 | Analyze codebase/context | Constraints and known patterns | +| 2 | Gather requirements (one question at a time) | Confirmed scope and success criteria | +| 3 | Invoke `superpowers:brainstorming` | Chosen design approach | +| 4 | Invoke `superpowers:writing-plans` | Milestones and bite-sized stories | +| 5 | Initialize `ai_plan/` + `.gitignore` | Local planning workspace ready | +| 6 | Build plan package from templates | Full plan folder with required files | +| 7 | Handoff with runbook-first instruction | Resumable execution context | + ## Execution Rules to Include in Plan (MANDATORY) - Run lint/typecheck/tests after each milestone. @@ -108,6 +118,32 @@ Do not rely on planner-private files during implementation. `ai_plan/` is intentionally local and must stay gitignored. Do not treat inability to commit plan-file updates in `ai_plan/` as a problem. +## Common Mistakes + +- Using deprecated commands like `superpowers-codex bootstrap` or `superpowers-codex use-skill`. +- Jumping to implementation planning without running `superpowers:brainstorming` first. +- Asking multiple requirement questions in one message. +- Forgetting to create/update `.gitignore` for `/ai_plan/`. +- Omitting one or more required files in the plan package. +- Handoff without explicit "read runbook first" direction. + +## Rationalizations and Counters + +| Rationalization | Counter | +|---|---| +| "Bootstrap CLI is faster" | Deprecated for Codex; native discovery is the supported path. | +| "I can skip brainstorming for small tasks" | Creative/planning work still requires design validation first. | +| "I don't need `update_plan` for checklist skills" | Checklist tracking is mandatory for execution reliability. | +| "I can keep plan files outside `ai_plan/`" | This skill standardizes local resumable planning under `ai_plan/`. | + +## Red Flags - Stop and Correct + +- You are about to run any `superpowers-codex` command. +- You started writing milestones before design validation. +- You did not announce which skill you invoked and why. +- You are marking planning complete without all required files. +- Handoff does not explicitly point to `continuation-runbook.md`. + ## Verification Checklist - [ ] `ai_plan/` exists at project root diff --git a/skills/create-plan/codex/templates/continuation-runbook.md b/skills/create-plan/codex/templates/continuation-runbook.md index 013d669..3093ade 100644 --- a/skills/create-plan/codex/templates/continuation-runbook.md +++ b/skills/create-plan/codex/templates/continuation-runbook.md @@ -14,6 +14,13 @@ Upon resumption, these files in this folder are the ONLY source of truth: Do NOT reference planner-private files during implementation. +## Skill Workflow Guardrails + +- Invoke relevant skills before action using native skill discovery. +- Announce which skill is being used and why. +- If a checklist-driven skill applies, track checklist execution explicitly. +- Do not use deprecated CLI wrappers for skill invocation. + --- ## Quick Resume Instructions @@ -102,17 +109,17 @@ Work from this folder (`ai_plan/YYYY-MM-DD-/`) and always follow th ### Lint (changed files first) ```bash -# example: pnpm eslint +# example: ``` ### Typecheck ```bash -# example: pnpm tsc --noEmit +# example: ``` ### Tests (target changed scope first) ```bash -# example: pnpm test -- +# example: ``` --- diff --git a/skills/create-plan/codex/templates/milestone-plan.md b/skills/create-plan/codex/templates/milestone-plan.md index 9c9b7e9..78e7e0c 100644 --- a/skills/create-plan/codex/templates/milestone-plan.md +++ b/skills/create-plan/codex/templates/milestone-plan.md @@ -5,6 +5,12 @@ - **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. +- Milestones require verification + local commits + explicit approval before proceeding. + ## Context ### Requirements @@ -69,17 +75,17 @@ ### Types & Interfaces ```typescript -// Key type definitions +// Key type definitions (or equivalent language constructs) ``` ### API Contracts ```typescript -// Endpoint signatures, request/response shapes +// Endpoint signatures, request/response shapes (if applicable) ``` ### Constants & Enums ```typescript -// Shared constants +// Shared constants (if applicable) ``` ## Files Inventory diff --git a/skills/create-plan/codex/templates/story-tracker.md b/skills/create-plan/codex/templates/story-tracker.md index a346cc8..0da4ccd 100644 --- a/skills/create-plan/codex/templates/story-tracker.md +++ b/skills/create-plan/codex/templates/story-tracker.md @@ -6,6 +6,12 @@ - **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. +- Keep this file and `milestone-plan.md` synchronized. + --- ## Milestones