review-flow: Skill for Claude Code

Clean Architecture - Tactical Guide

Persona

Read .claude/roles/architect.md — adopt this profile and follow all its rules.

Activation

This skill activates for any creation or modification of architectural components:

• Entities, Use Cases, Presenters
• Controllers, Gateways, Guards
• Services
• Module structure

Core Principle

"The architecture should scream the intent of the system." — Uncle Bob

┌─────────────────────────────────────┐
│       Interface Adapters            │  ← Controllers, Presenters, Gateways
├─────────────────────────────────────┤
│           Use Cases                 │  ← Application Business Rules
├─────────────────────────────────────┤
│            Entities                 │  ← Enterprise Business Rules
└─────────────────────────────────────┘

Dependency Rule: Dependencies point inward. The domain knows nothing about infrastructure.

---

Module Structure

src/
├── entities/
│   └── <entity>/
│       ├── <entity>.ts              # Entity + business logic
│       ├── <entity>.schema.ts       # Zod schema
│       ├── <entity>.guard.ts        # Boundary validation
│       └── <entity>.gateway.ts      # Interface (port)
├── usecases/
│   └── <action><Entity>.usecase.ts
├── interface-adapters/
│   ├── controllers/
│   │   ├── webhook/
│   │   │   └── <platform>.controller.ts
│   │   ├── http/
│   │   │   └── <feature>.routes.ts
│   │   └── mcp/
│   │       └── <action>.handler.ts
│   ├── presenters/
│   │   └── <feature>.presenter.ts
│   ├── gateways/
│   │   └── <entity>.<source>.gateway.ts
│   └── adapters/
│       └── <platform>.adapter.ts
├── shared/
│   └── foundation/
│       ├── usecase.base.ts
│       ├── guard.base.ts
│       ├── gateway.base.ts
│       └── presenter.base.ts
└── tests/
    ├── units/
    ├── factories/
    ├── stubs/
    └── mocks/

---

Components

Entity

Pure business logic, independent of any framework.

// entities/review/reviewScore.valueObject.ts
export class ReviewScore {
  private constructor(private readonly props: ReviewScoreProps) {}

  static create(props: ReviewScoreProps): ReviewScore {
    const validated = ReviewScoreSchema.parse(props);
    return new ReviewScore(validated);
  }

  get blocking(): number {
    return this.props.blocking;
  }

  get severity(): Severity {
    if (this.blocking > 0) return 'critical';
    if (this.warnings > 0) return 'warning';
    if (this.suggestions > 0) return 'info';
    return 'clean';
  }

  get hasBlockingIssues(): boolean {
    return this.blocking > 0;
  }
}