# Pattern gallery

This page is a lookup surface for choosing how to structure a hank. A codon is a sealed agent task; a pattern is a repeatable way of arranging codons, rigs, and sentinels to get a class of work done. Each card below names the problem it solves, links to a checked fixture or a fuller explanation, and records what a real run produced, so you can compare approaches before committing to one.

The cards fall into two groups. The first group is runnable: every example there ships in the 0.10.0 fixture bundle with dated captures, measured costs, and verification scripts. The second group is reference material: planned examples, retired pages, and a job-to-pattern mapping carried over from older docs. Costs on these cards are dated capture measurements, not estimates for your run.

## Choose by problem shape

Start with the problem shape, then follow the pattern or fixture link for implementation details. The five pattern families are [reliability](/author/patterns/reliability), [context](/author/patterns/context), [completion](/author/patterns/completion), [human judgment](/author/patterns/human-judgment), and [composition](/author/patterns/composition). For the complete fixture inventory, see [the fixture index](/tutorial/fixtures).

If you used the data-codebook example's **Adapting This Example** table, its job-to-pattern mapping survives below under "Map one pipeline to many jobs".

## Run checked examples

The 0.10.0 fixture bundle is available at [/fixtures/0.10.0/hankweave-fixtures-0.10.0.tar.gz](/content-assets/cf45dff5691c48c0/fixtures/0.10.0/hankweave-fixtures-0.10.0.tar.gz). It contains one top-level `hankweave-fixtures-0.10.0/` directory. Extract it from its parent directory, then enter the named fixture directory; do not create a second directory with the same prefix.

```sh
tar -xzf hankweave-fixtures-0.10.0.tar.gz
cd hankweave-fixtures-0.10.0/anchor-hank
```

To run the checked examples below, use Bun and Git and a non-root account with writable execution and output directories. The minimal fixture and chapters 1–2 use `ANTHROPIC_API_KEY`; chapters 3–5 and the full anchor also use `BASETEN_API_KEY` for the two `pi/baseten/deepseek-ai/DeepSeek-V4-Pro` codons. A Claude Code login alone is not the default direct-Anthropic credential for these runs.

<a id="normalize-and-reconcile-quoted-requests"></a>

### Anchor: normalize, validate, reconcile, publish

The anchor is the largest checked fixture and the reference point for the rest of this page: a full procurement-style pipeline run end to end against live providers.

* **Problem shape:** normalize eight quoting suppliers across five BOM parts, quarantine an unknown template, reconcile the rows, and publish a cited award brief plus an exception queue.
* **Pattern:** staged normalization and validation with a deterministic (reproducible) output boundary.
* **Status:** checked @ 0.10.0; the capture is one complete live execution with seven of seven codons complete. Its dated tracked-codon cost is embedded below. Read the [anchor fixture README](/content-assets/cf45dff5691c48c0/fixtures/0.10.0/files/anchor-hank/README.md) for the entry point.
* **What it teaches:** seven codons run in order without loops: three Haiku normalizers, a Haiku survey, two `pi/baseten/deepseek-ai/DeepSeek-V4-Pro` judgment codons, and a Haiku award codon. The configured per-codon caps sum to `$9.00`; that is a configured ceiling, not a predicted bill. The output contains eight envelope files, `survey-notes.json`, `validated-records.json`, `exception-ledger.json`, `unified-records.csv`, `exceptions.csv`, and `award-brief.md`.
* **Scope:** AST, BCN, CDR, DVR, EMB, FJR, HBR, and IRS cover five parts for 40 supplier-part data rows. GRN is quarantined rather than counted as a ninth quoting supplier. The exception queue has eight rows spanning eight hazard types.
* **Artifact boundary:** the `quality-observer` is an event-only sentinel (an event-triggered observer) of completion-event fields. It does not inspect the files or prove row coverage. The bare `quality-observer.log` name resolves under `exec/.hankweave/sentinels/outputs/quality-observer/`; use `verify.py` and the exported CSV/JSON checks for artifact assertions.

The capture manifest and the run commands below come from the fixture itself. The manifest records the capture date, runtime version, completion count, and measured tracked-codon cost; the command block is the verified sequence to prepare inputs, validate, run headless, and check the output.

```text
# Capture manifest
- Captured: 2026-09-06T13:07:23.154353+00:00 · runtime: hankweave@0.10.0
- actual_service_output: true
- Scope: one complete live execution
- Raw execution (path normalized): ~/.hankweave-executions/anchor/1788699352631-qoit-40a58f
- Complete codons: 7/7
- Tracked codon cost: $0.88303367 (provider health checks and sentinel calls are separate)
```

```sh
python3 ../verify.py prepare-data ../quote-template-unification task-data
bunx hankweave@0.10.0 hank.json task-data --validate
bunx hankweave@0.10.0 hank.json task-data --headless --start-new --execution exec --max-cost 9 --shim-idle-timeout 1800 --overwrite-output -o out
python3 ../verify.py anchor out
bun rigs/render-exceptions.ts out --check && bun rigs/render-award.ts out --check
```

The anchor preparation step copies task inputs into `task-data/` and keeps the answer key, generator, and planted failures outside the agent's input directory. `verify.py anchor out` compares the output with the held-out truth and exits nonzero for missing or duplicate rows, value drift, missing hazards, or broken exception fields. The 19 failure fixtures exercise the corpus's validation gates: for example, expired quotes, NO BID rendered as zero, and an unknown part alias; the preflight-hash, watermark, and publication cases stop at their respective gates rather than all belonging to one codon.

> **Pitfall:** `truth/` is the answer key. `prepare-data` keeps it out of the mounted input directory, and `verify.py` compares the output with it afterward; the quality-observer log is not that check.

<a id="choose-the-run-controls"></a>
Two flags in that command block are easy to misread. `--validate` checks configuration and paths without running codons or provider health checks; `--headless` means without the TUI. Validation does not prove that credentials work. Runtime startup health checks are separate and can make small provider calls outside the tracked-codon total. The recipe's two positional arguments are required. `--headless`, `--start-new`, `--validate`, `-y`, and `-o <dir>` are optional; the anchor additionally uses `--execution`, `--overwrite-output`, `--shim-idle-timeout`, and `--max-cost`.

```text
FICTIONAL TRAINING FIXTURE — NOT CUSTOMER DATA
```

<a id="use-one-provider-and-one-output"></a>
The anchor's input data is fictional, as the fixture states in one line:

### Minimal: one provider, one codon

* **Problem shape:** a smallest useful hank for the quickstart: one codon, one provider key, and one output file.
* **Pattern:** a minimal first run.
* **Status:** checked @ 0.10.0; one of one codon completed in the dated capture below. The [minimal fixture README](/content-assets/cf45dff5691c48c0/fixtures/0.10.0/files/minimal-single-provider/README.md) is its bundle-relative entry point.
* **What to check:** `--validate` produces the `GOOD TO RUN!` box; the run prints the `Hankweave v0.10.0` banner; afterward, inspect `out/summary.md`.

The capture and README below show what a successful run looks like and how the fixture regenerates the documentation quickstart's pasted transcripts.

```text
# Capture manifest
- Captured: 2026-09-06T05:52:24.303456+00:00 · runtime: hankweave@0.10.0
- actual_service_output: true
- Scope: one complete live execution
- Raw execution (path normalized): ~/.hankweave-executions/minimal/1788673917095-hvhh-c5c378
- Complete codons: 1/1
- Tracked codon cost: $0.01394590 (provider health checks and sentinel calls are separate)
```

```text
# minimal-single-provider

The smallest useful hank: one codon (a codon — one sealed agent task), one provider key (`ANTHROPIC_API_KEY`), one output file. This is the documentation quickstart's fixture: the docs' pasted transcripts are regenerated from THIS directory against the pinned runtime, so they can never silently rot.

Run it (from this directory):

    bunx hankweave@0.10.0 hank.json data/ --validate     # schema and paths only; no provider health check
    bunx hankweave@0.10.0 hank.json data/ --headless --start-new -o out

Observables (the docs' Check-its): the `GOOD TO RUN!` box from validate; the run banner `Hankweave v0.10.0`; `out/summary.md` afterwards. `expected/` holds captured transcripts with their capture date and runtime version; `expected/fail-no-key.txt` is the error you get with no key set (kept as an expected-failure regression).
```

With `ANTHROPIC_API_KEY` unset, the checked expected failure is `No authentication found (set ANTHROPIC_API_KEY)`. This is the default direct-Anthropic requirement; it is not replaced by a local Claude Code login. The captured startup output shows the exact error shape:

```text
[<ts>] [ERROR] Self-test completed: FAILED
[<ts>] [ERROR] Self-test FAILED: Some checks failed
[<ts>] [ERROR]   - authentication: ✗ No authentication found (set ANTHROPIC_API_KEY)
[ERROR] Server startup failed!
Error message: Self-test failed for 1 model(s):
  - Claude Haiku 4.5 (latest) (anthropic/claude-haiku-4-5): Some checks failed
      • authentication: No authentication found (set ANTHROPIC_API_KEY)
```

<a id="build-the-staged-anchor-chapters"></a>

### Chapters: grow the same anchor in checkpoints

In the [chapter tour](/tutorial/0-tour), we build the anchor through five runnable directories, not checkpoint tags. Use the [chapter progression](/content-assets/cf45dff5691c48c0/fixtures/0.10.0/files/chapters/PROGRESSION.md) to find each bundle-relative entry. Each chapter has its own dated capture and executable semantic check. The progression table below summarizes codon counts, supplier scope, required keys, and results per chapter:

```text
# Chapter progression

| Chapter | Codons | Supplier scope | Keys | Result |
|---|---:|---|---|---|
| ch1 | 1 | AST | ANTHROPIC_API_KEY | two Aster envelopes |
| ch2 | 3 | AST, BCN, CDR | ANTHROPIC_API_KEY | three envelope files |
| ch3 | 4 | AST, BCN, CDR | ANTHROPIC_API_KEY, BASETEN_API_KEY | validated records and exceptions |
| ch4 | 5 | AST, BCN, CDR | ANTHROPIC_API_KEY, BASETEN_API_KEY | 15 supplier-part data rows |
| ch5 | 7 | AST, BCN, CDR, DVR, EMB, FJR, HBR, IRS | ANTHROPIC_API_KEY, BASETEN_API_KEY | full anchor: 40 data rows, cited award brief; GRN quarantined |

Each chapter's `EXPECTED.md` gives commands from its own directory and an executable semantic check. ch1–ch4 intentionally remain smaller checkpoints; the eight-supplier scope begins at ch5. The full-anchor prompt files are under ch5/prompts/, exactly where hank.json references them.

Use a non-root user, Bun and Git. Validation is not a live run. For an independent repeat, use `--start-new` and a new output directory; to resume after interruption, use the same data source without `--start-new`. Input checksums do not guarantee byte-identical model output.
```

The five checkpoint captures are dated 2026-09-06 and record measured tracked-codon costs in their [ch1](/content-assets/cf45dff5691c48c0/fixtures/0.10.0/files/chapters/ch1/expected/CAPTURE.md), [ch2](/content-assets/cf45dff5691c48c0/fixtures/0.10.0/files/chapters/ch2/expected/CAPTURE.md), [ch3](/content-assets/cf45dff5691c48c0/fixtures/0.10.0/files/chapters/ch3/expected/CAPTURE.md), [ch4](/content-assets/cf45dff5691c48c0/fixtures/0.10.0/files/chapters/ch4/expected/CAPTURE.md), and [ch5](/content-assets/cf45dff5691c48c0/fixtures/0.10.0/files/chapters/ch5/expected/CAPTURE.md) capture manifests; provider health checks and sentinel calls are separate. Use a new output and `--start-new` for an independent repeat. Input checksums do not make model output byte-identical.

<a id="track-the-documentation-build"></a>

### Docs maintenance: the documentation is a hank

We also use hanks to build this documentation. An earlier forge design split the work into C1 for skeleton, preservation, and briefs; C2 for writing and validation; and B for publication. Its historical record reports a 13-codon C3 run with exit 0, 13 upstream issues filed, and the anchor golden run. Follow the [documentation maintenance example](/examples/docs-maintenance) for that history and the current pipeline; the older C1/C2/B split is not the current build recipe.

<a id="review-a-plan-through-updates"></a>

### Build-review loop

**plan-review-update** is a checked build-review pattern: one `plan` codon followed by three `blind-reviews` iterations, each containing `review` and `update`, all using Haiku with fresh continuation. Its 2026-09-03 capture has seven codon completions; the dated measured total is embedded below. The break variants demonstrate a model-mismatch load failure and a rig failure when `allowFailure` is absent. See [the reliability pattern](/author/patterns/reliability), [the example](/examples/plan-review-update), and the [fixture artifact](/content-assets/cf45dff5691c48c0/fixtures/0.10.0/files/plan-review-update/README.md).

```text
- Captured: 2026-09-03T07:20Z · runtime: hankweave@0.10.0 (published npm artifact, `bunx hankweave@0.10.0 --version` → 0.10.0) · models: haiku (plan/review/update)
```

```text
- costs.json: per-codon `codon.completed` costs and the total ($0.272) — measured 2026-09-03, haiku throughout.
```

<a id="build-and-test-a-connector"></a>

### Polymorphic connector build

**connector-build-test** is a checked connector pattern: a fixed `spec.md` contract and a deterministic `bun test` suite drive `research` → a three-iteration fresh `implement` loop → `document`. Its 2026-09-03 capture has five codon completions; the dated measured total is embedded below. The break-gate variant fails when the document rig runs without `allowFailure`. See [the composition pattern](/author/patterns/composition), [the example](/examples/connector-build-test), and the [fixture artifact](/content-assets/cf45dff5691c48c0/fixtures/0.10.0/files/connector-build-test/README.md).

```text
- Captured: 2026-09-03T07:25Z · runtime: hankweave@0.10.0 (published npm artifact, `bunx hankweave@0.10.0 --version` → 0.10.0) · model: haiku
```

```text
- costs.json: per-codon costs and the total ($0.125) for the successful run (research, implement#0, implement#1, implement#2 …, document) — measured 2026-09-03, haiku.
```

> **Pitfall:** capture costs are dated tracked-codon measurements. The anchor's `$9.00` cap sum is not a bill, and a captured `expected/` directory is not proof that a later rerun will pass.

## When no fixture exists yet

**statement-unifier** is planned as a second anchor-scale example under a stricter synthetic regime. It is not yet a checked fixture; see its planned entry in the [examples index](/examples/index).

The retired use-cases page contributes six card ideas only: polymorphic connectors, data onboarding, research-design-implement, extract-classify-transform, generate-run-fix, and concept-mock-feedback. None is presented as a runnable fixture here; the old polymorphic example hank is invalid as written because its loop codons have no prompt. The classification idea writes to a workspace path, not the mounted input directory.

## Map one pipeline to many jobs

The four-stage shape carried over from the retired data-codebook example is **observe → generate → validate → document**. The table maps that shape onto common jobs and links a named pattern only where one is documented:

| Job              | Observe                   | Generate                     | Validate                | Document           | Named pattern route                         |
| ---------------- | ------------------------- | ---------------------------- | ----------------------- | ------------------ | ------------------------------------------- |
| API client       | read an OpenAPI spec      | generate a TypeScript client | test against a live API | usage docs         | no named pattern page                       |
| Test suite       | analyze existing code     | generate tests               | run and fix             | coverage report    | [reliability](/author/patterns/reliability) |
| Data migration   | analyze the source schema | generate scripts             | dry-run and fix         | runbook            | no named pattern page                       |
| Config generator | read requirements         | generate Terraform/YAML      | validate                | explain the result | [composition](/author/patterns/composition) |

<a id="treat-the-anchor-as-an-instance-not-a-promise"></a>
Use the anchor as one worked instance of this shape, not as proof that every job above already has a fixture. It uses staged observe/normalize → validate → document work, a Bun-and-TypeScript rig, an event-only quality-observer sentinel, and per-codon budgets with differing `onExceeded` policies. On budget exhaustion, its normalizers and reconcile are marked failed; survey, validate, and award are marked completed even if their work is partial.

## Find retired examples here

<a id="retire-the-data-codebook-example"></a>
`examples/data-codebook.mdx` is retired because its promised data-parse check is not enforced mechanically. The anchor supersedes it, and the migration map supplies the redirect. The retained material is the four-prompt structure, the template-rig pattern, the narrator-plus-cost-tracker sentinel idea, the `beforeCopy` quality-gate concept, and the adapting table now shown above.

<a id="retire-the-use-cases-guide"></a>
`guides/use-cases.mdx` retires into this gallery plus [examples/index](/examples/index). Its anti-patterns and core-techniques method material belongs on the author method pages rather than on cards. The useful conclusion remains: start simple and add complexity only when needed; resist over-engineering the first hank.