# Host adapters

> **Generated file.** Do not hand-edit. Source: `pyproject.toml` `[tool.sumo-qa.plugin]`.
> Regenerate with `python -m plugin_packaging.plugin_generator sync`.

`sumo-qa` ships first-class plugin folders for two hosts today:

| Host | Manifest | Published JSON Schema | Validation in CI |
| --- | --- | --- | --- |
| Claude Code | `.claude-plugin/plugin.json` | https://json.schemastore.org/claude-code-plugin-manifest.json | Schema validation against vendored copy |
| OpenAI Codex | `.codex-plugin/plugin.json` | _none published_ | MCP `initialize` handshake smoke |

Both adapters share `.mcp.json`, `skills/`, and `assets/`. Hook files
diverge by schema (`hooks/hooks.json` for Claude Code, `hooks/hooks-codex.json`
for Codex) but are generated from the same `[[tool.sumo-qa.plugin.hooks]]`
overlay in `pyproject.toml`.

## Marketplace copy

Marketplace-facing copy is canonical in `pyproject.toml`
`[tool.sumo-qa.plugin]` and propagates ONLY through the generator; no
host template duplicates it. `short_description` (capped at 200 chars by
the canonical loader) is available to any host field that wants short
copy; the `[project]` description stays the default `description` in the
host manifests. Visual assets live in `assets/` (icon + preview) and are
regenerated by `scripts/generate_marketplace_assets.py`.

- **Display name:** Sumo QA
- **Category:** testing
- **Keywords:** `qa`, `testing`, `tdd`, `mutation-testing`, `mcp`, `claude-code`, `codex`
- **Short description:** A QA-native MCP server and skills library: analyze a repo, map risks to tests and evidence, plan and scaffold tests, strengthen weak suites, and review diffs before merge with senior-QA discipline.

Sumo QA packages a senior QA engineer's working discipline as an MCP server with a bundled skills library. It drives the QA loop end to end: analyze the repository to understand what it does, map named risks to the tests and evidence that would catch them, decide a grounded test approach, then do the work: test plans, TDD scaffolding, mutation-testing follow-up, test-data discovery, and pre-merge diff review.

Every recommendation cites a curated QA catalogue of principles, techniques, classifications, and approaches instead of improvised advice, so guidance stays consistent across hosts and models. It ships as a standard stdio MCP server: install with pip, wire it into a supported host with one command, and verify the setup with the bundled doctor.

## Architecture

The canonical source is `pyproject.toml`:

- Shared metadata (`name`, `version`, `description`, `license`,
  `author`, `homepage`, `repository`) flows from `[project]` and
  `[project.urls]`. It is not duplicated.
- Plugin-specific overlay lives under `[tool.sumo-qa.plugin]`.

The generator (`python -m plugin_packaging.plugin_generator sync`)
reads this canonical source, emits every committed plugin folder, and
writes a SHA256 sidecar at `plugin_packaging/generated/manifest.json`.
CI runs `python -m plugin_packaging.plugin_generator check` on every PR;
if any emitted file drifts from the canonical source, the gate fails.

## Wheel-vs-repo path resolution

- `pip install sumo-qa && sumo-qa-install`: installer resolves bundled
  content from `<site-packages>/sumo_qa/_data/{skills,hooks,assets}/`.
- `claude plugin install <repo>` / git clone: content lives at repo
  root; plugin manifests use repo-root-relative paths (`./skills/`,
  `./hooks/hooks.json`).

The wheel bundles `skills/`, `hooks/`, and `assets/` via
`[tool.hatch.build.targets.wheel.force-include]` so both layouts work
out of the box.

## Adding a new host

1. Add `plugin_packaging/templates/<host>.py` rendering
   `CanonicalPlugin -> dict`.
2. Wire it into `plugin_packaging/plugin_generator.py`'s sync map.
3. Run `python -m plugin_packaging.plugin_generator sync`.
4. If the host publishes a JSON Schema, vendor it under
   `plugin_packaging/schemas/` and add a validation case to
   `plugin_packaging/validate_plugins.py`. Otherwise, extend the
   install-smoke matrix with a `--plugin-dir`-style MCP handshake.

## Supported adapters

- **Claude Code**: `.claude-plugin/plugin.json` auto-discovers `skills/`,
  `hooks/`, and `.mcp.json`. Two load paths: `claude --plugin-dir <repo>`
  (session-scoped local-dev), or persistent marketplace install; add this
  repo as a marketplace and install the plugin:

      /plugin marketplace add sumithr/sumo-qa
      /plugin install sumo-qa@sumo-qa

  The marketplace catalog (`.claude-plugin/marketplace.json`) is generated
  from the same canonical source and lists this repo as a single plugin
  whose source is the repo root. **Note:** the marketplace add → install
  flow is wired and schema-valid but has not yet been run end-to-end in a
  live Claude Code session; treat the live install as unverified until that
  confirmation is recorded.
- **Codex**: `.codex-plugin/plugin.json` declares explicit `skills` /
  `mcpServers` / `hooks` paths. The install + MCP-server-launch flow
  hasn't been verified end-to-end yet; treat as TBD until confirmed.

The `pip install sumo-qa && sumo-qa-install` flow is the canonical
persistent install for every host (Claude Code, Claude Desktop, VS Code,
JetBrains). See [INSTALL.md](INSTALL.md).
