Skill: Create a New Module

Skill: Create a New Module

Prerequisites

  • Module is defined in DOMAIN_MODEL.md (aggregates, events, value objects)
  • Module name is agreed upon

Steps

1. Create Directory Structure

src/Module/{ModuleName}/
├── Domain/Model/
├── Domain/Event/
├── Domain/Repository/
├── Domain/Exception/
├── Application/Command/
├── Application/Query/
├── Application/EventHandler/
├── Infrastructure/Persistence/mapping/
├── Infrastructure/Service/
├── Presentation/Controller/
├── Presentation/DTO/
├── Contract/
└── config/

2. Domain Layer

  • Create aggregate root(s) with invariants
  • Create value objects (IDs, typed fields)
  • Create domain events (JSON-serializable, versioned)
  • Create repository interface(s)
  • Create domain-specific exceptions

3. Application Layer

  • Create commands and command handlers
  • Create queries and query handlers
  • Create event handlers for external events (if consuming)

4. Infrastructure Layer

  • Implement repository using Doctrine
  • Create Doctrine ORM mapping (XML in mapping/ directory)
  • Create any external service adapters

5. Presentation Layer

  • Create API controller(s) — thin, delegates to handlers
  • Create request DTOs (input validation)
  • Create response DTOs (output shaping)
  • Add OpenAPI attributes for documentation

6. Contract Layer

  • If other modules need to read data from this module, create a provider interface
  • Keep contracts minimal — only expose what’s needed

7. Configuration

  • Add config/routes.yaml with API routes
  • Add config/services.yaml with service definitions
  • Import routes and services in the main config

8. Deptrac

  • Register the module in deptrac.yaml
  • Define allowed dependencies
  • Run make lint to verify boundaries

9. Documentation

  • Update .ai/context/MODULE_STATUS.md (set to 🚧 In Progress)
  • Add events to .ai/context/EVENT_CATALOG.md

10. Tests

  • Unit tests for aggregate (creation, transitions, invariants)
  • Unit tests for command handlers (mocked repos)
  • Integration tests for API endpoints
  • Update MODULE_STATUS.md to ✅ when complete

11. Migration

  • Create Doctrine migration for new tables
  • Ensure migration is reversible
  • Test on clean database