Create Plan

Generate a structured implementation plan and copy it to the clipboard.

IMPORTANT: Enter Plan Mode first

Before doing anything else, enter Plan Mode (use the EnterPlanMode tool if you are not already in it). Do not write or modify any code. Plan Mode allows you to explore the codebase read-only and design the plan without making changes.

Phase 1: Receive Task

The user's request: $ARGUMENTS

If $ARGUMENTS is provided, use it as the initial task description. If empty, ask the user what feature or task to plan. Do not proceed to Phase 2 until you have a clear task description.

Phase 2: Clarify Requirements

Use AskUserQuestion to deepen your understanding of the task through natural conversation. Do not follow a fixed checklist — adapt your questions based on what the user has already told you and what you still need to know to generate actionable TODO items.

What you need to know (not a script to follow)

Your goal is to gather enough context so that each TODO item you generate later is unambiguous and independently implementable. Work backward from that goal:

• What is ambiguous? If the task description leaves room for interpretation, ask about the intended behavior or expected output.
• What decisions haven't been made? Surface implicit choices the user may not have considered (e.g., "Should this be synchronous or async?", "Do we need backward compatibility?").
• What does the user know that you don't? Ask about business context, prior attempts, team conventions, or constraints that aren't visible in the codebase.
• What would block implementation? Identify unknowns that would force you to stop mid-task and ask (e.g., "Which API endpoint should this call?", "What happens when X fails?").

How to ask

• Ask two or three questions at a time. Do not overwhelm the user.
• Frame questions as concrete choices or scenarios when possible (e.g., "When the token expires, should we retry silently or show an error to the user?") rather than open-ended ("What about error handling?").
• If the user's answer reveals a new area of complexity, follow up on it before moving to the next topic.
• Do not move on by yourself. When you believe you have enough information, summarize what you understood and ask the user to confirm before proceeding: "Here is my understanding so far: ... Shall we move on to research, or is there anything else to clarify?"

Phase 3: Research (Parallel Subagents)

Based on the task and requirements clarified in Phase 1-2, design and launch subagents tailored to the specific research needs. Do not use a fixed set of agents — decide what research is needed for this particular task.

How to design agents

1. Identify the distinct areas of research needed (codebase, external docs, dependencies, etc.)
2. Create one agent per area, each with a focused responsibility
3. Choose the appropriate subagent_type for each:
   • Explore — for codebase exploration (file structure, existing code, patterns)
   • Plan — for analysis (dependencies, impact, implementation order)
   • Use WebSearch / WebFetch in agents that need to research external documentation
4. Launch all agents in parallel using the Agent tool
5. Pass each agent a summary of the task and clarified requirements

Examples

Example: Adding a new domain to CDN via GCS

• Agent 1 (Explore): Search Terraform codebase for existing domain/bucket configurations
• Agent 2 (Explore + WebSearch): Research Fastly CDN configuration and official docs
• Agent 3 (Explore): Investigate GCS bucket setup patterns in the codebase
• Agent 4 (Plan): Analyze DNS, SSL, and deployment dependencies

Always include identifying the project's layers (directories, dependency direction, where migrations live) in one agent's scope — the TODO section is split by those layers.

Example: Adding a REST API endpoint

• Agent 1 (Explore): Find existing API endpoint patterns, conventions, and the project's layer structure
• Agent 2 (Explore): Investigate DB schema and repository layer
• Agent 3 (Explore): Search for related test patterns and fixtures

Example: Refactoring authentication middleware

• Agent 1 (Explore): Map all usage of current auth middleware across the codebase
• Agent 2 (Plan): Analyze breaking changes and migration path
• Agent 3 (Explore + WebSearch): Research the target auth library's official docs

Wait for all agents to complete before proceeding to Phase 4.

Phase 4: Present Draft Plan

Synthesize the results from all subagents and the clarified requirements to generate a draft plan. Read references/plan-format.md first — it is the complete format specification with examples.

Key points:

• Start with What — clarify the goal and why it matters before diving into details
• Group TODOs into PRs (### PR <n>: <scope>: <one-line purpose>), each one reviewable purpose that merges and deploys on its own, numbered in dependency order
• Inside each PR, split TODOs by layer, one layer per TODO, using the layers found in the codebase; order the layer headings by dependency (e.g. DDL → domain → repository → usecase → handler)
• Never mix DDL with application code in one TODO
• Order tasks by dependency (upstream tasks first)
• Each TODO must be completable in a single Claude Code session
• Give every TODO a "Done when" (observable behavior the reviewer checks) and a "Verify" (the command or check the implementing session runs)
• Write each "Done when" at that layer's boundary; if even that is impossible, merge the TODO into the one in the same layer that first uses it
• Include code examples for non-trivial logic
• When a TODO has conditional logic, write its "Done when" as a decision table scoped to that TODO, with every condition as a yes/no question (Y / N / -); use a shared table under Verification only for rules several TODOs must follow
• List all relevant files, PRs, and documents in References

Present the draft to the user and ask for confirmation or changes.

Phase 5: Finalize and Copy to Clipboard

After the user confirms the plan, pipe it to the bundled clipboard script, which detects the platform (macOS, WSL, Wayland, X11):

"${CLAUDE_SKILL_DIR}/scripts/copy-to-clipboard.sh" <<'PLAN_EOF'
<the confirmed plan>
PLAN_EOF

If the script exits non-zero (no clipboard tool available), output the plan in a single fenced code block so the user can copy it manually.

Inform the user that the plan has been copied to their clipboard so they can paste it into their preferred note-taking app.

Guidelines

• Write TODO items as imperative actions: "Add field X to struct Y", not "Field X should be added"
• Target file paths should be explicit: src/repository/item_repository.ts, not "the item repository"
• Code examples in TODOs should be minimal but sufficient to convey the approach
• Decision tables cover every yes/no combination exactly once, use - for "don't care", and give each question an exact threshold (no "a few minutes")
• Do not copy a table into several TODOs — if more than one TODO needs it, make it shared
• "Done when" states behavior, never "tests pass" or a restatement of the task
• Every shared decision table row should be cited by at least one TODO's "Done when"; an uncited row means a TODO is missing
• References should include the reason each resource is relevant