design-plan ยท git:20260220.898bd93 ยท 2026-02-20 ยท sha256 2507075e980c0930

design-plan git:20260220.898bd93A

Immutable. This exact content never changes and is served at /api/v1/blob/2507075e980c0930.

No tool to install first
claude plugin marketplace add https://markdownregistry.com/mp/a/art_x76ghr7hxbvbk3ld/2507075e980c0930eca612cfd3ddc512b14ca3ac0c4724d3ff627213bac37c4c.json

Then /plugin install design-plan@markdownregistry-x76ghr7hxbvbk3ld in Claude Code. It installs this exact version, the one graded A here, pinned to the commit it was graded at, and leaves it there.

---
name: design-plan
description: Create implementation plans for complex tasks with architectural guidance. Use for complex features, multi-file changes, or when planning is needed before implementation.
allowed-tools:
  - Read
  - Grep
  - Glob
  - Bash
  - WebSearch
  - WebFetch
user-invocable: true
---

# Design Plan

## Purpose

Create comprehensive implementation plans for complex tasks, providing architectural guidance that can be followed for implementation.

## When to Use

- Complex features with architectural decisions
- Tasks spanning multiple files/modules
- New patterns or abstractions needed
- When user requests `--with-architect` flag

## Task-Specific Rules

Based on task type, reference these rules when planning:

| Task Type    | Rules to Reference                                                           |
| ------------ | ---------------------------------------------------------------------------- |
| Component    | [components.md](../../rules/components.md), [figma.md](../../rules/figma.md) |
| Token System | [tokens.md](../../rules/tokens.md)                                           |

**Always also load:** Base rules (workflow, github, linear)

## Planning Process

### Phase 1: Understand Requirements

1. **Read the Linear ticket thoroughly:**

   ```
   mcp__linear__get_issue(id: "{issue_id}", includeRelations: true)
   ```

2. **Extract key information:**
   - What problem is being solved?
   - What are the acceptance criteria?
   - Any constraints or requirements?
   - Linked designs or references?

3. **If Figma link present:**
   - Use `mcp__figma__get_design_context` to understand the design
   - Note complexity and variants

### Phase 2: Research Technology Context

**IMPORTANT:** Before designing, understand the current state of technologies involved.

1. **Identify technologies in scope:**
   - What libraries/frameworks will be used?
   - What version is the project using? (check `package.json`)

2. **Use WebSearch to research:**
   - Latest best practices for the technology
   - Version-specific features or limitations
   - Known issues, deprecations, or breaking changes
   - Recommended patterns from official docs

3. **Key questions to answer:**

   | Question                        | Why It Matters               |
   | ------------------------------- | ---------------------------- |
   | What version are we using?      | APIs differ between versions |
   | What's the recommended pattern? | Avoid deprecated approaches  |
   | Any known issues?               | Prevent predictable problems |
   | What's new in this version?     | Leverage latest features     |

4. **Document findings** that affect the design decision

### Phase 3: Explore Existing Architecture

1. **Find related code:**
   - How do similar features work?
   - What patterns are established?
   - What can be reused?

2. **Identify integration points:**
   - What existing modules will this touch?
   - What APIs/interfaces exist?
   - What dependencies are involved?

3. **Note constraints:**
   - Performance requirements
   - Backwards compatibility
   - Security considerations

### Phase 4: Design the Solution

1. **Consider multiple approaches:**
   - What are the options?
   - What are the trade-offs?

2. **Choose the best approach based on:**
   - Alignment with existing patterns
   - Maintainability
   - Scalability
   - Simplicity (avoid over-engineering)

3. **Define the architecture:**
   - File structure
   - Data flow
   - Component/module boundaries
   - Interfaces between parts

### Phase 5: Create Implementation Plan

1. **Break down into phases:**
   - Each phase should be independently testable
   - Order by dependencies (foundation first)
   - Include testing in each phase

2. **For each phase, specify:**
   - What files to create/modify
   - What the code should do
   - What patterns to follow
   - What to test

3. **Identify risks and decisions:**
   - What needs user input?
   - What could go wrong?
   - What assumptions are being made?

### Phase 6: Present Plan for Approval

Output the plan and **WAIT for user approval** before implementation.

## Output Format

```markdown
## ๐Ÿ›๏ธ Implementation Plan

### Task

- **Linear:** {issue_id} - {title}
- **Complexity:** {Low|Medium|High}
- **Estimated Phases:** {count}

### Overview

{1-2 sentence summary of what will be built and how}

### Architecture Decision

**Approach:** {chosen approach}

**Why this approach:**

- {reason 1}
- {reason 2}

**Alternatives considered:**
| Alternative | Why Not |
|-------------|---------|
| {option} | {reason} |

### File Structure
```

{path}/
โ”œโ”€โ”€ {file1} โ€” {purpose}
โ”œโ”€โ”€ {file2} โ€” {purpose}
โ””โ”€โ”€ {file3} โ€” {purpose}

```

### Implementation Phases

#### Phase 1: {name}

**Goal:** {what this phase accomplishes}

**Files:**
- Create `{path/file}` โ€” {description}
- Modify `{path/file}` โ€” {description}

**Key Implementation Notes:**
- {note 1}
- {note 2}

**Verification:**
- {how to verify this phase works}

---

#### Phase 2: {name}

{same structure}

---

### Risks & Decisions

| Item | Type | Notes |
|------|------|-------|
| {item} | Risk/Decision | {details} |

### Questions for User

{Any clarifications needed before proceeding}

---

**Ready for implementation?** Approve to proceed.
```

## Principles to Follow

1. **Design for the codebase** โ€” Follow existing patterns, don't invent new ones
2. **Simple over clever** โ€” The best architecture is the simplest one that works
3. **Think in phases** โ€” Break work into testable increments
4. **Surface decisions** โ€” Don't hide assumptions, make them explicit
5. **Plan for handoff** โ€” Implementation should be possible without guessing

## What NOT to Do

- Don't over-engineer for hypothetical requirements
- Don't introduce new patterns when existing ones work
- Don't skip the trade-off analysis
- Don't assume โ€” ask user when unclear
- Don't write code โ€” only plan (implementation is separate)