Skip to content

cianfhoghlaim/cianchosaint / .agents/skills/baml-schema-sync

baml-schema-sync

Verified


name: baml-schema-sync description: "Layer 7 of the knowledge-sync-loop — the BAML schema surface validator. Use when the user asks 'are the BAML schemas healthy', 'is the baml-cli test passing', 'what BAML functions exist', 'is the baml_schemas Cognee cluster populated', 'how many BAML clients do we have', or 'what does sync:baml do'. Per the 2026-08-15-baml-sync-loop-v1 change. Triggers: 'sync:baml', 'sync:baml-drift', 'sync:baml-ccc', 'sync:baml-cognee', 'sync:baml-test', 'sync:baml-lint', 'baml_schemas', 'baml-function-search', 'baml_client', 'minimax-m3', 'clients.baml', 'clients_biep_v3.py'."

BAML Schema Sync (Layer 7 of the knowledge-sync-loop)

The Layer 7 of the 6-layer pull-based sync architecture from 2026-08-15-knowledge-sync-loop-v1. Validates the 320 .baml files (558 functions + 838 classes + 288 enums + 33 LLM clients) + closes the biggest remaining gap in the sync loop.

Why Layer 7?

The 6-layer architecture from 2026-08-15-knowledge-sync-loop-v1 (extended by 2026-08-15-retroactive-pre-v7-cleanup-v1 to include Layer 6 — Dagster) covered 9 of the 14 knowledge surfaces identified in the reconnaissance. The biggest remaining gap was the BAML extraction schema surface — the 320 .baml files that are the schema source for every extraction function in the platform.

BAML drift is silent (no test catches baml-cli generate drift), and the schema is the backbone of the data pipeline. Drift in .baml files propagates to every downstream consumer (DLT sources, Dagster assets, agents). Layer 7 closes this gap.

What Layer 7 covers

bash scripts/sync/baml.sh walks the 7 BAML clusters + the 3 top-level BAML files + produces a per-cluster report to stedding/sync-reports/baml-{date}.md with:

  • .baml file count per cluster (american_nations + british_isles + celtic + commonwealth + european_nations + european_union + processing)
  • function / class / enum / client<llm> / test counts per cluster
  • The top-level BAML files (clients.baml + clients_llama_swap.baml + clients_ocr_ensemble.baml + clients_biep_v3.py + baml.toml + README.md)
  • Drift detection (gemma-3-4b-it + gemma-3-27b-it should be 0 after the model-registry cleanup)

The orchestrator mise run sync:baml runs all 5 sub-layers + writes a unified report to stedding/sync-reports/baml-all-{date}.md.

The 5 sub-layers

Sub-layerTaskWhat it does
1sync:baml-driftDetects reference + syntax drift (historical Gemma 3 refs, duplicate names)
2sync:baml-cccAppends the 22nd CCC concept guide (baml-function-search) + reindex
3sync:baml-cogneeIngests the 320 .baml files into the 11th Cognee cluster (baml_schemas)
4sync:baml-testRuns baml-cli test on the 11 test blocks
5sync:baml-lintBAML lint gate (client references + model drift)

The new artifacts

ArtifactFilePurpose
baml-schema-sync skill.agents/skills/baml-schema-sync/SKILL.mdthis file
22nd CCC concept guide.cocoindex_code/guides.ymlbaml-function-search
11th Cognee clusterbaml_schemasthe 320 .baml files
baml_sync_health assetorchestration/defs/sync_assets.pyDagster asset
scripts/cognee_ingest_baml_schemas.pythe canonical ingestor
notebooks/sync_health.py (BAML tab)the Layer 7 dashboard

BAML evolution feedback loop

The system grows its knowledge surface over time via the BAML evolution feedback loop:

.baml file modified
  → sync:baml-cognee detects the change (via file mtime)
  → re-cognifies the modified file into the baml_schemas cluster
  → sync:baml-ccc updates the 22nd concept guide
  → The deployment control panel (notebook 24) surfaces the change

Quick routing

If you want to...Do this
Check the BAML schema healthmise run sync:baml
See the per-cluster breakdowncat stedding/sync-reports/baml-$(date +%Y-%m-%d).md
Add a new BAML functionCreate the .baml file with function + client X + run sync:baml
Fix a BAML driftsync:baml will show the broken file; fix + re-run
See the BAML sync dashboardOpen notebooks/sync_health.py (BAML tab)
Run the BAML testsmise run baml:test (the canonical entry point)

Cross-references

  • openspec/changes/2026-08-15-baml-sync-loop-v1/ (this change)
  • openspec/changes/2026-08-15-knowledge-sync-loop-v1/ (the foundation)
  • openspec/changes/2026-08-15-retroactive-pre-v7-cleanup-v1/ (Layer 6 extension)
  • baml_src/ (the 320 .baml files)
  • baml_src/clients.baml (the canonical 33 LLM clients)
  • baml_src/clients_biep_v3.py (the Python spec for the BIEP v3 clients)
  • scripts/sync/ (the 8 sync scripts)
  • .agents/skills/knowledge-sync-loop/SKILL.md (the parent sync loop skill)
  • .agents/skills/dagster-asset-sync/SKILL.md (the Layer 6 skill)
slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack."Stars: 197kUpdated Claude CodeCodexVerifiedInstall
ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read.Stars: 194kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report.Stars: 194kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt.Stars: 194kUpdated Claude CodeCodexVerifiedInstall