patterns

A CLI and registry for distributable architecture patterns — bundles that encode a project's folder structure and the architecture that lives in it, so humans and coding agents stop re-deciding (and re-guessing) how to organize code on every project and every session.

The CLI is LLM-free and deterministic; your coding agent supplies the intelligence.

Install

The CLI runs on Node.js 20 or newer and is published as @mimrai/patterns:

npm install --global @mimrai/patterns
patterns --version

For a one-off command, use npx @mimrai/patterns --help. Pattern bundles themselves remain Git-native: the catalog discovers them, while patterns add installs directly from a Git ref.

Use

patterns <command>                 # e.g. patterns scan .
patterns <command> --help          # a command's options and defaults

Develop

bun bin/patterns.ts <command>      # run from a clone without linking
bun run check                      # lint, format, types, tests, Node/package smoke

Commands

init <name>        scaffold a new empty pattern bundle
add <ref>          fetch a pattern from a git ref and install it (descriptive only)
list               list patterns installed in this project
remove <name>      uninstall a pattern
check [path]       verify the repo's imports respect installed patterns' boundaries
sync [dir]         install the consume skill + wire the agent files to follow patterns
validate [path]    check patterns.yaml + that the rich index matches real files
scan [path]        emit a structure-map (findings JSON) of a codebase
detect [path]      emit architectural incongruities (reflexion diff JSON)
emit [dir]         write a bundle from a manifest JSON on stdin
find [query]       browse or search the patterns.directory catalog
inspect <selector> inspect a catalog entry, Git ref, or local bundle before install
update [name]      refresh installed pattern(s)
publish [ref]      register a pattern in the patterns.directory index (auth)

Run patterns <command> --help for a command's options and defaults.

Pattern identity and discovery metadata

patterns.yaml keeps the install identity separate from the name people see:

name: vertical-slice-use-case        # immutable ID: namespace, relations, .patterns/<name>
title: Backend Features Organized by Use Case
version: 0.2.0
description: Keep each backend operation together as one independently changeable feature.
scope: shareable
category: backend
targets: [api, worker]
languages: [typescript]
frameworks: []
runtimes: [node]
tags: [vertical-slice, use-case]
aliases: [vertical slice architecture]
related: []
isolations:
  - within: apps/*/src/**
    why: Applications communicate through published contracts.
stack: [typescript, node]            # free-form technology list

name is a stable machine identifier and must not be renamed after publication; title is the human-readable label shown by the CLI and registry. The manifest is a single flat schema: only name, version, and description are required, and every discovery field is optional. An empty array and an absent field mean the same thing — unclassified on that axis. Facet values are normalized to kebab-case.

The separate ref (owner/repo[/subdir][#revision]) is the Git address. boundaries forbid a declared from → to dependency; isolations capture one sibling identity with a segment-level * and forbid imports between different captures.

patterns init creates an honest, classified bundle. On a terminal it asks for missing classification; in automation, pass --description, --category, and each axis explicitly (--framework none means framework-independent).

Discover before installing

patterns find backend --language typescript --runtime node
patterns inspect vertical-slice-use-case
patterns inspect owner/repo/subdir#commit --json

find preserves server relevance and supports category, target, language, framework, and runtime filters. inspect resolves catalog entries at their indexed commit and prints the complete manifest, relationships, guide index, boundaries, isolations, and a pinned install command.

Safety model

Bundles, Git repositories, catalog responses, and existing project files are untrusted. Installs are size-bounded and staged before replacement; managed files are written transactionally; external symlinks and ref traversal are rejected. Publishing sends GitHub credentials only to the canonical HTTPS catalog. A custom catalog requires HTTPS and PATTERNS_ALLOW_CUSTOM_AUTH=1 before credentials are sent.

The extract flow

scan → detect → grill → emit turns an existing repo into a publishable pattern. It is driven by the extract Agent Skill (skills/extract/) — the agent reads the repo directly and that understanding is authoritative; the CLI verbs are optional deterministic accelerators it may invoke. detect enforces the boundaries you grilled, declared in patterns.yaml.

Each pattern declares a scope: internal (a house pattern — domain-rich, to keep one codebase consistent) or shareable (domain-agnostic — roles and shapes only, safe to distribute). The skill asks which up front; publish accepts only a shareable pattern (--force to override) and is authenticated — it sends your GitHub token (gh auth token / GITHUB_TOKEN) so the index can verify you have push access to the repo before registering it, and reserves each pattern name first-claim to its owner.

The consume flow

Installing a pattern isn't enough — your agent has to follow it. So patterns add (and update/remove/sync) also wires the consume Agent Skill (skills/consume/) into the repo: it copies the skill to .claude/skills/consume/ and writes a managed # Project patterns block — the consume skill, when to follow it, and the installed patterns — into every agent-instruction file it supports: AGENTS.md, CLAUDE.md, .cursor/rules/patterns.mdc, and .github/copilot-instructions.md.

The skill is generic and auto-invocable: whenever an agent places code in a repo with installed patterns, it reads the relevant patterns.yaml first, opens only the doc it needs (progressive disclosure), and respects the declared boundaries — so new code lands where the architecture says. Each block is marker-delimited and create-if-missing, so anything you write outside the markers is preserved.

To verify code actually respects the installed patterns, run patterns check: it unions every installed pattern's declared boundaries and fails (non-zero exit) on a forbidden import, so it works as a pre-commit hook or CI gate. Deterministic and LLM-free.

To wire (or re-wire) a repo without installing a pattern, run patterns sync (or ./skill.sh [dir]). Installs are descriptive only — your src/ is never touched.

Docs

• CONTEXT.md — the glossary (canonical vocabulary)
• ARCHITECTURE.md — the implementation map