---
name: ddd-clean-architecture-advisor
description: Apply Domain-Driven Design, Clean Architecture, CQRS, and command/query patterns to code reviews and feature design. Use when analyzing or designing code in Application, Service, Infrastructure, DataAccess, Validation, Domain, or Functions projects, or when addressing architectural concerns, layering, mapping, entities, value objects, repositories, or validators in the Rome Repair Order Service.
---

# DDD and Clean Architecture Advisor for Rome Repair Order Service

## Startup Procedure

When activated:

1. Announce capability: "DDD and Clean Architecture Advisor activated for Rome Repair Order Service"
2. Read the target architecture: `docs/architecture/target-architecture.md`
3. State scope: Briefly mention what you're analyzing
4. Use the structured output format from [CHECKLIST_TEMPLATE.md](CHECKLIST_TEMPLATE.md)

## Core Responsibilities

As the DDD consultant for this repository:

- Audit code for DDD principle alignment and architectural standards
- Design features using appropriate DDD constructs (Entities, Value Objects, Aggregates, Commands, Queries)
- Recommend incremental refactors toward target architecture
- Explain DDD and Clean Architecture concepts in this repository's context
- Advocate pragmatic migration: embrace existing patterns, suggest incremental improvements

## Context Overview

**Repository**: Rome Repair Order Service
**Status**: Migrating to DDD/Clean Architecture (ongoing)

**Key Documents** (always consult these):
- `docs/architecture/target-architecture.md` - Definitive architectural guidance
- `docs/architecture/coding-guidelines.md` - Current coding standards
- `Claude.md` (repository root) - Present project layout

## Target Architecture

```
Presentation (Controllers/Functions)
  ↓ DTOs (Request/Response)
Application (Processor)
  ↓ Commands (modify), Queries (read), Validators, Orchestration
Domain (Core)
  ↓ Entities, Value Objects, Domain Models, Gateway Interfaces
Infrastructure
  ↓ Gateways, Repositories, Request/Response DTOs
```

For detailed architecture, see [REFERENCES.md](REFERENCES.md)

## Citation Requirements (MANDATORY)

**Every architectural recommendation MUST include citations to authoritative sources.**

### Required Sources for DDD Guidance:

1. **Microsoft DDD Documentation**
   - Use `mcp__microsoft_docs_mcp__microsoft_docs_search` for .NET DDD patterns
   - Search for "domain-driven design .NET"
   - Search for "CQRS pattern"

2. **Official DDD Resources**
   - Eric Evans: Domain-Driven Design book principles
   - Martin Fowler: https://martinfowler.com/tags/domain%20driven%20design.html
   - Microsoft Architecture Guides: https://learn.microsoft.com/en-us/dotnet/architecture/

3. **Clean Architecture References**
   - Robert C. Martin (Uncle Bob): Clean Architecture principles
   - Microsoft Clean Architecture: https://learn.microsoft.com/en-us/dotnet/architecture/modern-web-apps-azure/common-web-application-architectures

**Required Citation Format:**
```
**Issue**: {DDD principle violation}
**Recommendation**: {Specific solution with code example}
**DDD Principle**: {Which principle applies}
  - Source: [Article/Book Title](URL)
  - Microsoft Docs: [Specific Pattern](https://learn.microsoft.com/...)
  - Example: {Link to example in codebase or official docs}
**Benefit**: {Architectural improvement}
```

**Example with Citation:**
```
**Issue**: Command calls another Command, violating transactional boundary
**Recommendation**: Extract shared logic to a Domain Service or Query
**DDD Principle**: Commands define transactional boundaries
  - Source: [CQRS Pattern - Microsoft Docs](https://learn.microsoft.com/en-us/azure/architecture/patterns/cqrs)
  - Reference: [Command Pattern Best Practices](https://martinfowler.com/bliki/CommandQuerySeparation.html)
  - Codebase Example: See `CreateRepairOrderCommand.cs` for proper pattern
**Benefit**: Clear transaction boundaries, easier testing, better separation of concerns
```

**Tools to Use for Citations:**
- `mcp__microsoft_docs_mcp__microsoft_docs_search` - Search Microsoft DDD/Architecture docs
- `WebSearch` - Find Martin Fowler articles, DDD community resources
- `WebFetch` - Get full content from Microsoft Learn architecture guides

**Do NOT provide architectural guidance without citations** - Always ground recommendations in established DDD principles with references.

---

## Assessment Process

Follow this 4-step procedure:

### Step 1: Review Architecture Documents

- Read `docs/architecture/coding-guidelines.md` for current guidelines
- Read `docs/architecture/target-architecture.md` for target state
- Check `Claude.md` for present layout
- **Search for official DDD guidance** relevant to the code being reviewed

### Step 2: Determine Context

- Which layer? (Presentation, Application, Domain, Infrastructure)
- New code (apply target patterns) or existing (propose migration)?
- Request type? (Review, design, refactor, teach)
- **Identify which DDD principles apply** and find authoritative sources

### Step 3: Assess Against DDD Principles

Evaluate:
- **Layer Separation**: Correct project/layer placement?
- **CQRS**: Commands and Queries properly separated?
- **Rich Domain Models**: Business logic in entities/value objects vs anemic DTOs?
- **Validation Placement**:
  - BasicValidator: Service project and controllers (presentation concern)
  - Business rules: Value Objects/Entities/Domain Services (target)
- **Mapping Patterns**: Correct MapFrom vs MapToCommand usage?
- **Dependencies**: Does domain depend on infrastructure? (undesirable)
- **Naming**: Consistent Command/Handler/DTO naming?
- **Command/Handler Co-location**: Each handler with its command .cs file?
- **Avoid Generic Commands**: Prefer specific commands
- **Single Responsibility**: Each command = one transactional boundary
- **Value Objects**: Immutable, no identity sub-resources
- **Vertical Slices**: Related code co-located by feature?
- **Domain Logic Location**: Business rules in Domain vs Application?

### Step 4: Produce Findings

Use the exact output structure from [CHECKLIST_TEMPLATE.md](CHECKLIST_TEMPLATE.md):

1. Architecture Analysis section
2. DDD Principle Checklist (with [x]/[ ]/[~] indicators)
3. Concrete Recommendations (with code examples and migration paths)
4. References to architecture docs

## Core DDD Principles

### CQRS (Command Query Separation)

- **Commands**: Alter state, define transactional boundaries, should NOT call other Commands
- **Queries**: Retrieve state, no transactions, may be consumed by Commands or other Queries

Examples: See [REFERENCES.md](REFERENCES.md) for command and query examples in the codebase

### Validation Pattern

**BasicValidator** (Presentation/Service):
- Input validation, format checking, null checks
- Required fields, string length, regex patterns

**Business Validators** (Domain/Application):
- Business rule enforcement
- Order status transitions, date range validation, business constraints

**Value Objects** (Target):
- Self-validating, encapsulate business rules
- Throw domain exceptions on invalid state

For detailed validation guidance, see `docs/architecture/coding-guidelines.md`

### Mapping Patterns

- **MapFrom**: Infrastructure → Application (FROM data layer TO domain)
- **MapToCommand**: Presentation → Application (FROM presentation TO command)

## Pragmatic Migration Mindset

- Accept current repository state without excessive criticism
- Recognize migration is ongoing
- Recommend incremental changes toward target architecture
- Avoid one-off large rewrites
- Provide stepwise migration plans
- Reference good examples already in codebase

For migration strategy details, see [REFERENCES.md](REFERENCES.md)

## Common Use Cases

Enable this skill for requests such as:

- "Review this command for DDD compliance"
- "Should this be an entity or a value object?"
- "How should I structure a new gateway?"
- "Is my validator in the correct layer?"
- "Design a new feature using DDD patterns"
- "How should I map this DTO to a command?"

For comprehensive examples, see [EXAMPLES.md](EXAMPLES.md)

## Quick Reference

**Architecture Docs**: [REFERENCES.md](REFERENCES.md)
**Output Template**: [CHECKLIST_TEMPLATE.md](CHECKLIST_TEMPLATE.md)
**Use Case Examples**: [EXAMPLES.md](EXAMPLES.md)

**DDD Learning**: See Microsoft DDD Guide in [REFERENCES.md](REFERENCES.md)