SkillAgentSearch skills...

nw-fp-domain-modeling

Domain modeling with algebraic data types, smart constructors, and type-level error handling

Install / Use

npx skills add nWave-ai/nWave --skill nw-fp-domain-modeling

Installs into whichever agent you are using.

About this skill
📄

SKILL.md

Installable skill definition

Quality Score

87/100

Category

Automation

Supported Platforms

Universal

Our assessment of nw-fp-domain-modeling

nw-fp-domain-modeling scores 87/100 on our quality scale, 1711th of 2,769 Automation skills we index.

Its SKILL.md is 9.2 KB long, well organised into 24 sections with 7 code examples: a thorough specification that gives an agent plenty to work with.

It has 617 GitHub stars, a meaningful sign that others use it.

Substance
29/30
Structure
20/20
Description
12/15
Adoption
12/20
Freshness
15/15

Maintenance, license and trust

  • The repository was last updated about 2 months ago, so nw-fp-domain-modeling is actively maintained.
  • Our last check on 2026-10-11 found the source still online.
  • It is released under the MIT license, a permissive license that allows use, modification and commercial use with attribution.
  • Its trust signals score 100/100, with no cautions. These come from repository metadata, not a code audit — read the skill file before letting an agent act on it.

Safety scan

No issues found

Our scan of the whole file found no instruction hijacking, hidden characters, credential access, data exfiltration or destructive commands. An AI review of the same text found nothing harmful.

AI review by kimi-k2.7-code on 2026-10-08. Automated pattern scan on 2026-10-08. It catches known dangerous patterns, not every risk — read a skill before letting an agent act on it.

nw-fp-domain-modeling compared with similar skills

All 4 of these similar skills score higher than nw-fp-domain-modeling; compare them before choosing.

SkillScoreStarsUpdatedFormat
nw-fp-domain-modeling (this skill)by nWave-ai876172mo agoSKILL.md
taste-skillby Leonxlnx100117.6k9d agoCLAUDE.md
Agent-Reachby Panniantong100112.7k9d agoCLAUDE.md
rufloby ruvnet10082.0ktodayCLAUDE.md
Claude-Code-Game-Studiosby Donchitos10039.9k8d agoCLAUDE.md

Frequently asked questions

How do I install nw-fp-domain-modeling?
Run npx skills add nWave-ai/nWave --skill nw-fp-domain-modeling. The install tabs above show the steps for each supported agent.
Which AI agents does nw-fp-domain-modeling work with?
It is written for Universal, as a SKILL.md file. Other agents that read the same format can often use it too.
Is nw-fp-domain-modeling safe to use?
Our scan of the whole file found no instruction hijacking, hidden characters, credential access, data exfiltration or destructive commands. An AI review of the same text found nothing harmful. It is MIT-licensed and scores 100/100 on trust signals. Skills are instructions an agent will follow, so read the file before installing it and do not approve commands you do not understand.
Is nw-fp-domain-modeling still maintained?
The repository was last updated about 2 months ago, so nw-fp-domain-modeling is actively maintained.

name: nw-fp-domain-modeling agent: nw-functional-software-crafter description: Domain modeling with algebraic data types, smart constructors, and type-level error handling user-invocable: false disable-model-invocation: true

FP Domain Modeling

Domain modeling with types. Make illegal states unrepresentable, workflows as pipelines, error handling at the type level.

Cross-references: fp-principles | fp-hexagonal-architecture | fp-algebra-driven-design


1. The Two Building Blocks

[STARTER]

All domain types compose from two operations:

  • AND (Record Types): Value has ALL of these fields. Order requires CustomerInfo AND ShippingAddress AND OrderLines.
  • OR (Choice Types): Value is ONE OF these alternatives. ProductCode is either WidgetCode OR GizmoCode.

Combined recursively, these express virtually any domain structure.


2. Domain Wrappers for Primitives

[STARTER]

Never use primitives directly in the domain model. Each domain concept gets its own wrapper type.

What: Wrap primitives so the compiler distinguishes CustomerId from OrderId. When: Every primitive with domain meaning. Why: Prevents accidental mixing (compiler rejects comparing CustomerId with OrderId). Each wrapper carries its own validation rules. The type name IS the documentation.


3. Validated Construction (Smart Constructors)

[STARTER]

Raw constructor is private. A create function validates input and returns a Result type, making validation failure explicit.

Pattern: UnitQuantity must be between 1 and 1000. Its create function rejects values outside that range. A companion value function provides read access to the inner primitive.

When: Every domain wrapper with validation rules. Why: Once constructed, a value is guaranteed valid. No defensive checks deeper in the code.


4. Making Illegal States Unrepresentable

[STARTER]

The central design guideline. Instead of flags and runtime checks, model the domain so invalid states cannot be constructed.

Replace Flags with Distinct Types

Instead of { EmailAddress; IsVerified: bool }, create separate VerifiedEmailAddress and UnverifiedEmailAddress types. Functions requiring verification take VerifiedEmailAddress, making misuse a compile error.

Replace Optional Fields with Choice Types

Instead of { Email: option; Address: option } (where both could be None), create: EmailOnly | AddressOnly | EmailAndAddress. The "at least one required" rule becomes structurally enforced.

NonEmptyList for "At Least One" Rules

Define a type guaranteeing at least one element. Order with OrderLines: NonEmptyList<OrderLine> cannot have zero lines.


5. Workflows as Functions

[STARTER]

Every business workflow is a single function: Command in, Events out.

PlaceOrderWorkflow : PlaceOrderCommand -> AsyncResult<PlaceOrderEvent list>

Pipeline Composition

Workflows decompose into steps, each transforming one document type into the next:

UnvalidatedOrder -> ValidatedOrder -> PricedOrder -> Events

Each step is stateless, pure, has single input/output type, and is independently testable. The workflow assembles by piping steps together.

Why: Pipeline makes the business process visible. Each step name is a domain concept.


6. Document Lifecycle as State Types

[INTERMEDIATE]

Rather than one Order type with flags, create separate types for each lifecycle stage:

  • UnvalidatedOrder (raw input, all fields strings)
  • ValidatedOrder (all fields checked)
  • PricedOrder (prices calculated)

A top-level Order choice type unifies all states. New states (e.g., Refunded) added without breaking existing code.

When: Domain entities with distinct lifecycle stages where different data is available at each stage.


7. State Machines with Types

[INTERMEDIATE]

When an entity has distinct states with different data and different allowed operations, model each state as a separate type.

ShoppingCart = EmptyCart | ActiveCart of ActiveCartData | PaidCart of PaidCartData

Transition functions take the choice type, pattern-match on current state, return new state.

Benefits: All states explicit | each state has own data | invalid transitions prevented by types | pattern matching warnings reveal unhandled edge cases.


8. Error-Track Pipelines (Railway Pattern)

[INTERMEDIATE]

Each function returns a Result type. Pipeline short-circuits on first failure.

rawInput
  |> validateOrder           -- Result<ValidOrder, Error>
  |> bind calculateTotal     -- Result<PricedOrder, Error>
  |> bind checkInventory     -- Result<ConfirmedOrder, Error>
  |> bind chargePayment      -- Result<PaidOrder, Error>
  |> map generateReceipt     -- Result<Receipt, Error>

Key combinators:

  • map: Transform success value (one-track into two-track)
  • bind: Chain a function that itself returns Result
  • mapError: Transform error value
  • tee: Perform side effect without changing value (logging)

Error Classification

| Category | Examples | Strategy | |---|---|---| | Domain Errors | Validation failure, out of stock | Model as types, return via Result | | Panics | Out of memory, null reference | Throw exceptions, catch at top level | | Infrastructure Errors | Network timeout, auth failure | Case-by-case |

Unifying Error Types

Each step may have its own error type. Define a common error choice type and use mapError to lift step errors before composing.

Collecting All Errors (Applicative Validation)

[ADVANCED]

Standard bind short-circuits on first error. For validation where you want ALL errors, use Applicative style -- runs all validations and accumulates errors into a list. See fp-principles section 5.

When: Form validation | batch input checking | any place user needs all errors at once.


9. Modeling Dependencies

[INTERMEDIATE]

Each workflow step declares exactly the functions it needs as parameters:

CheckProductCodeExists : ProductCode -> bool
GetProductPrice        : ProductCode -> Price

Convention: Dependencies first in parameter list, primary input last. Enables partial application (functional DI).

Public vs. internal: Top-level workflow hides dependencies from callers. Internal steps make them explicit.

See fp-hexagonal-architecture section 5 for full DI decision tree.


10. Persistence Ignorance

[INTERMEDIATE]

Domain model has no awareness of databases. Two distinct type hierarchies:

  • Domain types: Rich, nested, use choice types, validated wrappers. Not serialization-friendly.
  • DTO types: Flat, primitives, nullable, arrays. Designed for serialization.

Conversion Pattern

  • fromDomain: Domain -> DTO. Always succeeds.
  • toDomain: DTO -> Result<Domain, Error>. May fail (validation happens here).

Serialization as Pipeline Steps

JSON -> deserialize -> DTO -> toDomain -> [WORKFLOW] -> fromDomain -> DTO -> serialize -> JSON

Domain workflow never sees JSON or DTOs directly.


11. Bounded Contexts

[ADVANCED]

Each context has its own dialect of domain language. Contexts communicate only through events and DTOs. Design for autonomy.

Trust boundaries: Input gate validates and converts incoming DTOs to domain types. Output gate converts domain types to DTOs, deliberately dropping private information.

Inter-context relationships: Shared Kernel (shared design) | Customer/Supplier (downstream defines contract) | Anti-Corruption Layer (translator preventing external model from corrupting internal domain).


Decision Tree: How to Model This Domain Concept?

Is it a simple value with validation rules?
  YES --> Domain Wrapper + Smart Constructor
  NO -->
    Does it represent one of several alternatives?
      YES --> Choice Type (sum type)
      NO -->
        Does it group several values together?
          YES --> Record Type (product type)
          NO -->
            Does it have distinct lifecycle stages?
              YES --> State Machine with Types (section 7)
              NO -->
                Is it an operation that transforms data through stages?
                  YES --> Workflow Pipeline (section 5)
                  NO --> Evaluate whether it needs modeling at all

12. Key Design Heuristics

  1. Start from events and workflows, not data structures
  2. Let the domain expert drive naming -- their vocabulary, not technical jargon
  3. Use types to enforce business rules at compile time -- every rule in the type system needs no unit test
  4. Document effects in signatures -- Result for errors | Async for I/O | Option for missing data
  5. Separate domain types from serialization types -- domain is pure; serialization is infrastructure
  6. Prefer explicit over implicit -- every input and dependency is a function parameter

Naming Patterns

  • Types as nouns: Order | ProductCode | CustomerInfo
  • Workflows as verbs: ValidateOrder | PriceOrder | PlaceOrder
  • Events in past tense: OrderPlaced | OrderShipped
  • Commands in imperative: PlaceOrder | ShipOrder | CancelOrder
  • Lifecycle prefixes: UnvalidatedOrder | ValidatedOrder | PricedOrder

Related Skills

View on GitHub
GitHub Stars617
CategoryAutomation
Updated2mo ago
Forks63

Languages

Python

Trust signals

100/100

From repository metadata: license, adoption, age and documentation. Not a code audit — see the Safety scan above for what the skill file itself contains.

No cautions
nw-fp-domain-modeling — Universal Skill: Install & Safety Check | SkillAgent