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

feat(create-plan/codex): switch to native superpowers workflow and add guardrails

Browse Source
This commit is contained in:
luke
2026-02-11 18:03:16 +00:00
parent 39d758298b
commit 76fd7f374f
4 changed files with 104 additions and 49 deletions
Download Patch File Download Diff File Expand all files Collapse all files

122
skills/create-plan/codex/SKILL.md
View File

@@ -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-<short-title>/`
**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-<short-title>/` with all files below:
1. `original-plan.md` - copy of original planner-generated plan.
@@ -86,13 +84,25 @@ Create `ai_plan/YYYY-MM-DD-<short-title>/` 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-<short-title>/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

13
skills/create-plan/codex/templates/continuation-runbook.md
View File

@@ -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-<short-title>/`) and always follow th
### Lint (changed files first)
```bash
# example: pnpm eslint <changed-file-1> <changed-file-2>
# example: <lint-command> <changed-file-1> <changed-file-2>
```
### Typecheck
```bash
# example: pnpm tsc --noEmit
# example: <typecheck-command>
```
### Tests (target changed scope first)
```bash
# example: pnpm test -- <related spec/file>
# example: <test-command> <related spec/file>
```
---

12
skills/create-plan/codex/templates/milestone-plan.md
View File

@@ -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

6
skills/create-plan/codex/templates/story-tracker.md
View File

@@ -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