Skip to content

feat(tools): require and document a Prerequisites section for every tool - #616

Merged
potiuk merged 1 commit into
mainfrom
feat/tool-prerequisites
Jun 29, 2026
Merged

potiuk merged 1 commit into
mainfrom
feat/tool-prerequisites

Conversation

@potiuk

@potiuk potiuk commented Jun 29, 2026

Copy link
Copy Markdown
Member

What

Makes the tool inventory self-describing and keeps the vendor-neutrality
explainer honest. Four parts:

  1. Validator — a new HARD tool-prerequisites check in
    skill-and-tool-validator requires every tools/<name>/README.md to
    carry a ## Prerequisites section, alongside the existing
    **Capability:** requirement. New tests cover present / missing /
    both-missing; pre-existing fixtures updated.
  2. Every tool README now declares its prerequisites — runtime,
    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.
  3. tools/AGENTS.md (new) — conventions for the tools/ tree: the
    two 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.md
    whenever a tool or its tracking issues change.
  4. docs/vendor-neutrality.md refresh — 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-validate passes (all 32 tools carry capability +
    prerequisites); doctoc, markdownlint, lychee, ruff check/format,
    placeholder check all green.
  • mypy + pytest verified green via uv run for the validator project.
    The workspace-mypy / workspace-pytest pre-commit hooks were skipped
    at commit only because their binaries can't spawn in my environment —
    CI will run them normally.

🤖 Generated with Claude Code

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)
@potiuk
potiuk merged commit 5691d27 into main Jun 29, 2026
30 checks passed
@potiuk
potiuk deleted the feat/tool-prerequisites branch June 29, 2026 02:30
@potiuk potiuk added the family:cross-family Sweeps over the labeler limit label Nov 1, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

family:cross-family Sweeps over the labeler limit

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant