@edupia-tutor/spec-driven-docs 0.14.0

package/core/modules/dotnet/architecture-snippets/clean-arch.md

@@ -0,0 +1,160 @@
+# .NET Clean Architecture — Code Patterns
+
+## Command and Query with MediatR
+
+```csharp
+// Application/Orders/Commands/CreateOrder/CreateOrderCommand.cs
+// @trace.implements=ORDER-UC1-SC1
+public record CreateOrderCommand(
+    long CustomerId,
+    List<OrderItemDto> Items,
+    string ShippingAddress
+) : IRequest<CreateOrderResult>;
+
+// Application/Orders/Commands/CreateOrder/CreateOrderCommandHandler.cs
+public class CreateOrderCommandHandler : IRequestHandler<CreateOrderCommand, CreateOrderResult>
+{
+    private readonly IOrderRepository _orderRepository;
+    private readonly IUnitOfWork _unitOfWork;
+
+    public CreateOrderCommandHandler(IOrderRepository orderRepository, IUnitOfWork unitOfWork)
+    {
+        _orderRepository = orderRepository;
+        _unitOfWork = unitOfWork;
+    }
+
+    public async Task<CreateOrderResult> Handle(CreateOrderCommand command, CancellationToken ct)
+    {
+        var order = Order.Create(command.CustomerId, command.Items, command.ShippingAddress);
+        await _orderRepository.AddAsync(order, ct);
+        await _unitOfWork.SaveChangesAsync(ct);
+        return new CreateOrderResult(order.Id, order.Status.ToString());
+    }
+}
+
+// Application/Orders/Queries/GetOrder/GetOrderQuery.cs
+// @trace.implements=ORDER-UC1-SC2
+public record GetOrderQuery(long OrderId) : IRequest<OrderDto>;
+```
+
+## FluentValidation for Commands
+
+```csharp
+// Application/Orders/Commands/CreateOrder/CreateOrderCommandValidator.cs
+public class CreateOrderCommandValidator : AbstractValidator<CreateOrderCommand>
+{
+    public CreateOrderCommandValidator()
+    {
+        RuleFor(x => x.CustomerId).GreaterThan(0);
+        RuleFor(x => x.Items).NotEmpty().WithMessage("Order must have at least one item.");
+        RuleFor(x => x.ShippingAddress).NotEmpty().MaximumLength(500);
+        RuleForEach(x => x.Items).ChildRules(item =>
+        {
+            item.RuleFor(i => i.ProductId).GreaterThan(0);
+            item.RuleFor(i => i.Quantity).InclusiveBetween(1, 999);
+        });
+    }
+}
+```
+
+## Domain Entity Pattern
+
+```csharp
+// Domain/Entities/Order.cs
+public class Order : BaseEntity
+{
+    private readonly List<OrderItem> _items = new();
+
+    public long CustomerId { get; private set; }
+    public OrderStatus Status { get; private set; }
+    public string ShippingAddress { get; private set; } = string.Empty;
+    public IReadOnlyCollection<OrderItem> Items => _items.AsReadOnly();
+    public decimal TotalAmount => _items.Sum(i => i.Subtotal);
+
+    private Order() { }  // EF Core constructor
+
+    public static Order Create(long customerId, IEnumerable<OrderItemDto> items, string shippingAddress)
+    {
+        var order = new Order
+        {
+            CustomerId = customerId,
+            ShippingAddress = shippingAddress,
+            Status = OrderStatus.Pending,
+            CreatedAt = DateTime.UtcNow
+        };
+
+        foreach (var item in items)
+            order._items.Add(OrderItem.Create(item.ProductId, item.Quantity, item.UnitPrice));
+
+        order.AddDomainEvent(new OrderCreatedEvent(order.Id, order.CustomerId));
+        return order;
+    }
+
+    public void Cancel()
+    {
+        if (Status == OrderStatus.Shipped)
+            throw new DomainException("Cannot cancel an order that has already been shipped.");
+        Status = OrderStatus.Cancelled;
+    }
+}
+```
+
+## Repository Implementation with EF Core
+
+```csharp
+// Infrastructure/Persistence/Repositories/OrderRepository.cs
+public class OrderRepository : IOrderRepository
+{
+    private readonly AppDbContext _context;
+
+    public OrderRepository(AppDbContext context) => _context = context;
+
+    public async Task<Order?> GetByIdAsync(long id, CancellationToken ct = default)
+        => await _context.Orders
+            .Include(o => o.Items)
+            .FirstOrDefaultAsync(o => o.Id == id, ct);
+
+    public async Task AddAsync(Order order, CancellationToken ct = default)
+        => await _context.Orders.AddAsync(order, ct);
+
+    public async Task<IReadOnlyList<Order>> GetByCustomerAsync(long customerId, CancellationToken ct = default)
+        => await _context.Orders
+            .Where(o => o.CustomerId == customerId)
+            .OrderByDescending(o => o.CreatedAt)
+            .ToListAsync(ct);
+}
+```
+
+## Minimal API Controller Pattern
+
+```csharp
+// Presentation/Endpoints/OrderEndpoints.cs
+// @trace.implements=ORDER-UC1
+public static class OrderEndpoints
+{
+    public static void MapOrderEndpoints(this IEndpointRouteBuilder app)
+    {
+        var group = app.MapGroup("/v1/orders").RequireAuthorization();
+
+        // @trace.implements=ORDER-UC1-SC1
+        group.MapPost("/", async (CreateOrderCommand command, IMediator mediator, CancellationToken ct) =>
+        {
+            var result = await mediator.Send(command, ct);
+            return Results.Created($"/v1/orders/{result.Id}", result);
+        })
+        .WithName("CreateOrder")
+        .Produces<CreateOrderResult>(StatusCodes.Status201Created)
+        .ProducesValidationProblem();
+
+        // @trace.implements=ORDER-UC1-SC2
+        group.MapGet("/{id:long}", async (long id, IMediator mediator, CancellationToken ct) =>
+        {
+            var result = await mediator.Send(new GetOrderQuery(id), ct);
+            return result is null ? Results.NotFound() : Results.Ok(result);
+        })
+        .WithName("GetOrder")
+        .Produces<OrderDto>()
+        .Produces(StatusCodes.Status404NotFound);
+    }
+}
+```

package/core/modules/dotnet/module.yaml

@@ -0,0 +1,6 @@
+name: ".NET"
+version: "1.0.0"
+description: ".NET 8 with Clean Architecture"
+language: "C#"
+framework: ".NET 8 / ASP.NET Core"
+stack_type: "backend"

package/core/modules/dotnet/stack-profile.yaml

@@ -0,0 +1,50 @@
+build:
+  compile: "dotnet build"
+  test: "dotnet test"
+  run: "dotnet run --project src/{ProjectName}.Api"
+
+architecture:
+  style: "Clean Architecture"
+  layers:
+    - name: "Domain"
+      contains: "Entities, Value Objects, Domain Events, Interfaces"
+      rules:
+        - "No dependencies on outer layers"
+        - "Pure business logic only"
+    - name: "Application"
+      contains: "Commands, Queries, Handlers (MediatR), DTOs, Validators"
+      rules:
+        - "Depends only on Domain"
+        - "All use cases are Commands or Queries"
+        - "Validation via FluentValidation"
+    - name: "Infrastructure"
+      contains: "EF Core DbContext, Repository implementations, External service adapters"
+      rules:
+        - "Implements interfaces from Application and Domain"
+        - "No business logic"
+    - name: "Presentation"
+      contains: "Controllers (or Minimal API endpoints), Middleware"
+      rules:
+        - "Dispatches to MediatR only"
+        - "No direct service injection (only IMediator)"
+
+coding_standards:
+  naming:
+    classes: "PascalCase"
+    methods: "PascalCase"
+    interfaces: "IPascalCase (with I prefix)"
+    async_methods: "PascalCase + Async suffix (e.g., GetOrderAsync)"
+  patterns:
+    cqrs: "MediatR — IRequest<T> for commands/queries, IRequestHandler<T,R> for handlers"
+    validation: "FluentValidation — one AbstractValidator<T> per command/query"
+    error_handling: "Result pattern or domain exceptions, caught by global middleware"
+    response_type: "IActionResult with ProblemDetails for errors (RFC 7807)"
+
+testing:
+  unit: "xUnit + Moq + FluentAssertions"
+  integration: "WebApplicationFactory<Program> + Testcontainers"
+  patterns:
+    - "Arrange / Act / Assert structure"
+    - "Method names: MethodName_WhenCondition_ShouldExpectation"
+    - "Use FluentAssertions for readable assertions"
+    - "Mock only the direct dependencies of the unit under test"

package/core/modules/flutter/module.yaml

@@ -0,0 +1,14 @@
+name: "Flutter"
+version: "1.0.0"
+description: "Cross-platform mobile (iOS + Android) with Flutter/Dart"
+language: "Dart"
+framework: "Flutter"
+stack_type: "mobile"
+default_layer_order:
+  - Models / entities (domain)
+  - Repositories (data layer)
+  - Use cases (domain logic)
+  - BLoC / Cubit or Riverpod providers (state)
+  - Widgets (presentation)
+  - Pages / screens
+test_framework: "flutter_test + mocktail"

package/core/modules/flutter/stack-profile.yaml

@@ -0,0 +1,59 @@
+build:
+  compile: "flutter build apk / flutter build ios"
+  test: "flutter test"
+  run: "flutter run"
+  lint: "flutter analyze"
+
+architecture:
+  style: "Feature-based (presentation → domain → data)"
+  key_rules:
+    - "Widget tree is pure UI — business logic lives in BLoC/Cubit or Riverpod providers"
+    - "Repositories abstract data sources; services contain domain logic"
+    - "State management: BLoC (complex flows) or Riverpod (simple/medium)"
+    - "Never call API directly inside a Widget build() method"
+    - "Shared UI widgets in lib/shared/widgets/, feature widgets in lib/features/{name}/presentation/"
+    - "Use const constructors wherever possible for performance"
+  folder_structure: |
+    lib/
+    ├── core/
+    │   ├── theme/        ← AppTheme, colors, text styles
+    │   ├── router/       ← GoRouter or auto_route
+    │   └── utils/
+    ├── shared/
+    │   └── widgets/      ← reusable UI widgets (AppButton, AppInput...)
+    ├── features/
+    │   └── {domain}/
+    │       ├── data/         ← repositories, data sources, models
+    │       ├── domain/       ← entities, use cases, repo interfaces
+    │       └── presentation/ ← pages, widgets, BLoC/Cubit
+    └── main.dart
+
+coding_standards:
+  naming:
+    widgets: "PascalCase (e.g., OrderListPage, CreateOrderForm)"
+    blocs: "PascalCase + Bloc/Cubit suffix (e.g., OrderListCubit)"
+    repositories: "PascalCase + Repository suffix (e.g., OrderRepository)"
+    files:
+      page: "{feature}_page.dart"
+      widget: "{feature}_widget.dart"
+      cubit: "{feature}_cubit.dart"
+      repository: "{feature}_repository.dart"
+      model: "{feature}_model.dart"
+  patterns:
+    state_management: "BLoC / Cubit (flutter_bloc) or Riverpod"
+    navigation: "GoRouter or auto_route"
+    networking: "Dio with interceptors"
+    serialization: "json_serializable / freezed"
+
+testing:
+  unit: "flutter_test + mocktail"
+  widget: "flutter_test WidgetTester"
+  integration: "integration_test package"
+  patterns:
+    - "Test BLoC/Cubit in isolation with fake repositories"
+    - "Widget tests pump the widget tree and find by key or semantics label"
+    - "Use goldenFileComparator for snapshot tests of complex widgets"
+
+trace_tags:
+  implements: "// @trace.implements={UC-ID}-SC{N}"
+  source: "// @trace.source=specs/{domain}/{prd-slug}/bdd/{UC-ID}.feature"

package/core/modules/golang/architecture-snippets/domain-layout.md

@@ -0,0 +1,283 @@
+# Go — Domain-Driven Layout Code Patterns
+
+## Domain Model
+
+```go
+// internal/domain/order.go
+package domain
+
+import (
+    "errors"
+    "time"
+)
+
+// OrderStatus represents the lifecycle state of an order.
+type OrderStatus string
+
+const (
+    OrderStatusPending   OrderStatus = "PENDING"
+    OrderStatusConfirmed OrderStatus = "CONFIRMED"
+    OrderStatusShipped   OrderStatus = "SHIPPED"
+    OrderStatusCancelled OrderStatus = "CANCELLED"
+)
+
+// Order is the aggregate root for the order domain.
+type Order struct {
+    ID              int64
+    CustomerID      int64
+    Status          OrderStatus
+    Items           []OrderItem
+    ShippingAddress string
+    CreatedAt       time.Time
+    UpdatedAt       time.Time
+}
+
+// OrderItem represents a single line item within an order.
+type OrderItem struct {
+    ProductID  int64
+    Quantity   int
+    UnitPrice  float64
+}
+
+// TotalAmount calculates the total order value.
+func (o *Order) TotalAmount() float64 {
+    var total float64
+    for _, item := range o.Items {
+        total += float64(item.Quantity) * item.UnitPrice
+    }
+    return total
+}
+
+// Cancel transitions the order to CANCELLED status.
+func (o *Order) Cancel() error {
+    if o.Status == OrderStatusShipped {
+        return errors.New("cannot cancel an order that has already been shipped")
+    }
+    o.Status = OrderStatusCancelled
+    return nil
+}
+```
+
+## Repository Interface (defined in domain)
+
+```go
+// internal/domain/order_repository.go
+package domain
+
+import "context"
+
+// OrderRepository defines persistence operations for orders.
+// Implementations live in internal/repo/.
+type OrderRepository interface {
+    GetByID(ctx context.Context, id int64) (*Order, error)
+    GetByCustomerID(ctx context.Context, customerID int64) ([]*Order, error)
+    Create(ctx context.Context, order *Order) error
+    Update(ctx context.Context, order *Order) error
+}
+```
+
+## Use Case (business logic)
+
+```go
+// internal/usecase/order_usecase.go
+// @trace.implements=ORDER-UC1
+package usecase
+
+import (
+    "context"
+    "fmt"
+    "myapp/internal/domain"
+    "time"
+)
+
+// OrderUseCase handles all order-related business operations.
+type OrderUseCase struct {
+    repo domain.OrderRepository
+}
+
+// NewOrderUseCase creates a new OrderUseCase with required dependencies.
+func NewOrderUseCase(repo domain.OrderRepository) *OrderUseCase {
+    return &OrderUseCase{repo: repo}
+}
+
+// CreateOrderRequest holds input data for creating an order.
+type CreateOrderRequest struct {
+    CustomerID      int64
+    Items           []domain.OrderItem
+    ShippingAddress string
+}
+
+// CreateOrder creates a new order for a customer.
+// @trace.implements=ORDER-UC1-SC1
+func (uc *OrderUseCase) CreateOrder(ctx context.Context, req CreateOrderRequest) (*domain.Order, error) {
+    if len(req.Items) == 0 {
+        return nil, fmt.Errorf("order must contain at least one item")
+    }
+
+    order := &domain.Order{
+        CustomerID:      req.CustomerID,
+        Status:          domain.OrderStatusPending,
+        Items:           req.Items,
+        ShippingAddress: req.ShippingAddress,
+        CreatedAt:       time.Now(),
+    }
+
+    if err := uc.repo.Create(ctx, order); err != nil {
+        return nil, fmt.Errorf("create order: %w", err)
+    }
+    return order, nil
+}
+
+// GetOrder retrieves an order by ID.
+// @trace.implements=ORDER-UC1-SC2
+func (uc *OrderUseCase) GetOrder(ctx context.Context, id int64) (*domain.Order, error) {
+    order, err := uc.repo.GetByID(ctx, id)
+    if err != nil {
+        return nil, fmt.Errorf("get order %d: %w", id, err)
+    }
+    if order == nil {
+        return nil, domain.ErrNotFound
+    }
+    return order, nil
+}
+```
+
+## HTTP Handler (Gin)
+
+```go
+// internal/handler/order_handler.go
+// @trace.implements=ORDER-UC1
+package handler
+
+import (
+    "errors"
+    "net/http"
+    "strconv"
+
+    "github.com/gin-gonic/gin"
+    "myapp/internal/domain"
+    "myapp/internal/usecase"
+)
+
+// OrderHandler handles HTTP requests for order operations.
+type OrderHandler struct {
+    uc *usecase.OrderUseCase
+}
+
+// NewOrderHandler creates a new OrderHandler.
+func NewOrderHandler(uc *usecase.OrderUseCase) *OrderHandler {
+    return &OrderHandler{uc: uc}
+}
+
+// RegisterRoutes registers all order endpoints on the given router group.
+func (h *OrderHandler) RegisterRoutes(r *gin.RouterGroup) {
+    r.POST("/orders", h.CreateOrder)        // @trace.implements=ORDER-UC1-SC1
+    r.GET("/orders/:id", h.GetOrder)        // @trace.implements=ORDER-UC1-SC2
+}
+
+// CreateOrder handles POST /v1/orders.
+func (h *OrderHandler) CreateOrder(c *gin.Context) {
+    var req usecase.CreateOrderRequest
+    if err := c.ShouldBindJSON(&req); err != nil {
+        c.JSON(http.StatusBadRequest, gin.H{"error": err.Error()})
+        return
+    }
+    order, err := h.uc.CreateOrder(c.Request.Context(), req)
+    if err != nil {
+        c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()})
+        return
+    }
+    c.JSON(http.StatusCreated, order)
+}
+
+// GetOrder handles GET /v1/orders/:id.
+func (h *OrderHandler) GetOrder(c *gin.Context) {
+    id, err := strconv.ParseInt(c.Param("id"), 10, 64)
+    if err != nil {
+        c.JSON(http.StatusBadRequest, gin.H{"error": "invalid order id"})
+        return
+    }
+    order, err := h.uc.GetOrder(c.Request.Context(), id)
+    if errors.Is(err, domain.ErrNotFound) {
+        c.JSON(http.StatusNotFound, gin.H{"error": "order not found"})
+        return
+    }
+    if err != nil {
+        c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()})
+        return
+    }
+    c.JSON(http.StatusOK, order)
+}
+```
+
+## Table-Driven Test Pattern
+
+```go
+// internal/usecase/order_usecase_test.go
+// @trace.verifies=ORDER-UC1
+// @trace.test_type=unit
+package usecase_test
+
+import (
+    "context"
+    "testing"
+
+    "github.com/stretchr/testify/assert"
+    "github.com/stretchr/testify/mock"
+    "myapp/internal/domain"
+    "myapp/internal/usecase"
+)
+
+func TestOrderUseCase_CreateOrder(t *testing.T) {
+    tests := []struct {
+        name        string
+        request     usecase.CreateOrderRequest
+        setupMock   func(*MockOrderRepository)
+        expectError bool
+        expectOrder bool
+    }{
+        {
+            name: "valid order with items should create successfully",
+            request: usecase.CreateOrderRequest{
+                CustomerID:      1,
+                Items:           []domain.OrderItem{{ProductID: 10, Quantity: 2, UnitPrice: 99.9}},
+                ShippingAddress: "123 Main St",
+            },
+            setupMock: func(m *MockOrderRepository) {
+                m.On("Create", mock.Anything, mock.AnythingOfType("*domain.Order")).Return(nil)
+            },
+            expectError: false,
+            expectOrder: true,
+        },
+        {
+            name: "empty items should return validation error",
+            request: usecase.CreateOrderRequest{
+                CustomerID: 1,
+                Items:      []domain.OrderItem{},
+            },
+            setupMock:   func(m *MockOrderRepository) {},
+            expectError: true,
+            expectOrder: false,
+        },
+    }
+
+    for _, tt := range tests {
+        t.Run(tt.name, func(t *testing.T) {
+            mockRepo := new(MockOrderRepository)
+            tt.setupMock(mockRepo)
+            uc := usecase.NewOrderUseCase(mockRepo)
+
+            order, err := uc.CreateOrder(context.Background(), tt.request)
+
+            if tt.expectError {
+                assert.Error(t, err)
+                assert.Nil(t, order)
+            } else {
+                assert.NoError(t, err)
+                assert.NotNil(t, order)
+            }
+            mockRepo.AssertExpectations(t)
+        })
+    }
+}
+```

package/core/modules/golang/module.yaml

@@ -0,0 +1,6 @@
+name: "Go"
+version: "1.0.0"
+description: "Go with domain-driven layout"
+language: "Go"
+framework: "Standard library / Gin / Echo"
+stack_type: "backend"

package/core/modules/golang/stack-profile.yaml

@@ -0,0 +1,40 @@
+build:
+  compile: "go build ./..."
+  test: "go test ./..."
+  run: "go run ./cmd/{service-name}"
+
+architecture:
+  style: "Domain-driven layout"
+  directory_structure:
+    cmd/: "Main entry points, one per binary (e.g., cmd/api/main.go)"
+    internal/domain/: "Domain entities, interfaces, and business rules"
+    internal/repo/: "Repository implementations (DB, cache)"
+    internal/handler/: "HTTP handlers (Gin/Echo) — thin, delegate to use cases"
+    internal/usecase/: "Use case implementations (business logic)"
+    pkg/: "Reusable packages safe for external use"
+    config/: "Configuration loading (env vars, YAML)"
+  key_rules:
+    - "Define interfaces in the consumer package (dependency inversion)"
+    - "internal/ packages cannot be imported outside the module"
+    - "Handlers must not contain business logic — only parse, call use case, respond"
+    - "Use cases own business rules and call repository interfaces"
+    - "Repositories implement persistence — never call use cases"
+
+coding_standards:
+  naming:
+    packages: "lowercase single word (e.g., order, handler, repo)"
+    interfaces: "Describe behavior, no 'I' prefix (e.g., OrderRepository, not IOrderRepository)"
+    structs: "PascalCase for exported, camelCase for unexported"
+    methods: "PascalCase for exported, camelCase for unexported"
+  patterns:
+    error_handling: "Return error as last return value; use errors.Is/As; wrap with fmt.Errorf(\"...: %w\", err)"
+    interfaces: "Define small interfaces at point of use; prefer 1-2 method interfaces"
+    constructors: "NewXxx(deps...) *Xxx — always use constructor functions"
+
+testing:
+  framework: "Standard library testing package + testify"
+  patterns:
+    - "Table-driven tests for all cases"
+    - "Use testify/assert and testify/mock"
+    - "Test file: {file}_test.go in same package (white-box) or {pkg}_test package (black-box)"
+    - "Integration tests in internal/{pkg}/integration_test.go with build tag //go:build integration"

package/core/modules/ios-swiftui/module.yaml

@@ -0,0 +1,13 @@
+name: "iOS (SwiftUI)"
+version: "1.0.0"
+description: "Native iOS development with SwiftUI + Swift"
+language: "Swift"
+framework: "SwiftUI"
+stack_type: "mobile"
+default_layer_order:
+  - Models / entities
+  - Repository (data sources)
+  - UseCase (business operations)
+  - ViewModel (ObservableObject state)
+  - View (SwiftUI presentation)
+test_framework: "XCTest + Quick/Nimble"

package/core/modules/ios-swiftui/stack-profile.yaml

@@ -0,0 +1,55 @@
+build:
+  compile: "xcodebuild -scheme {AppName} -configuration Release"
+  test: "xcodebuild test -scheme {AppName}"
+  run: "Open in Xcode → Run (⌘R)"
+  lint: "swiftlint"
+
+architecture:
+  style: "MVVM + Clean Architecture (View → ViewModel → UseCase → Repository)"
+  key_rules:
+    - "Views are pure SwiftUI — no business logic, no direct API calls"
+    - "ViewModels are ObservableObject classes; bind via @StateObject / @ObservedObject"
+    - "UseCases encapsulate single business operations"
+    - "Repositories abstract data sources (network, cache, local DB)"
+    - "Dependency injection via environment or constructor injection"
+    - "Use Combine or async/await for async flows — never DispatchQueue in ViewModel"
+  folder_structure: |
+    Sources/
+    ├── Core/
+    │   ├── Network/      ← URLSession wrapper, interceptors
+    │   ├── Theme/        ← Color, Font, Spacing tokens
+    │   └── Utils/
+    ├── Shared/
+    │   └── Components/   ← reusable SwiftUI views (AppButton, AppTextField...)
+    ├── Features/
+    │   └── {Domain}/
+    │       ├── Views/
+    │       ├── ViewModels/
+    │       ├── UseCases/
+    │       └── Repository/
+
+coding_standards:
+  naming:
+    views: "PascalCase + View suffix (e.g., OrderListView, CreateOrderView)"
+    viewmodels: "PascalCase + ViewModel suffix (e.g., OrderListViewModel)"
+    usecases: "PascalCase + UseCase suffix (e.g., CreateOrderUseCase)"
+    files:
+      view: "{Feature}View.swift"
+      viewmodel: "{Feature}ViewModel.swift"
+      usecase: "{Feature}UseCase.swift"
+  patterns:
+    async: "async/await + Combine"
+    navigation: "NavigationStack (iOS 16+)"
+    persistence: "Core Data or SwiftData"
+    networking: "URLSession or Alamofire"
+
+testing:
+  unit: "XCTest + Quick/Nimble"
+  ui: "XCUITest"
+  patterns:
+    - "Test ViewModel by injecting mock repositories"
+    - "UI tests use accessibility identifiers — set .accessibilityIdentifier on Views"
+
+trace_tags:
+  implements: "// @trace.implements={UC-ID}-SC{N}"
+  source: "// @trace.source=specs/{domain}/{prd-slug}/bdd/{UC-ID}.feature"