Planning Mode
You are now in planning mode for [PROJECT_NAME].
Prerequisites - Read First
Before creating any plan, you MUST read ALL THE LINES of:
- @docs/ARCHI.md - Understand current system architecture
- [ADAPT_TO_PROJECT: optional — list additional living docs a plan must respect (e.g. an operations manual, a public API contract), each with the condition under which it must be read ("only if the feature touches X"). Remove this line if the project has none.]
Your Task
Plan the following feature: $ARGUMENTS
YOLO: if the arguments contain --yolo, strip the flag from the feature description and run in YOLO mode — Step 4's approval question is skipped and the plan chains directly into TRIP-2-implement once Codex returns APPROVED. NEEDS_REWORK always cancels YOLO and falls back to the normal Step 4 question. Discovery questions (Step 1) still run — YOLO removes the end gate, not the understanding phase.
Step 1: Discovery & Clarification (Interactive)
Do NOT start writing a plan immediately. First, engage in a discovery conversation to fully understand the user's intent.
1.1 Initial Understanding
After reading the feature request, summarize your understanding in 2-3 sentences, then use the AskUserQuestion tool to present clarifying questions with structured options.
Frame questions around:
- Scope: What's included vs excluded?
- Behavior: How should it work from the user's perspective?
- Constraints: Any technical limitations, deadlines, or dependencies?
- Priority: What's most important if trade-offs are needed?
For each question, provide 2-4 concrete options based on your analysis of the codebase and the feature request. Always let the user provide custom input via the built-in "Other" option.
Every question ships a recommendation. For each question, pick the option you'd choose and mark it — put it first in the options list with (Recommended) appended to its label. If you genuinely have no lean, say so in the option descriptions rather than faking a recommendation.
1.2 Alignment: keep asking until aligned
The goal is a shared understanding of the feature, not a fixed number of questions. Batch up to 4 questions per AskUserQuestion call (one "round"), and keep asking follow-up rounds while genuine blocking ambiguities remain. Stop as soon as none do — do not manufacture questions to fill a quota.
A safety ceiling caps the questioning if you're still finding gaps, scaled by plan size:
| Plan size | Ceiling (rounds of up to 4 questions) |
|---|---|
| patch | 1 |
| minor | 3 |
| major | 5 |
When a ceiling is hit, summarize what you know, note open assumptions explicitly, and proceed to Step 2. Don't over-question: the Codex plan review (Step 3) backstops anything discovery misses, so lean toward proceeding rather than squeezing out every edge case.
User escape hatch. From the second round onward, include a standing option worded like "Use your recommendations for everything remaining → write the plan" as one of the choices. If the user picks it, stop asking immediately, adopt your recommended answer for every still-open question, and proceed to Step 2. The user decides when alignment is enough — this option lets them, without waiting for the ceiling.
After discovery ends (aligned, ceiling hit, or escape hatch), proceed directly to writing the plan (Step 2).
Step 2: Plan Document Creation
Once understanding is confirmed, create the plan document.
File Naming
Depending on the feature (major, minor, patch), propose a new version using SemVer (x.y.z) and create:
docs/1-plans/F_[version]_[feature-name].plan.md
Required Sections
markdown# [Feature Name] Implementation Plan ## Overview [2-4 sentences describing the feature and its purpose] ## Problem Statement (if applicable) [Current limitations/issues this feature addresses] ## Solution Architecture [High-level design approach] ## Implementation Details ### 1. [Component/Module/File Name] **File**: `path/to/file` [Detailed description of changes needed] **Current state** (if modifying existing): [Describe what currently exists] **Modifications**: - Specific change 1 (around line X) - Specific change 2 (around line Y) ### 2. [Next Component/Module/File] [Continue with same pattern] ## Technical Considerations [ADAPT_TO_PROJECT: Replace with project-specific technical concerns during Init] - **Pattern Usage**: Which existing patterns to follow (from ARCHI.md) - **[Concern 1]**: [Description] - **[Concern 2]**: [Description] - **Edge Cases**: [Relevant edge cases for this feature] ## Files to Modify/Create [Comprehensive numbered list with purposes] 1. `path/to/file1` (modify) - Purpose description 2. `path/to/file2` (new) - Purpose description ## Type Definitions (if applicable) [New types, interfaces, structs, or modifications to existing ones] ## Performance & Cost Impact (if applicable) [Expected performance implications] ## Backward Compatibility (if applicable) [Migration strategy if needed] ## Test Impact [2-5 bullets: which existing tests the change affects, what new logic will need tests, whether an integration/E2E check applies. No test code — the TRIP-2 testing gate consumes this section.] ## Documentation Impact [Mandatory. List every document OUTSIDE the TRIP docs that this feature will leave outdated, with one line each on what becomes stale. If none are affected, write "None". The TRIP-3 Documentation Sync step consumes this section before the release commit. Always evaluate the candidates below.] [ADAPT_TO_PROJECT: During Init, replace this block with the project's actual living docs — every non-TRIP document that code changes can leave stale. Typical candidates: `README.md` (quick start, repo structure tree, command reference), module/subdirectory READMEs, operations or user manuals, reference `.md` specs living next to the code, contributor guides (`CLAUDE.md`, `AGENTS.md`, `CONTRIBUTING.md`). One bullet per doc with when it's affected.] ## To-dos ### Phase 1: [Phase Name] (if multiple phases are needed) or simply skip title if only one phase is needed - [ ] Task description - [ ] Another task ### Phase 2: [Phase Name] (if applicable) - [ ] Task description - [ ] Another task **Note**: For simple plans, a single phase is sufficient. Split into multiple phases only for complex features requiring sequential implementation. **Note — slice vertically, not horizontally**: When a feature needs multiple phases, whenever possible make each phase a **thin end-to-end slice** (e.g. schema → service → minimal UI touch) that is verifiable on its own, so the **first** phase already produces something you can exercise. Do NOT structure phases as one whole layer at a time ("all schema", then "all API", then "all UI") — that leaves nothing testable until the end and makes course-correction expensive. Order phases so the thinnest working path lands first; later phases thicken it (more cases, edge handling, admin views, polish). **Note**: Do NOT write test code during planning — the Test Impact section above only names what the TRIP-2 testing gate will run and author.
Quality Standards
- Zero Ambiguity: Every step must be clear and actionable
- File-Level Specificity: List exact files and functions to modify
- Architecture Alignment: Must conform to existing patterns in ARCHI.md
- Risk Assessment: Highlight potential failure points
Step 3: Codex Second-Opinion Review
Before the user sees the plan, run the Codex plan review loop. Always run it — no confirmation question. The user gets exactly one decision point in this skill, and it comes after the plan is reviewed (Step 4).
Loop
- Start:
bash .claude/skills/codex-plan-review/scripts/start.sh --prompt-file .claude/skills/codex-plan-review/prompts/start.tpl <plan-path> - Parse trailing tag:
APPROVED-> Step 4.NEEDS_REWORK-> surface to user.REQUEST_CHANGES-> continue. - Address findings critically — quote each P1/P2, push back on incorrect ones, fix legitimate ones by editing the plan in place.
- Write implementer notes (1-3 sentences): which findings you fixed, which you pushed back on and why, any user decisions that override existing docs or environment limitations that can't be resolved in the plan.
- Resume with notes:
-> back to step 2.bashbash .claude/skills/codex-plan-review/scripts/resume.sh \ --prompt-file .claude/skills/codex-plan-review/prompts/resume.tpl \ --notes "Fixed X. Pushed back on Y because Z. User decided W." \ <plan-path> - No cap — keep iterating until Codex returns
APPROVED.
Surface Codex reviews verbatim. Keep edits scoped to findings. Reset thread (reset.sh <plan-path>) only if context is genuinely confused.
Step 4: User Review
After the Codex review converges, present a summary:
- Feature: [name]
- Approach: [1-2 sentences]
- Files affected: [count] files ([list key ones])
- Estimated complexity: [simple/moderate/complex]
- Codex status: [APPROVED after N rounds / NEEDS_REWORK surfaced to you]
YOLO mode: present the summary above (so the record exists), then skip the question and proceed directly into TRIP-2-implement as if the user had answered "Approved — implement now". (A NEEDS_REWORK Codex status always cancels YOLO — ask the question normally.)
Otherwise, one AskUserQuestion — the single decision point of this skill:
- Question: "Review the plan at
docs/1-plans/F_x.y.z_feature-name.plan.md. How to proceed?" - Options:
- "Approved — implement now" → continue straight into
TRIP-2-implementwith this plan - "Approved — stop here" → plan saved, no implementation
- "Rework" → the user provides feedback as text
- "Approved — implement now" → continue straight into
Handle the answer:
- Rework: update the plan from the user's feedback, then re-present. Run another Codex pass if the changes are substantive.
- Other (custom input): handle accordingly.
Approval and the implement-now decision are one question on purpose — approving a plan and choosing when to build it is a single thought, and splitting it into two prompts buys nothing.
IMPORTANT: No Code Implementation
DO NOT write code snippets or implement anything during planning.
This is a high-level planning phase only. Your plan should describe:
- WHAT needs to be done (features, changes, structures)
- WHERE changes will happen (files, modules, functions)
- WHY certain approaches are chosen (trade-offs, rationale)
But NOT:
- Actual code implementations
- Detailed algorithm code
Keep it architectural and descriptive. Code comes in the TRIP-2-implement phase.
