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, context, completion, human judgment, and composition. For the complete fixture inventory, see the fixture index.

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. 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.

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.

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 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.

# 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)

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.

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.

FICTIONAL TRAINING FIXTURE — NOT CUSTOMER DATA

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 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.

# 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)

# 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:

[<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)

Chapters: grow the same anchor in checkpoints#

In the chapter tour, we build the anchor through five runnable directories, not checkpoint tags. Use the chapter progression 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:

# 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, ch2, ch3, ch4, and ch5 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.

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 for that history and the current pipeline; the older C1/C2/B split is not the current build recipe.

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, the example, and the fixture artifact.

- 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)

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

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, the example, and the fixture artifact.

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

- 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.

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.

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:

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#

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.

guides/use-cases.mdx retires into this gallery plus 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.