feat: add Claude Code Plugin (Phase 2 — plugin-modernization)

[costiash]

Summary

• Create native Claude Code plugin with /docs command, Skill, and SessionStart hook
• Plugin uses Claude native Read/Grep/Glob tools — zero Python/shell dependencies for users
• Docs stored at ~/.claude-code-docs/ via git clone (updated by SessionStart hook)
• Additive only — no existing functionality removed

New Files

• .claude-plugin/marketplace.json — marketplace registration
• plugin/.claude-plugin/plugin.json — plugin metadata
• plugin/commands/docs.md — /docs slash command (plugin version)
• plugin/skills/claude-docs/SKILL.md — auto-discoverable documentation Skill
• plugin/skills/claude-docs/manifest-reference.md — category reference
• plugin/hooks/hooks.json — SessionStart hook config
• plugin/hooks/sync-docs.sh — git clone/pull script

Modified Files

• README.md — plugin install as recommended method, script install as legacy

Test plan

• All existing tests pass (294 pass, 2 skipped)
• Plugin JSON manifests are valid
• /docs command works via plugin
• Skill auto-discovers for Claude Code questions
• SessionStart hook clones docs on first run
• SessionStart hook updates docs on subsequent runs
• Legacy curl | bash still works alongside plugin

[github-actions]

Coverage report

This PR does not seem to contain any modification to coverable code.

[claude]

hello world test

[claude]

Deleting test - please ignore

[claude]

PR Review: feat: add Claude Code Plugin (Phase 2)

Great overall direction. The two-layer separation (plugin logic vs. doc data) is well-conceived, and the phased migration approach is the right call for 338+ active users. Here is detailed feedback:

What is Good

• Architectural clarity: Separating plugin (logic) from docs (data cloned via git) is sound. Docs evolve every 3 hours via CI/CD; the plugin is stable metadata.
• CI/CD fix is correct: The git add -A docs/ paths_manifest.json change is a genuine bug fix - this was the root cause of the stale manifest.
• Graceful degradation in hook: timeout 10 git pull --ff-only is the right pattern - network failures must never block session start.
• Additive-only approach: Nothing broken for existing users.
• New integration test: TestManifestStaging directly validates the CI/CD fix.
• Depth-1 clone: depth 1 on initial clone is a sensible performance optimization.

Bugs

1. JSON injection risk in sync-docs.sh output_context()

The msg argument is interpolated directly into a JSON heredoc. Current call sites use hardcoded strings so nothing breaks today. But if msg ever contains a double-quote or newline (e.g., from a dynamic git log entry in a future version), the output will be malformed JSON. Low severity now, worth hardening before Phase 3.

2. Source URL mapping in SKILL.md is incorrect for Agent SDK

SKILL.md states that files starting with en__ point to platform.claude.com. But Agent SDK files are stored as docs__en__agent-sdk__overview.md (with a docs__ prefix, confirmed by paths_manifest.json). The docs__ prefix is shared between Claude Code CLI docs AND Agent SDK docs, so filename prefix alone does not distinguish them. Claude will generate incorrect source URLs for Agent SDK topics.

3. TOPIC variable not substituted in commands/docs.md

The instruction to glob with dollar-sign-TOPIC as a variable will not work because TOPIC is not a Claude Code substitution variable - only ARGUMENTS is. This should be rephrased as natural language: find files whose names contain the topic keyword.

4. Uninstall command references the wrong path for plugin users

In commands/docs.md, the uninstall instruction references rm ~/.claude/commands/docs.md. Plugin users do not have this file - that is the legacy install artifact. The uninstall instruction should only reference rm -rf ~/.claude-code-docs plus a note to use the native plugin uninstall mechanism.

Issues

5. CLAUDE_PLUGIN_ROOT - is this env var guaranteed by the plugin runtime?

hooks.json references this env var for the sync-docs.sh path. This variable does not appear in Claude Code publicly documented hooks spec. If it is not set by the plugin runtime, the hook silently fails on every session start. Worth verifying against the actual spec before merge.

6. manifest-reference.md file pattern table is inaccurate

The table maps core_documentation to en__docs__build-with-claude__star.md, but those paths in paths_manifest.json produce files named docs__en__build-with-claude__star.md (with docs__ prefix, not en__). Agent SDK has the same discrepancy. Since this reference file is read by the Skill during searches, incorrect patterns will cause Claude to miss documentation.

7. git pull --dry-run does not check remote state

In commands/docs.md for the freshness check, git pull --dry-run replays the local merge step only - it does not fetch from the remote or report pending remote changes. It will always say Already up to date regardless of actual remote state. The correct approach is git fetch followed by git log HEAD..origin/main --oneline.

8. Missing set -u in sync-docs.sh

Every other shell script in this repo uses set -euo pipefail. Skipping -e for a SessionStart hook is intentional and correct - network failures should not crash the session. But adding set -u alone would catch typos silently expanding to empty strings.

Minor Notes

9. Plan files in docs/plans/

Three detailed AI-generated planning documents are committed into the live docs tree. Consider moving to docs/internal/ or GitHub wiki.

10. CLAUDE.md still references v0.5.0

Expected for phased migration, but a short note acknowledging the plugin path (v0.6.0) would help new contributors understand current architecture state.

11. No plugin structure validation in tests

The new integration test validates CI/CD staging. Lightweight test additions could validate plugin artifacts exist and have valid JSON, and that sync-docs.sh is executable.

Summary

Three bugs need attention before merge:

1. TOPIC variable in commands/docs.md - will not be substituted, will confuse search behavior
2. Agent SDK source URL mapping in SKILL.md and manifest-reference.md - incorrect patterns generate wrong source URLs
3. Verify CLAUDE_PLUGIN_ROOT is an actual env var provided by the Claude Code plugin runtime

The JSON injection in output_context() is low-risk today but worth noting for Phase 3. The CI/CD fix for paths_manifest.json staging is a standalone valuable change that should ship regardless of the plugin work.

[costiash]

Closing — will reopen after Phase 1 merges with clean commit messages.