Anatomy of a pattern

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 set a scope type (folder, file_type or project) and a priority (high, medium, low). A rule that leaves them out is imported as a project rule at medium priority. An imported rule keeps both, so a high-priority folder rule from a pattern surfaces exactly like one you wrote yourself.
• Skill pieces carry a skill name and optional tags, and their one-line summary becomes the skill's description. On import the skill is also tagged pattern:<slug>, so you can find every skill a pattern brought in as a group. 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.

Rule pieces also carry an enforcement mode (advisory or strict), and the manual copy labels each rule with one. Import does not carry it: an imported rule arrives as an advisory rule that rides along as context, whatever the catalog labels it. Blocking an edit needs an executable constraint that a person has approved, the same as for any rule, as described in Rules as guardrails. That keeps blocking a decision a person on your team makes, not something a catalog switches on.

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 "4 Rules, 2 Memories, 1 Skill" line and the list of target paths on each catalog page and in the package README 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 1.0.1. It is shown on the catalog page and in the import preview. The import token does not carry it: ::pathrule:package:<slug> always means the version your client ships.
• updatedAt is the date of the last content change. It is the "Updated" date on the catalog page and the last-modified date in the sitemap.
• changelog is a list of human-readable entries, newest first, recording what changed between versions. Every pattern in the catalog carries one, readable in the open package.

Versioning matters because import is a one-time seed (see Importing a pattern). Your copy never changes underneath you, and Pathrule does not track which version you imported or notify you when a newer one is published. Compare the version and updated date on the catalog page with when you imported, and read the changelog to see what moved. Importing a pattern covers how to bring a newer version in.

Display metadata

Besides the pieces, a pattern carries what the catalog needs to present it: a name, a one-line tagline, a longer description, a category (one of Framework, Frontend, Backend, Billing, Infra, Workflow, AI and Security) and an icon. Every pattern in the catalog also explains itself with the problem it solves, the audience it is built for, and a list of the mistakes it keeps your assistant from making. The catalog page shows all three under "Why this pattern".

Matching metadata

A pattern can declare what kind of project it fits, under an appliesTo block: relevant paths, stack tags (for example nextjs, react) and dependency names. Every pattern in the catalog declares one. The web catalog uses the stack tags for search. The import preview hands the same block to your assistant, which compares it with your project's tree and stack before writing anything and asks you to confirm when the pattern does not appear to fit.

The open package

The catalog is backed by a single open package, @pathrule/patterns, published on npm 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 catalog, the import tooling and the markdown views all render the same content. The Pathrule MCP server carries its own copy of the package, which is why a newly published pattern becomes importable once the release of Pathrule you run includes it.

What to read next

• Importing a pattern shows how a bundle gets written into your workspace and how to remove it.
• Patterns overview is the higher-level picture if you skipped it.
• Writing rules and Writing skills cover the piece types in depth.