Skip to the content.

Writing an adapter

A harness adapter is the “compiler backend” that turns canonical components into one harness’s native plugin format. It is a plain object implementing HarnessAdapter from @michaelfromyeg/weft-adapter-kit, and it depends only on @michaelfromyeg/weft-adapter-kit and @michaelfromyeg/weft-schema, never on core internals. The consumer (the CLI, or an embedding app) registers it.

The contract

import type { HarnessAdapter } from "@michaelfromyeg/weft-adapter-kit";

export const myAdapter: HarnessAdapter = {
  target: "myharness",            // must be a known Target (extend @michaelfromyeg/weft-schema's enum)
  version: "0.1.0",               // this adapter package's version (lockfile axis 3)
  targetSchema: "myharness/1.0",  // the harness manifest schema version you emit
  harness: {                      // optional: upstream harness CLI + supported range (axis 4)
    name: "My Harness",
    versionCommand: "myharness --version",
    range: ">=1.0.0 <2.0.0",      // the harness version range your emitted format is verified against
  },

  detect(scope, cwd) { /* InstallPaths for user|project */ },
  transform(component, ctx) { /* one component -> native artifacts */ },
  emitManifest(plugin, ctx) { /* plugin-level manifest, or [] */ },
  emitCatalog(marketplace) { /* native catalog from a ResolvedMarketplace */ },

  driver: { /* optional: headless eval support */ },
};

targetSchema is the churn firewall

Put every harness-specific fact behind this adapter, including manifest field names, file locations, and headless flags, and bump targetSchema when the harness changes its format. That way an upstream change is a version bump in one package, not a change to any plugin. The verified facts to encode are in docs/harness-research.md.

CompiledArtifact

interface CompiledArtifact {
  relPath: string;            // relative to the native plugin/output root
  contents: string | Buffer;
  kind?: ArtifactKind;        // "skill" | "mcp" | ... for the trust summary + lockfile
  executable?: boolean;       // passthrough; core places it DISABLED
}

relPath is plugin-root-relative (e.g. skills/code-review/SKILL.md, .claude-plugin/plugin.json). Core decides the absolute base per build mode and scope, so your adapter never hard-codes absolute paths.

PluginCtx

Passed to every adapter call:

interface PluginCtx {
  plugin: Plugin;
  read(relPath: string): Buffer;     // read a plugin file (store standards verbatim)
  list(relDir: string): string[];    // recursively list files under a plugin dir
  aliasFor(componentId: string): string;  // bare alias, or the fqid on collision
}

Use list + read to copy a component directory verbatim; use read to parse a server.json and derive the harness’s runnable MCP config.

Two emission modes

Headless eval (optional)

Provide a driver only if the harness has a headless mode that exposes a usable result:

interface HarnessDriver {
  readonly target: Target;
  available(): Promise<boolean>;   // CLI installed AND headless-capable; never throws
  run(opts): Promise<Transcript>;  // normalize stdout into { finalText, toolCalls, ... }
}

If the harness exposes no structured tool-call trace, set traceUnavailable: true on the Transcript; the eval runner degrades trace assertions to output assertions and reports the harness honestly rather than faking a pass.

Registering it

import { AdapterRegistry } from "@michaelfromyeg/weft-core";
import { myAdapter } from "@michaelfromyeg/weft-adapter-myharness";

const registry = new AdapterRegistry().register(myAdapter);

Publish it as an npm package; anyone can register it without forking Weft.