--- name: planner description: Script-guided plan-and-execute workflow run one numbered step at a time. planner.py drafts a plan through forced reflection pauses, then runs a comment-analyzer and critic review of the plan file; executor.py delegates each milestone of an approved plan file to specialized agents and, on resume, reconciles the file against completed work. Use when you say "run the planner workflow", "review the plan file at plans/X.md", "execute the plan at plans/X.md", "pick up where the plan left off", or "resume execution". Do NOT use to decompose a spec into milestones and tasks in the lifecycle chain (use plan), or to log progress on a plan artifact (use execution-plans). license: MIT metadata: routing: role: front-door invoker: autoplan trigger: autoplan routes execution, review, or resume of a planner-written plan file to planner user-facing: true version: 1.0.0 --- # Planner Skill ## Purpose Two script-guided workflows. Each script prints the guidance for one numbered step; the caller passes the step number and its thoughts on every call, and nothing is saved between calls: 1. **Planning workflow** (planner.py): Draft a plan through forced reflection pauses, then run the comment-analyzer and critic review of the plan file 2. **Execution workflow** (executor.py): Execute an approved plan file through delegation. On resume, step 1 reconciles the plan file against work already done The `plan` skill owns lifecycle decomposition of a spec into milestones and tasks. Use this skill when that work needs forced reflection pauses, a formal review pass, or delegated execution. ## Invocation Routing **Invoke planner.py** when user asks to: - "run the planner workflow" for a plan that needs forced reflection pauses - "review" a written plan file before execution (review phase) A request to break a spec into milestones and tasks, with no plan file and no executor run in view, belongs to the `plan` skill, not here. **Invoke executor.py** when user asks to: - "execute" or "implement" an approved plan file - "pick up where the plan left off", "resume", or "continue" execution - Provides a plan file path for implementation **Agent names in script output.** `@agent-X` in the scripts' output means the `X` agent: `comment-analyzer` and `critic` review the plan, `implementer` writes code, `debug` finds the cause of a failure, `qa` checks a milestone's acceptance criteria during reconciliation, and `code-reviewer` reviews implemented code. **Delegation on each host.** "Delegate to the `X` agent" means the host's subagent tool: Claude Code `Task` with `subagent_type="X"`; Copilot CLI `task` with `agent_type="project-toolkit:X"`; Codex `spawn_agent` with `agent_type="X"`, plus `fork_turns="none"` when the agent reviews or judges work (the default hands it your whole history); Muse Code `subagent_spawn` with `role="X"` and an `objective`, plus `worktree_isolation: true` for an agent that writes files. If the host has no subagent tool, or no `X` agent is installed, run the step yourself in this session. --- ## When to Use Use the planner skill when the task has: - An approved plan file whose milestones need delegated execution - Architectural decisions requiring documentation - Migration steps that need coordination - Complexity that benefits from forced reflection pauses ## When to Skip Skip the planner skill when the task is: - Single-step with obvious implementation - A quick fix or minor change - Already well-specified by the user --- ## Scripts | Script | Purpose | |--------|---------| | `scripts/planner.py` | Planning and review workflow, one numbered step per call | | `scripts/executor.py` | Execution workflow for approved plans with milestone delegation | ## Triggers | Trigger Phrase | Operation | |----------------|-----------| | `run the planner workflow` | planner.py (planning phase) | | `review the plan file at plans/X.md` | planner.py (review phase) | | `pick up where the plan left off` | executor.py (reconcile, then continue) | | `execute the plan at plans/X.md` | executor.py (execution phase) | | `resume execution` | executor.py (reconcile the plan file against completed work) | --- ## Anti-Patterns | Avoid | Why | Instead | |-------|-----|---------| | Skipping review phase after planning | Misses quality/temporal issues | Always run review steps 1-2 before execution | | Starting execution without /clear | Context pollution from planning | User should /clear before execution workflow | | Manually following workflow steps | Each step prints the guidance and the next command | Run the script and follow its output | | Planning single-step tasks | Overhead exceeds benefit | Implement directly without planner | | Editing plan during execution | Creates drift between plan and actions | Return to planning phase for changes | --- ## Verification After planning: - [ ] Plan file written to specified path - [ ] Review phase completed (both comment review and plan review steps) - [ ] Plan review verdict is APPROVED or APPROVED_WITH_CONCERNS After execution: - [ ] All milestones marked complete - [ ] Post-implementation review has no blocking findings - [ ] Documentation step completed - [ ] Retrospective generated --- ## Process ### Planning Overview ```text PLANNING PHASE (steps 1-N) | v Write plan to file | v REVIEW PHASE (steps 1-2) |-- Step 1: @agent-comment-analyzer (comment review) |-- Step 2: @agent-critic (plan review) v APPROVED --> Execution workflow ``` ### Planning Preconditions Before invoking step 1, you MUST have: 1. **Plan file path** - If user did not specify, ASK before proceeding 2. **Clear problem statement** - What needs to be accomplished ### Planning Invocation ```bash python3 scripts/planner.py \ --step-number 1 \ --total-steps \ --thoughts "" ``` ### Planning Arguments | Argument | Description | | --------------- | ------------------------------------------------ | | `--phase` | Workflow phase: `planning` (default) or `review` | | `--step-number` | Current step (starts at 1) | | `--total-steps` | Estimated total steps for this phase | | `--thoughts` | Your thinking, findings, and progress | ### Planning Steps 1. Confirm preconditions (plan file path, problem statement) 2. Invoke step 1 immediately 3. Complete REQUIRED ACTIONS from output 4. Invoke next step with your thoughts 5. Repeat until `STATUS: phase_complete` 6. Write plan to file using format below ## Phase Transition: Planning to Review When planning phase completes, the script outputs an explicit `ACTION REQUIRED` marker: ```text ============================================ >>> ACTION REQUIRED: INVOKE REVIEW PHASE <<< ============================================ ``` **You MUST invoke the review phase before proceeding to execution.** The review phase ensures: - Temporally contaminated comments are fixed (found by @agent-comment-analyzer) - Code snippets have WHY comments (gaps found by @agent-comment-analyzer) - Plan is validated for production risks (via @agent-critic) - Documentation needs are identified ## Review Phase After writing the plan file, transition to review phase: ```bash python3 scripts/planner.py \ --phase review \ --step-number 1 \ --total-steps 2 \ --thoughts "Plan written to [path/to/plan.md]" ``` ### Review Step 1: Comment Review Delegate to @agent-comment-analyzer. It is read-only and returns findings. Apply the findings to the plan file yourself: fix or remove contaminated comments, add WHY comments from the Decision Log, enrich plan prose, and add a documentation milestone if missing. ### Review Step 2: Plan Review Delegate to @agent-critic. The brief names the review criteria and the resources that define them, so no mode keyword is needed. ### After Review - **APPROVED / APPROVED_WITH_CONCERNS**: Ready for execution workflow - **NEEDS_REVISION**: Return to planning phase to address issues - **BLOCKED**: Stop and report the blocker (missing dependency, misaligned objective, or feasibility concern) to the user. Do not execute the plan until the user resolves it, then restart planning. --- ## Execution Workflow (executor.py) ### Execution Overview ```text Step 1: Execution Planning | v Step 2: Reconciliation (conditional, if prior work signaled) | v Step 3: Milestone Execution (repeat until all complete) | v Step 4: Post-Implementation Review | v Blocking findings? --YES--> Step 5: Issue Resolution --> delegate fixes --> Step 4 | NO v Step 6: Documentation | v Step 7: Retrospective ``` ### Execution Preconditions Before invoking step 1, you MUST have: 1. **Approved plan file** - Plan that passed review phase 2. **Clear context window** - User should /clear before execution ### Execution Invocation ```bash python3 scripts/executor.py \ --plan-file PATH \ --step-number 1 \ --total-steps 7 \ --thoughts "" ``` ### Execution Arguments | Argument | Description | | --------------- | -------------------------------- | | `--plan-file` | Path to the approved plan file | | `--step-number` | Current step (1-7) | | `--total-steps` | Always 7 for executor | | `--thoughts` | Your current thinking and status | ## Execution Steps | Step | Name | Purpose | | ---- | ---------------------- | --------------------------------------------- | | 1 | Execution Planning | Analyze plan, detect reconciliation, strategy | | 2 | Reconciliation | (conditional) Validate existing code vs plan | | 3 | Milestone Execution | Delegate to agents, run tests (repeat) | | 4 | Post-Implementation Review | Code review of implemented code | | 5 | Issue Resolution | (conditional) Present issues, collect fixes | | 6 | Documentation | Docs pass for CLAUDE.md, README.md | | 7 | Retrospective | Present execution summary | Note: Step 3 may be re-invoked multiple times until all milestones complete. Step 4 may loop back through step 5 until no blocking finding remains. --- ## Resources | Resource | Purpose | | ------------------------------------- | -------------------------------------------------- | | `resources/plan-format.md` | Plan template (injected at planning completion) | | `resources/diff-format.md` | Authoritative specification for code change format | | `resources/temporal-contamination.md` | Detecting/fixing temporally contaminated comments | | `resources/default-conventions.md` | Default conventions when project docs are silent | Note: Execution guidance is embedded directly in `scripts/executor.py` (not in separate resource files) since it's only used by that script. --- ## References | Reference | Purpose | |-----------|---------| | `references/strategy-ooda-loop.md` | Map planning and execution phases to OODA stages | | `references/design-pit-of-success.md` | Design milestones so the obvious path produces correct results | | `references/mental-models-galls-law.md` | Validate milestone decomposition against incremental complexity | | `.claude/skills/analyze/references/engineering-complexity-tiers.md` | Classify tasks by tier (single source of truth in analyze skill) | | `references/explainers-and-intents.md` | Write explainers before work, use intents as permission gates | | `references/agent-architecture-patterns.md` | Skill budget rule, 3-file planning pattern, milestone decomposition for agent systems | | `references/hybrid-memory-architecture.md` | Hybrid retrieval cascade, memory decay tiers, decision extraction for planning memory systems | --- ## Quick Reference ```bash # === PLANNING WORKFLOW === # Start planning python3 scripts/planner.py --step-number 1 --total-steps 4 --thoughts "..." # Continue planning python3 scripts/planner.py --step-number 2 --total-steps 4 --thoughts "..." # Start review (after plan written) python3 scripts/planner.py --phase review --step-number 1 --total-steps 2 \ --thoughts "Plan at plans/feature.md" # Continue review python3 scripts/planner.py --phase review --step-number 2 --total-steps 2 \ --thoughts "Comment review done, ready for plan review" # === EXECUTION WORKFLOW === # Start execution python3 scripts/executor.py --plan-file plans/feature.md --step-number 1 \ --total-steps 7 --thoughts "Execute the feature plan" # Continue milestone execution python3 scripts/executor.py --plan-file plans/feature.md --step-number 3 \ --total-steps 7 --thoughts "Completed M1, M2. Executing M3..." # After the post-implementation review passes python3 scripts/executor.py --plan-file plans/feature.md --step-number 6 \ --total-steps 7 --thoughts "Review passed. Running documentation." # Generate retrospective python3 scripts/executor.py --plan-file plans/feature.md --step-number 7 \ --total-steps 7 --thoughts "Execution complete. Generating retrospective." ```