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)
+    }
+}
+```

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

@@ -0,0 +1,637 @@
+# Java Implementation Example Session
+
+This is an example session showing how the `/ddd-implement` skill works in a Java project.
+
+## Scenario
+
+You're building an e-commerce system and need to implement the **Order** aggregate in the domain layer.
+
+---
+
+## User Request
+
+```
+/ddd-implement --lang=java "Implement Order aggregate with these requirements:
+- Order has order number, customer ID, list of line items, and status
+- Can add/remove line items (only when status is DRAFT)
+- Can place order (transitions to PLACED)
+- Can cancel order (transitions to CANCELLED)
+- Cannot modify after PLACED or CANCELLED
+- Total amount is calculated from line items"
+```
+
+---
+
+## Agent Response
+
+I'll implement the **Order aggregate** in the domain layer following DDD patterns.
+
+### Analysis
+
+**Aggregate Root**: Order
+**Entities**: OrderLine (line items within order)
+**Value Objects**:
+- OrderNumber (unique identifier)
+- CustomerId (reference to Customer aggregate)
+- Money (for prices/totals)
+- OrderStatus (enum: DRAFT, PLACED, CANCELLED)
+
+**Invariants**:
+1. Cannot modify order after PLACED or CANCELLED
+2. Cannot place order with zero line items
+3. Line items must have positive quantity
+4. Order total = sum of line item totals
+
+**Layer**: Domain (`com.example.domain.order`)
+
+Let me implement this:
+
+### Error Types
+
+```java
+package com.example.domain.order;
+
+/**
+ * Order domain errors.
+ */
+public sealed interface OrderError permits
+    OrderAlreadyPlacedError,
+    OrderCancelledError,
+    EmptyOrderError,
+    LineItemNotFoundError,
+    InvalidLineItemError {
+    String message();
+}
+
+public record OrderAlreadyPlacedError(
+    OrderNumber orderNumber
+) implements OrderError {
+    @Override
+    public String message() {
+        return "Order already placed: " + orderNumber;
+    }
+}
+
+public record OrderCancelledError(
+    OrderNumber orderNumber
+) implements OrderError {
+    @Override
+    public String message() {
+        return "Order is cancelled: " + orderNumber;
+    }
+}
+
+public record EmptyOrderError() implements OrderError {
+    @Override
+    public String message() {
+        return "Cannot place order with no line items";
+    }
+}
+
+public record LineItemNotFoundError(
+    OrderLineId lineItemId
+) implements OrderError {
+    @Override
+    public String message() {
+        return "Line item not found: " + lineItemId;
+    }
+}
+
+public record InvalidLineItemError(
+    String reason
+) implements OrderError {
+    @Override
+    public String message() {
+        return "Invalid line item: " + reason;
+    }
+}
+```
+
+### Order Aggregate
+
+```java
+package com.example.domain.order;
+
+import com.example.shared.result.Result;
+import static com.example.shared.result.Result.Failure;
+import static com.example.shared.result.Result.Success;
+
+import java.time.Instant;
+import java.util.ArrayList;
+import java.util.List;
+import java.util.Objects;
+
+/**
+ * Order aggregate root.
+ *
+ * Invariant: Cannot modify order after PLACED or CANCELLED
+ * Invariant: Cannot place order with zero line items
+ * Invariant: Order total = sum of line item totals
+ */
+public class Order {
+    private final OrderNumber orderNumber;
+    private final CustomerId customerId;
+    private final List<OrderLine> lineItems;
+    private OrderStatus status;
+    private final Instant createdAt;
+    private Instant updatedAt;
+
+    /**
+     * Private constructor - use factory method.
+     */
+    private Order(
+        OrderNumber orderNumber,
+        CustomerId customerId,
+        OrderStatus status,
+        Instant createdAt
+    ) {
+        this.orderNumber = orderNumber;
+        this.customerId = customerId;
+        this.lineItems = new ArrayList<>();
+        this.status = status;
+        this.createdAt = createdAt;
+        this.updatedAt = createdAt;
+    }
+
+    /**
+     * Creates a new Order in DRAFT status.
+     */
+    public static Result<OrderError, Order> create(
+        OrderNumber orderNumber,
+        CustomerId customerId
+    ) {
+        Order order = new Order(
+            orderNumber,
+            customerId,
+            OrderStatus.DRAFT,
+            Instant.now()
+        );
+
+        return Result.success(order);
+    }
+
+    // Getters
+    public OrderNumber orderNumber() { return orderNumber; }
+    public CustomerId customerId() { return customerId; }
+    public OrderStatus status() { return status; }
+    public Instant createdAt() { return createdAt; }
+    public Instant updatedAt() { return updatedAt; }
+
+    /**
+     * Returns defensive copy of line items.
+     */
+    public List<OrderLine> lineItems() {
+        return List.copyOf(lineItems);
+    }
+
+    /**
+     * Calculates total order amount.
+     *
+     * Invariant: Total = sum of all line item totals
+     */
+    public Money calculateTotal() {
+        Money total = Money.usd(0);
+
+        for (OrderLine line : lineItems) {
+            Money lineTotal = line.calculateTotal();
+            total = switch (total.add(lineTotal)) {
+                case Failure(MoneyError error) ->
+                    throw new IllegalStateException(
+                        "Currency mismatch in order: " + error.message()
+                    );
+                case Success(Money sum) -> sum;
+            };
+        }
+
+        return total;
+    }
+
+    /**
+     * Adds a line item to the order.
+     *
+     * Invariant: Cannot modify after PLACED or CANCELLED
+     */
+    public Result<OrderError, Void> addLineItem(
+        ProductId productId,
+        String productName,
+        Money unitPrice,
+        int quantity
+    ) {
+        // Guard: Check order status
+        if (status == OrderStatus.PLACED) {
+            return Result.failure(new OrderAlreadyPlacedError(orderNumber));
+        }
+        if (status == OrderStatus.CANCELLED) {
+            return Result.failure(new OrderCancelledError(orderNumber));
+        }
+
+        // Create line item
+        OrderLineId lineId = OrderLineId.generate();
+
+        return switch (OrderLine.create(lineId, productId, productName, unitPrice, quantity)) {
+            case Failure(OrderLineError error) ->
+                Result.failure(new InvalidLineItemError(error.message()));
+            case Success(OrderLine line) -> {
+                lineItems.add(line);
+                this.updatedAt = Instant.now();
+                yield Result.success(null);
+            }
+        };
+    }
+
+    /**
+     * Removes a line item from the order.
+     *
+     * Invariant: Cannot modify after PLACED or CANCELLED
+     */
+    public Result<OrderError, Void> removeLineItem(OrderLineId lineItemId) {
+        // Guard: Check order status
+        if (status == OrderStatus.PLACED) {
+            return Result.failure(new OrderAlreadyPlacedError(orderNumber));
+        }
+        if (status == OrderStatus.CANCELLED) {
+            return Result.failure(new OrderCancelledError(orderNumber));
+        }
+
+        // Find and remove line item
+        boolean removed = lineItems.removeIf(line -> line.id().equals(lineItemId));
+
+        if (!removed) {
+            return Result.failure(new LineItemNotFoundError(lineItemId));
+        }
+
+        this.updatedAt = Instant.now();
+        return Result.success(null);
+    }
+
+    /**
+     * Updates quantity of an existing line item.
+     *
+     * Invariant: Cannot modify after PLACED or CANCELLED
+     */
+    public Result<OrderError, Void> updateLineItemQuantity(
+        OrderLineId lineItemId,
+        int newQuantity
+    ) {
+        // Guard: Check order status
+        if (status == OrderStatus.PLACED) {
+            return Result.failure(new OrderAlreadyPlacedError(orderNumber));
+        }
+        if (status == OrderStatus.CANCELLED) {
+            return Result.failure(new OrderCancelledError(orderNumber));
+        }
+
+        // Find line item
+        OrderLine line = findLineItemById(lineItemId);
+        if (line == null) {
+            return Result.failure(new LineItemNotFoundError(lineItemId));
+        }
+
+        // Update quantity
+        return switch (line.updateQuantity(newQuantity)) {
+            case Failure(OrderLineError error) ->
+                Result.failure(new InvalidLineItemError(error.message()));
+            case Success(Void ignored) -> {
+                this.updatedAt = Instant.now();
+                yield Result.success(null);
+            }
+        };
+    }
+
+    /**
+     * Places the order (transitions from DRAFT to PLACED).
+     *
+     * Invariant: Cannot place empty order
+     * Invariant: Can only place order in DRAFT status
+     */
+    public Result<OrderError, Void> place() {
+        // Guard: Check status
+        if (status == OrderStatus.PLACED) {
+            return Result.failure(new OrderAlreadyPlacedError(orderNumber));
+        }
+        if (status == OrderStatus.CANCELLED) {
+            return Result.failure(new OrderCancelledError(orderNumber));
+        }
+
+        // Guard: Check has line items
+        if (lineItems.isEmpty()) {
+            return Result.failure(new EmptyOrderError());
+        }
+
+        // Transition to PLACED
+        this.status = OrderStatus.PLACED;
+        this.updatedAt = Instant.now();
+
+        return Result.success(null);
+    }
+
+    /**
+     * Cancels the order.
+     *
+     * Invariant: Can cancel from DRAFT or PLACED, not from CANCELLED
+     */
+    public Result<OrderError, Void> cancel() {
+        // Guard: Already cancelled
+        if (status == OrderStatus.CANCELLED) {
+            return Result.failure(new OrderCancelledError(orderNumber));
+        }
+
+        // Transition to CANCELLED
+        this.status = OrderStatus.CANCELLED;
+        this.updatedAt = Instant.now();
+
+        return Result.success(null);
+    }
+
+    private OrderLine findLineItemById(OrderLineId id) {
+        return lineItems.stream()
+            .filter(line -> line.id().equals(id))
+            .findFirst()
+            .orElse(null);
+    }
+
+    @Override
+    public boolean equals(Object o) {
+        if (this == o) return true;
+        if (!(o instanceof Order order)) return false;
+        return Objects.equals(orderNumber, order.orderNumber);
+    }
+
+    @Override
+    public int hashCode() {
+        return Objects.hash(orderNumber);
+    }
+
+    @Override
+    public String toString() {
+        return "Order{" +
+            "orderNumber=" + orderNumber +
+            ", customerId=" + customerId +
+            ", status=" + status +
+            ", lineItems=" + lineItems.size() +
+            ", total=" + calculateTotal() +
+            '}';
+    }
+}
+```
+
+### OrderLine Entity
+
+```java
+package com.example.domain.order;
+
+import com.example.shared.result.Result;
+import java.util.Objects;
+
+/**
+ * OrderLine errors.
+ */
+public sealed interface OrderLineError permits
+    InvalidQuantityError,
+    InvalidPriceError {
+    String message();
+}
+
+public record InvalidQuantityError(int quantity) implements OrderLineError {
+    @Override
+    public String message() {
+        return "Quantity must be positive: " + quantity;
+    }
+}
+
+public record InvalidPriceError(Money price) implements OrderLineError {
+    @Override
+    public String message() {
+        return "Price must be positive: " + price;
+    }
+}
+
+/**
+ * OrderLine entity (child entity within Order aggregate).
+ *
+ * Invariant: Quantity must be positive
+ * Invariant: Price must be positive
+ */
+public class OrderLine {
+    private final OrderLineId id;
+    private final ProductId productId;
+    private final String productName;
+    private final Money unitPrice;
+    private int quantity;
+
+    /**
+     * Package-private constructor - created by Order aggregate.
+     */
+    OrderLine(
+        OrderLineId id,
+        ProductId productId,
+        String productName,
+        Money unitPrice,
+        int quantity
+    ) {
+        this.id = id;
+        this.productId = productId;
+        this.productName = productName;
+        this.unitPrice = unitPrice;
+        this.quantity = quantity;
+    }
+
+    /**
+     * Creates a new OrderLine.
+     */
+    static Result<OrderLineError, OrderLine> create(
+        OrderLineId id,
+        ProductId productId,
+        String productName,
+        Money unitPrice,
+        int quantity
+    ) {
+        // Invariant: Quantity must be positive
+        if (quantity <= 0) {
+            return Result.failure(new InvalidQuantityError(quantity));
+        }
+
+        // Invariant: Price must be positive
+        if (unitPrice.isNegativeOrZero()) {
+            return Result.failure(new InvalidPriceError(unitPrice));
+        }
+
+        return Result.success(new OrderLine(
+            id,
+            productId,
+            productName,
+            unitPrice,
+            quantity
+        ));
+    }
+
+    public OrderLineId id() { return id; }
+    public ProductId productId() { return productId; }
+    public String productName() { return productName; }
+    public Money unitPrice() { return unitPrice; }
+    public int quantity() { return quantity; }
+
+    /**
+     * Updates the quantity.
+     *
+     * Invariant: Quantity must be positive
+     */
+    Result<OrderLineError, Void> updateQuantity(int newQuantity) {
+        if (newQuantity <= 0) {
+            return Result.failure(new InvalidQuantityError(newQuantity));
+        }
+
+        this.quantity = newQuantity;
+        return Result.success(null);
+    }
+
+    /**
+     * Calculates total price for this line.
+     */
+    public Money calculateTotal() {
+        return unitPrice.multiply(quantity);
+    }
+
+    /**
+     * Equality based on ID only (entity identity).
+     */
+    @Override
+    public boolean equals(Object o) {
+        if (this == o) return true;
+        if (!(o instanceof OrderLine that)) return false;
+        return Objects.equals(id, that.id);
+    }
+
+    @Override
+    public int hashCode() {
+        return Objects.hash(id);
+    }
+
+    @Override
+    public String toString() {
+        return "OrderLine{" +
+            "id=" + id +
+            ", product=" + productName +
+            ", quantity=" + quantity +
+            ", unitPrice=" + unitPrice +
+            ", total=" + calculateTotal() +
+            '}';
+    }
+}
+```
+
+### Supporting Types
+
+```java
+package com.example.domain.order;
+
+/**
+ * Order status enumeration.
+ */
+public enum OrderStatus {
+    DRAFT("Order is being created"),
+    PLACED("Order has been placed"),
+    CANCELLED("Order was cancelled");
+
+    private final String description;
+
+    OrderStatus(String description) {
+        this.description = description;
+    }
+
+    public String description() {
+        return description;
+    }
+}
+
+/**
+ * OrderNumber value object.
+ */
+public record OrderNumber(String value) {
+    public OrderNumber {
+        if (value == null || value.isBlank()) {
+            throw new IllegalArgumentException("OrderNumber cannot be empty");
+        }
+    }
+
+    public static OrderNumber of(String value) {
+        return new OrderNumber(value);
+    }
+
+    public static OrderNumber generate() {
+        return new OrderNumber("ORD-" + java.util.UUID.randomUUID());
+    }
+}
+
+/**
+ * OrderLineId value object.
+ */
+public record OrderLineId(String value) {
+    public OrderLineId {
+        if (value == null || value.isBlank()) {
+            throw new IllegalArgumentException("OrderLineId cannot be empty");
+        }
+    }
+
+    public static OrderLineId generate() {
+        return new OrderLineId(java.util.UUID.randomUUID().toString());
+    }
+}
+```
+
+---
+
+## Summary
+
+✅ **Implemented**:
+- Order aggregate root with all required operations
+- OrderLine entity (child entity, package-private constructor)
+- Sealed interfaces for error types
+- All invariants documented and enforced
+- Result types for all operations (no exceptions)
+- Pattern matching with switch expressions
+- Defensive copy for line items collection
+
+✅ **DDD Rules Followed**:
+- Aggregate is only entry point (line items accessed via Order methods)
+- Entities have ID-based equality
+- All invariants checked in constructor and mutation methods
+- No direct references to other aggregates (ProductId, CustomerId are IDs only)
+- One aggregate = one transaction boundary
+
+✅ **Layer**: Domain (no external dependencies)
+
+✅ **Files Created**:
+- `com/example/domain/order/Order.java`
+- `com/example/domain/order/OrderLine.java`
+- `com/example/domain/order/OrderError.java`
+- `com/example/domain/order/OrderLineError.java`
+- `com/example/domain/order/OrderStatus.java`
+- `com/example/domain/order/OrderNumber.java`
+- `com/example/domain/order/OrderLineId.java`
+
+---
+
+## Next Steps
+
+You can now:
+
+1. **Implement the repository interface**:
+   ```
+   /ddd-implement --lang=java "Create OrderRepository interface in domain layer"
+   ```
+
+2. **Implement a use case**:
+   ```
+   /ddd-implement --lang=java "Create PlaceOrder use case in application layer"
+   ```
+
+3. **Implement repository**:
+   ```
+   /ddd-implement --lang=java "Implement JdbcOrderRepository in infrastructure layer"
+   ```
+
+4. **Add tests**:
+   ```
+   Write unit tests for Order aggregate
+   ```