Imported from GaetanCARRE/agent-setup (machine/skills/plan/SKILL.md). Install upstream with npx skills add GaetanCARRE/agent-setup --skill plan. Copyright stays with the author.

Plan a Change

For planning subsequent work after the initial MVP — refactors, architecture changes, or any non-feature task.

Step 1: Load Context

Read llm-context/architecture.md first to understand the big picture. Then read relevant files in llm-context/ and recent plans in .scratch/plans/.

Step 2: Discussion

What are we changing and why?

Key questions to discuss:

• Does this align with the architecture vision?
• If this changes the architecture, we need to update llm-context/architecture.md as part of the plan
• What's the simplest way to achieve this?
• What could break?
• Test your mental model: What assumptions is this approach built on? Are you sure they're correct, or are you assuming? The more work that depends on an assumption, the more it's worth verifying before writing the plan.

Step 3: Write the Plan

Write to .scratch/plans/YYYY-MM-DD-<topic>.md:

# [Topic] Plan

**Goal:** [one sentence]
**Approach:** [2-3 sentences]
**Architecture impact:** [None / Updates architecture.md because...]

## File Map
[Which files will be created/modified]

## Tasks

### Task 1: [Description]
**Files:** [exact paths]
**Steps:**
- [ ] Step description
- [ ] Test expectations
- [ ] Verification: `make check`

Guidelines:

• Each task: a few minutes of work, specific files, verification step
• Include test expectations inline
• If the change touches more than ~5 files, consider splitting into multiple plans
• If it requires architecture changes, include the architecture.md update as a task

Step 4: Review With Plannotator

Use Plannotator as the plan review and approval mechanism. In Pi, the user enables planning with /plannotator-plan-mode, optionally passing the intended .scratch/plans/...md path. If Plannotator plan mode is not active, ask the user to enable it rather than inventing a separate annotation workflow.

1. Write the plan as a Markdown checklist.
2. Call plannotator_submit_plan with the plan path.
3. Address every annotation returned by Plannotator and update the plan.
4. Resubmit until the user approves it.

Approval applies only to the reviewed plan. Do not begin planned execution before approval.

Step 5: Execute

Once approved, proceed with execution. Write tests alongside code, run make check frequently, commit after each logical change.