name: create-plan description: Analyzes design docs and existing projects to create detailed, actionable implementation plans for Claude Code. Use when the user asks to create an implementation plan, analyze a feature, or break down tasks.

Create Implementation Plan

This skill helps transform design docs into structured implementation plans and actionable tasks that Claude Code can execute autonomously.

When to use this skill

User shares a design doc and asks for an implementation plan
User requests feasibility analysis of a feature
User asks to break down a feature into smaller tasks
Need to understand how a feature fits into the existing architecture

Plan creation process

1. Design Doc Analysis

Goal: Fully understand the feature's requirements and scope.

Actions:

Read the design doc provided by the user (use view if it's a file)
Identify the main objectives of the feature
List functional and non-functional requirements
Identify dependencies on other parts of the system
Note questions or ambiguities that need clarification

Ask the user if necessary:

Are there specific priorities among the requirements?
Are there technical approach preferences?

2. Existing Architecture Analysis

Goal: Understand how the feature fits into the current project.

Actions:

Read the project's architecture rules file located at docs/architecture-rules.md.
Identify patterns and conventions that must be followed
Check if there are templates or examples of similar implementations
If necessary, explore only the specific modules related to the feature

What to extract from architecture rules:

Folder structure and code organization
Naming conventions
Application layers (e.g., Routes, Application, Domain, Infra)
State management patterns
Error handling and validations
Allowed integrations and dependencies

Note: Browse through the code only if you need to understand a specific module that will be modified or used as a reference. The architecture rules should provide most of the necessary context.

3. Implementation Planning

Goal: Define the technical approach aligned with the architecture.

Create a plan that includes:

Solution Overview
- Summary of the chosen technical approach
- Justification for main decisions
- Components to be created/modified
Structural Changes
- New files/modules needed
- Modifications to existing files
- Data schema changes (if applicable)
Dependencies and Integrations
- Required NuGet packages
- APIs or services to be integrated
- Integration points with existing code

4. Break Down into Actionable Tasks for Claude Code

Goal: Create self-contained tasks that Claude Code can implement autonomously.

Principles for Claude Code executable tasks:

✅ Tasks should be:

Extremely specific - Leave no room for interpretation
Self-contained - All necessary information is in the task
With examples - Show reference code when possible
Sequential - Clear implementation order

❌ Avoid tasks that:

Depend on undocumented context
Are vague ("implement the logic")
Mix multiple responsibilities
Refer to "follow the pattern" without explaining what it is

DETAILED structure for each task:

# TASK 01: Descriptive Task Title

## Description

Clear explanation of why this task exists, how it relates to the overall feature, and what problems it solves.

## Objectives

- [ ] Specific objective 1 (measurable)
- [ ] Specific objective 2 (measurable)

## Prerequisites

- Task X must be complete
- File Y must exist
- Dependency Z must be installed

## Applicable architecture rules:

[Copy relevant rules from /docs/architecture-rules.md that apply to this task]

## Detailed Tasks

### 1. Domain Entity: Product

**File**: `src/AdminSystem.API/Domain/Entities/Product.cs`

```csharp
namespace AdminSystem.API.Domain.Entities
{
    public class Product
    {
        public Guid Id { get; private set; }
        public string Name { get; private set; }
        public decimal Price { get; private set; }
        public bool IsActive { get; private set; }
        public DateTime CreatedAt { get; private set; }
        public DateTime? UpdatedAt { get; private set; }

        private Product() { }

        public static Product Create(string name, decimal price)
        {
            // Validation logic here
            return new Product
            {
                Id = Guid.NewGuid(),
                Name = name,
                Price = price,
                IsActive = true,
                CreatedAt = DateTime.UtcNow
            };
        }

        public void UpdatePrice(decimal newPrice)
        {
            // Code to be implemented
        }
    }
}
```

---

### 2. Domain Abstraction: IProductRepository

**File**: `src/AdminSystem.API/Domain/Abstractions/IProductRepository.cs`

```csharp
namespace AdminSystem.API.Domain.Abstractions
{
    public interface IProductRepository
    {
        Task<Product?> GetById(Guid id, CancellationToken cancellationToken = default);
        Task<IEnumerable<Product>> GetAll(CancellationToken cancellationToken = default);
        Task<Product> Add(Product product, CancellationToken cancellationToken = default);
        Task Update(Product product, CancellationToken cancellationToken = default);
        Task Delete(Product product, CancellationToken cancellationToken = default);
    }
}
```

---

### 3. Infrastructure: ProductRepository Implementation

**File**: `src/AdminSystem.API/Infra/Database/Repositories/ProductRepository.cs`

```csharp
namespace AdminSystem.API.Infra.Database.Repositories
{
    public class ProductRepository : IProductRepository
    {
        private readonly ApplicationDbContext _context;

        public ProductRepository(ApplicationDbContext context)
        {
            _context = context;
        }

        public async Task<Product?> GetById(Guid id, CancellationToken cancellationToken = default)
        {
            // Code to be implemented
        }

        public async Task<Product> Add(Product product, CancellationToken cancellationToken = default)
        {
            await _context.Products.AddAsync(product, cancellationToken);
            await _context.SaveChangesAsync(cancellationToken);
            return product;
        }

        // Other methods...
    }
}
```

---

### 4. Infrastructure: Entity Configuration

**File**: `src/AdminSystem.API/Infra/Database/Configurations/ProductConfiguration.cs`

```csharp
namespace AdminSystem.API.Infra.Database.Configurations
{
    public class ProductConfiguration : IEntityTypeConfiguration<Product>
    {
        public void Configure(EntityTypeBuilder<Product> builder)
        {
            builder.ToTable("Products");
            builder.HasKey(p => p.Id);
            builder.Property(p => p.Name).IsRequired().HasMaxLength(200);
            // Code to be implemented
        }
    }
}
```

---

### 5. Application: DTOs

**File**: `src/AdminSystem.API/Application/DTOs/Requests/CreateProductRequest.cs`

```csharp
namespace AdminSystem.API.Application.DTOs.Requests
{
    public record CreateProductRequest
    {
        public required string Name { get; init; }
        public required decimal Price { get; init; }
    }
}
```

**File**: `src/AdminSystem.API/Application/DTOs/Responses/ProductResponse.cs`

```csharp
// Code to be implemented
```

---

### 6. Application: Use Case

**File**: `src/AdminSystem.API/Application/UseCases/Products/CreateProduct/CreateProductUseCase.cs`

```csharp
namespace AdminSystem.API.Application.UseCases.Products.CreateProduct
{
    public class CreateProductUseCase
    {
        private readonly IProductRepository _productRepository;

        public CreateProductUseCase(IProductRepository productRepository)
        {
            _productRepository = productRepository;
        }

        public async Task<ProductResponse> Execute(
            CreateProductRequest request,
            CancellationToken cancellationToken = default)
        {
            // Create entity using factory method
            var product = Product.Create(request.Name, request.Price);

            // Persist
            await _productRepository.Add(product, cancellationToken);

            // Return response
            return new ProductResponse
            {
                Id = product.Id,
                Name = product.Name,
                Price = product.Price,
                IsActive = product.IsActive,
                CreatedAt = product.CreatedAt
            };
        }
    }
}
```

---

### 7. Routes: API Endpoints

**File**: `src/AdminSystem.API/Routes/V1/ProductsRoutes.cs`

```csharp
namespace AdminSystem.API.Routes.V1
{
    public static class ProductsRoutes
    {
        public static void MapProductsEndpoints(this IEndpointRouteBuilder app)
        {
            var group = app.MapGroup("/api/v1/products")
                .WithTags("Products")
                .WithOpenApi();

            group.MapPost("/", CreateProduct);
            // Other endpoints...
        }

        private static async Task<IResult> CreateProduct(
            CreateProductRequest request,
            CreateProductUseCase useCase,
            CancellationToken cancellationToken)
        {
            // Code to be implemented
        }
    }
}
```

---

## Acceptance Criteria

### Functionality:

- [ ] Functionality X
- [ ] Functionality Y
- [ ] Functionality Z

### Quality:

- [ ] Quality X
- [ ] Quality Y
- [ ] Quality Z

### Performance:

- [ ] Performance X
- [ ] Performance Y
- [ ] Performance Z

### Security:

- [ ] Security X
- [ ] Security Y
- [ ] Security Z

---

## Dependencies

**Depends on:**

- None (first task of the feature)

**Blocks:**

- [02] Advanced notification system integration
- [03] Entity dashboard on frontend

5. File Organization

Output structure:

docs/features/[design-doc-name]/
├── 00-PLAN.md                      # Plan overview
├── 01-create-product-entity.md    # Product entity and repository
├── 02-product-use-cases.md        # Product use cases
└── 03-product-api-endpoints.md    # Product API endpoints

Contents of 00-PLAN.md:

# Implementation Plan: [Feature Name]

## Executive Summary

[Summary of what will be implemented in 2-3 paragraphs]

## Design Doc Analysis

### Main objectives

1. Objective 1
2. Objective 2
3. Objective 3

### Functional requirements

- Requirement 1
- Requirement 2
- Requirement 3

### Non-functional requirements

- Performance: [requirements]
- Security: [requirements]
- Scalability: [requirements]

### Scope

**Included:**

- Item 1
- Item 2

**Excluded (out of scope):**

- Item 1
- Item 2

### Folder Structure

src/AdminSystem.API/
│
├── Domain/                          # Domain Layer
│   ├── Entities/
│   │   ├── User.cs                  # ✅ Existing
│   │   └── Product.cs               # ✅ New
│   ├── Abstractions/
│   │   ├── IUserRepository.cs       # ✅ Existing
│   │   └── IProductRepository.cs    # ✅ New
│   └── Exceptions/
│       └── DomainException.cs       # ✅ Existing
│
├── Application/                     # Application Layer
│   ├── UseCases/
│   │   ├── Users/
│   │   │   └── CreateUser/
│   │   │       └── CreateUserUseCase.cs  # ✅ Existing
│   │   └── Products/
│   │       ├── CreateProduct/
│   │       │   └── CreateProductUseCase.cs  # ✅ New
│   │       └── UpdateProduct/
│   │           └── UpdateProductUseCase.cs  # ✅ New
│   ├── DTOs/
│   │   ├── Requests/
│   │   │   ├── CreateUserRequest.cs      # ✅ Existing
│   │   │   └── CreateProductRequest.cs   # ✅ New
│   │   └── Responses/
│   │       ├── UserResponse.cs           # ✅ Existing
│   │       └── ProductResponse.cs        # ✅ New
│   └── Validators/
│       └── CreateProductRequestValidator.cs  # ✅ New
│
├── Infra/                           # Infrastructure Layer
│   └── Database/
│       ├── Context/
│       │   └── ApplicationDbContext.cs   # ✅ Modified
│       ├── Configurations/
│       │   ├── UserConfiguration.cs      # ✅ Existing
│       │   └── ProductConfiguration.cs   # ✅ New
│       ├── Repositories/
│       │   ├── UserRepository.cs         # ✅ Existing
│       │   └── ProductRepository.cs      # ✅ New
│       └── Migrations/
│           └── AddProductTable.cs        # ✅ New
│
└── Routes/                          # API Layer
    └── V1/
        ├── UsersRoutes.cs           # ✅ Existing
        └── ProductsRoutes.cs        # ✅ New

### Implementation Order

**Task Status Legend:**
- ✅ COMPLETED - Task finished successfully
- 🔄 IN_PROGRESS - Currently being worked on
- ⏳ PENDING - Not yet started
- 🚫 BLOCKED - Waiting for dependencies

---

| # | Task | Status | Details |
|---|------|--------|---------|
| 01 | Create Product Entity | ⏳ PENDING | Product entity, IProductRepository interface, entity configuration |
| 02 | Product Use Cases | ⏳ PENDING | Create, Update, Delete product use cases with DTOs |
| 03 | Product API Endpoints | ⏳ PENDING | REST endpoints for product management |

---

**📌 NEXT TASK TO EXECUTE: [01] Create Product Entity**

---

### Task List (Detailed)

1. **[01] Create Product Entity** - ⏳ PENDING (NEXT)
   - Create Product entity, IProductRepository interface, entity configuration

2. **[02] Product Use Cases** - ⏳ PENDING
   - Create, Update, Delete product use cases with DTOs

3. **[03] Product API Endpoints** - ⏳ PENDING
   - REST endpoints for product management

### External services

- None (or list external APIs, if any)

### Required configurations

- Config X
- Config Y
- Config Z

### Required NuGet packages

- Package X
- Package Y
- Package Z

Usage example

User: "Let's create an implementation plan for the product catalog feature design doc"

Claude executes:

view /docs/features/product-catalog/design-doc-product-catalog.md
view /docs/architecture-rules.md
Generates 00-PLAN.md with complete overview
Generates detailed tasks with complete C# code
Presents created files with summary

Best practices

✅ DO:

Always read architecture-rules.md before planning
Include COMPLETE code in tasks (not just structure)
Number tasks in logical dependency order
Consider testability from the start
ALWAYS include the Implementation Order section with:
- Task Status Legend (✅ COMPLETED, 🔄 IN_PROGRESS, ⏳ PENDING, 🚫 BLOCKED)
- Status table with columns: #, Task, Status, Details
- "📌 NEXT TASK TO EXECUTE" indicator
- Task List (Detailed) with status for each task and "(NEXT)" marker

❌ DON'T:

Create tasks without consulting architecture-rules.md
Leave code "to be implemented" without examples
Create tasks that are too large
Omit dependencies between tasks
Ignore existing patterns in the code
Use vague comments like "implement logic here"
Forget to include the status tracking structure in 00-PLAN.md

Frequently asked questions

Q: What if the design doc is vague or incomplete? A: List the ambiguities found in 00-PLAN.md and ask the user before proceeding with detailed tasks.

Q: How many tasks should I create? A: Depends on complexity. Generally 5-10 tasks. Each task should be completable in 2-8 hours.

Q: Do I need to include ALL the code or can I summarize? A: Include COMPLETE and functional code. Claude Code should be able to copy and use it directly.

Final checklist

Before presenting the plan to the user, verify:

I read and fully understood the design doc
I consulted the project's architecture-rules.md
I created the 00-PLAN.md file with detailed overview
I broke down the implementation into 5-10 logical tasks
Each task has: complete C# code, acceptance criteria
I followed C# conventions and project patterns
I organized files in docs/features/[feature-name]/
All tasks are executable by Claude Code
I included the Implementation Order section with status tracking:
- Task Status Legend
- Status table with all tasks
- "📌 NEXT TASK TO EXECUTE" indicator
- Task List (Detailed) with "(NEXT)" marker

create-plan

SKILL.md