Patterns

This repo houses a collection of common patterns that can be mixed and matched together.

Pattern Index

ID	Pattern	Description
P001	RFC Process	Structured proposal workflow for non-trivial changes.
P002	Absolutely Pinned GitHub Actions	Pin GitHub Actions by immutable SHA with a # tag comment.
P003	Using mise	mise.toml as the single source of truth for tool/language versions.
P004	Using pnpm	pnpm declared via packageManager, committed lockfile, gitignored store.
P005	Using Biome	Biome lint/format pinned with a version-matched biome.json.
P006	Using TypeScript	tsc with strict mode, single src/ root, declaration emit.
P007	Using markdownlint-cli2	Markdown lint via .markdownlint-cli2.jsonc, composed into pnpm lint.
P008	Using hadolint	Dockerfile lint via mise-provisioned binary + .hadolint.yaml, gated in CI.
P009	Using actionlint	GitHub Actions workflow lint via mise binary + .actionlint.yaml, gated in CI.
P010	Using uv and pyproject.toml	pyproject.toml as the single config source, committed uv.lock, uv run everywhere (PEP 668).
P011	Using ruff	Python linter as a uv dev dep, configured in [tool.ruff], uv run ruff check ., gated in CI.
P012	Using ty	Python type checker as a uv dev dep, zero-config, uv run ty check src, gated in CI.
P013	Code Notes (GHC-style "Notes")	Titled, cross-referenceable block comments (Note [Title] / See Note [Title]) that describe the present state, not the journey.
P014	Using oxfmt	JS/TS/JSON formatter from oxc — devDependency (default) or mise tool; .oxfmtrc.jsonc, pnpm format/format:check.
P015	Using oxlint	JS/TS linter from oxc — devDependency (default) or mise tool; .oxlintrc.json, correctness/suspicious/perf as errors, pnpm lint.
P016	Using mise-action in CI	jdx/mise-action installs mise.toml tools in CI so versions never drift (SHA-pinned, the CI half of P003).
P017	The Release Skill	Encode the release pipeline as a trigger-gated agent skill: pre-flight gates → version → changelog → publish → tag → verify CI green.

Pattern Format

Location & Filename

Patterns are markdown files that live inside of patterns/, named sequentially like: patterns/P001-name-of-the-pattern.md.

Frontmatter Metadata

Patterns must contain the following YAML frontmatter at the beginning of their file:

---
id: P001
name: name-of-the-pattern
date: 2026-07-15
author: John Doe
used_in: ['github.com/capotej/example-repo']
---

Patterns can evolve over time. A revised pattern adds an optional revision key:

---
id: P006
name: using-typescript
date: 2026-06-27
revision: 1
author: Julio Capote
used_in: ['github.com/boldblackai/harness', 'github.com/capotej/pi-zsearch']
---

• A pattern as first published carries no revision key — that's the implicit revision 0 (the original). date stays as the creation date and does not change on revision.
• The first material edit adds revision: 1; each subsequent material edit increments it (2, 3, …).
• Omit the key for trivial edits (typos, formatting); bump it only when the documented guidance substantively changes.

Structure

Patterns contain fenced markdown codeblocks (always containing language and filename) surrounded by explanations of how/when they should be used.

Example:

export class UserService {
}

Usage

Point your agent at this repository with a prompt like "Implement patterns P031 and P021 in this project".