SkillAgentSearch skills...

nw-code-design-fp

FP code-design SSOT — the WHAT-to-design catalog (algebra-driven design, domain modelling with types, railway/error-track isolation) shared by the solution architect (design-time) and the functional crafter (execution-time).

Install / Use

npx skills add nWave-ai/nWave --skill nw-code-design-fp

Installs into whichever agent you are using.

About this skill
📄

SKILL.md

Installable skill definition

Quality Score

90/100

Category

Marketing

Supported Platforms

Universal

Our assessment of nw-code-design-fp

nw-code-design-fp scores 90/100 on our quality scale, 264th of 642 Marketing skills we index (top 42%).

Its SKILL.md is 13 KB long, well organised into 20 sections with 3 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
30/30
Structure
18/20
Description
15/15
Adoption
12/20
Freshness
15/15

Maintenance, license and trust

  • The repository was last updated about 2 months ago, so nw-code-design-fp is actively maintained.
  • 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-11-10. Automated pattern scan on 2026-11-10. It catches known dangerous patterns, not every risk — read a skill before letting an agent act on it.

nw-code-design-fp compared with similar skills

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

SkillScoreStarsUpdatedFormat
nw-code-design-fp (this skill)by nWave-ai906172mo agoSKILL.md
taste-skillby Leonxlnx100116.8k8d agoCLAUDE.md
Claude-Code-Game-Studiosby Donchitos10039.7k7d agoCLAUDE.md
x402by browser-use100121.0k3d agoSKILL.md
algorithmic-artby anthropics100177.9k55d agoSKILL.md

Frequently asked questions

How do I install nw-code-design-fp?
Run npx skills add nWave-ai/nWave --skill nw-code-design-fp. The install tabs above show the steps for each supported agent.
Which AI agents does nw-code-design-fp 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-code-design-fp 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-code-design-fp still maintained?
The repository was last updated about 2 months ago, so nw-code-design-fp is actively maintained.

name: nw-code-design-fp description: FP code-design SSOT — the WHAT-to-design catalog (algebra-driven design, domain modelling with types, railway/error-track isolation) shared by the solution architect (design-time) and the functional crafter (execution-time).

FP Code Design

Design-time catalog for functional work. The architect loads this to design the domain algebra, the type-level model, and the error/effect tracks BEFORE DISTILL authors ATs; the functional crafter loads the same SSOT for execution. This is the WHAT-to-design subset — execution mechanics (naive/discover/freeze testing, ORM/persistence mapping, language idioms) stay in nw-fp-algebra-driven-design, nw-fp-domain-modeling, and the language skills below.

FP language skills — resolve by target language, never by default

| Language skill | Languages | PBT sibling (when one exists) | |---|---|---| | nw-fp-clojure | Clojure | — | | nw-fp-erlang-elixir | Erlang, Elixir | nw-pbt-erlang-elixir | | nw-fp-fsharp | F# | nw-pbt-dotnet | | nw-fp-haskell | Haskell | nw-pbt-haskell | | nw-fp-kotlin | Kotlin | nw-pbt-jvm | | nw-fp-rust | Rust | nw-pbt-rust | | nw-fp-scala | Scala | nw-pbt-jvm | | nw-fp-typescript | TypeScript, JavaScript | nw-pbt-typescript |

Same shape as the Polyglot Adapter Matrix nw-test-design-mandates-layered-mechanics already uses for PBT bindings — one row per target language, resolved from the contract's own target evidence, never guessed. A language NOT in this table has no dedicated FP-idiom skill: load this catalog and nw-fp-domain-modeling alone (both are language-agnostic) rather than silently substituting a listed language's skill — the wrong language's idioms are worse than none.

Functional Core

Inside domain and application code:

  • Pure core, effects at the edge — domain functions take values and return values; I/O, time, randomness and persistence stay in a thin shell that calls the core. No mutation and no shared state in the core.
  • Total functions — every domain outcome is a case of the return type (see Railway, rule 5); no exception or null for a domain outcome.
  • Composition — small single-purpose functions composed through pipelines and the railway; dependencies as leading parameters (see Dependencies).
  • Laws — when the design declares an algebra, preserve each law; use nw-fp-algebra-driven-design to implement it, never to invent a new one.

Refactoring order within each delta, verified once with it — first readability (names, dead code, magic values), then complexity and duplication, then move each decision into the type or function that owns its data, then replace primitives and flags with domain types and choice types, then replace conditionals on data with pattern matching over a sum type, then extract the effects to the shell. Behaviour and declared laws stay unchanged.

Algebra-Driven Design

Discover the API before implementing by specifying the rules (equations) operations must satisfy. Rules generate property tests, reveal missing features, and catch contradictions at design time (minutes) not production (days).

Design process (5 steps)

  1. Start with scope, not implementation — do not fix data structures upfront.
  2. Define observations first — how users extract information; observations define equality (two values equal if no observation distinguishes them).
  3. Add operations incrementally — for each, write rules connecting it to existing ones. The web of rules IS the design.
  4. Let messy rules signal problems — complex rules mean coarse building blocks; decompose until each rule is near-trivial.
  5. Generalize aggressively — remove unnecessary type constraints; if operations ignore contained values, parameterize over them.

Algebraic structures (recognize → reuse known rules)

| Structure | Defining rule | Design signal / use | |-----------|---------------|---------------------| | Semigroup | (a·b)·c = a·(b·c) (associative) | Combining where parenthesization is irrelevant (concat, min/max, config merge) | | Monoid | Associative + identity e·x = x = x·e | Safe defaults, fold/reduce over collections ((+,0), (concat,[])) | | Semilattice | Associative + commutative + idempotent | Conflict resolution, CRDTs, eventually-consistent merges (max) | | Functor | Preserves identity + composition under map | Operations agnostic to the contained type | | Applicative | Element-wise combine + uniform fill | Combining containers of differing content | | Group | Monoid + inverse x·x⁻¹ = e | Undo, reversible spatial transforms |

Heuristic: associative? look for an identity → monoid. Have identity? check commutativity/inverse → semilattice/group. Each upgrade unlocks new rules.

API design properties (8, three categories)

| Category | Properties | |----------|-----------| | Clarity | Compositional · Task-relevant · Interrelated (rules link every operation) | | Economy | Parsimonious · Orthogonal · Generalized (no needless type constraints) | | Safety | Closed (valid construction ⇒ valid semantics) · Complete (max structure discovered) |

Decision tree — is algebraic thinking worth it?

  • Domain about COMBINING → rules (order/defaults/inverses) map to a known structure.
  • Domain about TRANSFORMING → look for Functor / structure-preserving patterns.
  • Small, well-understood surface → conventional design (algebra adds overhead).
  • Otherwise → rules still clarify, even without standard structures.

Domain Modelling with Types

Make illegal states unrepresentable; model workflows as pipelines; push errors to the type level. Every rule encoded in a type needs no unit test.

Building blocks and wrappers

  1. AND (record types) — value has ALL fields (Order = CustomerInfo AND Address AND OrderLines).
  2. OR (choice types) — value is ONE OF alternatives (ProductCode = Widget OR Gizmo). Compose recursively to express any domain structure.
  3. Domain precision — a domain concept gets its own type (record, choice type, opaque or newtype-style wrapper), never a raw primitive, string or bare collection inside the core. Prefer zero-cost native forms where the language offers them; raw primitives belong only at the adapters.
  4. Smart constructors — parse, don't validate — raw input becomes a domain type once, at the boundary, through a constructor that returns a result; the core never re-checks it. Reuse the existing owner of an invariant; a native representation that already makes the invalid state unconstructible needs no extra wrapper.

Make illegal states unrepresentable

| Smell | Fix | |-------|-----| | { Email; IsVerified: bool } flag | Distinct VerifiedEmail / UnverifiedEmail types; verification-requiring functions take VerifiedEmail | | { Email: option; Address: option } (both could be None) | Choice type EmailOnly \| AddressOnly \| EmailAndAddress — "at least one" enforced structurally | | List that must be non-empty | NonEmptyList<T> — zero-element state cannot be constructed |

Workflow as pipeline

Every workflow is one function: command in, events out. Decompose into stateless, pure, single-input/output steps, each transforming one document type to the next:

UnvalidatedOrder → ValidatedOrder → PricedOrder → Events

Each step name is a domain concept; each step is independently testable.

State machine with types

Model each lifecycle stage / state as a separate type; a top-level choice type unifies them (Cart = Empty | Active of ActiveData | Paid of PaidData). Transition functions pattern-match the current state and return the next. Benefits: all states explicit, per-state data, invalid transitions rejected by types, exhaustiveness warnings reveal unhandled cases. New states (e.g. Refunded) add without breaking existing code.

Dependencies and naming

  • Declare each step's dependencies as leading parameters, primary input last (enables partial application = functional DI). Top-level workflow hides dependencies; internal steps make them explicit.
  • Types as nouns · workflows as verbs · events past-tense · commands imperative · lifecycle prefixes (Unvalidated…/Validated…/Priced…).

Decision tree — how to model a concept?

Simple value with a domain meaning?   → Its own type; smart constructor at the boundary
One of several alternatives?         → Choice Type (sum)
Groups several values?               → Record Type (product)
Distinct lifecycle stages?           → State Machine with Types
Transforms data through stages?      → Workflow Pipeline

Railway

Each step returns a Result; the pipeline runs on two tracks (success/failure) and short-circuits on the first failure. Design the error track up front.

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

Combinators

| Combinator | Role | |------------|------| | map | Transform the success value (one-track → two-track) | | bind | Chain a function that itself returns Result | | mapError | Transform the error value (lift a step error into the common type) | | tee | Side effect without changing the value (logging) |

Error classification (design decision per category)

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

Design rules

  1. Unify error types — define one common error choice type; mapError to lift each step's error before composing.

  2. Accumulate when the user needs all errors — use Applicative validation (runs all checks, collects errors into a list) for forms / batch input; standard bind short-circuits on the first.

  3. Document effects in signatures — Result for errors, Async for I/O, Option for missing data; the signature is the contract.

  4. Declared inputs — what does this function READ that nobody passed it?

    The FP reading of contract:declared-inputs-not-ambient-reads (SSOT: nw-cross-cutting-invariants — the gate list and the anchor live there).

    For every gate that clause lists, decide in the signature: a parameter, a reader environment, an injected capability — with the ambient lookup kept as a default the caller may state.

    A function whose result depends on state absent from its arguments is not pure, whatever its body looks like, and no amount of Result in the return type recovers that. It also cannot be property-tested honestly: the generator cannot reach the cases the ambient state is silently fixing, so the suite looks thorough while the interesting partition is unreachable.

    Test-side mirror: the Algebraic Analysis Before the Scenario mandate (nw-test-design-mandates), its declared-inputs question.

  5. Count the outcomes before you choose the return type.

    How many outcomes does this operation have — and does its signature carry every one of them? Answering "it returns the value and raises on the bad case" is the wrong answer: that is N-1 outcomes in the type and one in the control flow. If any outcome is not in the return type, put it there — a sum type with one case per outcome, illegal combinations unconstructible.

    Raising is a control-transfer effect, so an operation that raises is not total. Two costs, and the second is the one that bites in a polyglot host:

    • Composition. A raising step cannot be bind-ed. Every caller needs an imperative wrapper and the railway degrades to one track with hidden exits.
    • Identity. except/

Truncated for display — read the full file on GitHub.

Related Skills

View on GitHub
GitHub Stars617
CategoryMarketing
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