tools CLAUDE.md

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

AGENTS.md is the single source of truth for agent instructions — repository overview, module layout, build and test commands, CI, environment, and the release process. This file is a quick-reference summary of the essentials; when the two disagree, AGENTS.md wins, and the build's crossDocConsistency enforcer rule fails if a key fact (e.g. the Java version) drifts apart between them.

Detail lives in the thirteen skills under .claude/skills/ (see Agent configuration). Prefer loading the relevant skill over re-deriving a convention.

Project

tools is a multi-module Maven library of Java tooling. Build with Maven 3.9.X: run mvn install from the repository root.

• Code generation (code/protogen-maven-plugin) — a Maven plugin that generates protobuf builders enforcing missing required fields at compile time (proto2 required, proto3 presence-aware accessors, oneof discriminators). Skill: protogen.
• Context engineering (code/context) — a regex-based class-usage finder and project-tree builder that assembles context for gen-AI agents, an emitter for Google's Open Knowledge Format (OKF v0.2 bundles of markdown concept documents), plus an MCP server exposing project_tree, find_context, estimate_tokens and okf_bundle. Skill: context-finder.
• Data (data) — data sources (CSV, GZip, JDBC, Parquet via an in-process DuckDB engine, plus forward-only JSON/YAML/TOON), each in in-memory and iterative variants. Schema-aware sources implement the narrower ColumnarDataSource contract, so a caller needing the schema (e.g. the uniqueness check) cannot be handed a forward-only source. Also a column-uniqueness/key finder, open-addressing collections, and an MCP server exposing the uniqueness checker. Skill: data-sources.
• Claude Code adoption (adopt) — an ordered pipeline that adopts Claude Code into a GitHub repository: check the toolchain, clone, check the cloned project's own build tool, branch, trust the checkout, claude init and conform the generated CLAUDE.md, wire a build-tool-aware guard in, verify it, push, and open a pull request. The default branch is never written to, clone-URL credentials are masked in everything the run reports and are never left in the checkout's .git/config, --dry-run leaves out the push and the pull request entirely, a git or gh the network refused is tried again with a backoff (--retries) while every other failure is reported at once, and one run adopts a list of repositories without letting a failure stop the rest. Skill: adopt-pipeline.
• Markdown reading (markdown-common) — the dependency-free reader both the claudeMdFormat rule and adopt's conformer parse a document with, so the checker and the rewriter cannot disagree about what is code, what is commented out, and what heading a line declares. Add no dependency to it.