Mohamed Boudra
609d11ee8d
Copy the orchestrate skill from ~/.agents/skills into the repo as paseo-orchestrate, replacing the old paseo-orchestrator.
120 lines
3.4 KiB
Markdown
120 lines
3.4 KiB
Markdown
# Planning Phase
|
|
|
|
Deploy planners to create an implementation plan informed by research findings. The number of planners and plan-reviewers scales with complexity order (see triage.md).
|
|
|
|
## Refactor-First Thinking
|
|
|
|
Every planner prompt must emphasize this: the default agent instinct is to bolt new code on top of existing code. Resist this.
|
|
|
|
The right approach:
|
|
1. Study the existing code — understand why it's shaped the way it is
|
|
2. Design the target shape — what would the code look like if this feature had always existed?
|
|
3. Identify the refactoring gap — what needs to change so the new feature slots in cleanly?
|
|
4. Plan refactor phases before feature phases — lay the groundwork first
|
|
|
|
If the plan has a phase called "wire up" or "connect" or "integrate," a refactor phase could probably eliminate the need for it.
|
|
|
|
## Launching Planners
|
|
|
|
Use the Paseo **create agent** tool with `background: true` and `notifyOnFinish: true`:
|
|
|
|
```
|
|
title: "planner-<scope>"
|
|
agentType: <resolved from providers.planning>
|
|
model: <resolved from providers.planning>
|
|
background: true
|
|
notifyOnFinish: true
|
|
initialPrompt: "You are a planner.
|
|
|
|
Read the research findings provided below and the objective.
|
|
|
|
<paste synthesized research findings and objective>
|
|
|
|
Draft a phased implementation plan. Think refactor-first: before planning the feature, identify what existing code needs to be reshaped so the feature slots in naturally.
|
|
|
|
For each phase, specify:
|
|
- What changes and why
|
|
- Files involved
|
|
- Types and interfaces affected
|
|
- Tests to write (failing test first — TDD)
|
|
- Acceptance criteria for the phase
|
|
|
|
Write the plan to ~/.paseo/plans/<task-slug>.md"
|
|
```
|
|
|
|
## Launching Plan-Reviewers
|
|
|
|
```
|
|
title: "plan-reviewer-<scope>"
|
|
agentType: <resolved from providers.planning>
|
|
model: <resolved from providers.planning>
|
|
background: true
|
|
notifyOnFinish: true
|
|
initialPrompt: "You are a plan-reviewer.
|
|
|
|
Read the plan at ~/.paseo/plans/<task-slug>.md.
|
|
|
|
Challenge the plan:
|
|
- Is it bolting new code on top, or reshaping existing code first?
|
|
- Are there coordination/glue/bridge layers that a better refactor would eliminate?
|
|
- What edge cases are missing? What will break?
|
|
- What's over-engineered? What's under-specified?
|
|
- Is the phase ordering correct? Are there hidden dependencies?"
|
|
```
|
|
|
|
## Multiple Planners (Order 3+)
|
|
|
|
For cross-module tasks, deploy planners focusing on different slices:
|
|
- One for backend phases
|
|
- One for frontend phases
|
|
- One for test strategy
|
|
|
|
Then deploy a plan-reviewer to challenge the combined plan.
|
|
|
|
## Iteration
|
|
|
|
If the plan-reviewer finds significant issues, either:
|
|
1. Send follow-up instructions via the Paseo **send agent prompt** tool to the planner
|
|
2. Launch a new planner if the original is stale
|
|
|
|
Iterate until the plan-reviewer's only feedback is minor. Then synthesize the final plan.
|
|
|
|
## Plan Structure
|
|
|
|
The final plan must follow this structure:
|
|
|
|
```
|
|
# <Task Title>
|
|
|
|
## Objective
|
|
<one-paragraph summary>
|
|
|
|
## Acceptance Criteria
|
|
- [ ] <criterion 1>
|
|
- [ ] <criterion 2>
|
|
|
|
## Plan
|
|
### Phase 1: <name>
|
|
<description, files, types, tests, acceptance criteria>
|
|
|
|
### Phase 2: <name>
|
|
...
|
|
```
|
|
|
|
## Persisting the Plan
|
|
|
|
Save the final plan to disk:
|
|
|
|
```bash
|
|
mkdir -p ~/.paseo/plans
|
|
cat > ~/.paseo/plans/<task-slug>.md << 'PLAN'
|
|
<plan content>
|
|
PLAN
|
|
```
|
|
|
|
This file is the durable reference. Re-read it before every verification, review, or QA phase. It survives context compaction.
|
|
|
|
## Always Archive
|
|
|
|
Archive all planners and plan-reviewers once the final plan is settled.
|