plan

name	plan
description	Agent Skill for planning implementation work into comprehensive, testable steps. Use before implementation to create a clear roadmap for execution.
metadata	{"attribution":"attribution.md"}

Plan

Overview

Plan implementation work for an implementer who starts with very little context about the codebase or problem domain. Shape the execution strategy into clear, reliable, and verifiable steps, then save the plan as a durable handoff artifact under plan/.

Every plan MUST include a ## References section generated by invoking the reference-recorder skill.

Default save path: plan/plan-<slug>-YYYYMMDD.md

User preferences for the plan location override this default.

When to Use

Use this skill when:

• the implementation direction is already decided and needs an execution plan
• an approved spec, requirements doc, issue, or user request needs to be turned into actionable work
• the work benefits from explicit sequencing, verification, and handoff context

Do not use this skill when:

• the user is still exploring options and the direction is not settled
• the next step is design exploration rather than execution planning

If the task still needs design work, use brainstorming first, then design-spec if a durable, reviewed spec is wanted before planning.

Source of Truth

Start from the best available source of truth:

• For larger or riskier work, prefer an approved spec, requirements doc, issue, or equivalent written artifact
• For smaller or straightforward work, the user request plus local codebase context may be enough
• If the source of truth is missing, conflicting, or ambiguous, clarify before planning

Adaptive Planning Process

Use one planning process that scales with task complexity. Simpler work needs fewer planning steps; larger work needs more detail.

1. Confirm the source of truth, scope, constraints, and success criteria
2. Gather context needed to plan reliably
3. Map the affected files, interfaces, tests, docs, dependencies, and risks
4. Break the work into incremental tasks with clear boundaries and ordering
5. Define verification for each task and for the final integrated result
6. Invoke reference-recorder skill to generate a ## References section
7. Review the plan and save it under plan/ or user-specified location

When todo tools or skills are available, use them to track planning progress.

Scope Check

If the work covers multiple independent subsystems or would produce an unwieldy single plan, propose splitting it into multiple plans. Each plan should target one coherent outcome and produce working, testable software on its own.

File and Boundary Mapping

Before defining tasks, map which files or areas are likely to change and why. This is where decomposition decisions get locked in.

• Prefer clear boundaries and well-defined interfaces
• Split by responsibility, not by technical fashion
• Surface risky interfaces, migrations, or cross-cutting dependencies early
• If an existing file is already too large or overloaded, it is reasonable to include a targeted split in the plan

Task Design

Each task should be meaningful, self-contained, and self-verifiable.

• Prefer small, focused steps that reduce ambiguity and support steady progress
• Split tasks that hide multiple responsibilities or unclear verification. The task should be small enough that a gemini-flash/claude-sonnet/gpt-mini model or any open-source model can correctly and reliably implement it without guessing.
• Include enough implementation detail to avoid guesswork, but do not turn the plan into a full code dump
• Use snippets, interfaces, or pseudocode if they can help reduce ambiguity
• When TDD fits the work, sequence tasks accordingly; when it does not, use the smallest reliable verification steps instead

Plan Document Header

Every plan MUST start with this header:

# [Feature Name] Implementation Plan

**Goal:** [One sentence describing what this changes]

**Source of Truth:** [Approved spec, issue, user request, or other basis for
this plan]

**Scope:** [What is included and any important exclusions]

**Approach:** [2-3 sentences about the execution strategy]

**Verification:** [How the final result will be validated]

---

Task Structure

Create a ## Task Steps section as following:

## Task Steps

When executing the plan:

- mark `[ ]` boxes as completed `[x]` when item is completed
- after each task, do a code review by spawning another subagent, and fix any valuable feedbacks
- before moving to the next task, commit the changes

Use a structure like this and adapt the detail to the task

### Task N: [Task Name]

#### N.1 Intent

[What this task accomplishes]

#### N.2 Files

- Create: `exact/path/to/new_file.py`
- Modify: `exact/path/to/existing.py`
- Test: `tests/exact/path/to/test_file.py`

#### N.3 Dependencies

[Earlier tasks, prerequisites, or "None"]

- [ ] **Step 1:** [Concrete action]
- [ ] **Step 2:** [Concrete action]
- [ ] **Step 3:** [Concrete action]

#### N.4 Verification

- Run: `pytest tests/path/test_file.py -v`
- Expect: [What should pass, change, or be observable]

#### N.5 Notes

- [Optional details, snippets, or edge cases only when useful]

References

Every plan MUST include a ## References section generated by invoking the reference-recorder skill.

Use references to capture:

• important files or specific file ranges
• relevant docs or design notes
• issues, tickets, PRs, or external URLs
• anything the implementer should read before or during execution

Mark especially important references clearly when needed.

Plan Review

Dispatch a plan reviewer subagent using references/plan-reviewer-prompt.md to review the plan before handoff to ensure the scope, task order, verification, and references are clear and reliable.

For smaller or straightforward tasks, one review iteration may be enough. For larger, riskier, or more ambiguous tasks, multiple iterations may be needed to ensure the plan is clear and reliable.

If the review loop exceeds 3 iterations, surface the problem to a human for guidance.

Execution Handoff

After saving the plan:

"Plan complete and saved to <path>. Review it and let me know how you'd like to execute it."

Present the saved plan to the user and ask for execution instructions.