Skip to content

docs: bring agent instructions and guides in line with the 1.0.0 SDK - #243

Merged
facontidavide merged 1 commit into
mainfrom
docs/agent-instructions-refresh
Nov 14, 2026
Merged

facontidavide merged 1 commit into
mainfrom
docs/agent-instructions-refresh

Conversation

@facontidavide

Copy link
Copy Markdown
Contributor

Why

Agents working in this repo (and plugin authors using the plotjuggler-plugin skill) were reading instructions that no longer match the code: four plugin families instead of five, a wrong toolbox threading rule, samples that do not compile, a host API that does not exist, a hash-map library the SDK does not depend on, and plan/history text mixed into current docs.

Four read-only audits checked every CLAUDE.md, skill and guide claim against the headers, CMake and the ## [1.0.0] — Unreleased changelog. Each finding was verified against the code before it was edited.

What changed

Entry points

  • Root CLAUDE.md: a read path for each kind of task (writing a plugin, changing the SDK, changing ABI), the correct changelog heading, all five floor-surface kinds, the real warning flags, how to run a test subset, and the two gates only CI runs (ABI drift, WASI). The 68 lines of release mechanics move to a new docs/RELEASING.md; the root keeps the bump table and the rules an agent must not miss.
  • Module CLAUDE.md files: libraryOwner() exists only on DataSourceHandle; the widget guide is linked; plugin_host is named; duplicated layering text removed; the dialog-protocol file keeps one line per trap and links the guide for the details.
  • README and test-and-commit: clang-tidy points at build/debug_asan (the folder ./build.sh --debug creates); layout and components listed.

plotjuggler-plugin skill

  • Five families, with a new references/widget.md.
  • Toolbox writes may come from the toolbox's own worker thread; onDataChanged is advisory.
  • Parser encodings come from a closed list (registeredParserEncodings()); PJ::ParserBindingRequest (was a non-compiling PJ::sdk:: name); config guard for an empty config; max_size == 0 means unlimited.
  • plugin_host for loader tests, PJ_BUILD_TESTS=OFF when vendoring, _NAMED macros, nulls on write and read, typed registerObjectTopic, GridMap/MeshMap, 1.0 pin guidance.

pj_plugins guides (18 confirmed defects): non-compiling samples, readSeries() and null handling, the removed colormap service, the parser C++ bridge contradiction, bindSchema() override must call the base, consumer CMake targets with pj_configure_plugin, runtime-host thread tags, and PR/pre-v4 history removed.

Reference docs: the dialog reference loses a nonexistent host API and gains the missing setters/handlers; plot markers describe the shipped producers; sdk-utilities.md lists the missing helpers; BACKLOG.md keeps only open items; V4_STORE.md → docs/object_store.md with the correct pj.toolbox_write.v1 id; the historical toolbox gap analysis moves to docs/archive/; cpp_design_recommendations.md drops tsl::robin_map and the invented flag list.

Code: comment-only changes in four builtin headers (Log::source, timestamp_ns) and one workflow comment. No version bump.

Not changed

  • packaging/conan-center-index/ is still seeded at 0.16.2 and lacks the source component; docs/RELEASING.md now says it is outside the build. Whether to update or delete it is a separate decision.
  • Dead tooling noticed but out of scope: install_qt6.sh and the Qt hint in build.sh (nothing uses Qt), the pj_ported_plugins/ handling in build.sh and CMakeLists.txt, and the unknown -DPJ_BUILD_PARQUET_IMPORT_EXAMPLE in test_sdk_install.sh.

Checks

  • pre-commit run --all-files passes.
  • Every relative markdown link and anchor resolves (script over all tracked .md except CHANGELOG and docs/archive/).
  • No build: the only non-markdown changes are comments.

🤖 Generated with Claude Code

An audit of every CLAUDE.md, skill and guide against the code found stale
claims, samples that do not compile, and history mixed into current docs.

- Root CLAUDE.md: read path for plugin authors and ABI changes, correct
  changelog heading, five floor-surface kinds, real warning flags, CI-only
  gates; release mechanics move to the new docs/RELEASING.md.
- plotjuggler-plugin skill: five families with a new Widget reference,
  correct toolbox threading, onDataChanged is advisory, closed encoding
  list, plugin_host for loader tests, null handling, 1.0 pin guidance.
- pj_plugins guides: fix non-compiling samples, document readSeries and
  nulls, resolve the parser-bridge contradiction, consumer CMake targets,
  remove PR and pre-v4 history.
- Reference docs: drop a nonexistent host API from the dialog reference,
  add missing setters/handlers and utilities, current marker producers,
  BACKLOG cut to open items, V4_STORE.md -> docs/object_store.md with the
  correct service id; the historical toolbox gap analysis goes to
  docs/archive/.
- C++ style docs: no tsl::robin_map (not a dependency), real flags.
- Header comments: Log `source`, `timestamp_ns` field names.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@facontidavide
facontidavide merged commit 5351588 into main Nov 14, 2026
4 checks passed
@facontidavide
facontidavide deleted the docs/agent-instructions-refresh branch November 14, 2026 15:02
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant