Download the exact captured file
---
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 <estimated_steps> \
--thoughts "<your thinking about the problem>"
```
### 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 "<user's request and context>"
```
### 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."
```