From 492732955c62db66f40ef34d64b61caf5ca60f29 Mon Sep 17 00:00:00 2001
From: luke <fiorini@gmail.com>
Date: Wed, 11 Feb 2026 17:58:39 +0000
Subject: [PATCH] docs(create-plan): normalize OpenCode paths to
 ~/.config/opencode

---
 docs/CREATE-PLAN.md | 77 ++++++++++++++++++++++++++-------------------
 1 file changed, 45 insertions(+), 32 deletions(-)

diff --git a/docs/CREATE-PLAN.md b/docs/CREATE-PLAN.md
index be0857e..88ccddd 100644
--- a/docs/CREATE-PLAN.md
+++ b/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`
-  - `writing-plans`
-- For Codex, Superpowers runner must exist at:
-  - `~/.codex/superpowers/.codex/superpowers-codex`
+  - `superpowers:brainstorming`
+  - `superpowers:writing-plans`
+- For Codex, native skill discovery must be configured:
+  - `~/.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
-cp -R skills/create-plan/opencode/* ~/.opencode/skills/create-plan/
+mkdir -p ~/.config/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`
-- `.../skills/writing-plans/SKILL.md`
-
-For Codex, verify runner:
-
-```bash
-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
-```
+- Codex: `~/.agents/skills/superpowers/brainstorming/SKILL.md`
+- Codex: `~/.agents/skills/superpowers/writing-plans/SKILL.md`
+- Claude Code: `~/.claude/skills/superpowers/brainstorming/SKILL.md`
+- Claude Code: `~/.claude/skills/superpowers/writing-plans/SKILL.md`
+- OpenCode: `~/.config/opencode/skills/superpowers/brainstorming/SKILL.md`
+- OpenCode: `~/.config/opencode/skills/superpowers/writing-plans/SKILL.md`
 
 ## Key Behavior
 
@@ -76,9 +65,30 @@ Codex must invoke these explicit commands during planning:
 - Produces:
   - `original-plan.md`
   - `final-transcript.md`
-  - `milestone-plan.md`
-  - `story-tracker.md`
-  - `continuation-runbook.md`
+  - `milestone-plan.md` — includes Planning Guardrails section
+  - `story-tracker.md` — includes Tracking Guardrails section
+  - `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:
-  - `~/.codex/superpowers/.codex/superpowers-codex bootstrap`
-  - `~/.codex/superpowers/.codex/superpowers-codex use-skill brainstorming`
-  - `~/.codex/superpowers/.codex/superpowers-codex use-skill writing-plans`
+- Must use native skill discovery from `~/.agents/skills/` (no CLI wrappers).
+- Must verify Superpowers skills symlink: `~/.agents/skills/superpowers -> ~/.codex/superpowers/skills`
+- Must invoke required sub-skills with explicit announcements:
+  - `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