Agent-Building Playbook — Repository Analysis

2026-08-22 · source · source ↗ · raw capture · wiki page

Overview

A curated, growing collection of 113 patterns for building better in the agentic age — self-described as "Programming Pearls, but actionable, for the cognitive-architecture era." The subject is deliberately how to build better, not narrowly how to build agents: patterns cover cognitive architecture, agentic workflow design, prompt/context engineering, orchestration, tooling, verification, and the craft of working alongside AI systems. It is an open-source, git-native pattern language in the A Pattern Language (Christopher Alexander) tradition.

The dual-audience architecture

The repo's defining structural idea is one canonical source, two generated views. Every pattern lives as a single markdown file under patterns/ with a flat three-field frontmatter (title, one_liner, dimensions) plus a markdown "pearl" body. Two build scripts render that source two ways, and neither output is ever hand-edited:

INDEX.md (agents) — a dense, token-efficient list built by scripts/build-index.sh, one line per pattern grouped by dimension tag.
wiki/ (humans) — a static HTML site built by .wiki/scripts/publish.sh (bash + embedded stdlib-only Python).

There is also a third projection: scripts/build-wheel.py renders the whole corpus as a "flavor wheel" — 6 families → 13 dimensions → 113 patterns — a radial taxonomy (wheel/taxonomy.yaml, wheel/wheel.md, wheel/wheel.dot, plus an interactive explore.html).

The pattern contract

The filename patterns/{kebab-title}.md is the canonical identifier (no id field). Frontmatter must stay flat — exactly three scalar lines — with dimensions a comma-separated multi-value tag list, so a pattern appears under every tag it carries. The body follows a conventional "pearl" shape: What it is / When to reach for it / When NOT to / Exemplars / Related. The ## When NOT to contraindication is the one field Alexander's originals lacked, and it recurs across the corpus.

Provenance and growth

Patterns are distilled from three sources treated as peers — external literature, battle-tested session history (68 Amplifier sessions), and the Amplifier team ecosystem — with no provenance weighting in v1. The seed research dump is preserved at docs/seed-research-dump.md. The tag vocabulary started at 10 seed tags and has grown to 13 (adding human-factors, intent, knowledge); contribution is via GitHub PRs against patterns/ only, with INDEX.md regenerated by a GitHub Action on merge.

Why it matters

It is one of the few open, machine-readable pattern catalogs for agentic software — the same pattern-language move as Agentic Design (Pattern Catalog), but git-native, contribution-driven, and explicitly dual-audience rather than a proprietary web catalog. Its real contribution is less any single pattern than the format decision: a flat, validated, machine-ingestible frontmatter contract that lets both an agent (skim INDEX.md) and a human (browse patterns/ or wiki/) read the same corpus, plus a curated taxonomy that names the shape of the field (Mindset, Context, Tooling, Orchestration, Trust, People).