diff --git a/docs/CREATE-PLAN.md b/docs/CREATE-PLAN.md index 0404b19..a92ef2e 100644 --- a/docs/CREATE-PLAN.md +++ b/docs/CREATE-PLAN.md @@ -80,6 +80,24 @@ Codex must invoke these explicit commands during planning: - `story-tracker.md` - `continuation-runbook.md` +## Variant Hardening Notes + +### Claude Code + +- Must invoke explicit required sub-skills: + - `superpowers:brainstorming` + - `superpowers:writing-plans` +- Must enforce plan-mode file-write guard: + - if in plan mode, instruct user to exit plan mode before generating files +- Must copy `original-plan.md` from `~/.claude/plans/` when available. + +### 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` + ## Execution Workflow Rules - Read runbook first. diff --git a/skills/create-plan/claude-code/SKILL.md b/skills/create-plan/claude-code/SKILL.md index 5cfb707..a2e9298 100644 --- a/skills/create-plan/claude-code/SKILL.md +++ b/skills/create-plan/claude-code/SKILL.md @@ -1,6 +1,6 @@ --- 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 starting a new feature, project, or complex task that needs structured planning with milestones, bite-sized stories, and resumable execution context. ALWAYS invoke when user says "create a plan", "make a plan", "plan this", "start planning", or similar planning requests. --- # Create Plan (Claude Code) @@ -9,7 +9,7 @@ Create and maintain a local plan folder under `ai_plan/` at project root. ## Prerequisite Check (MANDATORY) -This skill depends on Superpowers planning skills. Before proceeding, verify required dependencies exist. +This Claude Code variant depends on Superpowers planning skills and explicit sub-skill invocation. Required: - Superpowers repo: `https://github.com/obra/superpowers` @@ -23,19 +23,23 @@ If any dependency is missing, stop immediately and return: ## Process ### Phase 1: Analyze -- Explore the codebase and existing patterns. +- Explore the codebase with exploration agents. +- Understand existing patterns and context. ### Phase 2: Gather Requirements -- Ask questions one at a time until user says ready. -- Confirm scope, constraints, success criteria, dependencies. +- Ask questions ONE AT A TIME until user says ready. +- Cover scope, constraints, success criteria, dependencies. +- Summarize before proceeding. -### Phase 3: Design -- Invoke `superpowers:brainstorming`. -- Propose 2-3 approaches and recommend one. +### Phase 3: Design (REQUIRED SUB-SKILL) +- Invoke `superpowers:brainstorming` explicitly. +- Present 2-3 approaches and recommend one. +- Validate design in sections. -### Phase 4: Plan -- Invoke `superpowers:writing-plans`. -- Break into milestones and bite-sized stories. +### Phase 4: Plan (REQUIRED SUB-SKILL) +- Invoke `superpowers:writing-plans` explicitly. +- Break into milestones and bite-sized stories (2-5 min each). +- Story IDs: `S-{milestone}{sequence}`. ### Phase 5: Initialize Local Plan Workspace (MANDATORY) @@ -47,23 +51,44 @@ At project root: Recommended commit message: - `chore(gitignore): ignore ai_plan local planning artifacts` -### Phase 6: Generate Plan Files (MANDATORY) +### Phase 6: Generate Plan Files (MANDATORY - DO NOT SKIP) -Create `ai_plan/YYYY-MM-DD-/` 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). +⚠️ **PLAN MODE CHECK:** If currently in plan mode: +1. Inform user that plan files cannot be written while in plan mode. +2. Instruct user to exit plan mode (approve plan or use ExitPlanMode). +3. Proceed with file generation only after exiting plan mode. -Use templates from this skill's `templates/` folder. +Create `ai_plan/YYYY-MM-DD-/` with ALL files: +1. `original-plan.md` - Copy the plan file from `~/.claude/plans/` as-is. +2. `final-transcript.md` - Copy of final planning transcript for reference. +3. `milestone-plan.md` - Full specification (template-based). +4. `story-tracker.md` - Status tracking (template-based, all stories start as `pending`). +5. `continuation-runbook.md` - Resume context and execution protocol (template-based). -### Phase 7: Handoff +Use templates from this skill's `templates/` folder (or `~/.claude/skills/create-plan/templates/` when installed directly in Claude Code). -Always instruct the executing agent: -> Read `ai_plan/YYYY-MM-DD-/continuation-runbook.md` first, then execute from that folder. +### Phase 7: Handoff Instructions -Do not rely on planner-private files during implementation. +When handing off to execution, instruct: +> Read `ai_plan/YYYY-MM-DD-/continuation-runbook.md` first, then execute from `ai_plan` files only. + +Private plan files under `~/.claude/plans/` are planning artifacts and must not be used as execution source of truth. + +## Tracker Discipline (MANDATORY) + +**ALWAYS update `story-tracker.md` before/after each story. NEVER proceed with stale tracker state.** + +Before starting any story: +1. Open `story-tracker.md` +2. Mark story `in-dev` +3. Add notes if relevant +4. Then begin implementation + +After completing any story: +1. Mark story `completed` +2. Add commit hash in Notes +3. Review pending stories +4. Update Last Updated and Stories Complete counts ## Execution Rules to Include in Plan (MANDATORY) @@ -86,9 +111,12 @@ Do not rely on planner-private files during implementation. - [ ] `.gitignore` includes `/ai_plan/` - [ ] `.gitignore` ignore-rule commit was created if needed - [ ] Plan directory created under `ai_plan/YYYY-MM-DD-/` -- [ ] `original-plan.md` present +- [ ] `original-plan.md` copied from `~/.claude/plans/` plan file - [ ] `final-transcript.md` present - [ ] `milestone-plan.md` present -- [ ] `story-tracker.md` present +- [ ] `story-tracker.md` created with all stories as `pending` - [ ] `continuation-runbook.md` present - [ ] Handoff explicitly says to read runbook first and execute from plan folder + +## Exit Triggers for Question Phase +User says: "ready", "done", "let's plan", "proceed", "enough questions"