Agent Blueprints — Changelog

Release 0.2.330

Tue, 09 Jun 2026 00:00:00 GMT

First tagged release. Bundles two work streams: the three-tier taxonomy refactor (12 patterns + 3 primitives + 1 modifier under a single `taxonomy.yaml` source of truth, with byte-identical drift-checked generators) and an AI-tool-discoverability hygiene round (`llms.txt`, `agents.md`, root-level CHANGELOG/ROADMAP, action version unification, Conventional Commits convention). ### Added - **Three-tier taxonomy** (`patterns/`, `primitives/`, `modifiers/`) backed by a new `taxonomy.yaml` at the repo root. Adding a new cohort (e.g. `guardrails/`) is now one entry in `taxonomy.yaml` + a directory — no code change. The validator, catalog emitter, schemas test, docs generator, and website data generator all read taxonomy.yaml. Catalog `schema_version` bumped to 2; `workflows[]` becomes a derived view of `patterns[]` for backward compat. - **Generic taxonomy infrastructure**: new `meta/generate-docs.js` (replaces `AUTO:` marker blocks across markdown), new `meta/generate-website-data.js` (regenerates `website/src/data/patterns.ts` from the catalog), refactored `meta/validate-metadata.js` to be taxonomy-driven. Drift gates in `catalog-drift.yml` now cover catalog + docs + website TS together. - **Contributor manual** `meta/HOW_TO_ADD_AN_ENTRY.md` — quick-start commands, per-cohort recipes, prompts for Claude Code / Cursor / Copilot, post-AI verification checklist. `CONTRIBUTING.md` + `meta/contributing.md` refreshed to lead with the three-step flow. - Per-cohort READMEs at `primitives/README.md` and `modifiers/README.md`. - **AI-tool discovery** files at repo root: `llms.txt` (llmstxt.org spec) + `agents.md` (consumer-focused guide for AI tools reading the catalog). - CHANGELOG.md and ROADMAP.md moved to repo root (from `meta/`). Stubs remain at the old paths. - `patterns-catalog.yaml` — top-level machine-readable index aggregating every pattern + primitive + modifier + composition edge into one file. Generated by `node meta/validate-metadata.js --emit patterns-catalog.yaml`. Primary downstream consumer is the `agent-deployments` CI generator. See [`PATTERNS_CATALOG_SCHEMA.md`](PATTERNS_CATALOG_SCHEMA.md). - `meta/validate-metadata.js --emit ` flag — aggregates validated metadata into the catalog. Without the flag, validator behavior is unchanged. - `.github/workflows/catalog-drift.yml` — hard CI gate that regenerates the catalog on every PR and fails if the committed file diverges. - `composition/anti-compositions.md` — standalone reference for pattern pairs that fight, overlap, or leak state, with concrete what-to-use-instead guidance. - Two new reference architectures in `composition/reference-architectures.md`: high-stakes content moderation pipeline (Routing + Tool Use + Reflection + HITL) and event-driven ingestion + RAG enrichment (Event-Driven + Tool Use + RAG + Memory). - `meta/contributing.md` — "Good first contributions" section listing newcomer-friendly tasks. - Sitemap (`/sitemap-index.xml`) and RSS feed (`/changelog.rss`) on the documentation website. - Refreshed `.github/ISSUE_TEMPLATE/blueprint-proposal.yml` — current "pattern" terminology and added when-to-use / when-NOT-to-use fields.

Release 0.3.0

Sun, 31 May 2026 00:00:00 GMT

Six-PR improvement series. Closes the three-repo connectivity gap, fills the security/production-realities content layer, and evens out pattern depth. ### Added - **`agent-scaffold` connectivity.** `composition/blueprints-to-deployments.md` and `composition/blueprint-to-spec-to-scaffold.md` — reverse-lookup table and end-to-end walkthrough making `agent-deployments` and `agent-scaffold` reachable from this repo. README lifecycle diagram replaces the static three-repo block. - **Frameworks & MCP map.** `foundations/frameworks-and-integrations.md` — 15 patterns × 6 frameworks/MCP. New "MCP and tool registries" subsection in `patterns/tool_use/design.md`. - **Security & production foundations** (4 new docs): `foundations/security-and-safety.md`, `foundations/hallucination-and-grounding.md`, `foundations/evals-and-quality.md`, `foundations/cost-and-model-selection.md`. - **Per-pattern "Production concerns" subsection** added to all 15 workflow + pattern design docs. Each names a pattern-specific surface for prompt injection, hallucination, cost, rate limiting/retries, idempotency, observability. - **"When NOT to use" subsection** added to all 15 overview.md files with 3 concrete anti-cases each, seeded from `foundations/choosing-a-pattern.md`. - **"Next steps" footer** added to all 15 overview.md files pointing at the deployment mapping and scaffold walkthrough. - **CI rigor.** `.github/workflows/docs.yml` now does dynamic pattern validation and runs `npm run build` against the website on every PR. `validate-metadata.js` cross-checks `patterns.ts` registration. `.github/CODEOWNERS` and `.github/dependabot.yml` added. ### Changed - `patterns/multi_agent/design.md` expanded from 105 → 210 lines and pinned as the canonical exemplar in `meta/contributing.md` and `meta/style-guide.md`. Now the deepest pattern doc, exceeding `saga/design.md`. - 8 thin design docs (memory, reflection, routing, plan-and-execute, react, tool-use, rag, parallel-calls) expanded to consistent ~120–165 line floor with explicit Observability Hooks subsections. - `website/src/data/patterns.ts` — registered `saga` and `human-in-the-loop` (were missing). - `SECURITY.md` — adds adopter-facing security guidance pointing to the new foundations doc. ### Fixed - `docs.yml` shell loop now covers all 11 agent patterns (previously hardcoded to 8; `saga`, `human-in-the-loop`, `event-driven` were uncovered).

Release 0.1.0

Wed, 25 Mar 2026 00:00:00 GMT

Phase 1: Documentation-First Restructure. ### Added - `/foundations/` — Core concepts, terminology, anatomy of an agent, pattern selection guide with decision flowchart. - `/workflows/` — 4 workflow patterns (prompt chaining, parallel calls, orchestrator-worker, evaluator-optimizer) with 3-tier documentation. - `/patterns/` — 8 agent patterns (ReAct, plan & execute, tool use, memory, RAG, reflection, routing, multi-agent) with 3-tier documentation. - Evolution bridges (`evolution.md`) for each agent pattern showing the workflow-to-agent transition. - `/composition/` — Combination matrix and reference architectures. - `/meta/` — Contributing guide, style guide, roadmap, changelog. ### Changed - Repository philosophy: shifted from code-first blueprints to architecture-first documentation. - `README.md`: rewritten to reflect documentation-first approach. - `/patterns/` directory: replaced pattern reference docs with full 3-tier pattern documentation. ### Removed - Previous code implementations moved to `legacy/` (blueprints, CLI, website, scripts). - Original CI/CD workflows archived; replaced with documentation-focused validation.