tools AGENTS.md

AGENTS.md

Guidance for AI coding agents working in this repository. Human contributors may find it useful too. This file follows the agents.md convention and is the single source of truth for agent instructions; CLAUDE.md defers to it.

Detail that only matters while working on one area lives in the project skills under .claude/skills/ (see Agent configuration). Prefer loading the relevant skill over re-deriving a convention; this file states the rule, the skill carries the reasoning and the worked example.

Project overview

tools is a multi-module Maven library of Java tooling:

• Code generation (code/protogen-maven-plugin) — a Maven plugin that generates protobuf builders which detect a missing required field at compile time instead of runtime (shift-left). proto2 required fields are enforced by the builder chain; proto3 has no required fields, so its builders are all-optional with presence-aware hasXxx() accessors for message fields and explicit optional fields only; a oneof group gets a getXxxCase() discriminator and a clearXxx() that resets the whole group. Skill: protogen.
• Context engineering (code/context) — a fast, regex-based finder that builds the tree of classes a given class uses, plus a ProjectTreeBuilder that scans a whole Java project into a tree of folders, files and dependencies, to assemble context for gen-AI agents. The same tree can be emitted as a bundle in Google's Open Knowledge Format (OKF) v0.2 — a directory of markdown concept documents with YAML frontmatter, in the io.github.adamw7.context.okf package. An MCP server (io.github.adamw7.context.mcp) exposes the project-tree, context-finder, token-estimation and OKF-bundle tools. Skill: context-finder.
• Data (data) — data sources (CSV, GZip, JDBC, Parquet, JSON, YAML, TOON), each in an in-memory and an iterative variant. Parquet is read through an in-process DuckDB engine, so it exposes columns and rows like any other JDBC-backed source. Sources that know their columns up front implement ColumnarDataSource, a narrower contract than IterableDataSource, so a caller that needs the schema — such as the uniqueness check — cannot be handed a forward-only source (JSON/YAML/TOON) that would only answer null. A read that breaks part-way through fails instead of reading as a short file: the Scanner-backed sources check Scanner.ioException() before reporting the end of the data, so a truncated transfer or a corrupt GZip member cannot pass for a clean end and leave the uniqueness check calling a column unique on half a file. Also a uniqueness checker (does a subset of columns form a key, and is there a smaller one), open-addressing collections (OpenAddressingMap, OpenAddressingSet, the primitive IntKeyOpenAddressingMap), 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. Skill: adopt-pipeline. Summarised below.