atelier-spec-architect_skill

Overview

This skill guides feature design using Domain-Driven Design and hexagonal architecture with a functional core pattern. It prescribes a clear separation: a pure, testable functional core for business rules and an effectful edge for IO and integration. Use it to drive spec-first implementations, keep business logic deterministic, and make components easy to test and reason about.

How this skill works

The skill defines responsibility boundaries: Entities and Services live in a pure functional core; Routers, Repositories, Clients, Producers and Consumers form the effectful edge. The core exposes interfaces that the edge implements (dependency inversion). Tasks are ordered bottom-up—implement entities, then repositories, then services, then routers—so each layer has concrete inputs to work against.

When to use it

• Designing new features that require clear business-rule encapsulation
• Modeling domain objects, validations, and invariants
• Breaking a feature into testable implementation tasks
• Defining where to stub vs run real integrations in tests
• Refactoring code to isolate side effects from logic

Best practices

• Keep all business logic and validation in pure Entities and Services—no IO or framework code
• Define repository and client interfaces in the core, implement them in the edge
• Write unit tests for core functions and integration tests for edge implementations
• Follow bottom-up task ordering: Entity → Repository (interface) → Service → Router
• Return explicit success/error results from services instead of throwing side-effectful exceptions

Example use cases

• Designing an Order feature: Order entity, InventoryRepository interface, OrderService orchestration, HTTP order routes
• Adding a payment flow: pure Payment rules in core and a payment client implementation in the edge
• Creating event-driven features: domain events in core, event consumer/producer implementations in the edge
• Refining a legacy module by extracting pure validation and business rules into the functional core
• Planning tests: property and unit tests for entities; stub-driven service tests; integration tests for repositories and external clients