Skip to content

cianfhoghlaim/cianchosaint / .agents/skills/notebooks-sync

notebooks-sync

Verified

Layer 11 of the knowledge-sync-loop — the notebooks surface validator. Use when the user asks 'are all notebooks registered', 'is the notebook fleet healthy', 'does the notebook registry match the CI flow', 'what does sync:notebooks do', 'how many notebooks are there'. Per the 2026-08-15-notebooks-sync-loop-v1 change. Triggers: 'sync:notebooks', 'notebooks', 'notebook-search', 'marimo', '@app.cell', 'notebooks/cli.py', 'notebooks/_shared'.

Notebooks Sync (Layer 11 of the knowledge-sync-loop)

The Layer 11 of the 11-layer pull-based sync architecture. Validates the 104 notebook files (20+ numeric prefixes) at notebooks/.

Why Layer 11?

The 10-layer architecture covered 13 of the 14 knowledge surfaces. The last remaining gap was the notebooks surface - the 104 .py notebook files at notebooks/ (with 108 @app.cell decorators across 20+ numeric prefixes).

Notebook drift is silent: when a developer adds a new BIEP per-subdir notebook but doesn't register it in the notebooks/cli.py GROUPS tuple, the uv run python notebooks/cli.py list command misses it. The 16 speedrun

  • 12 corpus + 7 educational stages + 6 dev env tools + 11 BIEP per-subdir + 7 official media + ... each have their own patterns, and there's no canonical check that they all conform.

Layer 11 closes the notebooks gap.

What Layer 11 covers

bash scripts/sync/notebooks.sh walks the 20+ numeric prefixes at notebooks/ + produces a per-prefix report to stedding/sync-reports/notebooks-{date}.md with:

  • The per-prefix notebook counts
  • The @app.cell decorator counts
  • The canonical notebooks/_shared/ helpers + notebooks/cli.py

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

The 5 sub-layers

Sub-layerTaskWhat it does
1sync:notebooks-driftDetects unregistered notebooks + broken @app.cell decorators
2sync:notebooks-cccAppends the 26th CCC concept guide (notebook-search) + reindex
3sync:notebooks-cogneeIngests the 104 notebook files into the 15th Cognee cluster (notebooks)
4sync:notebooks-testRuns the notebook import test + reports pass/fail per notebook
5sync:notebooks-lintPer-prefix stats (20+ prefixes + 104 notebooks + canonical helpers)

The new artifacts

ArtifactFilePurpose
notebooks-sync skill.agents/skills/notebooks-sync/SKILL.mdthis file
26th CCC guidenotebook-searchsurfaces the 104 notebook files via CCC
15th Cognee clusternotebooksthe 104 notebook files
notebooks_sync_health assetorchestration/defs/sync_assets.pyDagster asset
scripts/cognee_ingest_notebooks.pyingestorThe canonical Cognee cluster ingestor
notebooks/sync_health.pydashboardNotebooks tab in the grouped sync-health marimo surface

Notebooks evolution feedback loop

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

notebook file modified
  → sync:notebooks-cognee detects the change
  → re-cognifies the modified notebook into the notebooks cluster
  → sync:notebooks-ccc updates the 26th concept guide
  → The deployment control panel (notebook 24) surfaces the change

Quick routing

If you want to...Do this
Check the notebook fleet healthmise run sync:notebooks
See the per-prefix breakdowncat stedding/sync-reports/notebooks-$(date +%Y-%m-%d).md
Add a new notebookCreate the .py file in the right prefix dir + register it in notebooks/cli.py GROUPS + update notebooks/AGENTS.md + run sync:notebooks
Fix a registration driftsync:notebooks-drift will list the unregistered notebooks; register + re-run
See the notebooks dashboardOpen notebooks/sync_health.py (Notebooks tab)
Run the notebook import testuv run python -c "import notebooks.X"

Cross-references

  • openspec/changes/2026-08-15-knowledge-sync-loop-v1/ (the foundation)
  • openspec/changes/2026-08-15-stacks-sync-loop-v1/ (Layer 8)
  • openspec/changes/2026-08-15-dlt-sync-loop-v1/ (Layer 9)
  • openspec/changes/2026-08-15-agent-definitions-sync-loop-v1/ (Layer 10)
  • notebooks/ (the 104 .py files + 108 with @app.cell)
  • notebooks/_shared/ (the canonical notebook helpers)
  • notebooks/cli.py (the canonical notebook GROUPS)
deprecation-and-migrationaddyosmani/agent-skillsManages deprecation and migration. Use when removing old systems, APIs, or features. Use when migrating users from one implementation to another. Use when migrating a database schema in production, such as renaming or dropping a column without downtime (expand/contract). Use when deciding whether to maintain or sunset existing code.Stars: 119kUpdated Claude CodeCodexVerifiedInstall
performance-optimizationaddyosmani/agent-skillsOptimizes application performance across frontend, backend, queries, and databases. Use when performance requirements exist, when you suspect performance regressions, when Core Web Vitals or load times need improvement, when N+1 query patterns need fixing, or when profiling reveals bottlenecks.Stars: 119kUpdated Claude CodeCodexVerifiedInstall
Agent Cost Reportthedotmack/claude-memBelievable agent cost report for any period, default the last 7 full days PT, not counting today. Measured tokens from Claude Code transcripts priced at OpenRouter list prices (ESTIMATED), measured provider spend when a sanctioned source exists, note-taker cost separate, Timing-style HTML/PDF plus report.json, line-items.csv, evidence.json.Stars: 118kUpdated Claude CodeCodexVerifiedInstall
Agent Cost Reportthedotmack/claude-memBelievable agent cost report for any period, default the last 7 full days PT, not counting today. Measured tokens from Claude Code transcripts priced at OpenRouter list prices (ESTIMATED), measured provider spend when a sanctioned source exists, note-taker cost separate, Timing-style HTML/PDF plus report.json, line-items.csv, evidence.json.Stars: 118kUpdated Claude CodeCodexVerifiedInstall