{
  "markdown": "# Doc Detective Agent Tools\n\nAgent tools for testing documentation procedures and validating that documented workflows match actual application behavior. Compatible with Gemini CLI, Claude Code, Cursor, Codex, OpenCode, GitHub Copilot, and other AI coding agents that support plugins, skills, or commands.\n\n- **Set up Doc Detective for a project.** Initialize Doc Detective in a project with automatic documentation detection, config generation, and test creation.\n- **Generate tests.** Convert documentation into executable test specifications.\n- **Run tests.** Execute tests against your application and report results.\n- **Inject tests into your docs content.** Embed test steps close to associated documentation content.\n- **Install the Doc Detective GitHub Action.** Add a Doc Detective GitHub Actions workflow for automated documentation testing in CI.\n\n## Installation\n\n### Claude Code\n\n1. Open Claude Code:\n\n   ```bash\n   claude\n   ```\n\n2. Add the Doc Detective marketplace and plugin:\n\n   ```text\n   /plugin marketplace add doc-detective/agent-tools\n   /plugin install doc-detective@doc-detective\n   ```\n\n3. Ask about Doc Detective, or use the `init` command to get started:\n\n   ```text\n   /doc-detective-init\n   ```\n\n### Gemini CLI\n\n1. Install the extension and open Gemini CLI:\n\n   ```bash\n   gemini extensions install https://github.com/doc-detective/agent-tools.git --auto-update\n   gemini\n   ```\n\n2. Ask about Doc Detective, or use the `init` command to get started:\n\n   ```text\n   /doc-detective-init\n   ```\n\n### Copilot CLI\n\n1. Open Copilot CLI:\n\n   ```bash\n   copilot\n   ```\n\n2. Install the Doc Detective plugin:\n\n   ```text\n   /plugin marketplace add doc-detective/agent-tools\n   /plugin install doc-detective@doc-detective\n   ```\n\n3. Ask about Doc Detective, or use the `init` command to get started:\n\n   ```text\n   /doc-detective-init\n   ```\n\n### Qwen Code\n\n1. Install the plugin and open Qwen Code:\n\n   ```bash\n   qwen extensions install https://github.com/doc-detective/agent-tools\n   qwen extensions install doc-detective:doc-detective\n   qwen\n   ```\n\n2. Ask about Doc Detective, or use the `init` command to get started:\n\n   ```text\n   /doc-detective-init\n   ```\n\n### OpenCode\n\n1. Clone the repository:\n\n   ```bash\n   git clone https://github.com/doc-detective/agent-tools.git\n   ```\n\n2. Copy the plugin contents to your project's `.opencode/` directory:\n\n   ```bash\n   mkdir -p .opencode/plugins\n   cp agent-tools/plugins/doc-detective/opencode-plugin.mjs .opencode/plugins/\n   cp -r agent-tools/plugins/doc-detective/hooks .opencode/\n   cp -r agent-tools/plugins/doc-detective/skills .opencode/\n   cp -r agent-tools/plugins/doc-detective/agents .opencode/\n   ```\n\n3. Start OpenCode and ask about Doc Detective, or use the `init` command:\n\n### Codex\n\n1. Clone the repo and copy the plugin and marketplace into your project:\n\n   ```bash\n   git clone https://github.com/doc-detective/agent-tools.git\n   cp -r agent-tools/plugins/doc-detective ./plugins/doc-detective\n   mkdir -p .agents/plugins\n   cp agent-tools/.agents/plugins/marketplace.json .agents/plugins/marketplace.json\n   ```\n\n2. Open Codex and install the plugin from the marketplace:\n\n   ```bash\n   codex\n   ```\n\n3. Ask about Doc Detective, or use the `init` command to get started:\n\n   ```text\n   /doc-detective-init\n   ```\n\nWhat installing the plugin gives you:\n\n- **Skills.** Running `codex plugin marketplace add <path>` then `codex plugin add doc-detective@doc-detective` loads the Doc Detective skills into Codex.\n- **MCP tools.** The plugin bundles its MCP server in `plugins/doc-detective/.mcp.json`, so the remote MCP tools auto-register on install — no manual `~/.codex/config.toml` edit required.\n- **Hooks.** Codex supports lifecycle hooks, but the tool-matched guardrails (validation, anti-pattern blocking, etc.) key on Claude's `Edit`/`Write` tool names, which Codex does not use — so they do not currently fire on Codex. They run on Claude Code, Gemini CLI, and OpenCode.\n\n### Cursor\n\nDoc Detective ships as a [Cursor plugin](https://cursor.com/docs/plugins) (Cursor 2.5+).\n\n#### Install locally (works on any plan — Free, Pro, Teams)\n\nThis is the method for an individual machine. It needs no marketplace and no Teams plan.\n\n1. Clone the repo:\n\n   ```bash\n   git clone https://github.com/doc-detective/agent-tools.git\n   ```\n\n2. Copy the plugin folder into Cursor's local plugins directory. Copy\n   `plugins/doc-detective` itself (the folder that contains `.cursor-plugin/plugin.json`):\n\n   **macOS / Linux:**\n\n   ```bash\n   mkdir -p ~/.cursor/plugins/local                 # create the dir on a fresh install\n   rm -rf ~/.cursor/plugins/local/doc-detective     # remove any previous copy first\n   cp -r agent-tools/plugins/doc-detective ~/.cursor/plugins/local/doc-detective\n   ```\n\n   **Windows (PowerShell):**\n\n   ```powershell\n   $dest = \"$HOME\\.cursor\\plugins\\local\\doc-detective\"\n   New-Item -ItemType Directory -Force -Path \"$HOME\\.cursor\\plugins\\local\" | Out-Null\n   Remove-Item -Recurse -Force $dest -ErrorAction SilentlyContinue\n   Copy-Item -Recurse agent-tools\\plugins\\doc-detective $dest\n   ```\n\n   (Creating the directory first handles a fresh Cursor install; removing any previous copy\n   avoids nesting the plugin inside an existing `doc-detective/` folder.)\n\n   When done, the manifest must sit at\n   `~/.cursor/plugins/local/doc-detective/.cursor-plugin/plugin.json` (on Windows,\n   `%USERPROFILE%\\.cursor\\plugins\\local\\doc-detective\\.cursor-plugin\\plugin.json`) — i.e.\n   **not** double-nested under a second `doc-detective/` folder.\n\n3. Reload Cursor: open the Command Palette (`Cmd/Ctrl+Shift+P`) and run\n   **Developer: Reload Window** (or quit and reopen Cursor).\n\n4. Verify: in Agent chat, type `/` and confirm the `/doc-detective-*` commands appear.\n   Then get started:\n\n   ```text\n   /doc-detective-init\n   ```\n\n> **Developing on the plugin?** Symlink instead of copying so edits show up on reload:\n>\n> ```bash\n> mkdir -p ~/.cursor/plugins/local\n> rm -rf ~/.cursor/plugins/local/doc-detective   # clear any existing copy first\n> ln -s \"$PWD/agent-tools/plugins/doc-detective\" ~/.cursor/plugins/local/doc-detective\n> ```\n\n#### With the `cursor-agent` CLI\n\nThe [Cursor CLI](https://cursor.com/docs/cli) has **no marketplace** — load the plugin with\n`--plugin-dir` (this loads the skills, agent, rule, and MCP server):\n\n```bash\ncursor-agent --plugin-dir \"$PWD/agent-tools/plugins/doc-detective\"\n```\n\n#### Via Claude Code skills/subagents (third-party import)\n\nCursor can load resources from other ecosystems. In **Settings → Rules, Skills, Subagents**,\nenable **\"Include third-party Plugins, Skills and other configs\"** — Cursor then imports\nskills and subagents from Claude Code's `~/.claude/skills` and `~/.claude/agents` (and Codex\nconfigs). So if you already run Doc Detective in Claude Code (or `npx skills add\ndoc-detective/agent-tools`), this toggle surfaces it in Cursor with no separate Cursor\nplugin. (It imports *everything* from those ecosystems, so the dedicated Cursor plugin above\nis more targeted.)\n\n#### Distribute to a team (Teams / Enterprise plans only)\n\nTeam Marketplaces are **not available on individual (Free/Pro) plans** — if you don't see\nthe option below, use the local install above. On a Teams or Enterprise plan, an admin can\nimport this repo as a custom marketplace from the **web dashboard** (not the in-app\nsettings):\n\n1. Go to [cursor.com](https://cursor.com) → **Dashboard → Settings → Plugins → Team\n   Marketplaces → Import**.\n2. Paste `https://github.com/doc-detective/agent-tools` and review the parsed plugins\n   (Cursor reads the repo's `.cursor-plugin/marketplace.json`).\n3. Assign access groups, mark the plugin Required or Optional, and save.\n\n(Auto-refresh needs the Cursor GitHub App and updates at most every 10 minutes; re-import\nthe URL to pick up newly added plugins.)\n\n#### Official marketplace (once published)\n\nAfter the plugin is listed on the [Cursor marketplace](https://cursor.com/marketplace),\ninstall it with `/add-plugin doc-detective` in Agent chat, or \"Add to Cursor\" on the\nmarketplace page.\n\nWhat installing the plugin gives you:\n\n- **Skills.** The Doc Detective skills load into Cursor and are invocable as slash\n  commands (`/doc-detective-test`, `/doc-detective-generate`, `/doc-detective-validate`,\n  `/doc-detective-inject`, `/doc-detective-init`, `/doc-detective-install-github-action`).\n- **Agent.** The `doc-detective-specialist` subagent is available for documentation-testing tasks.\n- **Rule.** A persistent \"docs as tests\" rule reminds the agent to validate and test\n  documented procedures (and to use the correct `{ \"action-name\": ... }` spec format)\n  when you edit docs or test specs.\n- **MCP tools.** The plugin registers the Doc Detective remote MCP server inline in its\n  manifest, so the MCP tools are available without a manual `.cursor/mcp.json` edit.\n- **Hooks.** Cursor's hook protocol differs from Claude's, so the plugin routes Cursor's\n  `sessionStart` and `afterFileEdit` events through an adapter\n  (`hooks/scripts/cursor-hook-adapter.js`) that reuses the shared hook scripts —\n  giving you install detection, spec validation, formatting, and anti-pattern guidance.\n  See [docs/README.cursor.md](docs/README.cursor.md) for details.\n\n### Other agents\n\n#### Option 1: Install with `npx skills`\n\n> [!WARNING]\n> `npx skills` only installs skills, not agents, commands, or other tools. For full functionality, consider [manual installation](#option-2-manual-installation).\n\nInstall these skills with the [`skills`](https://github.com/vercel-labs/skills) package from Vercel. This works with Claude Code, Cursor, Codex, OpenCode, and other AI coding tools.\n\n```bash\nnpx skills add doc-detective/agent-tools\n```\n\nFollow the prompts. The CLI auto-detects which AI tools you have installed and places the skills in the appropriate directories.\n\n#### Option 2: Manual Installation\n\n#### Copy to your project directory\n\n```bash\ngit clone https://github.com/doc-detective/agent-tools.git\n\ncp -r agent-tools/agents .{agent-dir}/agents      # Agents\ncp -r agent-tools/commands .{agent-dir}/commands  # Commands\ncp -r agent-tools/skills .{agent-dir}/skills      # Skills\ncp -r agent-tools/hooks .{agent-dir}/hooks        # Hooks\n```\n\n> [!IMPORTANT]\n> Adjust the destination path based on your agent's expected skill/plugin directory. For example, `.agents` for Codex, `.cursor` for Cursor, etc.\n\n## Usage\n\n### Bootstrap Doc Detective for a Project\n\n```bash\n/doc-detective-init\n```\n\nInitializes Doc Detective in your repository by:\n1. Detecting documentation files\n2. Generating a minimal configuration\n3. Creating tests for identified procedures\n4. Running tests\n5. Iteratively fixing failures with confidence-based suggestions\n\n### Convert Documentation to Tests\n\n```bash\n/doc-detective-generate path/to/documentation.md\n```\n\nIdentify testable procedures and convert them into Doc Detective test specifications.\n\n### Run Tests\n\n```bash\n/doc-detective-test path/to/documentation.md\n```\n\nRuns tests from docs or test specification files:\n\n1. Extracts step-by-step procedures from your documentation.\n2. Converts them to Doc Detective test specifications.\n3. Validates the test specs.\n4. Executes tests using Doc Detective.\n5. Reports results with any failures mapped back to documentation sections.\n\n### Validate Test Specifications\n\n```bash\n/doc-detective-validate test-spec.json\n```\n\nValidates structure before execution:\n\n- Required fields present\n- Action types recognized\n- Parameter types correct\n\n### Inject Tests into Documentation\n\n```bash\n/doc-detective-inject tests/spec.yaml docs/procedure.md --apply\n```\n\nTakes a well-formed test specification and injects test steps as inline comments into the associated documentation content so you don't have to maintain separate files.\n\n### Install the Doc Detective GitHub Action\n\n```bash\n/doc-detective-install-github-action [options]\n```\n\nInstalls a Doc Detective GitHub Actions workflow for automated documentation testing in CI:\n\n1. Detects project context (config files, docs directory, existing workflows).\n2. Generates a workflow YAML with configurable triggers and optional features.\n3. Writes the workflow to `.github/workflows/doc-detective.yml`.\n4. Reports manual steps needed (e.g., enabling Actions permissions).\n\n| Option | Default | Description |\n|--------|---------|-------------|\n| `--trigger <event>` | `pull_request` | Workflow trigger (`pull_request`, `push`, `schedule`, etc.) |\n| `--exit-on-fail` | false | Fail CI when tests fail |\n| `--create-pr-on-change` | false | Open a PR when files change during test execution |\n| `--create-issue-on-fail` | false | Create a GitHub issue when tests fail |\n| `--integrations <list>` | (none) | Comma-separated integrations to mention in issues |\n| `--ci` | false | Non-interactive; use defaults, no prompts |\n\n## Doc Detective Actions Reference\n\nThe plugin includes complete documentation for Doc Detective actions:\n\n| Action                    | Purpose                              |\n| ------------------------- | ------------------------------------ |\n| `goTo`                    | Navigate to a URL                    |\n| `click`                   | Click an element (prefer text-based) |\n| `find`                    | Verify an element exists             |\n| `type`                    | Type text input                      |\n| `httpRequest`             | Make HTTP requests                   |\n| `runShell`                | Execute shell commands               |\n| `screenshot`              | Capture screenshots                  |\n| `wait`                    | Pause or wait for elements           |\n| `checkLink`               | Verify URL returns OK                |\n| `loadVariables`           | Load environment variables           |\n| `saveCookie`/`loadCookie` | Manage session persistence           |\n| `record`/`stopRecord`     | Video recording                      |\n\nSee `skills/doc-detective-doc-testing/references/actions.md` for detailed documentation.\n\n## Hooks\n\nThe plugin includes hooks that activate automatically when installed. Hooks provide deterministic guardrails that run at key points during your agent session — no configuration required.\n\n| Hook | Trigger | Behavior |\n|------|---------|----------|\n| **Test spec validation** | After editing a `.json` test spec | Automatically validates the spec structure and reports errors |\n| **Action anti-pattern blocker** | Before writing test spec content | Blocks the common mistake of `{\"action\": \"goTo\"}` — the correct format is `{\"goTo\": \"url\"}` |\n| **Documentation test reminder** | After editing a documentation file | Suggests running `/doc-detective-test` if the project has a Doc Detective config |\n| **Installation check** | Session start | Checks if the Doc Detective CLI is available and provides installation instructions if not |\n| **Test spec formatting** | After editing a `.json` test spec | Normalizes JSON formatting to 2-space indentation |\n| **Inline test warning** | After editing a doc with inline tests | Warns that inline Doc Detective test comments may need updating |\n\nHooks are supported in Claude Code, Gemini CLI, and OpenCode. Other agents can use the shared scripts in `hooks/scripts/` with their own hook configuration.\n\n## Language server (LSP)\n\nOn **Claude Code**, the plugin bundles a Doc Detective language server that gives the agent live, authoring-time feedback on test specs — the same schema knowledge the runner validates against, surfaced the moment a spec is edited rather than only when it runs.\n\n| Capability | Behavior |\n|------------|----------|\n| **Diagnostics** | Schema errors are reported inline as you edit `*.spec.json` / `*.spec.yaml` and `.doc-detective.*` config files, and inside inline Doc Detective tests in Markdown/AsciiDoc/HTML/DITA. The `action`-keyed anti-pattern (using an `action` property instead of the compact action-as-key form) gets one clear message instead of a wall of schema errors. |\n| **Completion** | Action keys and their fields, with schema-aware value snippets. |\n| **Hover** | Action descriptions pulled straight from the schema. |\n\nThe server activates automatically on install. It launches through `lsp/lsp-launch.js`, which resolves the Doc Detective CLI in the same order as the install check — a project-local install first (so a workspace's pinned version wins), then a global `doc-detective`, then `npx`. LSP is a Claude Code capability, so this does not apply to the other hosts.\n\n## Inline Test Injection\n\nInject test steps from separate spec files directly into documentation as inline comments:\n\n```bash\n/doc-detective-inject tests/login.yaml docs/login.md --apply\n```\n\n**Before:**\n\n```markdown\n1. Go to [Login Page](https://example.com/login).\n2. Click **Sign In**.\n```\n\n**After:**\n\n```markdown\n1. Go to [Login Page](https://example.com/login).\n<!-- step {\"goTo\":\"https://example.com/login\"} -->\n2. Click **Sign In**.\n<!-- step {\"click\":\"Sign In\"} -->\n```\n\nSteps are matched to content using semantic patterns (links, bold text, action verbs) and placed close to their associated documentation.\n\n## Examples\n\n### Test a Login Procedure\n\nDocumentation:\n\n```markdown\n# Login Procedure\n\n1. Navigate to https://example.com/login\n2. Enter your username\n3. Enter your password\n4. Click \"Sign In\"\n5. Verify you see the Dashboard\n```\n\nUse the skill:\n\n```\n/doc-detective-test path/to/file.md this login procedure from our docs to make sure it still works\n```\n\n### Test Multiple Workflows\n\nCreate a test specification file `workflows.json`:\n\n```json\n{\n  \"tests\": [\n    {\n      \"testId\": \"signup-flow\",\n      \"description\": \"New user signup\",\n      \"steps\": [\n        { \"goTo\": \"https://example.com/signup\" },\n        { \"find\": \"Create Account\" },\n        { \"type\": { \"keys\": \"newuser@example.com\", \"selector\": \"#email\" } },\n        { \"click\": \"Sign Up\" },\n        { \"find\": \"Welcome\" }\n      ]\n    },\n    {\n      \"testId\": \"password-reset\",\n      \"description\": \"Forgot password flow\",\n      \"steps\": [\n        { \"goTo\": \"https://example.com/login\" },\n        { \"click\": \"Forgot Password\" },\n        { \"type\": { \"keys\": \"user@example.com\", \"selector\": \"#email\" } },\n        { \"click\": \"Reset\" },\n        { \"find\": \"Check your email\" }\n      ]\n    }\n  ]\n}\n```\n\nThen execute:\n\n```\n/doc-detective-test workflows.json\n```\n\n## Resources\n\n- [Doc Detective Documentation](https://doc-detective.com)\n- [Doc Detective GitHub](https://github.com/doc-detective/doc-detective)\n- [Test Specification Format](https://doc-detective.com/docs/get-started/doc-detective-tests)\n- [Actions Reference](https://doc-detective.com/docs/category/actions)\n\n## MCP server\n\nDoc Detective hosts a remote Model Context Protocol server at `https://agency.doc-detective.com/mcp` that exposes three tools to MCP-compatible clients:\n\n| Tool | Purpose |\n|------|---------|\n| `detect_tests` | Parse documentation content into a resolved Doc Detective test plan. |\n| `validate_spec` | Validate a spec, config, test, step, or context object against `doc-detective-common` schemas. |\n| `log_observation` | Send anonymous, agent-initiated feedback to Doc Detective for roadmap improvement. Never carries user content. |\n\nWhen you install the plugin or extension, the MCP server is auto-registered for:\n\n- **Claude Code** (via plugin)\n- **Gemini CLI** (via extension)\n- **Qwen Code** (via extension)\n- **OpenCode** (via plugin)\n- **Codex** (via the plugin's bundled `.mcp.json`)\n\nFor the hosts below, paste the snippet into the indicated config file:\n\n### Cursor — `.cursor/mcp.json`\n\n```json\n{\n  \"mcpServers\": {\n    \"doc-detective\": {\n      \"url\": \"https://agency.doc-detective.com/mcp\",\n      \"headers\": { \"X-DD-Client\": \"cursor\" }\n    }\n  }\n}\n```\n\n### Codex — `~/.codex/config.toml`\n\nInstalling the Codex plugin auto-registers the MCP server from its bundled `.mcp.json`. If you installed only the skills (e.g. via `npx skills`), register it manually instead:\n\n```toml\n[mcp_servers.doc-detective]\nurl = \"https://agency.doc-detective.com/mcp\"\nhttp_headers = { \"X-DD-Client\" = \"codex\" }\n```\n\n### Copilot CLI — `~/.copilot/mcp-config.json`\n\n```json\n{\n  \"mcpServers\": {\n    \"doc-detective\": {\n      \"type\": \"http\",\n      \"url\": \"https://agency.doc-detective.com/mcp\",\n      \"headers\": { \"X-DD-Client\": \"copilot-cli\" }\n    }\n  }\n}\n```\n\n### Privacy\n\nThe server only receives the arguments you pass to its tools. The `X-DD-Client` header identifies the host (e.g., `claude-code`, `gemini-cli`) — no personally identifying information. The `log_observation` tool is reserved for abstract feedback only — never file paths, URLs, selectors, or spec contents. To opt out, remove the `mcpServers` (or `mcp`) entry from your host's config.\n\n## Repository Structure\n\nSource content lives in `src/`. The build system (`npm run build`) generates downstream artifact directories that consumers install:\n\n| Directory | Description |\n|-----------|-------------|\n| `src/agents/` | Agent definitions (source of truth) |\n| `src/skills/` | Skill implementations — SKILL.md, references/, scripts/ (source of truth) |\n| `src/hooks/` | Hook scripts and platform-specific configs (source of truth) |\n| `agents/` | Copied from `src/agents/` (build artifact) |\n| `skills/` | Copied from `src/skills/` (build artifact) |\n| `hooks/` | Copied from `src/hooks/` (build artifact) |\n| `commands/*.md` | Generated from user-invocable skills (build artifact) |\n| `commands/doc-detective/*.toml` | Generated from command .md files for Gemini CLI (build artifact) |\n| `plugins/doc-detective/` | Copied from `agents/`, `skills/`, and `hooks/` (build artifact) |\n| `plugins/doc-detective/opencode-plugin.mjs` | OpenCode plugin — wraps hook scripts as OpenCode hooks (build artifact) |\n| `plugins/doc-detective/.codex-plugin/plugin.json` | Codex plugin manifest — version synced from package.json; includes `mcpServers: \"./.mcp.json\"` when Codex MCP servers are enabled (build artifact) |\n| `plugins/doc-detective/.mcp.json` | Codex MCP registration generated from enabled `src/mcp-servers.json` entries; removed when none are enabled (build artifact) |\n| `.agents/plugins/marketplace.json` | Codex marketplace pointing to `plugins/doc-detective/` |\n\n> [!NOTE]\n> Do not edit files in `agents/`, `skills/`, `hooks/`, `commands/`, or `plugins/` directly. Edit the source in `src/` and run `npm run build`.\n\n## License\n\nAGPL3\n\n## Contributing\n\nTo contribute improvements to this plugin, submit issues or pull requests to the repository.\n",
  "bytes": 22431,
  "sha": "d37078d255309dc488313acc2905dd8ed8e15585909ce9ea1ebd756dccb89592",
  "repo_slug": "doc-detective/agent-tools",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/plg_doc_detective_agent_tools_e553364c/readme"
}