docs: and skills

bin/.claude/skills/ddd-implement/examples/go-example.md

@@ -0,0 +1,595 @@
+# Go Implementation Example Session
+
+This is an example session showing how the `/ddd-implement` skill works in a Go project.
+
+## Scenario
+
+You're building a reservation system and need to implement the **Booking** aggregate in the domain layer.
+
+---
+
+## User Request
+
+```
+/ddd-implement --lang=go "Implement Booking aggregate with these requirements:
+- Booking has ID, room ID, guest ID, check-in/check-out dates, and status
+- Can confirm booking (transitions to CONFIRMED)
+- Can cancel booking (transitions to CANCELLED)
+- Cannot modify after checked in
+- Check-out date must be after check-in date"
+```
+
+---
+
+## Agent Response
+
+I'll implement the **Booking aggregate** in the domain layer following DDD patterns for Go.
+
+### Analysis
+
+**Aggregate Root**: Booking
+**Value Objects**:
+- BookingID (unique identifier)
+- RoomID (reference to Room aggregate)
+- GuestID (reference to Guest aggregate)
+- DateRange (check-in to check-out)
+- BookingStatus (Pending|Confirmed|Cancelled|CheckedIn|CheckedOut)
+
+**Invariants**:
+1. Check-out date must be after check-in date
+2. Cannot modify booking after checked in
+3. Can only confirm booking in Pending status
+4. Can only cancel before checked in
+
+**Layer**: Domain (`internal/domain/booking`)
+
+Let me implement this:
+
+### Error Types
+
+```go
+package booking
+
+import "errors"
+
+var (
+    ErrInvalidDateRange     = errors.New("check-out date must be after check-in date")
+    ErrBookingAlreadyConfirmed = errors.New("booking is already confirmed")
+    ErrBookingCancelled     = errors.New("booking is cancelled")
+    ErrBookingCheckedIn     = errors.New("cannot modify booking after check-in")
+    ErrInvalidStatus        = errors.New("invalid status transition")
+)
+
+// BookingNotFoundError represents a specific booking not found error
+type BookingNotFoundError struct {
+    BookingID BookingID
+}
+
+func (e BookingNotFoundError) Error() string {
+    return "booking not found: " + e.BookingID.Value()
+}
+```
+
+### Value Objects
+
+```go
+package booking
+
+import (
+    "errors"
+    "time"
+
+    "github.com/google/uuid"
+)
+
+// BookingID uniquely identifies a booking
+type BookingID struct {
+    value string
+}
+
+func NewBookingID(value string) (BookingID, error) {
+    if value == "" {
+        return BookingID{}, errors.New("booking ID cannot be empty")
+    }
+    return BookingID{value: value}, nil
+}
+
+func GenerateBookingID() BookingID {
+    return BookingID{value: uuid.New().String()}
+}
+
+func (id BookingID) Value() string {
+    return id.value
+}
+
+func (id BookingID) Equals(other BookingID) bool {
+    return id.value == other.value
+}
+
+// RoomID references a Room aggregate
+type RoomID struct {
+    value string
+}
+
+func NewRoomID(value string) (RoomID, error) {
+    if value == "" {
+        return RoomID{}, errors.New("room ID cannot be empty")
+    }
+    return RoomID{value: value}, nil
+}
+
+func (id RoomID) Value() string {
+    return id.value
+}
+
+// GuestID references a Guest aggregate
+type GuestID struct {
+    value string
+}
+
+func NewGuestID(value string) (GuestID, error) {
+    if value == "" {
+        return GuestID{}, errors.New("guest ID cannot be empty")
+    }
+    return GuestID{value: value}, nil
+}
+
+func (id GuestID) Value() string {
+    return id.value
+}
+
+// DateRange represents check-in to check-out period
+type DateRange struct {
+    checkIn  time.Time
+    checkOut time.Time
+}
+
+// NewDateRange creates a DateRange with validation
+func NewDateRange(checkIn, checkOut time.Time) (DateRange, error) {
+    // Invariant: Check-out must be after check-in
+    if !checkOut.After(checkIn) {
+        return DateRange{}, ErrInvalidDateRange
+    }
+
+    return DateRange{
+        checkIn:  checkIn,
+        checkOut: checkOut,
+    }, nil
+}
+
+func (dr DateRange) CheckIn() time.Time {
+    return dr.checkIn
+}
+
+func (dr DateRange) CheckOut() time.Time {
+    return dr.checkOut
+}
+
+func (dr DateRange) Nights() int {
+    duration := dr.checkOut.Sub(dr.checkIn)
+    return int(duration.Hours() / 24)
+}
+
+func (dr DateRange) Contains(date time.Time) bool {
+    return (date.Equal(dr.checkIn) || date.After(dr.checkIn)) &&
+        date.Before(dr.checkOut)
+}
+
+// BookingStatus represents the current status of a booking
+type BookingStatus int
+
+const (
+    BookingStatusPending BookingStatus = iota
+    BookingStatusConfirmed
+    BookingStatusCancelled
+    BookingStatusCheckedIn
+    BookingStatusCheckedOut
+)
+
+func (s BookingStatus) String() string {
+    switch s {
+    case BookingStatusPending:
+        return "PENDING"
+    case BookingStatusConfirmed:
+        return "CONFIRMED"
+    case BookingStatusCancelled:
+        return "CANCELLED"
+    case BookingStatusCheckedIn:
+        return "CHECKED_IN"
+    case BookingStatusCheckedOut:
+        return "CHECKED_OUT"
+    default:
+        return "UNKNOWN"
+    }
+}
+```
+
+### Booking Aggregate
+
+```go
+package booking
+
+import (
+    "time"
+)
+
+// Booking aggregate root.
+//
+// Invariants:
+// - Check-out date must be after check-in date
+// - Cannot modify booking after checked in
+// - Can only confirm booking in Pending status
+// - Can only cancel before checked in
+type Booking struct {
+    id        BookingID
+    roomID    RoomID
+    guestID   GuestID
+    dateRange DateRange
+    status    BookingStatus
+
+    createdAt time.Time
+    updatedAt time.Time
+}
+
+// NewBooking creates a new booking in Pending status.
+func NewBooking(
+    id BookingID,
+    roomID RoomID,
+    guestID GuestID,
+    dateRange DateRange,
+) (*Booking, error) {
+    now := time.Now()
+
+    return &Booking{
+        id:        id,
+        roomID:    roomID,
+        guestID:   guestID,
+        dateRange: dateRange,
+        status:    BookingStatusPending,
+        createdAt: now,
+        updatedAt: now,
+    }, nil
+}
+
+// Getters
+func (b *Booking) ID() BookingID           { return b.id }
+func (b *Booking) RoomID() RoomID          { return b.roomID }
+func (b *Booking) GuestID() GuestID        { return b.guestID }
+func (b *Booking) DateRange() DateRange    { return b.dateRange }
+func (b *Booking) Status() BookingStatus   { return b.status }
+func (b *Booking) CreatedAt() time.Time    { return b.createdAt }
+func (b *Booking) UpdatedAt() time.Time    { return b.updatedAt }
+
+// Confirm transitions booking from Pending to Confirmed.
+//
+// Invariant: Can only confirm Pending bookings
+func (b *Booking) Confirm() error {
+    // Guard: Check status
+    if b.status == BookingStatusConfirmed {
+        return ErrBookingAlreadyConfirmed
+    }
+    if b.status == BookingStatusCancelled {
+        return ErrBookingCancelled
+    }
+    if b.status == BookingStatusCheckedIn || b.status == BookingStatusCheckedOut {
+        return ErrBookingCheckedIn
+    }
+
+    // Transition to Confirmed
+    b.status = BookingStatusConfirmed
+    b.updatedAt = time.Now()
+
+    return nil
+}
+
+// Cancel transitions booking to Cancelled.
+//
+// Invariant: Cannot cancel after checked in
+func (b *Booking) Cancel() error {
+    // Guard: Already cancelled
+    if b.status == BookingStatusCancelled {
+        return nil // Idempotent
+    }
+
+    // Guard: Cannot cancel after check-in
+    if b.status == BookingStatusCheckedIn || b.status == BookingStatusCheckedOut {
+        return ErrBookingCheckedIn
+    }
+
+    // Transition to Cancelled
+    b.status = BookingStatusCancelled
+    b.updatedAt = time.Now()
+
+    return nil
+}
+
+// CheckIn transitions booking to CheckedIn status.
+//
+// Invariant: Can only check in Confirmed bookings
+func (b *Booking) CheckIn() error {
+    // Guard: Must be confirmed
+    if b.status != BookingStatusConfirmed {
+        if b.status == BookingStatusCancelled {
+            return ErrBookingCancelled
+        }
+        if b.status == BookingStatusCheckedIn {
+            return nil // Idempotent
+        }
+        return ErrInvalidStatus
+    }
+
+    // Transition to CheckedIn
+    b.status = BookingStatusCheckedIn
+    b.updatedAt = time.Now()
+
+    return nil
+}
+
+// CheckOut transitions booking to CheckedOut status.
+//
+// Invariant: Can only check out after checked in
+func (b *Booking) CheckOut() error {
+    // Guard: Must be checked in
+    if b.status != BookingStatusCheckedIn {
+        if b.status == BookingStatusCancelled {
+            return ErrBookingCancelled
+        }
+        if b.status == BookingStatusCheckedOut {
+            return nil // Idempotent
+        }
+        return ErrInvalidStatus
+    }
+
+    // Transition to CheckedOut
+    b.status = BookingStatusCheckedOut
+    b.updatedAt = time.Now()
+
+    return nil
+}
+
+// UpdateDates changes the check-in/check-out dates.
+//
+// Invariant: Cannot modify after checked in
+// Invariant: New dates must be valid (check-out after check-in)
+func (b *Booking) UpdateDates(newDateRange DateRange) error {
+    // Guard: Cannot modify after check-in
+    if b.status == BookingStatusCheckedIn || b.status == BookingStatusCheckedOut {
+        return ErrBookingCheckedIn
+    }
+
+    // Guard: Cannot modify cancelled booking
+    if b.status == BookingStatusCancelled {
+        return ErrBookingCancelled
+    }
+
+    // Update dates
+    b.dateRange = newDateRange
+    b.updatedAt = time.Now()
+
+    return nil
+}
+```
+
+### Repository Interface
+
+```go
+package booking
+
+import (
+    "context"
+    "time"
+)
+
+// Repository defines persistence operations for Booking aggregates.
+type Repository interface {
+    // Save persists a booking (insert or update)
+    Save(ctx context.Context, booking *Booking) error
+
+    // FindByID retrieves a booking by ID
+    FindByID(ctx context.Context, id BookingID) (*Booking, error)
+
+    // FindByGuest retrieves all bookings for a guest
+    FindByGuest(ctx context.Context, guestID GuestID) ([]*Booking, error)
+
+    // FindByRoom retrieves all bookings for a room
+    FindByRoom(ctx context.Context, roomID RoomID) ([]*Booking, error)
+
+    // FindOverlapping finds bookings that overlap with the given date range for a room
+    FindOverlapping(ctx context.Context, roomID RoomID, dateRange DateRange) ([]*Booking, error)
+
+    // Delete removes a booking
+    Delete(ctx context.Context, id BookingID) error
+}
+```
+
+### Domain Service (Optional)
+
+```go
+package booking
+
+import (
+    "context"
+    "time"
+)
+
+// Service provides domain operations for bookings.
+type Service struct {
+    repo Repository
+}
+
+// NewService creates a booking service.
+func NewService(repo Repository) *Service {
+    return &Service{repo: repo}
+}
+
+// CheckAvailability checks if a room is available for the given dates.
+//
+// This is a domain service because it queries across multiple bookings.
+func (s *Service) CheckAvailability(
+    ctx context.Context,
+    roomID RoomID,
+    dateRange DateRange,
+) (bool, error) {
+    // Find overlapping bookings
+    overlapping, err := s.repo.FindOverlapping(ctx, roomID, dateRange)
+    if err != nil {
+        return false, err
+    }
+
+    // Check if any active bookings overlap
+    for _, booking := range overlapping {
+        // Ignore cancelled bookings
+        if booking.status == BookingStatusCancelled {
+            continue
+        }
+
+        // Found an active booking that overlaps
+        return false, nil
+    }
+
+    // Room is available
+    return true, nil
+}
+```
+
+---
+
+## Summary
+
+✅ **Implemented**:
+- Booking aggregate root with all required operations
+- Value objects: BookingID, RoomID, GuestID, DateRange, BookingStatus
+- Custom error types for domain-specific errors
+- Repository interface in domain layer
+- Optional domain service for availability checking
+
+✅ **DDD Rules Followed**:
+- Aggregate is only entry point
+- All invariants documented in comments
+- Invariants checked in NewBooking and mutation methods
+- No direct references to other aggregates (RoomID, GuestID are IDs only)
+- Pointer receiver for aggregate (*Booking)
+- Value receiver for value objects (DateRange)
+- One aggregate = one transaction boundary
+
+✅ **Go Conventions**:
+- Unexported fields, exported methods
+- Constructor function (NewBooking)
+- Error return values (not panics)
+- Sentinel errors (ErrInvalidDateRange, etc.)
+- Custom error types (BookingNotFoundError)
+
+✅ **Layer**: Domain (no external dependencies)
+
+✅ **Files Created**:
+- `internal/domain/booking/booking.go` - Aggregate root
+- `internal/domain/booking/value_objects.go` - Value objects and IDs
+- `internal/domain/booking/errors.go` - Domain errors
+- `internal/domain/booking/repository.go` - Repository interface
+- `internal/domain/booking/service.go` - Domain service
+
+---
+
+## Next Steps
+
+You can now:
+
+1. **Implement the repository**:
+   ```
+   /ddd-implement --lang=go "Implement PostgreSQL repository for Booking aggregate"
+   ```
+
+2. **Implement a use case**:
+   ```
+   /ddd-implement --lang=go "Create CreateBooking use case in application layer"
+   ```
+
+3. **Add tests**:
+   ```
+   Write unit tests for Booking aggregate
+   ```
+
+4. **Implement HTTP handler**:
+   ```
+   /ddd-implement --lang=go "Create HTTP handler for booking endpoints in infrastructure layer"
+   ```
+
+---
+
+## Testing Example
+
+Here's how you would test the Booking aggregate:
+
+```go
+package booking_test
+
+import (
+    "testing"
+    "time"
+
+    "myapp/internal/domain/booking"
+)
+
+func TestBooking_Confirm_FromPending_Succeeds(t *testing.T) {
+    // Arrange
+    id := booking.GenerateBookingID()
+    roomID, _ := booking.NewRoomID("room-123")
+    guestID, _ := booking.NewGuestID("guest-456")
+    checkIn := time.Now().AddDate(0, 0, 1)
+    checkOut := time.Now().AddDate(0, 0, 3)
+    dateRange, _ := booking.NewDateRange(checkIn, checkOut)
+
+    b, err := booking.NewBooking(id, roomID, guestID, dateRange)
+    if err != nil {
+        t.Fatalf("NewBooking failed: %v", err)
+    }
+
+    // Act
+    err = b.Confirm()
+
+    // Assert
+    if err != nil {
+        t.Errorf("Confirm failed: %v", err)
+    }
+
+    if b.Status() != booking.BookingStatusConfirmed {
+        t.Errorf("Expected status CONFIRMED, got %v", b.Status())
+    }
+}
+
+func TestBooking_Cancel_AfterCheckIn_Fails(t *testing.T) {
+    // Arrange
+    id := booking.GenerateBookingID()
+    roomID, _ := booking.NewRoomID("room-123")
+    guestID, _ := booking.NewGuestID("guest-456")
+    checkIn := time.Now().AddDate(0, 0, 1)
+    checkOut := time.Now().AddDate(0, 0, 3)
+    dateRange, _ := booking.NewDateRange(checkIn, checkOut)
+
+    b, _ := booking.NewBooking(id, roomID, guestID, dateRange)
+    _ = b.Confirm()
+    _ = b.CheckIn()
+
+    // Act
+    err := b.Cancel()
+
+    // Assert
+    if err != booking.ErrBookingCheckedIn {
+        t.Errorf("Expected ErrBookingCheckedIn, got %v", err)
+    }
+}
+
+func TestDateRange_InvalidDates_Fails(t *testing.T) {
+    // Arrange
+    checkIn := time.Now().AddDate(0, 0, 3)
+    checkOut := time.Now().AddDate(0, 0, 1) // Before check-in!
+
+    // Act
+    _, err := booking.NewDateRange(checkIn, checkOut)
+
+    // Assert
+    if err != booking.ErrInvalidDateRange {
+        t.Errorf("Expected ErrInvalidDateRange, got %v", err)
+    }
+}
+```