code-library — how code work is organized here

The user wants to hand experiment execution to agents and just read the logs. For that to work, every project's code must be discoverable and its state never lost. This skill is the index to that system.

The big picture

1. Code library (Code/<repo>/) — a durable map of how each repo works, shared across projects. Built once per repo via [[code-ingest]].
2. Project hub card (Papers|Projects|Staff/<slug>/<slug>.md) — records which repo a project uses and what edits this project made to it (the diff from upstream).
3. Experiment monitoring — per experiment: a log note + a results-table note + an auto-refreshed plot, kept current by a monitoring loop.

If a project has code, all three must exist. An agent picking up the project reads the project card → follows the link into the Code library → knows what to run.

1. Code library → see [[code-ingest]]

• Location: ${OBSIDIAN_VAULT}/personal/code-library/.
• One folder per repo; canonical overview is personal/code-library/<repo>/<repo>.md (always read this first), plus module notes.
• It maps the upstream repo (entrypoint, modules, dispatch points, "where to edit X"). It does NOT hold project-specific edits — those live in the project card.
• To add a repo: invoke code-ingest with the URL/path.
• First repo in the library: [[personal/code-library/llm-baselines/llm-baselines|llm-baselines]] (EPFL; base for several optimizer/pretraining projects).

2. Project hub card — ## Код section

Every project that uses code adds this to its hub card:

## Код
- Репозиторий: [[Code/<repo>/<repo>|<repo>]] — <fork? branch?>
- Локально: `~/brainlab/<направление>/<тема>/<работа>/code/` · сервер: `~/<dir>` (<host>)
- Правки этого проекта (диф от upstream):
  - new:    <files added>
  - patched:<files changed + why>
  - flags:  <new CLI flags / configs>

This is the per-project delta. The Code library tells you how the repo works; the card tells you what this project changed and where to run it.

3. Experiment monitoring (the standard)

Per experiment series, in the project folder:

• Experiments/<name>.md — the log: goal, fixed config, run layout (sessions/GPUs), status timeline, and a ## Progress snapshots table (one timestamped row per check).
• Results/<name>-table.md — the results: final metric tables + an embedded loss-curve plot (![[...png]]).
• Plot: generated by a house-style plotter (see [[handbook/tools/plot-curves]]). Rules: compact figure + large fonts (Obsidian downscales), two panels (full + zoom on the recent frontier), nothing overlaps, value labels flip left near the right edge, version the PNG filename each refresh (Obsidian caches by name) and rewrite the embed.
• Keep these notes closed in the Obsidian app while a loop writes to them (an open note re-saves its cached copy over CLI edits = iCloud conflict).
• Long runs: launch in tmux on the server, monitor with a /loop that reconnects the VPN on ssh timeout, appends a snapshot row, and refreshes the plot.

Your coding skills (when to reach for which)

• daily-coding — everyday write/modify source (the QA checklist). Default for coding tasks.
• architecture-design — new registrable components (factory/registry patterns).
• tdd / tdd-guide — test-first feature/bugfix.
• diagnose / bug-detective — hard bugs, perf regressions, root-cause loops.
• code-review (/code-review) / code-review-excellence — review a diff/PR.
• simplify (/code-review --fix), refactor-clean — dead code / consolidation.
• build-fix / build-error-resolver — get the build green, type errors.
• verification-loop — build+type+lint+test+security before a PR.
• uv-package-manager — Python deps/venv with uv.
• improve-codebase-architecture — deepen/consolidate architecture (uses CONTEXT.md, ADRs).
• git-workflow / git-guardrails — Conventional Commits, branching, blocking dangerous git.
• Research-side: results-analysis, results-report, analyze-results for post-run stats/figures/reports.

Coding rules in effect (from ~/.claude/CLAUDE.md + ~/.claude/rules/)

• coding-style.md: files 200-400 lines (split at 400+), @dataclass(frozen=True) config (no globals), type hints everywhere, logging not print, specific exceptions, no mutable defaults, factory+registry for models/datasets, model __init__ takes only cfg, __all__ in __init__.py. Prohibited: files >800 lines, nesting >4, globals, unused imports, debug print.
• agents.md: auto-invoke code-reviewer after writing code; build-error-resolver on build/type errors; dev-planner→architect for complex features; bug-analyzer on bug reports; tdd-guide for new features needing tests. Run independent agents in parallel.
• claude-scholar-core.md: uv, Hydra+OmegaConf, Transformers Trainer when appropriate, Conventional Commits, small reviewable diffs; align on approach before multi-file work; real verification after meaningful work.
• security.md: no hardcoded secrets/keys/IPs; secrets in env/.env; parameterized queries; no eval/exec on user input.
• Surgical changes only; match surrounding style; don't refactor out of scope; remove orphaned imports your change caused but not pre-existing dead code.

See also

• [[code-ingest]] — add a new repo to the library.
• ~/.claude/rules/code-workflow.md — the always-on rule that makes agents follow this.