Patterns

Anatomy of a pattern

The content model behind a pattern, how each piece is typed and pre-scoped, and how versioning and the open package keep the catalog honest.

Ask ChatGPT Ask Claude View as Markdown

A pattern is deliberately simple. It is a small bundle of typed pieces plus the metadata needed to display it, version it and match it to a project. Understanding the shape makes it obvious what you are getting when you import one.

A pattern is a bundle of pieces

Every pattern carries a list of pieces. Each piece is exactly one memory, one rule or one skill, and it knows where it should land.

A piece declares:

kind: memory, rule or skill. This decides which content type it becomes on import.
nodePath: the workspace-relative path it belongs to, for example /app, /services/billing, or / for the root. This is the scope the piece is delivered with.
title: the memory title, rule name or skill name.
summary: a one-line description shown in the bundle list, separate from the body.
body: the full markdown content. This is exactly what gets written into your workspace, with no transformation.

Because each piece names its own path, a pattern is path-scoped by construction. The bundle is not a single document that has to be filed somewhere; it is a set of pieces that already know where they go.

Type-specific metadata

Some pieces carry extra fields that match their content type, and these survive import intact.

Rule pieces can set a scope type (folder, file_type or project), a priority (high, medium, low) and an enforcement mode (advisory or strict). An imported rule keeps all three, so a strict, high-priority rule from a pattern behaves like one you wrote yourself, including being enforced at the hook.
Skill pieces carry a skill name and optional tags. After import the skill is discoverable and invocable by name, the same as any other workspace skill.
Memory pieces need no extra metadata; the body and path are enough.

For the underlying meaning of scope, priority and enforcement, see Core concepts.

Counts and paths are derived

A pattern never hand-maintains its own summary. The "12 rules, 7 memories, 4 skills" line and the list of target paths on each catalog page are computed from the pieces. That means the displayed contents can never drift from what the bundle actually contains. Add a rule to a pattern and its count updates on its own.

Versioning and freshness

Each pattern is versioned and dated so you can tell what you are adopting and when it last changed:

version is a display version like v1, also used in the import token.
updatedAt is the date of the last content change. It drives the freshness signal on the catalog and the last-modified date in the sitemap.
changelog is an optional list of human-readable entries, newest first, recording what changed between versions.

Versioning matters because import is a one-time seed (see Importing a pattern). When a pattern publishes a newer version, that surfaces as an explicit "new version available" prompt rather than a silent overwrite of content you may have already edited.

Matching metadata

A pattern can optionally declare what kind of project it fits, under an appliesTo block: relevant paths, stack tags (for example nextjs, react) and dependency names. The web catalog uses this for display and search. The same metadata is what lets the import flow check whether a pattern's stack matches your project before writing anything, and ask you to confirm when it does not.

The open package

The catalog is backed by a single open package, @pathrule/patterns, published under Apache-2.0. The package is pure and serializable: it carries the pattern definitions, their types and a few helper functions, with no dependency on any UI or cloud code. That keeps it readable as plain data and lets every surface consume the exact same bundles.

Adding a pattern is one new entry registered in that package. Because the package is the single source of truth, the website, the import tooling and the markdown views all render the same content.