Contributing a New Coding Agent Host

August 4, 2026 · View on GitHub

Adding a Coding Agent is not one manifest or one transcript parser. It is a set of independently evidenced support claims: native discovery, configured assets, session evidence, shared workflow activation, output routing, and packaging. Implement only the slices the host can support, and mark every other slice as partial or unavailable.

This guide is the canonical contribution workflow for a new host. Before editing, read the repository agent instructions, contribution guide, architecture principles, directory ownership ADR, community extension map, and host adapter matrix. Current repository contracts take precedence over the worked pull requests at the end of this guide.

1. Define the Support Claim

Start with a dated spec under docs/specs/ as required by AGENTS.md. Give each claimed slice a stable acceptance id and an evidence route. Use [NEEDS CLARIFICATION: ...] instead of guessing a host contract.

Slice	Decide explicitly	Canonical owner	Minimum evidence
Native contract	Host/version, primary source, supported lifecycle	Spec and PR evidence	Versioned official docs or host source
Shell and discovery	Native manifest, source-local shell, generated shell, or none	Thin host metadata root; generated artifacts under `scripts/packaging/`	Native install/link/discovery smoke or unavailable note
Configured assets	Available, partial, or unavailable scopes	`scripts/agent-customize/providers/<host>.mjs`	Sanitized fixtures plus bounded real-host inventory smoke
Session evidence	Available, partial, or unavailable fields/events	`scripts/session-analysis/platforms/<host>.mjs`	Deterministic fixtures plus workspace-qualified source/facts smoke
Shared registration	Which public commands accept the host	`scripts/host-support/` support slices plus capability-owned registries and CLIs	Catalog mapping, help, unknown-host, delegation, and bundle tests
Plugin lifecycle	Better Harness install/status/verify dispositions by native surface	`scripts/host-support/profiles/<host>.mjs` plus `scripts/plugin-lifecycle/`	Profile validation, redacted native-help evidence, deterministic plan, and read-only fixture tests
Output	Existing Canvas, HTML, Markdown, or a justified new mode	`templates/reporting/` and report routing	Validated render for the claimed mode
Packaging	npm metadata root, runtime bundle, source-only, or none	`package.json` and `scripts/npm-package/`	`npm run pack:verify` when shipped files change
Documentation	Positioning, paths, coverage, smoke, limitations	host adapter matrix and capability references	Link checks and commands matching observed behavior

A shell does not prove configured-asset or session support. A session parser does not prove the Skill is natively discoverable. Do not register one slice merely to make another slice appear complete.

Capability levels

Not every host lands with full end-to-end support. Be explicit about which of these levels the contribution reaches, and do not promote a host to the next level until the corresponding evidence exists:

Level	What it means	Minimum evidence	Public visibility
Partial adapter	Some slices work (often shell, configured assets, or sessions) while others are partial or unavailable.	Spec names claimed, partial, and unavailable slices; provider/session tests pass for the claimed subset.	Matrix and docs list the host with explicit limitations; do not add to the public Quickstart list.
Verified install/discovery	The native install, link, or discovery command is smoke-tested and the Skill loads.	Native CLI smoke in an isolated home/config when possible; fallback is a pinned official doc reference plus a recorded evidence boundary.	README Installation section may list the host; still not Quickstart unless the report loop is validated.
Public Quickstart-ready	Full report loop works: install/discovery, configured assets, session evidence (when claimed), output routing, and a validated report render.	End-to-end report generation on a real or representative repository; tests cover the public-entrypoint set.	Host appears in the README Quickstart list, Docusaurus home-page cards, and installation tabs.

A host can be merged at the partial or verified level and later promoted to public Quickstart-ready once the report loop evidence is complete.

2. Verify the Native Host Contract

Do not derive a new host contract by renaming another adapter. Record the host version and primary evidence in the spec or pull request, then verify the parts that affect the proposed support:

the native manifest filename, schema, discovery order, install/link command, and version rules;
configuration, runtime, cache, and session roots, including environment and CLI override precedence;
every primary and secondary configured-asset root the provider reads, such as a state database, shared client cache, or user-level compatibility directory, plus a redacted fallback label and its relocation below an isolated --host-home;
workspace identity and path normalization for spaces, Unicode, punctuation, Windows drive letters, case differences, symlinks, and case-insensitive file systems;
trust, extension enablement, configuration precedence, and inline settings that can add Skills, hooks, MCP servers, rules, or commands;
session event shape, call/result correlation, terminal statuses, unknown event handling, compaction, subagent, permission, and usage fields;
privacy boundaries: which fields are required for evidence, which may contain credentials or user content, and which must never leave the local machine.

Use real host data only for a bounded local smoke. Commit deterministic, synthetic, and redacted fixtures; never commit raw transcripts, prompts, credentials, tokens, or machine-specific absolute paths.

3. Keep the Host Shell Thin

Add a host metadata root only when the native host needs one. The shell may own install and discovery metadata and pointers to canonical root Skills. It must not copy product judgment, scoring, evidence rules, or report contracts out of skills/, models/, references/, templates/, or capability-owned scripts.

When the shell ships in the public package, align its version with the package, add it to the package whitelist and verifier, and prove native discovery with the actual host CLI. Generated host artifacts remain validation/install output; their canonical source belongs under scripts/packaging/ after the matrix split triggers justify a builder.

4. Add Configured-Asset Evidence

A provider under scripts/agent-customize/providers/ should:

keep Plugin, user, project, and inherited scopes distinct;
follow native precedence and effective enablement rather than only checking whether a file or directory exists;
include native inline configuration sources when the host supports them;
honor documented CLI and environment overrides, including empty and malformed values, without silently falling back to unrelated data;
emit metadata needed for review without serializing secret values or private file contents;
remain deterministic and fail closed when identity, trust, or ownership is ambiguous.

Register the provider through its capability-owned index. Then trace the host id through every public inventory, lint, evidence-bundle, help, and report path that claims configured-asset support.

5. Add Session Evidence Only When It Is Defensible

A platform adapter under scripts/session-analysis/platforms/ should qualify a session to the requested workspace before it can influence a report. Normalize only observed fields into the existing session contracts:

preserve or explicitly account for unknown events instead of silently dropping them;
represent missing token usage or lifecycle fields as unobserved, not zero;
map cancelled, rejected, failed, and successful operations according to the host's native states;
correlate calls and results with native ids and deterministic fallbacks;
deduplicate canonical paths and session identities without double-reading the same file on a case-insensitive filesystem;
keep partial transcript, metadata, and audit coverage visible in output.

If local sessions are unavailable, unstable, encrypted, or cannot be matched to the workspace safely, document session evidence as unavailable. Shell or asset support can still land independently.

6. Propagate the Host Identity Deliberately

Add stable identity, display, home-option, and independently evidenced support slices to scripts/host-support/index.mjs. Do not claim every capability by default: Kimi and Grok, for example, can remain absent from Checkup while their configured-asset and session adapters are available.

Executable imports remain explicit in each capability. Register only the provider, analyzer, report, or packaging slices backed by the spec and tests, then search for host-specific native behavior that cannot be projected from the catalog:

rg -n "<host-id>|<Host Display Name>" scripts test references templates docs package.json

Use the results as an inventory, not a replacement template. Typical capability composition surfaces include:

scripts/host-support/profiles/<host>.mjs for the lifecycle shadow profile; use profile-builders.mjs constructors, let profile-model.mjs validate and deeply freeze the declaration locally, and keep profiles.mjs as an import-only composition root. Do not defer a malformed profile to aggregate registry validation. Declare every provider primary and secondary inventoryHomeRoutes entry there with its option, isolated relative path, and redacted safe fallback; do not let a state file, shared cache, or compatibility root fall back to the real user home when --host-home is supplied. Declare the surface observation kind and discovery source (executable, diagnostic, or unobserved) there as well; do not let one surface inherit another surface's executable or provider-state evidence. Use scopeArtifactPolicy: shared only when versioned native evidence proves that scopes mutate one artifact, and declare nativeHomeBinding only when the cited native contract proves the environment or config override applies to the emitted steps. Otherwise an isolated mutation plan must fail closed and must not emit an unbound native verification step. Do not add a host-id branch to lifecycle status or a second target resolver to status/plan. Host work must not copy plugin leaf metadata into either the root registry or lifecycle CLI, or construct status rows outside the shared status-row factory. Do not construct lifecycle plans, duplicate transition policy, or label verification as a mutation outside the shared plan-model factory;
scripts/agent-customize/providers/index.mjs and its public inventory CLI;
scripts/session-analysis/analyzer.mjs and the platform loader/help contract;
scripts/harness-analysis/evidence-bundle/ provider validation and routing;
report and output-mode composition roots whose support differs by host;
host-native defaults, environment variables, state files, cache roots, and privacy predicates that do not belong in the stable identity catalog;
package whitelists and manifest-version checks, when a shell ships;
deterministic help snapshots and tests that intentionally lock the public host list.

Do not add a capability claim unless its executable composition and tests are present. Catalog-derived gates must fail closed, and capability-mapping tests must detect both a claimed slice without an implementation and an implementation without a claim. Prefer a visible unsupported error over a host id that falls through to another provider.

7. Build an Evidence Ladder

Map tests to the spec acceptance ids. At minimum, cover the risks that apply to the host:

Risk	Fixture or check
Invented native contract	Pinned source/doc reference plus native CLI smoke
Path mismatch	POSIX and Windows paths, spaces, Unicode, punctuation, case, symlink/canonical identity
Wrong home or precedence	CLI override, environment override, default, empty, and malformed cases
Foreign workspace evidence	Positive and negative workspace qualification fixtures
Lost or inflated events	Unknown events, missing fields, call/result correlation, every terminal status
Duplicate evidence	Canonical-path and case-insensitive deduplication fixture
Secret leakage	Credential-shaped fixture with value-level non-disclosure assertions
Packaging drift	Manifest presence/version assertions and `npm run pack:verify`

During development, run focused provider, session, manifest, bundle, and CLI tests. Before review, run the full repository suite. When Markdown is added or moved, regenerate and verify the link graph:

node scripts/doc-link-graph/cli.mjs skills/better-harness
node --test test/doc-link-graph.test.mjs
npm test
npm run pack:verify
git diff --check

Run npm ci and npm run build from docs/ when the published site changes. CI must cover Windows, macOS, and Linux for cross-platform paths or filesystem behavior. A real-host smoke should separately prove native discovery, configured assets, session source/facts when claimed, evidence-bundle propagation, and a validated report render. Record unavailable checks honestly.

8. Document and Review the Delivered Boundary

Update the host adapter matrix with positioning, shell, configured assets, session evidence, default output, rules/prompts, and a reproducible smoke route. Add or update capability references for host-specific paths and evidence limits. Add README installation instructions only after the native command has been verified. Use a host-specific adapter page only when the matrix's split triggers are met.

Before commit or review, use the Change Traceability Review in Review Readiness Check mode. The pull request should state:

the host/version and primary contract evidence;
the claimed and unavailable support slices;
spec and acceptance ids, changed canonical owners, and explicit non-goals;
exact focused, full-suite, native-smoke, cross-platform, and packaging results;
privacy, compatibility, generated-file, rollback, and residual risks;
AI involvement and the human verification performed.

Use the repository pull request template. Do not infer Story ids, AI involvement, CI status, or native compatibility from branch names, prose, passing synthetic tests, or similarity to another host.

Worked Pull Request Examples

These examples are review material, not templates to copy verbatim. Re-check their latest diff and status before citing them.

PR #6: Qwen Code host adapter shows why native source verification matters. Its review and follow-ups cover manifest identity, config/runtime roots, path sanitization, effective enablement, inline MCP/hooks, terminal statuses, environment precedence, credential boundaries, and case-insensitive filesystem deduplication. The key lesson is that a green suite can consistently encode the wrong host contract.
PR #22: GitHub Copilot as a first-class host shows a spec-led decomposition across shell, configured assets, sessions, shared registries, docs, and fixtures. Its evidence model keeps missing usage fields explicit, rejects foreign-workspace sessions, and accounts for unknown event types. Because review can change the PR, treat it as an evolving example, not proof that a capability is merged or released.