docs: bind plugin & agent sync to the release process - #226
Merged
Conversation
Expand CONTRIBUTING.md "Documentation changes (mandatory!)" with three sub-categories (CLI surface / auto-generated / plugin hand-maintained) and explicit sub-bullets for plugins/kbagent/agents/keboola-expert.md: Rule 6 VERSION GATE examples, the tool-selection matrix, and inline gotchas. None of these have CI freshness checks today; the new "Plugin synchronization map" table makes the silent-drift surface visible at a glance, and the new "Releasing a new version" checklist walks the manual review steps that CI cannot perform. Add CLAUDE.md coding convention #17 that points at these new sections and lists the silent-drift surfaces by name. Replace the stale parallel update list under "Claude Code Plugin (Marketplace)" (which still told contributors to bump plugin.json by hand even though the pre-commit hook auto-syncs it from pyproject.toml) with a single pointer to CONTRIBUTING.md, keeping one authoritative source of truth. Add a heads-up note above CLAUDE.md "## All CLI Commands" so anyone editing the table sees the cross-file obligations before touching it.
3 tasks
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
CONTRIBUTING.mdmore binding around the plugin surface inplugins/kbagent/. CI catches drift inSKILL.md(decision table),plugin.json(version), andchangelog.py-- but everything else (AGENT_CONTEXT,keboola-expert.md,gotchas.md,commands-reference.md, the## All CLI Commandsblock inCLAUDE.md) is a silent-drift surface that ships broken if forgotten.CLAUDE.md: new coding convention v0.6.0: Branch lifecycle management + security hardening #17 pointing at the new sections, a heads-up note above## All CLI Commands, and a rewrite of the Claude Code Plugin (Marketplace) section to remove a stale parallel update list (it still told contributors to bumpplugin.jsonby hand even though the pre-commit hook auto-syncs it).Why
The highest silent-drift risk in the repo is
plugins/kbagent/agents/keboola-expert.md: its Rule 6 VERSION GATE references hard-coded versions (flow update needs 0.22.0+,schedule find needs 0.23.0+), its tool-selection matrix has rows tagged(0.25.0+), and its inline gotchas reflect specific past incidents. Nothing in CI catches when those go stale. If a release adds a command and the keboola-expert subagent is not updated, the AI agent will either refuse the task (false negative) or fall back to MCPtool callwith the old shape.Test plan
make checkpasses (no Python touched -- expected to be a no-op for lint / format / tests)CONTRIBUTING.mdon GitHub and confirm:## Plugin synchronization maptable renders as a 13-row Markdown table[Plugin synchronization map](#plugin-synchronization-map)from## Releasing a new versionresolveskeboola-expert.mdrender correctlyCLAUDE.mdon GitHub and confirm convention v0.6.0: Branch lifecycle management + security hardening #17 + the## All CLI Commandsblockquote appear correctly