/plan -- Architecture-Aware Planning
What
Enters a structured planning mode that considers the project's architecture pattern before producing an implementation plan. Instead of jumping straight to code, this command forces a deliberate pause to:
- Identify the project's current architecture (or recommend one)
- Map the task to affected layers, modules, and boundaries
- Produce a numbered implementation plan with clear steps
- Iterate on the plan until it is solid before writing any code
Plans are living documents -- if something goes sideways during implementation, stop and re-plan rather than pushing through a broken approach.
When
- Non-trivial tasks requiring 3 or more implementation steps
- Tasks involving architectural decisions (new modules, cross-cutting concerns, new bounded contexts)
- Features that touch multiple layers (API, application, domain, infrastructure)
- Refactoring that could affect multiple consumers
- Any time the user says "plan", "think through", "design this", or "how should I approach"
Skip planning for: Single-file changes, simple bug fixes, typo corrections, config tweaks.
How
Step 1: Understand the Task
Check docs/specs/ for an approved spec covering this task — if one exists, it is
the source of truth: map its acceptance criteria to plan steps and skip ahead to
Step 2. If the feature is spec-worthy (too big to describe in one sentence) and no
spec exists, recommend /spec first instead of planning on assumptions.
Otherwise, clarify what the user wants to build with focused questions.
Do not assume requirements that were not stated.
Step 2: Detect Architecture
Use the architecture-advisor skill to determine the project's architecture:
- Check for existing architecture markers (folder structure, project references, patterns)
- If no architecture is established, run the architecture questionnaire
- Load the appropriate architecture-specific skill (vertical-slice, clean-architecture, ddd)
Step 3: Map Affected Areas
Identify every layer, module, and boundary the task touches:
- Which projects/folders will have new or modified files?
- Are there cross-cutting concerns (auth, caching, validation, logging)?
- What existing code will be impacted? Use
find_referencesandfind_callersMCP tools for blast radius. - Are there database migrations needed?
Step 4: Produce the Plan
Output a numbered plan with this structure:
## Plan: [Task Title] **Architecture:** [Detected architecture] **Affected layers:** [List] **Estimated steps:** [Count] ### Steps 1. [Step] -- [Which file/layer] -- [Why this order] 2. ... ### Open Questions - [Anything that needs user input before proceeding] ### Risks - [Potential issues and mitigations]
Step 5: Iterate
Present the plan and ask: "Does this plan look right, or should I adjust anything?" Revise until the user confirms. Only then proceed to implementation.
Example
User: /plan Add a product catalog feature with search and filtering Claude: Let me analyze your project structure first... ## Plan: Product Catalog Feature **Architecture:** Vertical Slice Architecture **Affected layers:** Features/, Infrastructure/Persistence/, Tests/ **Estimated steps:** 6 ### Steps 1. Create Product entity + EF config -- Domain layer -- Foundation for everything else 2. Add migration -- Infrastructure -- Schema must exist before features 3. Scaffold GetProducts feature (with filtering) -- Features/Products/ -- Read path first 4. Scaffold CreateProduct feature -- Features/Products/ -- Write path 5. Add integration tests -- Tests/Features/Products/ -- Verify both features 6. Wire up OpenAPI metadata -- Features/Products/ -- Documentation ### Open Questions - Should search be full-text (PostgreSQL tsvector) or simple LIKE? - Do products need categories/tags for filtering? Does this plan look right, or should I adjust anything?
Related
/spec-- Write the spec first for features too big to describe in one sentence/scaffold-- Generate the files once the plan is approved/verify-- Run verification after implementing the plan
