Repository navigation
feat(tools): require and document a Prerequisites section for every tool - #616
Merged
Merged
Conversation
Three related changes that make the tool inventory self-describing and keep the vendor-neutrality explainer honest. 1. Validator (skill-and-tool-validator): a new HARD `tool-prerequisites` check requires every `tools/<name>/README.md` to carry a `## Prerequisites` section, alongside the existing `**Capability:**` requirement. Tests cover present/missing/both-missing cases; the fixtures that previously omitted the section were updated. 2. Every tool README now declares its prerequisites — runtime, required CLIs, credentials/auth, network reach, and optional deps — derived from each tool's actual pyproject/scripts, not guessed. Pure interface-spec tools (adapter contracts with no code) say so and defer to their adapters. 3. tools/AGENTS.md: new conventions doc for the tools/ tree. States the two HARD README requirements (capability + prerequisites) and the maintenance rule — when a tool is added/renamed/removed or its backends/tracking issues change, refresh the Capability-to-tool map (validator-enforced) and the hand-maintained extension-point list in docs/vendor-neutrality.md. Also refresh docs/vendor-neutrality.md itself: add a sixth axis (Communication channels) with the mail/chat extension-point issues, link the VCS issues (#601-#605, #608) and the security/CNA backends (OSV #311), and correct the Bitbucket reference (#606, not #306; #306 is Mailman 3). mypy + pytest verified green via `uv run` for the validator project; the workspace-mypy / workspace-pytest pre-commit hooks were skipped only because their binaries cannot spawn in this environment. Generated-by: Claude Code (Opus 4.8)
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
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.
What
Makes the tool inventory self-describing and keeps the vendor-neutrality
explainer honest. Four parts:
tool-prerequisitescheck inskill-and-tool-validatorrequires everytools/<name>/README.mdtocarry a
## Prerequisitessection, alongside the existing**Capability:**requirement. New tests cover present / missing /both-missing; pre-existing fixtures updated.
required CLIs, credentials/auth, network reach, optional deps —
derived from each tool's actual
pyproject/scripts, not guessed.Pure interface-spec tools (adapter contracts with no code) say so and
defer to their adapters.
tools/AGENTS.md(new) — conventions for thetools/tree: thetwo HARD README requirements, plus the maintenance rule to refresh
the Capability-to-tool map (validator-enforced) and the
hand-maintained extension-point list in
docs/vendor-neutrality.mdwhenever a tool or its tracking issues change.
docs/vendor-neutrality.mdrefresh — adds a sixth axis(Communication channels) with the mail/chat extension-point issues,
links the VCS issues (feat(tools/mercurial): Mercurial (Hg) version-control support for the local dev-loop #601-feat(tools/perforce): Perforce / Helix Core (centralized VCS) support #605, feat(tools/asf-svn): ASF SVN-based tool adapter (svn.apache.org + dist.apache.org), full capability surface like tools/github #608) and security/CNA backends
(OSV feat(tools/osv): query OSV.dev for vulnerability cross-references during security triage #311), and corrects the Bitbucket reference (feat(tools/bitbucket): Bitbucket forge + tracker bridge (Atlassian) #606, not feat(tools/mail-source/mailman3): add Mailman 3 / Hyperkitty archive backend #306;
feat(tools/mail-source/mailman3): add Mailman 3 / Hyperkitty archive backend #306 is Mailman 3 — a regression that landed via docs(vendor-neutrality): cite the open forge/runtime extension-point issues #614).
Verification
skill-and-tool-validatepasses (all 32 tools carry capability +prerequisites); doctoc, markdownlint, lychee, ruff check/format,
placeholder check all green.
uv runfor the validator project.The
workspace-mypy/workspace-pytestpre-commit hooks were skippedat commit only because their binaries can't spawn in my environment —
CI will run them normally.
🤖 Generated with Claude Code