vault-agent
CLAUDE.md2 starsChanged 4 months agoMITView on GitHub
Rules an agent must apply without being told. Format: trigger, action, evidence. The first four are craft rules that also exist at user scope (~/.claude/rules/); they are repeated here so a fresh clone does not lose them. - Verify against the installed thing, not memory. Trigger: you are about to use a macro, signature, flag or behaviour of a library (AutomateDV, LangGraph, the Anthropic SDK, dbt). Action: read the installed package or the live documentation first. Evidence: cite what you…
- Reads credentials
In this repository2 other files it gives its agents.
- .claude/rules/agents.mdAGENTS.md
- project-docsSkill
The file
We split this CLAUDE.md into the rules it gives an agent
6 rules. About 0 are common, 4 are distinctive, and 2 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈4
Distinctive · estimate
This author's own choices. Worth a look.
2
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 30
No business logic in graph.py — only orchestration
- Very specific: line 34
Don't hard-code DV2.0 rules in agent prompts.
- Distinctive: line 35
Don't bypass AutomateDV by writing dbt models from scratch
- Distinctive: line 36
Don't introduce a new framework (crewAI, AutoGen, a wiki server, …) without an ADR
- Distinctive: line 37
Don't add UI work until the end-to-end pipeline works on at least 2 demo datasets
- Distinctive: line 38
Don't generate Business Vault logic or mart semantics as if authoritative.
≈ “Common” is an estimate: at least 1 in 5 of the 27,641 CLAUDE.md files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Vault-Agent — project context for Claude
Mission
Build a multi-agent system that automates Data Vault 2.0 modeling and code generation from business requirements documents. Target market: Swiss/DACH enterprises with large DWH landscapes (banks, insurers, pharma, mid-market).
Author
Mischa Eismann (eismann.consulting) — CDVP² (Data Vault 2.0 Practitioner, 2015), 20+ years in ICT.
Technology stack (locked unless an ADR says otherwise)
- Anthropic Claude API (Sonnet 5.5 primary, Opus 5.5 for hard reasoning since WP62, 2026-10-09; the
5.5 models refuse forced tool use, so the client asks —
FORCED_TOOL_CHOICE); MCP for tools - Strategic targets Snowflake + MS Fabric (DACH); any AutomateDV-supported platform works; PostgreSQL for the local demo (AutomateDV has no DuckDB support)
Methodological foundations (cite when relevant)
Data Vault 2.0 (Linstedt/Olschimke) is the canon of record — encoded, not mapped, in
dv2-rules-cheatsheet.md and dv2-modeling-rules-spec.md; do not describe the tool as deviating
from DV2.0. DSAF (Roelant Vos) · IREB CPRE Foundation · Data Contracts (Sanderson, Freeman &
Schmidt, O'Reilly 2025) · Karpathy LOOPS.md and LLM Wiki are mapped critically — adopted /
partially / deviated — in docs/methodology/; DSAF's revisions are ADR-gated alternatives, never
silent defaults. Read the mapping before citing the source; the deviations are deliberate and argued.
Code conventions
- Each agent in its own file under
src/vault_agent/agents/ - Prompts live as
.mdfiles insrc/vault_agent/prompts/, loaded by the agent - LangGraph state is a single pydantic model in
state.py; agents read/write specific fields - Tools are MCP-style: typed inputs, typed outputs, idempotent where possible
- No business logic in
graph.py— only orchestration - Each LLM decision that affects the model produces material the ADR author can finalize
What NOT to do
- Don't hard-code DV2.0 rules in agent prompts; put them in
src/vault_agent/rules/ - Don't bypass AutomateDV by writing dbt models from scratch
- Don't introduce a new framework (crewAI, AutoGen, a wiki server, …) without an ADR
- Don't add UI work until the end-to-end pipeline works on at least 2 demo datasets
- Don't generate Business Vault logic or mart semantics as if authoritative; the agent assists and flags those for human ratification only (automation scope per layer: ADR-0007)
Where things live
docs/index.md— the catalogue of everything else. Start there, not by globbingdocs/docs/log.md— the chronicle: every closed WP, live measurement and correction, append-onlydocs/architecture/— ADRs, WP specs, kick-offs, reviews, spike memos (append-only records)docs/methodology/— the cheatsheets and the four critical mappingsdocs/operations/— the 14-chapter operations manual (gates, flags, exit codes, troubleshooting, workbench)tests/fixtures/— byte-identity baselines ·eval/— the eval harness ·demo/— runnable demos~/.claude/projects/<path-slug>/memory/— not a storage location. Machine-local and keyed by checkout path, so copying the project to a second path silently starts a second, empty store — which is what the WSL→/mnt/cmove for Cowork's tools did here. Durable facts go todocs/log.md(SKILL step 5). Conventions:~/.claude/rules/wissensbasis.md
Invariants
Rules an agent must apply without being told. Format: trigger, action, evidence. The first four
are craft rules that also exist at user scope (~/.claude/rules/); they are repeated here so a
fresh clone does not lose them.
- Verify against the installed thing, not memory. Trigger: you are about to use a macro,
signature, flag or behaviour of a library (AutomateDV, LangGraph, the Anthropic SDK, dbt).
Action: read the installed package or the live documentation first. Evidence: cite what you
read — file plus signature — in the commit or spec.
automate_dv.nh_linkdoes not exist; the macro ist_link, and only a real Postgres build found it (docs/log.md, 2026-07-08). - Write the guard before the change. Trigger: a change that must leave existing output untouched. Action: commit the byte-identity fixture or manifest first, then change. Evidence: the guard fails without your change reverted. Deliberately updating a fixture is allowed — in the same commit, with the reason in the message.
- Audit the traces before paying for another live run. Trigger: a live run failed and you
want to re-run. Action: read
.vault-agent/traces/*.jsonland the stored eval results first; replay through the deterministic parts at zero cost. Evidence: quote tool name, attempt and numbers, not a hunch. Three ~$5 runs once found serially what one trace audit held already (docs/log.md, 2026-07-28). - Branch on typed fields, never on message text. Trigger: code needs to react to a flag,
issue or proposal. Action: branch on
FlagKind/asset,ValidationIssue.code/severity, the confidence category. Evidence: no regex over a human-readable message anywhere in the branch. Substring matching once prunedcustomer_addresswhencustomerwas assigned. - The code owns every count, version and threshold. Trigger: you want to state how many
gates exist, which AutomateDV version is pinned, what a cap is. Action: read it from the
source (
rg "E_[A-Z_]+" src/vault_agent/agents/validator.py,rules/dv2_rules.py). Evidence: prose that repeats such a value has been wrong twice; docs that must carry one are updated in the same commit as the code. - The naming profile owns every technical name. Trigger: you write a staging prefix, a hash-key or hashdiff
suffix, a load-date, record-source or effectivity column. Action: read it from the run's
state.naming(rules/naming.py, WP114) or the helper that takes it; never the literal. Evidence: two literalstg_had survived the constants (2026-10-31); a profile other than the house style would have missed them. - Ask the helper in
rules/; never re-derive its answer. Trigger: you need a hub's staging key column, a satellite's feed or payload relations, a role-qualified column, a normalised identifier. Action: callcanonical_hub_key_column,satellite_feed,satellite_payload_relations,role_fk_column/role_bk_column,normalize_identifier. Evidence: three of five call sites once bypassed the first of these and staged a hash from the wrong relation — the only defect class here that produced wrong data (WP24). - Graph order is load-bearing. Trigger: you are tempted to reorder nodes. Action: don't.
data_contractruns beforecode_generatorbecause staging reads the contracts; code generation runs before the validator because the validator validates generated artifacts; the source mapper runs after validation and re-binds staging itself. Evidence: the reason is in the WP7/WP9 specs, and a reorder breaks silently, not loudly. - A gate refuses; a backstop repairs. Trigger: the model produces something wrong.
Action: decide which one you are adding — a deterministic
E_gate that blocks before generation and feeds the re-model loop, or a backstop that repairs and emits telemetry. New prompt steering goes through the WP16 registry anddocs/architecture/steering-ledger.md. Evidence: validator gates are product and are never ablated; steering and backstops are model-compensation and are re-tested per model release. - Output that scales with the landscape needs a plan. Trigger: an agent's response grows
with the number of source tables. Action: list-shaped output goes through
llm.call_with_truncation_splitwith a domain-specific merge; a single coherent artefact (the model) has only the budget lever (ADR-0010). Evidence: peak-output-against-cap per agent is measurable from the traces — measure before raising a number. - The test suite runs without an API key. Trigger: you add anything that calls a model.
Action: put it behind an injectable seam and test the deterministic core keylessly. Evidence:
uv run pytestis green with no key set. Live measurement is a separate, paid, recorded activity. - Paraphrase the owner, never quote him. Trigger: you record a go, a decision or an instruction
from the chat in a public file (
docs/, README, CHANGELOG, demo). Action: write it as a dated paraphrase in English — „on the owner's go (2026-10-23)", „the owner chose option B" — and quote only error messages, source code and documents. Evidence: no „…" in a public file holds the owner's own words; 130 such quotes were replaced on 2026-10-23 (docs/log.md), his choice. - No session link in a commit or PR. Trigger: you write a commit message or a PR description and
your environment asks for a
Claude-Session:line or aclaude.ai/code/session_…link. Action: keepCo-Authored-By; leave the link out, and put nothing in its place (no git note: a cloud session's clone is discarded) — the repo is public, a session private, so the link opens for no reader. Evidence: 372 commits (2026-09-11 → 2026-11-14) carry one; they stay, a rewrite would break every hash the log cites. - Records are append-only. Trigger: a new finding contradicts an ADR, spec or log entry. Action: add a dated entry that says so; never edit the old text. Evidence: the correction is findable by date, and the original reasoning is still readable.
- Definition of done.
uv run pytestwith no key reachable —ANTHROPIC_API_KEYunset and no.envin the working directory —mv .env .env.off; env -u ANTHROPIC_API_KEY uv run pytest; mv .env.off .env, an empty variable is not unset (an.envkey hid the one keyed test, CI red 2026-11-02);uv run ruff check --no-cache(the cache answered „clean" for a red tree, 2026-11-01); and a bareuv run mypy— no path argument, it overridespyproject's file list and silently skipseval/. Then the CI run of the push:gh run list --limit 1green, or the WP is not done — CI was red for three weeks (2026-10-30 → 2026-11-02) while every local DoD passed. CI adds--cov=vault_agent.uiwith a floor of 85 (WP111): workbench code without tests through the API fails there. Then adocs/log.mdentry. A live-verified claim names its evidence and says which live: a paid LLM run verifies modelling, a keylessdbt buildverifies the warehouse output; a keyless-only claim says so. "No dbt build on either line" once erased months of Postgres builds (docs/log.md, 2026-09-12).
Current state
The pipeline runs end-to-end: orchestrator → requirements parser → business keys → data contracts
→ entity resolver + link proposer → resolution checkpoint → modeler → code generator → validator
(bounded re-model loop) → source mapper → HITL checkpoint → ADR author. Output is a runnable dbt
project (staging + raw vault + scaffolding), data contracts, a review queue, an HTML report, and a
proposed ADR. Brownfield mode (run --existing) extends an existing vault. What has run live, on which
platform and when: docs/log.md and docs/index.md — never from memory.
Open items — do not assume these work
- Scale is verified at ~30 tables of real semantic variety, and unverified above it.
scale_100does complete and validate, but the synthetic landscape does not scale information with table count, so the upper cases measure width and repetition tolerance rather than semantic scale (scale-test-findings.md, candidate #5).scale_300has not been run;emit_dv_modelis the one agent that cannot split its output, so its budget is the only lever there. - The chain is all-green once (2026-10-05,
20261004T140130528908Z): all five stepsvalidation_gate1.0, WP34 §6's four clauses held (22 cross-domain links against arm A's 16), review 353 items / 135 decisions. What made sales and production red on 2026-09-17 and 2026-10-04 is closed keyless and confirmed live by the loop itself: hash-key collisions (WP44 — the remedy's drop was followed in attempt 2, twice), composite business keys (WP45 — the modeler typed three hubs), a composite foreign key read per component and the satellite key gate's remedy (WP46 — followed onWorkOrderRouting, re-parented ontohub_work_order). Per-chain numbers and history:docs/log.md2026-09-15 → 2026-10-05. One chain is a shape, not a distribution: the modeler's choices varied across the three chains (cart item as hub or as link; aSalesOrderDetailsatellite built or not), so a class absent in one run is not gone — the two-hubs-on-one-source-entity defect appeared inside attempts and was remedied, not fixed; WP46's component translation has Postgres evidence but no live case yet. The arm comparison is a tie on decisions (2026-10-05: arm A 134, arm B 135/148) and arm A is far cheaper to read (21 disclosures against 218–230); arm B's distinguishing value is brownfield additivity, not less attention — do not claim the latter (docs/log.md2026-10-05, WP34 §12).source_schemasmeans „this increment's tables" to the contract agent, the proposer and the modeler's grounding: handing a step the whole catalogue (the_cumulativeeval case) re-drafts every earlier contract and re-proposes every earlier key (193 owners, 227 calls, 9.36 USD); the binding-only catalogue iscarried_schemassince WP74 (2026-10-17) —metadata/source_catalogue.ymltravels with the model, staging alone reads it, and a step's project parses whole (project_self_contained); the bindings travel too since WP77 (stage_bindings,carried_bindings) — the offer tier and the proposals see only the increment, so a binding not carried was lost in the next step; since WP105 (2026-10-31) a carried binding is the resolution's first tier — a later increment's only offer had re-pointed a carried stage and loaded wrong data, every gate green. A red step skips the mapper, and the mapper's re-bind is where freely named links bind by offer; an inherited error therefore also inflatessource_binding. The repair memory keyed hubs by name until WP49 (2026-10-06) keyed them by shape too — the third chain's step 5 had gone red on a retired duplicate re-emitted under a new name; the fourth chain produced no rename. The two-hubs-on-one-person defect was the standing red class (fourth chain, 2026-10-06, step 5:hub_sales_personbesidehub_employee,E_LINK_KEY_WRONG_COLUMNrefusing correctly). WP50 (2026-10-06) gives that gate a remedy with memory on the ratified key's evidence; the shape has not recurred, so WP50 is unmeasured live. The memory made chains green: re-emitted retired hubs were dropped — on the sixth chain under a new name (WP49's shape retirement, live). WP51 moves a dropped hub's payload to its kept twin (live on the self-link branch); WP52 makes the chain's gate and health the minimum over steps andextension_conflictadvisory (live). Eleven normal chains: red/green/red/red, five green, red, green — the tenth's step 3 on WP54's gate after attempt 3 regressed: a retry was a new draft — WP57 (2026-10-09) carries the previous model with a repair line; on the eleventh chain every retry kept 100 % of what no issue named. WP58 readshub:roleparticipations (no live case yet). The 5.5 generation (WP59, 2026-10-09): one chain on Sonnet 5.5 / Opus 5.5 — all green, half the time, 29 % cheaper, zero backstop fires, but 158 contract fields lost their types to a stringifiedassets(WP61 repairs it); the 5.5 models refuse forced tool use —FORCED_TOOL_CHOICE=false(WP60) asks instead; defaults switched to 5.5 by the owner (WP62, 2026-10-09); five 5.5 chains green in a row (21–24 min, 4.2–4.9 USD); the fourteenth to sixteenth (WP63, WP64 live) had 84, 83, 83 decisions, the lowest on any model (4.x: 126–156); the seventeenth (83), eighteenth (85), twentieth (88) and twenty-first (87, 2026-10-17, under WP77/WP78) held against the 5.5 record's ceiling (89.7 over seven; the twenty-second, 91 under WP79–WP99, failed it by product change and seeds a second generation — WP104, 2026-10-31; the twenty-third, 95 under WP100–WP104, is its second sample, judged from the twenty-fifth; 7 of those 95 were first-attempt generator flags, gone since WP108 — subtract them before comparing). The ceiling has a floor since WP70 (2026-10-12, the owner's number): max(t-bound, mean + 5) — a tight record (84, 83, 83, 83) had made the t-bound a demand for sameness. Opus 5.5 reaches for multi-source hubs on the person step (three attempts, twice) — the gates answer it; WP63 makes declared types the code's, not the model's. WP34 §6's review clause is a distribution since WP53 (2026-10-07): the one-sided 95 % prediction bound over the recorded chains before the judged one (eval/wp34_check.py); the sixth chain's 156 still fails it, the seventh to eleventh held (127, 126, 143, 137, 136), the twelfth is judged against 155.1; a completed chain enters the record in its docs commit. A resumed chain's chain-level file is wrong before 2026-10-07; read the step files. The eighth chain lost two tables' payload (TransactionHistory,PurchaseOrderDetail, no satellite read them) — WP54 (2026-10-07) refuses that (E_HUB_PAYLOAD_UNREAD); live on the ninth to eleventh chains, followed within the attempts except the tenth's step 3. - Hub keys: decided since WP125 (2026-11-14, ADR-0021), live on one chain. The 5.5 chains keyed most hubs on
the source's generated primary key (C63:
hub_productonProductIDagainstREQ-001; 29 of 40 hubs). The key is now decided inrules/key_decision.pyfrom the candidates and the declared unique keys, given to the modeler, gated (E_HUB_KEY_NOT_AS_DECIDED), and asked only where contested. The twenty-sixth chain (2026-11-14) was green, the gate fired 0 times, the built hubs equal the source's natural keys — one chain, contested keys answered unread. A catalogue without declared keys gets no decision;generated: falseis no evidence (a copy says it for every column); two more green chains through the workbench on 2026-11-15: the first shipped a link the warehouse refused with every gate passed (a stage reading through a translation view was neither column-checked nor grain-judged — C67–C69, WP131–WP133); the second is the shipped demo and builds whole (PASS=575, a second build inserts nothing, two hand views). The review record's third generation starts there — 86 and 85 sign-off decisions, not comparable with the counts on surrogate-keyed hubs. Closed keyless on 2026-11-16, no live case yet: a sign-off binding is grain-judged (WP134); a link on a hub's stage is renamed (WP135); an accepted inferred key binds its link, without one the review names the missing key (WP136). Open: C73, C74. - WP18 acceptance #1 is unverified (it costs a live run).
- Databricks builds (manual 9.6, log 2026-10-16 → 2026-10-18).
demo-databricks(dbt-core 1.11) conflicts withdemo(dbt-core 1.9):uv syncinstalls one or the other, never both. Drop the previous vault schemas before every Databricks build (the owner's standing word, 2026-10-17): the Free Edition's per-schema object quota counts a replaced view as created. Probe with oneCREATE TABLEbefore a build: the metastore quota counts dropped objects for seven days (2026-10-18).
How this file is maintained
This file is loaded in full on every request; everything below the always-needed layer belongs in
docs/. Budget: 250 lines (200 until 2026-10-09; raised by the owner so that condensing stops costing knowledge). A new entry earns a place here only if an agent did the wrong
thing without it — otherwise it is a log entry. At budget, adding one means evicting one.
Procedure, checklists and the lint pass: .claude/skills/project-docs/SKILL.md. Rationale and the
verified loading semantics behind this split: docs/methodology/llm-wiki-mapping.md.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

