Architecture
Weft is a compiler, not a platform. The primary artifact is an importable library
(@michaelfromyeg/weft-core) with a thin CLI on top. Everything tool-specific lives behind a versioned
adapter, so an upstream manifest change touches one adapter, not your plugins.
Packages and dependency direction
schema <- core <- (adapter-*, eval, index) <- cli
^
adapter-kit (the public contract adapters implement)
@michaelfromyeg/weft-schemais the canonical data model. It holds Zod schemas forweft.yaml,marketplace.yaml,weft.lock, andcases.yaml; inferred types; a JSON-Schema export for editor autocomplete; and the YAML-1.2 / JSON5 parse path.@michaelfromyeg/weft-adapter-kitis theHarnessAdapterandHarnessDriverinterfaces plus shared helpers (frontmatter, paths, artifact builder). A community adapter depends only on this +@michaelfromyeg/weft-schema.@michaelfromyeg/weft-coreis the compile pipeline, the adapter registry, namespacing/aliases, placement (build vs install), and the lockfile.@michaelfromyeg/weft-adapter-*is one package per harness. Each implementsHarnessAdapter.@michaelfromyeg/weft-clisits at the top of the graph and wires concrete adapters into a registry. Core never imports a concrete adapter, which keeps the dependency direction one-way and lets community adapters slot in.
The compile pipeline (@michaelfromyeg/weft-core)
compile(fetchedPlugin, { registry, targets }) runs the canonical-to-native transform
(spec §9.1). Placement and the lockfile are deliberately separate so build can produce
inspectable output without touching any harness install directory.
- Load and validate.
weft.yamlis parsed (YAML 1.2-strict | JSON5) and validated by Zod with path-precise errors.weft_min_versionis enforced. - Static validation (
staticPass) confirms that referenced files exist, skill/agent frontmatter is well-formed,server.jsonparses, and descriptions clear a quality bar. This is the deterministic “is this plugin valid?” pass behind the valid badge. - Namespace and alias resolution. Each component gets a fully-qualified id
{namespace}/{plugin}:{leaf}; a leaf used by exactly one component earns the bare alias, and a shared leaf surfaces as a collision (never silent last-wins). - Transform. For each
(component x target), the adapter’stransformproduces native artifacts;emitManifestproduces the plugin-level manifest (e.g. Claudeplugin.json);emitCatalogproduces the marketplace catalog. - Place.
buildwritesoutDir/<target>/in marketplace+plugin layout;installcopies the plugin tree into the scope’s dirs and records every file. - Lockfile.
installwritesweft.lockwith content hashes, scope/paths, adapter and target-schema versions, and the alias table.
Diagnostics are accumulated, not thrown, so the caller can render every problem at once;
build/install fail closed when any error is present.
The adapter seam
interface HarnessAdapter {
readonly target: Target;
readonly version: string; // adapter package version (versioning axis 3)
readonly targetSchema: string; // the harness manifest schema version it emits
readonly harness?: HarnessCompat; // upstream harness CLI + supported range (axis 4)
detect(scope, cwd): InstallPaths;
transform(component, ctx): CompiledArtifact[];
emitManifest(plugin, ctx): CompiledArtifact[];
emitCatalog(marketplace): CompiledArtifact[]; // marketplace is fully resolved
driver?: HarnessDriver; // present iff headless eval is supported
}
Every harness-specific fact (manifest field names, install paths, headless flags) lives
behind targetSchema. When an upstream tool changes its format, that is a new adapter
release with a bumped targetSchema, and plugins are untouched. See
docs/harness-research.md for the verified per-harness facts.
Versioning (four independent axes)
All four are recorded in weft.lock (spec §5):
- Plugin version: semver, git-tag to resolved SHA.
- Weft/CLI version: plugins declare
weft_min_version. - Adapter <-> target-schema version: each adapter declares the harness schema it emits.
- Harness CLI version: each adapter declares a
harnessrange its emitted format is verified against.weft builddetects the installed harness version (or takes--harness <target>@<version>) and warns when it falls outside that range – the early signal that an upstream release may have moved the format past what the adapter emits.
Content-addressed artifact hashes make “is there really a new version?” exact: weft
update re-resolves, recompiles, diffs hashes, and re-places only what changed.
Why these boundaries
- Single source of truth. The author writes the plugin once; all tool-specific output is generated, never hand-maintained. No command ever asks you to edit a generated file.
- Standards as inputs.
SKILL.mdandserver.jsonare stored verbatim in the plugin; the adapter is the only place that knows a harness’s shape. - Deep modules.
compiledoes a lot behind a small interface; adapters hide a harness’s full manifest complexity behind four methods.