Skip to content

Fix plugin slash-command docs to use the namespaced form - #723

Merged
anshss merged 1 commit into
mainfrom
fix/plugin-command-namespacing
Aug 14, 2026
Merged

Fix plugin slash-command docs to use the namespaced form#723
anshss merged 1 commit into
mainfrom
fix/plugin-command-namespacing

Conversation

@anshss

@anshss anshss commented Aug 14, 2026

Copy link
Copy Markdown
Contributor

Summary

  • Claude Code namespaces every plugin command as /<plugin-name>:<command> (prefix from plugin.json's name, which is tokenjam). Both READMEs documented the bare forms (/onboard, /status, /optimize, /doctor, /uninstall), which do not resolve once the plugin is installed. Reproduced live: typing /onboard after a successful marketplace add + install matches nothing.
  • Corrected all references (table entries and mid-sentence prose) in README.md and plugin/README.md to the namespaced form, and fixed the install line to /plugin install tokenjam@tokenjam.
  • Added tests/unit/test_plugin_command_docs_namespaced.py, which derives the command set from plugin/commands/*.md and the prefix from plugin.json at test time (not hardcoded), so a rename or a newly added/removed command is caught automatically if the docs drift again.

Test plan

  • python3 -m pytest tests/unit/test_plugin_command_docs_namespaced.py -v — 4 passed
  • Confirmed the guard actually fails: temporarily reintroduced a bare /onboard in README.md, reran the test, observed a real AssertionError failure with a useful message, then restored and reran to confirm it passes again
  • claude plugin validate ./plugin --strict — Validation passed
  • Grepped the existing test suite for the bare command strings before editing; all hits were unrelated /api/v1/* HTTP routes and code comments, not plugin slash-command docs, so nothing needed inverting

Claude Code namespaces every plugin command as /<plugin-name>:<command>,
so the bare forms documented in both READMEs (/onboard, /status, /optimize,
/doctor, /uninstall) do not resolve after install. Correct both READMEs to
the namespaced form, fix the install line to /plugin install tokenjam@tokenjam,
and add a test that derives the plugin's command set and prefix from
plugin/commands/*.md and plugin.json so the docs cannot silently drift from
the manifest again.

Co-Authored-By: Claude <noreply@anthropic.com>
@anshss
anshss requested a review from anilmurty as a code owner August 14, 2026 15:43
@greptile-apps

greptile-apps Bot commented Aug 14, 2026

Copy link
Copy Markdown
Contributor

Greptile Summary

The PR corrects Claude Code plugin installation and command documentation to use the configured marketplace and plugin namespace. It also adds a regression test that derives command names and the namespace from plugin metadata.

  • Updates both READMEs to advertise /tokenjam:<command> forms.
  • Changes the installation example to /plugin install tokenjam@tokenjam.
  • Adds a pytest guard against bare plugin-command references.

Confidence Score: 4/5

The PR appears safe to merge, with a non-blocking gap in the new documentation regression test.

The documentation changes match the configured plugin and marketplace names, but the test can still pass when namespaced command references are stale or missing because it checks only for bare forms.

Files Needing Attention: tests/unit/test_plugin_command_docs_namespaced.py

Important Files Changed

Filename Overview
README.md Updates plugin installation and slash-command examples consistently with the repository metadata.
plugin/README.md Documents the namespace rule and updates all listed plugin commands and related prose.
tests/unit/test_plugin_command_docs_namespaced.py Adds useful bare-command detection, but does not enforce the stated rename and command-set drift guarantees.
Prompt To Fix All With AI
### Issue 1
tests/unit/test_plugin_command_docs_namespaced.py:79-81
**Guard misses namespaced drift**

The test computes `namespaced` but only asserts that bare references are absent. A plugin rename or command addition, rename, or removal can therefore leave namespaced references missing or stale while this regression guard still passes, contrary to its stated coverage.

---

For each issue above, determine whether it is valid and should be fixed. If so, fix it directly.

Reviews (1): Last reviewed commit: "docs: fix plugin slash-command reference..." | Re-trigger Greptile

Comment on lines +79 to +81
assert not bare_hits, (
f"{doc_path.relative_to(_REPO_ROOT)} documents the bare command "
f"`/{stem}`, which Claude Code will not resolve — it must be "

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2 Guard misses namespaced drift

The test computes namespaced but only asserts that bare references are absent. A plugin rename or command addition, rename, or removal can therefore leave namespaced references missing or stale while this regression guard still passes, contrary to its stated coverage.

Prompt To Fix With AI
This is a comment left during a code review.
Path: tests/unit/test_plugin_command_docs_namespaced.py
Line: 79-81

Comment:
**Guard misses namespaced drift**

The test computes `namespaced` but only asserts that bare references are absent. A plugin rename or command addition, rename, or removal can therefore leave namespaced references missing or stale while this regression guard still passes, contrary to its stated coverage.

---

For each issue above, determine whether it is valid and should be fixed. If so, fix it directly.

Note: If this suggestion doesn't match your team's coding style, reply to this and let me know. I'll remember it for next time!

@anshss
anshss merged commit 2c80d43 into main Aug 14, 2026
7 checks passed
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