Claude Code plugin: one-step /getdocs for coding-agent users (branch 2)

[jonbakerfish]

Depends on #19 (the agent-native completion summary). The plugin reads the outcome summary that #19 produces; it cannot be finished until #19 lands.

Problem Statement

A user working inside Claude Code wants their agent to pull a library's documentation into the workspace as clean local markdown — but today that means the user has to remember getdocs exists, know it's installable, recall the right getdocs crawl invocation and flags, decide whether to block on it or background it, and then figure out what to do with the result (a Pages tree to grep? a cloned repo to serve?). None of that is discoverable from inside the agent, and the agent left to its own devices will get it wrong — e.g. naively blocking on a thousand-Page Crawl, or hunting the filesystem for output it can't locate. getdocs is "agent-ready" as a CLI (ADR-0007), but there is no frictionless, discoverable way for a Claude Code user to give their agent that capability.

Solution

Ship a Claude Code plugin that adds a /getdocs capability to the agent, distributed so a user can install it in one step. The plugin:

• Bootstraps with no install step — it invokes getdocs via uvx getdocs …, so the user never has to pip install anything first.
• Picks the right execution mode — a bounded synchronous run for "get me this docs section," or a background run (which Claude Code resumes on completion) for "mirror the whole site," instead of leaving the agent to guess.
• Acts on the Outcome — it reads the completion summary from Agent-native completion summary: report the Crawl/Clone Outcome #19 and guides the next step based on whether the run produced a Crawl or a Clone: point the agent at the Pages tree to grep, offer to mkdocs serve a Clone, or suggest raising the limit when the Crawl was truncated.

Distribution makes the getdocs repository itself a plugin marketplace, so a user runs an add-marketplace command followed by an install command and immediately has /getdocs. The repo's README documents the one-step install, and the plugin is submitted to community plugin marketplaces / awesome-lists so coding-agent users can discover it.

User Stories

1. As a Claude Code user, I want to install a getdocs plugin in one step, so that my agent can fetch documentation without me wiring anything up.
2. As a Claude Code user, I want to add the getdocs marketplace from its GitHub repo, so that I can install the plugin from the source I trust.
3. As a Claude Code user, I want a /getdocs <url> command, so that I can pull docs with a single, memorable invocation.
4. As a Claude Code user, I don't want to pre-install getdocs with pip, so that trying it out has zero setup friction.
5. As a coding agent, I want the command to run getdocs via uvx, so that the tool is fetched on demand and I don't fail on "command not found."
6. As a coding agent, I want the command to choose a bounded synchronous run for a specific docs section, so that I get the Pages back in one turn without blocking on a huge Crawl.
7. As a coding agent, I want the command to choose a background run for a whole-site mirror, so that I can keep working and be resumed when the Crawl finishes.
8. As a coding agent, I want the command to tell me which mode it picked and why, so that my behavior is predictable to the user watching.
9. As a coding agent, after a run I want to read the Outcome summary, so that I know whether I produced a Crawl or a Clone.
10. As a coding agent, when the Outcome is a Crawl, I want to be pointed at the output directory and told to grep/read the Pages, so that I ground my answer in the real docs.
11. As a coding agent, when the Outcome is a Clone, I want to be offered the local serve path (mkdocs serve of the generated config), so that the user can browse the docs.
12. As a coding agent, when a Crawl was truncated, I want to be told it was capped, so that I can offer to re-run with a higher limit.
13. As a Claude Code user, I want the plugin's behavior documented, so that I understand what /getdocs will do before I run it.
14. As a Claude Code user, I want the plugin to respect getdocs's polite defaults (robots.txt, throttling, honest User-Agent), so that I don't have to think about etiquette.
15. As a Claude Code user, I want to crawl a docs section into my current project, so that my agent has the reference material alongside my code.
16. As a Claude Code user, I want the option to mirror an entire docs site in the background, so that I can build a local knowledge base without babysitting it.
17. As a coding-agent user browsing a plugin marketplace, I want to discover getdocs, so that I learn this capability exists.
18. As a maintainer, I want the repository to double as the plugin marketplace, so that I don't run separate infrastructure to distribute the plugin.
19. As a maintainer, I want the plugin manifest validated in CI, so that I never ship a marketplace that fails to load.
20. As a maintainer, I want the plugin to be a thin wrapper over the getdocs CLI, so that crawl/clone behavior stays tested in one place and the plugin carries no duplicated logic.
21. As a maintainer, I want the plugin to depend on the documented --summary-json contract, so that it keeps working as long as that interface is stable.
22. As a Claude Code user on a fresh machine, I want the plugin to work as long as uv/uvx is available, so that onboarding is minimal.
23. As a contributor, I want the plugin's command instructions to be readable markdown, so that I can review and improve the agent guidance.
24. As a user, I want clear install/uninstall instructions in the README, so that I can manage the plugin's lifecycle.
25. As a user evaluating the plugin, I want a short demo (e.g. a recorded run), so that I can see the sync-vs-background flow before installing.
26. As a maintainer, I want the plugin versioned alongside getdocs, so that the command's expectations match the installed tool's behavior.

Implementation Decisions

• Artifact: a Claude Code plugin, not a bare skill. The distributable, marketplace-listable unit is a plugin; it bundles a /getdocs slash-command and a thin skill. (Confirm the exact plugin manifest filename/fields and the commands-vs-skills layout against current Claude Code plugin docs at build time — the decision is "a plugin with one command + a thin skill," not a specific on-disk schema.)
• The repo is also the marketplace. A marketplace manifest in the getdocs repository lists this one plugin, so a user adds the marketplace by pointing at jonbakerfish/getdocs and installs the plugin from it. One repository serves as project source + marketplace + plugin. (Confirm the marketplace manifest location and the exact add/install commands at build time.)
• Thin wrapper over the CLI (ADR-0007). The plugin contains no crawling logic. Its command is instructions the agent follows: invoke uvx getdocs crawl <url> with appropriate flags, then read the result. All Crawl/Clone behavior remains in getdocs and its existing test suite. No MCP server, no new runtime surface.
• Bootstrap via uvx. The command invokes getdocs through uvx so no prior install is required; documentation notes uv as the one prerequisite.
• Mode selection encoded in the command. The command instructs the agent to run synchronously with bounded flags (a modest --limit/--depth, relying on Scope from the Seed URL's path prefix) for a targeted section, and to run as a background task for a whole-site mirror, leveraging Claude Code's resume-on-completion. The heuristic (section vs whole-site) is part of the command's guidance.
• Outcome-driven follow-up via --summary-json (depends on Agent-native completion summary: report the Crawl/Clone Outcome #19). The command runs getdocs with --summary-json, parses the Outcome, and branches: crawled → direct the agent to grep/read output_dir and surface the Manifest; cloned → offer to serve via the generated config; truncated → suggest re-running with a higher limit. This is the single hard dependency on Agent-native completion summary: report the Crawl/Clone Outcome #19.
• Polite defaults preserved. The command does not pass --ignore-robots; getdocs's defaults (robots.txt, throttling, honest User-Agent) carry through unchanged.
• README install section. Document the add-marketplace + install commands, the uv prerequisite, and a short usage example; link it from the existing "Use with your agent" recipe delivered in Agent-native completion summary: report the Crawl/Clone Outcome #19.
• Distribution tasks (tracked, not code): submit the plugin to community plugin marketplaces / awesome-claude-code; produce a short demo recording; a Show HN is optional go-to-market.

Testing Decisions

• A markdown/JSON instruction artifact is not behaviorally unit-testable. The plugin encodes agent guidance, not Python behavior, so tests assert that the artifact is well-formed and self-consistent — not that "the agent follows the skill correctly." Behavioral correctness of crawling/cloning is already covered by getdocs's own suite (and Agent-native completion summary: report the Crawl/Clone Outcome #19's summary tests); the plugin adds no behavior to re-test.
• Manifest-validation seam (new, small, highest automated point). A test parses the plugin manifest and the marketplace manifest and asserts: required fields are present and valid; every command/skill file the manifests reference exists; and the command's invocation targets getdocs with the expected flag (--summary-json). This catches the realistic failure modes (a marketplace that won't load, a dangling reference, a command that forgot the summary flag). Prior art: the YAML-parsing assertions in test_source.py's write_mkdocs_config test — parse the produced artifact, assert its structure.
• Official validation in CI if it exists. If Claude Code ships a plugin/marketplace validation command, run it in CI as a higher-fidelity structural check (confirm availability at build time). Prior art: the existing .github/workflows/publish.yml CI pattern.
• Manual dogfooding for behavior (acceptance check, not automated). Install the plugin locally, run /getdocs <url> against a real docs site for both a section (synchronous) and a whole site (background), and confirm: correct mode selection, and correct Outcome-driven guidance for both a Crawl and a Clone. Documented as the acceptance procedure.

Out of Scope

• The completion summary itself (Agent-native completion summary: report the Crawl/Clone Outcome #19). This PRD consumes the outcome contract; it does not define or build it.
• Non-Claude-Code agents. The plugin is Claude-Code-specific. Other agents use getdocs directly via the CLI (synchronous/poll); no portable plugin abstraction is attempted here (it doesn't exist — ADR-0007's research found background-resume is Claude-Code-only).
• An MCP server or any tool-registry integration. Rejected in ADR-0007.
• Changes to getdocs crawl/clone behavior or flags beyond consuming --summary-json.
• Go-to-market execution (the actual Show HN post, blog, social) beyond preparing the demo and the marketplace/awesome-list submissions.
• Auto-installing uv/uvx for the user — documented as a prerequisite, not bootstrapped.

Further Notes

• Domain vocabulary: the plugin is a discovery/ergonomics layer over a getdocs run, which yields one Outcome — a Crawl (Pages + Manifest) or a Clone (repo + serve config) — per CONTEXT.md. The plugin branches on exactly that distinction.
• Relevant ADRs: ADR-0007 (agent integration is the CLI run by the harness — the plugin is the Claude Code packaging of that, not a new surface), ADR-0006 (source-first → the Clone Outcome the plugin must handle), ADR-0002 (subprocess-per-Crawl; the plugin just shells out).
• This is branch 2 of the agent-native plan; branch 1 is Agent-native completion summary: report the Crawl/Clone Outcome #19. The plan was reached in a grilling session; the plugin is the agent-native distribution channel that replaced the MCP-registry channel dropped when MCP was ruled out.
• Verification note: a background research attempt to pull exact plugin/marketplace manifest schemas was inconclusive during drafting; the implementing agent should confirm the current plugin manifest format, marketplace manifest location, and the exact /plugin marketplace add + install commands against https://code.claude.com/docs before building. The decisions above are stated at a level that survives schema details.