Docko Adapters

---
name: docko-adapters
description: Runtime adapter guidance for the docko repository. Use when working on runtime-specific packages, template installers, hook flows, snippet assets, runtime documentation, or when extending support beyond the current Claude Code adapter.
---

# docko Adapters

Rules for working on docko's runtime adapters. Use it before changing adapter packages, templates,
or the plugin bundle.

## Read first

- `docs/adapter-spec.md`
- `docs/claude-code.md`
- `docs/agents-md-runtimes.md`
- `packages/adapters/claude-code/src/index.ts`
- `packages/adapters/claude-code/plugin/` (canonical hook launcher, commands, skill, hooks manifest)
- `packages/adapters/claude-code/templates/project/.claude/snippets/`
- `tests/claude-code-adapter.test.mjs`, `tests/claude-plugin.test.mjs`
- For Codex-specific wording, verify `AGENTS.md`, skills, subagents, and hooks claims against official OpenAI docs.

## Reference model

- Treat the Claude adapter as the reference implementation for installer structure, template layout, and runtime-to-protocol mapping.
- Be explicit about what is implemented versus what is only documented or planned.
- Claude Code is the only implemented runtime adapter today.
- Codex guidance is currently manual and docs-driven. Do not imply a shipped Codex adapter unless this repo gains a package, templates, and tests for it.
- OpenAI documents Codex hooks, including Windows-specific command and managed-directory fields. Do not present hooks as docko's default Codex path until this repo ships and tests a dedicated Codex adapter.

## Change rules

- Keep adapters thin and avoid changing ownership semantics in adapter code.
- Put runtime-specific templates, snippets, and helper assets beside the adapter that owns them.
- Update the plugin bundle, snippets, examples, docs, and tests together. The bundle is the single source for the launcher, commands, and skill; the repo-local installer copies from it, and this repository's own `.claude-plugin/docko` and `.claude` assets must stay identical to it.
- Keep the two install paths in sync: matchers, timeouts, and subcommands are asserted against `plugin/hooks/hooks.json`.
- Bump the launcher's `// docko-launcher-version:` header with the packages (`scripts/bump-version.mjs` does it).
- If runtime-specific commands are added to the CLI, document them in `docs/cli-reference.md`.
- For Codex or OpenAI-specific guidance, verify against official OpenAI docs before writing instructions.
- For future runtimes, keep design notes clearly labeled as future or guidance-only until implementation exists.

## Verify

- `pnpm build`
- `pnpm check`
- `pnpm test`
- Focus on `tests/claude-code-adapter.test.mjs` plus any new adapter coverage when verification needs to be selective.