Manifest

Complete example

name: vertical-slice-use-case
title: Organize Backend Features by Use Case
version: 0.2.0
description: Keep each backend request, job, or message with its validation, handler, dependencies, and tests.
scope: shareable

category: code-organization
targets: [backend-operation, backend-service]
languages: [typescript]
frameworks: []
runtimes: [node]
tags: [vertical-slice, use-case-first, operation-folders]
aliases:
  - vertical slice architecture
  - use-case folders

# Free-form technology list. Prefer the typed facets above.
stack: [typescript, node]

related:
  - pattern: modular-monolith
    relationship: composes-with
    why: Use-case slices can organize operations inside one capability module.

structure:
  - path: structure/operation-anatomy.md
    is: The validation, handler, ports, adapters, and tests owned by one operation.
rules:
  - path: rules/dependency-direction.md
    enforces: Handler policy does not import transports or concrete adapters.
recipes:
  - path: recipes/add-operation.md
    when: A request, job, or message needs an independently changeable outcome.
adrs:
  - path: adrs/0001-organize-by-operation.md
    decides: The primary unit of organization is one observable use-case outcome.
boundaries:
  - from: "**/operations/*/handler.ts"
    to: "**/operations/*/transport.ts"
    why: Application policy remains independent from delivery.

Required fields

There is a single flat schema, and only three fields are required:

• name is the immutable machine ID and one safe path segment. In the public directory it is also globally unique: one name identifies one pattern, and publishing a name another indexed ref already claims is rejected.
• version is the semantic version of the bundle's guidance.
• description is a plain-language value statement, not a restatement of the title.

Everything else is optional. No field selects a manifest contract; a residual schemaVersion key left over in an older manifest is tolerated and ignored.

Identity and presentation

• title is the human label used by GitHub READMEs, the directory, CLI output, and agent routers. Without one, clients fall back to the machine ID.
• scope is internal or shareable and defaults to internal. Public publishing rejects internal bundles unless explicitly forced.

Discovery facets

• category describes the kind of decision, such as code-organization, system-architecture, contracts, or persistence. Patterns without a category are browsable as uncategorized.
• targets describes where it applies. backend-application and frontend-application are the canonical app-level pair (the seed catalog uses them), and granular scopes are allowed alongside the deploy target — for example backend-operation or persistence-layer next to backend-application — when the guidance is narrower than the whole deployable.
• languages, frameworks, and runtimes are separate so the index never guesses what a mixed stack token means.
• runtimes uses a canonical vocabulary: node, browser, edge, deno, and react-native. An empty list means runtime-agnostic. Avoid ambiguous execution models such as worker and device classes such as mobile; they fragment filtering without naming a real runtime.
• tags are normalized technical search terms.
• aliases are human phrases and canonical names used for search. Do not claim that a merely related architecture is an alias.
• related explains composition, complement, specialization, or alternatives with another stable pattern ID. See Related patterns.

Facet tokens are normalized to kebab-case when indexed — Next.js becomes next-js, C# becomes c-sharp — so cosmetic spelling differences do not fragment search.

An empty facet array and an absent facet field mean the same thing: the pattern is unclassified on that axis. Declare a value only when the guidance genuinely depends on it.

stack is a free-form technology list. Prefer the typed facets, which search can filter precisely.

Related patterns

Each related entry names another stable pattern ID, one of four relationships, and a why that justifies the link:

• composes-with — containment: one pattern organizes code inside the other's boundary. In the seed catalog, vertical-slice-use-case composes with modular-monolith: slices organize operations inside one capability module.
• complements — the patterns work well together without containment. In the seed catalog, frontend-feature-modules complements vertical-slice-use-case: both organize by outcome, one in a React UI and one in backend operations.
• specializes — this pattern is a concrete case of a more general one. In the seed catalog, swappable-repository-adapters specializes typescript-hexagonal-service by applying the port-and-adapter boundary specifically to persistence.
• alternative-to — both solve the same problem; adopt one. Declare it when choosing one pattern makes the other redundant for that decision.

specializes has no inverse in this vocabulary: the general pattern declares its specialization as complements.

Guide index

The four guide arrays are the progressive-disclosure router. Each path is relative to the bundle root and each summary should tell an agent why to open that document.

Boundaries

boundaries are forbidden import rules expressed as from → to globs plus a reason. patterns check can enforce only relationships represented by the repository's resolved local import graph. Do not describe a prose rule as machine-enforced unless the declared glob actually covers it.