majiayu000 Planner Skill
Purpose
Two workflows for complex tasks:
- Planning workflow (planner.py): Create and review implementation plans
- Execution workflow (executor.py): Execute approved plans through delegation
Invocation Routing
Invoke planner.py when user asks to:
- "plan", "design", "architect" a feature
- "review" an existing plan
- Break down a complex task into milestones
Invoke executor.py when user asks to:
- "execute", "implement", "run" a plan
- "resume" or "continue" execution
- Provides a plan file path for implementation
When to Use
Use the planner skill when the task has:
- Multiple milestones with dependencies
- 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
PLANNING WORKFLOW (planner.py)
Workflow Overview
PLANNING PHASE (steps 1-N)
|
v
Write plan to file
|
v
REVIEW PHASE (steps 1-2)
|-- Step 1: @agent-technical-writer (plan-annotation)
|-- Step 2: @agent-quality-reviewer (plan-review)
v
APPROVED --> Execution workflow
Preconditions
Before invoking step 1, you MUST have:
- Plan file path - If user did not specify, ASK before proceeding
- Clear problem statement - What needs to be accomplished
Invocation
python3 scripts/planner.py \
--step-number 1 \
--total-steps <estimated_steps> \
--thoughts "<your thinking about the problem>"
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 Workflow
- Confirm preconditions (plan file path, problem statement)
- Invoke step 1 immediately
- Complete REQUIRED ACTIONS from output
- Invoke next step with your thoughts
- Repeat until
STATUS: phase_complete - Write plan to file using format below
Phase Transition: Planning to Review
When planning phase completes, the script outputs an explicit ACTION REQUIRED
marker:
============================================
>>> ACTION REQUIRED: INVOKE REVIEW PHASE <<<
============================================
You MUST invoke the review phase before proceeding to execution.
The review phase ensures:
- Temporally contaminated comments are fixed (via @agent-technical-writer)
- Code snippets have WHY comments (via @agent-technical-writer)
- Plan is validated for production risks (via @agent-quality-reviewer)
- Documentation needs are identified
Review Phase
After writing the plan file, transition to review phase:
python3 scripts/planner.py \
--phase review \
--step-number 1 \
--total-steps 2 \
--thoughts "Plan written to [path/to/plan.md]"
Review Step 1: Technical Writer
Delegate to @agent-technical-writer with mode: plan-annotation
Review Step 2: Quality Reviewer
Delegate to @agent-quality-reviewer with mode: plan-review
After Review
- PASS / PASS_WITH_CONCERNS: Ready for execution workflow
- NEEDS_CHANGES: Return to planning phase to address issues
EXECUTION WORKFLOW (executor.py)
Workflow Overview
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 QR
|
v
QR issues? --YES--> Step 5: Issue Resolution --> delegate fixes --> Step 4
|
NO
v
Step 6: Documentation
|
v
Step 7: Retrospective
Preconditions
Before invoking step 1, you MUST have:
- Approved plan file - Plan that passed review phase
- Clear context window - User should /clear before execution
Invocation
python3 scripts/executor.py \
--plan-file PATH \
--step-number 1 \
--total-steps 7 \
--thoughts "<user's request and context>"
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 QR | Quality review of implemented code |
| 5 | Issue Resolution | (conditional) Present issues, collect fixes |
| 6 | Documentation | TW 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 QR passes.
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.
Quick Reference
# === 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 "TW done, ready for QR"
# === 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 QR passes
python3 scripts/executor.py --plan-file plans/feature.md --step-number 6 \
--total-steps 7 --thoughts "QR 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."