plan

name	plan
description	Collaborative planning conversation to produce a Master Plan for a feature
argument-hint	<feature idea or problem to solve>
tags	["planning","collaboration","architecture"]

Plan Skill

Start a collaborative planning session. This is a CONVERSATION - not auto-generation.

Purpose

You and the engineer will discuss, explore, and align on what to build before any PRDs or code are written. The output is a Master Plan document that both sides fully understand.

How This Works

This is the most important phase. All thinking happens here. The execution phase should require zero decisions from agents.

Step 1: Understand the Request

The engineer described: {{argument}}

Start by:

1. Restating what you understand in your own words
2. Asking clarifying questions about scope, constraints, and goals
3. Identifying what you DON'T know yet

Do NOT move forward until the engineer confirms you understand the request correctly.

Step 2: Explore the Codebase

Before proposing any architecture:

• Search for existing code related to the feature
• Understand current patterns, conventions, and structure
• Identify files that will likely be touched
• Find reusable components, utilities, and patterns

Use Glob, Grep, and Read tools to explore.

When exploration gets complex, use /team-research to parallelize:

1. Propose 2-4 focused research questions to the engineer
2. Wait for engineer approval
3. Launch /team-research with those questions
4. Agents explore in parallel and report back
5. Synthesize findings into a research summary
6. Continue the planning conversation with full context

See .claude/skills/team-research/SKILL.md for how research agents work.

Step 3: Discuss Architecture

Present your findings and proposed approach:

• What exists today that's relevant
• Proposed architecture / approach
• Key tradeoffs and alternatives considered
• Risks or unknowns
• Cross-boundary consumers: When a feature changes how data is stored, accessed, or structured, identify all consumers that read that data across the codebase. If the change is scoped (e.g., per-tenant, per-org, per-environment) but some consumers operate cross-scope, flag this explicitly as a design challenge in the Master Plan. These cross-boundary patterns often require different handling and are easy to miss during PRD generation.

Ask the engineer:

• "Does this approach align with what you had in mind?"
• "Are there constraints I'm missing?"
• "Which tradeoff do you prefer?"

Iterate until aligned. This may take multiple rounds. Don't rush.

Step 4: Break Into PRDs

Propose the PRD breakdown:

• How many PRDs and what each one covers
• Dependencies between PRDs (draw the DAG)
• Rough task count per PRD
• Which PRDs can run in parallel

Ask: "Does this breakdown make sense? Want to adjust anything?"

Iterate until the engineer is satisfied with the breakdown.

Step 5: Write the Master Plan

Gate 1: Ask explicitly: "Ready for me to write the Master Plan?"

Only after confirmation, write the Master Plan to:

prds/<YYYY-MM-DDTHH-MM>_<feature-name>/master-plan.md

Follow the format in .claude/rules/prd-format.md. Include:

• Overview and goals
• All architectural decisions made during discussion
• PRD dependency graph (ASCII art)
• PRD summary table
• Out of scope items
• Resolved questions (empty open questions section)

Gate 2: After writing, tell the engineer: "Master Plan written to prds/<dir>/master-plan.md. Please review it. Want to change anything before I generate the detailed PRDs?"

Only after explicit approval, set the Status to APPROVED and tell the engineer to run /prd <directory-name>.

Rules

• NEVER skip the conversation. Even if the request seems clear, ask at least 2-3 clarifying questions.
• NEVER write the Master Plan without explicit approval to do so (Gate 1).
• NEVER proceed to PRDs without explicit approval of the Master Plan (Gate 2).
• NEVER generate PRDs during this phase. That's /prd.
• DO explore the codebase thoroughly. Read actual files, don't guess.
• DO present tradeoffs and let the engineer decide.
• DO use /team-research when exploration is complex (see Step 2).
• DO keep the Master Plan lightweight - no code-level detail.
• DO track every architectural decision made during the conversation.
• DO list everything that is out of scope.

What the Master Plan Is NOT

• It is NOT a PRD. It has no code snippets or file changes.
• It is NOT a task list. It has PRD summaries, not task details.
• It is NOT final. The engineer can revise it before PRD generation.

Conversation Flow Example

Engineer: /plan add user settings panel

Claude: "Let me make sure I understand. You want a settings panel where
users can manage their preferences. A few questions:
1. What settings? Profile info, theme, notifications?
2. Where does it live? Modal, sidebar panel, separate page?
3. How should settings persist? API call, localStorage?"

Engineer: "Profile + theme + notifications. Sidebar panel like the
existing ones. localStorage for now, API later."

Claude: [explores codebase - finds existing sidebar patterns, theme
CSS variables, notification state]

Claude: "I found X, Y, Z in the codebase. Here's what I'm thinking
for architecture: [proposal]. The main tradeoff is..."

Engineer: "Looks good, but let's skip notifications for v1."

Claude: [adjusts scope]

Claude: "Here's the PRD breakdown:
- PRD-01: Types + state (no deps) - 3 tasks
- PRD-02: Persistence (no deps) - 2 tasks
- PRD-03: UI components (depends 01, 02) - 4 tasks
- PRD-04: Sidebar integration (depends 03) - 2 tasks
Does this make sense?"

Engineer: "Yes, go ahead and write the master plan."

Claude: [writes master plan]

Claude: "Master Plan written. Please review. Want to change anything?"

Engineer: "Looks good, proceed to PRDs."

Claude: "Run `/prd <directory-name>` to generate the detailed PRDs."

When Research Gets Complex

If you find yourself needing to explore many files or understand complex subsystems:

"This touches a lot of the codebase. I'd like to spin up /team-research to explore in parallel. Here are the research questions I'd send to agents:

1. [area 1 question]
2. [area 2 question]
3. [area 3 question]

Want me to go ahead?"

Wait for engineer approval. Then run /team-research (or launch research agents directly using the Task tool with subagent_type: "Explore"). After results come back, synthesize and continue the planning conversation.

Skill Dependencies

This skill may use:

• /team-research - For deep codebase exploration during Step 2

This skill produces output for:

• /prd - The Master Plan that PRD generation reads