Reference
Agent adapters
An adapter connects the same installed domain to a client's native instructions, skills, and supported hooks.
There is no persisted active agent in .cumaru/config.yaml. Commands name their adapter target explicitly. Adapters may coexist in one project.
Generated artifacts
| Adapter | Instructions | Skills | Launchers | Hook configuration |
|---|---|---|---|---|
none | .agents/AGENTS.md | .agents/skills/cumaru-* | .agents/commands/cumaru/ | None |
claude | CLAUDE.md | .claude/skills/cumaru-* | Native skills | .claude/settings.json |
codex | AGENTS.md | .agents/skills/cumaru-* | Native skills | .codex/hooks.json |
opencode | opencode.json instructions array | .agents/skills/cumaru-* | .opencode/commands/cumaru/ | None |
Generic and OpenCode receive command launchers that forward arguments to installed skills. Claude and Codex invoke skills directly. The launchers carry no second workflow recipe.
Sources: artifact and invocation matrix and native adapter implementation.
Fresh installation or another adapter
Inside a project without .cumaru/, choose a domain and adapter. This example chooses SDLC Light and Codex:
cumaru install agent codex --domain sdlc-light Install refuses an existing .cumaru entry. To add or refresh another complete adapter in an installed project, preview the explicit target and then apply the reviewed change:
cumaru update agent claude Review the displayed changes. Apply them only after that review:
cumaru update agent claude --apply update skills refreshes the selected skills surface. It is not a substitute for the complete update agent integration. Opt-in skills are added separately through update skills <agent> --with <skill> --apply.
Sources: installation and adapter update modes.
Context loading
- Load the kernel
index.md, thendomain.md. - Load
disciplines/index.md, then every installed discipline. - Project the current root candidates with
cumaru tree .. - Let the role and task select relevant knowledge through the loading rule.
Claude and Codex receive session and per-prompt hook payloads; their managed instruction block retains a fallback pointer for missing context. Generic embeds discipline bodies in its managed block. OpenCode registers the native instruction entries for the kernel, domain and discipline glob.
The OpenCode instructions array keeps exactly one occurrence of each Cumaru entry in kernel, domain, disciplines order. Project-owned entries retain their relative order. Its existing integration has no Cumaru session-start hook; do not assume parity with Claude or Codex.
Source: context bootstrap.
Invocation is client-specific
Invoke the installed skill through the client's native skill interface. Codex can use $cumaru-role lead where the domain declares Lead. Claude uses its native skill invocation. Generic launchers use forms such as /cumaru:role <role>; OpenCode uses /cumaru/role <role>.
The role and its name must exist in the selected domain. Reloading a role changes context; it does not write an active-role setting. A slash launcher is not a native CLI command.
Sources: role skill contract and supported launchers.
Merge and removal boundaries
Managed instruction blocks and supported configuration are merged with adopter files. Hook registration preserves unrelated events and commands, including unrelated commands that share an event entry. Reapplying the same integration is idempotent.
Explicit adapter cleanup removes Cumaru-owned artifacts, not arbitrary project configuration. --clear mutates immediately after its recovery check; it is not a preview. Full uninstall targets all adapters and removes adopter knowledge under its explicit confirmation contract.
Inspect update and clear semantics before choosing a cleanup operation.
Check the actual integration
Run doctor for the configured tree and instruction checks. Then inspect the expected skill and hook files and open a new context in the intended client, respecting its reload and trust prompts. Confirm the expected session context or a visible diagnostic.
A successful doctor report only establishes its checked instruction surface; it does not validate every skill, launcher, or hook, and it does not prove the client executed a hook.
Read the hook reference for event behavior and diagnostics, or follow the adopter setup guide.