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

docs/CREATE-PLAN.md

@@ -8,14 +8,14 @@ Create structured implementation plans with milestone and story tracking.
 
 - Superpowers skills installed from: https://github.com/obra/superpowers
 - Required dependencies:
-  - `brainstorming`
+  - `superpowers:brainstorming`
-  - `writing-plans`
+  - `superpowers:writing-plans`
-- For Codex, Superpowers runner must exist at:
+- For Codex, native skill discovery must be configured:
-  - `~/.codex/superpowers/.codex/superpowers-codex`
+  - `~/.agents/skills/superpowers -> ~/.codex/superpowers/skills`
 
 If dependencies are missing, stop and return:
 
-"Missing dependency: Superpowers planning 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`). Install from https://github.com/obra/superpowers, then retry."
 
 ## Install
 
@@ -36,8 +36,8 @@ cp -R skills/create-plan/claude-code/* ~/.claude/skills/create-plan/
 ### OpenCode
 
 ```bash
-mkdir -p ~/.opencode/skills/create-plan
+mkdir -p ~/.config/opencode/skills/create-plan
-cp -R skills/create-plan/opencode/* ~/.opencode/skills/create-plan/
+cp -R skills/create-plan/opencode/* ~/.config/opencode/skills/create-plan/
 ```
 
 ## Verify Installation
@@ -45,28 +45,17 @@ cp -R skills/create-plan/opencode/* ~/.opencode/skills/create-plan/
 ```bash
 test -f ~/.codex/skills/create-plan/SKILL.md || true
 test -f ~/.claude/skills/create-plan/SKILL.md || true
-test -f ~/.opencode/skills/create-plan/SKILL.md || true
+test -f ~/.config/opencode/skills/create-plan/SKILL.md || true
 ```
 
 Verify Superpowers dependencies exist in your agent skills root:
 
-- `.../skills/brainstorming/SKILL.md`
+- Codex: `~/.agents/skills/superpowers/brainstorming/SKILL.md`
-- `.../skills/writing-plans/SKILL.md`
+- Codex: `~/.agents/skills/superpowers/writing-plans/SKILL.md`
-
+- Claude Code: `~/.claude/skills/superpowers/brainstorming/SKILL.md`
-For Codex, verify runner:
+- Claude Code: `~/.claude/skills/superpowers/writing-plans/SKILL.md`
-
+- OpenCode: `~/.config/opencode/skills/superpowers/brainstorming/SKILL.md`
-```bash
+- OpenCode: `~/.config/opencode/skills/superpowers/writing-plans/SKILL.md`
-test -x ~/.codex/superpowers/.codex/superpowers-codex
-~/.codex/superpowers/.codex/superpowers-codex --help
-```
-
-Codex must invoke these explicit commands during planning:
-
-```bash
-~/.codex/superpowers/.codex/superpowers-codex bootstrap
-~/.codex/superpowers/.codex/superpowers-codex use-skill brainstorming
-~/.codex/superpowers/.codex/superpowers-codex use-skill writing-plans
-```
 
 ## Key Behavior
 
@@ -76,9 +65,30 @@ Codex must invoke these explicit commands during planning:
 - Produces:
   - `original-plan.md`
   - `final-transcript.md`
-  - `milestone-plan.md`
+  - `milestone-plan.md` — includes Planning Guardrails section
-  - `story-tracker.md`
+  - `story-tracker.md` — includes Tracking Guardrails section
-  - `continuation-runbook.md`
+  - `continuation-runbook.md` — includes Skill Workflow Guardrails section
+
+## Template Guardrails
+
+All plan templates now include guardrail sections that enforce:
+
+**Planning Guardrails** (`milestone-plan.md`):
+- Design validation before implementation planning
+- Native skill discovery (no deprecated CLI wrappers)
+- Milestone verification + local commits + explicit approval
+
+**Tracking Guardrails** (`story-tracker.md`):
+- Immediate status updates when work starts/completes
+- Explicit user approval at each milestone boundary
+- No pushes until all milestones approved
+- Synchronization between tracker and plan files
+
+**Skill Workflow Guardrails** (`continuation-runbook.md`):
+- Native skill invocation before action
+- Explicit skill announcements
+- Checklist tracking for driven skills
+- No deprecated CLI wrappers
 
 ## Variant Hardening Notes
 
@@ -93,10 +103,13 @@ Codex must invoke these explicit commands during planning:
 
 ### Codex
 
-- Must run explicit commands:
+- Must use native skill discovery from `~/.agents/skills/` (no CLI wrappers).
-  - `~/.codex/superpowers/.codex/superpowers-codex bootstrap`
+- Must verify Superpowers skills symlink: `~/.agents/skills/superpowers -> ~/.codex/superpowers/skills`
-  - `~/.codex/superpowers/.codex/superpowers-codex use-skill brainstorming`
+- Must invoke required sub-skills with explicit announcements:
-  - `~/.codex/superpowers/.codex/superpowers-codex use-skill writing-plans`
+  - `superpowers:brainstorming` — for design exploration and approach validation
+  - `superpowers:writing-plans` — for milestone and story breakdown
+- Must track checklist-driven skills with `update_plan` todos.
+- Deprecated CLI commands (`superpowers-codex bootstrap`, `use-skill`) must NOT be used.
 
 ### OpenCode
 

docs/WEB-AUTOMATION.md

@@ -39,9 +39,9 @@ npx camoufox-js fetch
 ### OpenCode
 
 ```bash
-mkdir -p ~/.opencode/skills/web-automation
+mkdir -p ~/.config/opencode/skills/web-automation
-cp -R skills/web-automation/opencode/* ~/.opencode/skills/web-automation/
+cp -R skills/web-automation/opencode/* ~/.config/opencode/skills/web-automation/
-cd ~/.opencode/skills/web-automation/scripts
+cd ~/.config/opencode/skills/web-automation/scripts
 pnpm install
 pnpm add playwright-core camoufox-js
 npx camoufox-js fetch

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-<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`
+- Superpowers skills symlink: `~/.agents/skills/superpowers -> ~/.codex/superpowers/skills`
-- Codex Superpowers runner: `~/.codex/superpowers/.codex/superpowers-codex`
+- `superpowers:brainstorming`
-- `brainstorming` skill
+- `superpowers:writing-plans`
-- `writing-plans` skill
 
-Verify command availability before proceeding:
+Verify before proceeding:
 
 ```bash
-test -x ~/.codex/superpowers/.codex/superpowers-codex
+test -L ~/.agents/skills/superpowers
-~/.codex/superpowers/.codex/superpowers-codex --help
+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)
+### Phase 1: Analyze
-
-Run this exact command:
-
-```bash
-~/.codex/superpowers/.codex/superpowers-codex bootstrap
-```
-
-### Phase 2: 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
+### Phase 4: Plan (REQUIRED SUB-SKILL)
-~/.codex/superpowers/.codex/superpowers-codex use-skill brainstorming
-```
 
-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)
+### Phase 5: Initialize Local Plan Workspace (MANDATORY)
-
-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)
 
 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

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

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

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