harness-alchemist 0.1.4 → 0.1.6

package/.claude-plugin/plugin.json

@@ -2,7 +2,7 @@
   "$schema": "https://json.schemastore.org/claude-code-plugin-manifest.json",
   "name": "harness-alchemist",
   "displayName": "Harness Alchemist",
-  "version": "0.1.4",
+  "version": "0.1.6",
   "description": "Scaffold, validate, and publish portable coding-agent plugins across Claude Code, Codex, OpenCode, Antigravity, and DeepSeek Harness.",
   "author": {
     "name": "Haochuan Zhang"

package/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "harness-alchemist",
-  "version": "0.1.4",
+  "version": "0.1.6",
   "description": "Scaffold, validate, and publish portable coding-agent plugins across Claude Code, Codex, OpenCode, Antigravity, and DeepSeek Harness.",
   "author": {
     "name": "Haochuan Zhang",

package/README.md

@@ -1,140 +1,144 @@
-# Harness Alchemist
-
-Scaffold, validate, and publish portable coding-agent plugins across Claude Code, Codex/ChatGPT, OpenCode, Google Antigravity, and DeepSeek Harness/Cordis.
-
-Harness Alchemist is a zero-runtime-dependency CLI for Node.js and Bun. Its own repository follows the same universal plugin layout that it generates. The first frozen scaffold is `templates/v0.1.0`.
-
-## Quick Start
-
-Run with Node.js:
+<p align="center">
+  <a href="https://github.com/lunarmoon26/harness-alchemist">
+    <picture>
+      <source srcset="assets/harness-alchemist_dark.svg" media="(prefers-color-scheme: dark)">
+      <source srcset="assets/harness-alchemist_light.svg" media="(prefers-color-scheme: light)">
+      <img src="assets/harness-alchemist_light.svg" alt="Harness Alchemist logo" height="110">
+    </picture>
+  </a>
+</p>
+
+<p align="center">The universal scaffold for coding-agent plugins. One repository, five harnesses, skills that own their runtime.</p>
+<p align="center">
+  <a href="https://www.npmjs.com/package/harness-alchemist" target="blank">
+    <img src="https://img.shields.io/npm/v/harness-alchemist?style=flat-square" alt="Npm package for Harness Alchemist">
+  </a>
+  <a href="./LICENSE">
+    <img alt="License: MIT" src="https://img.shields.io/github/license/lunarmoon26/harness-alchemist?style=flat-square" />
+  </a>
+  <a href="https://github.com/lunarmoon26/harness-alchemist/actions/workflows/ci.yml" target="blank">
+    <img src="https://img.shields.io/github/actions/workflow/status/lunarmoon26/harness-alchemist/ci.yml?branch=main&style=flat-square&label=CI" alt="CI status for Harness Alchemist">
+  </a>
+  <br /><br />
+</p>
+
+<p align="center">
+  Follow <a href="https://x.com/haochuanzero">@haochuanzero on X</a> for updates · Start from the <a href="https://blog.haochuanz.net/harness-alchemist/">one-page tour</a>.
+</p>
+
+---
+
+Harness Alchemist scaffolds one TypeScript plugin repository that installs natively into **Claude Code**, **Codex/ChatGPT**, **OpenCode**, **Google Antigravity**, and **DeepSeek Harness/Cordis**. Product skills ship behavioral `.mjs`/`.py` script twins; every harness entrypoint is a thin adapter that delegates to them.
+
+## Install
 
 ```bash
-npx harness-alchemist create ./my-plugin \
-  --description "What the plugin does" \
-  --author "Example Team" \
-  --repository example/my-plugin
+npm install -g harness-alchemist
+# or run it without installing:
+npx harness-alchemist@latest create my-plugin --help
 ```
 
-Or with Bun:
+Requires Node.js 22.20+ (Bun 1.2+ also supported). Zero runtime dependencies.
+
+## Quick start
 
 ```bash
-bunx harness-alchemist create ./my-plugin \
+npx harness-alchemist@latest create my-plugin \
   --description "What the plugin does" \
   --author "Example Team" \
   --repository example/my-plugin
-```
-
-The destination must be missing or empty. Harness Alchemist renders into a staging directory, validates the result, and moves it into place without replacing existing content.
-
-## Commands
 
-```text
-harness-alchemist create <directory> [options]
-harness-alchemist validate [directory] [--external] [--json]
-harness-alchemist templates
-harness-alchemist version
+cd my-plugin && npm install && npm run verify
 ```
 
-`init` and `new` are aliases for `create`. Run `harness-alchemist create --help` for metadata and license options.
-
-New projects use the unreleased canonical `v0.1.0` template. Unknown versions
-fail instead of silently selecting a different layout.
-
-## Generated Layout
-
-```text
-.agents/
-  plugins/                       Codex repository marketplace
-  skills/develop-<name>/         Project-local maintenance skill and scripts
-.claude-plugin/                  Claude plugin and marketplace manifests
-.codex-plugin/                   Codex/ChatGPT plugin manifest
-skills/<name>/SKILL.md           Shared installable Agent Skill
-src/opencode.ts                  OpenCode npm plugin entrypoint
-src/deepseek.ts                  Cordis plugin entrypoint
-cordis.patch.yml                 DeepSeek Harness bundle layer
-plugin.json                      Antigravity plugin manifest
-package.json                     Canonical package metadata
-```
-
-Generated repositories start at version `0.1.0` with inert OpenCode and Cordis entrypoints. Add only the runtime hooks or services the plugin actually needs.
-
-The recursive part is intentional: Harness Alchemist itself uses this layout, and every generated repository receives `.agents/skills/develop-<name>/` with its own sync, validation, package-payload, and compatibility workflow.
+Creation only writes to a missing or empty destination. The generated project passes its own gate out of the box: TypeScript checks, runtime delegation tests, scaffold validation, and an npm-payload audit.
 
-## Guidance Tiers
+## Existing monorepos and SDK packages
 
-The repository-maintainer skill, the published CLI skill, and a generated
-project's local maintenance skill have different audiences and scopes. See
-[docs/skill-tiers.md](docs/skill-tiers.md) before moving guidance between them.
+`validate` also supports an adapted plugin package inside an existing repository.
+Add `alchemy.json` at the repository root:
 
-## Canonical Template
-
-`templates/v0.1.0/universal-typescript/` is the unreleased canonical scaffold. It includes the generated project's local maintenance skill, scoped to that project's ownership boundary. `lib/create.mjs` supplies the version-specific validator and license during the atomic render.
+```json
+{
+  "$schema": "https://unpkg.com/harness-alchemist/alchemy.schema.json",
+  "pluginRoot": "packages/my-sdk",
+  "opencodeExport": "./server"
+}
+```
 
-Future incompatible scaffold changes should create a new `templates/<version>/`
-snapshot instead of mutating `v0.1.0` after release.
+The manifest is JSON-Schema-validated; the schema ships in the npm package and
+is referenced through `$schema`, so editors autocomplete and check every field.
 
-## Local Development
+`pluginRoot` contains the canonical plugin manifests, shared skills, Cordis
+patch, adapter sources, and publishable package metadata. Repository marketplace
+manifests remain at the project root and point at that package directory.
+`opencodeExport: "./server"` preserves an SDK at the package root while exposing
+the OpenCode adapter through the modern server entrypoint. Omitting the file
+retains the strict generated single-package layout.
 
-Requires Node.js 22.20 or newer for the full build and package checks. The scaffolding and validation CLI also runs directly with Bun 1.2 or newer.
+The optional `runtime` field selects what the adapted package must contain:
 
-```bash
-npm install
-npm run verify
-node ./bin/harness-alchemist.mjs templates
-bun ./bin/harness-alchemist.mjs templates
-```
+- `"npm"` (default) — the full generated contract: npm metadata, OpenCode and
+  Cordis adapters, Cordis patch, and `.mjs`/`.py` script twins.
+- `"skills"` — skills and harness manifests only. No npm package, adapters, or
+  Cordis patch are required, and single-language scripts are allowed, so
+  Python, Go, Rust, Java, C#, or Swift repositories can expose their workflows
+  to Claude Code, Codex, Antigravity, and DeepSeek's filesystem skill roots
+  without adopting a JavaScript runtime.
 
-After changing package metadata:
-
-```bash
-npm run sync
-npm run verify
-```
+Generated projects include a `alchemy.json` manifest recording their
+`runtime`, canonical `template` version, `generator`, `generatorVersion`, and
+`createdAt`; `npm run sync` keeps `generatorVersion` aligned with the package
+version.
 
-Inspect the publish payload before release:
+## What you get
 
-```bash
-npm pack --dry-run
-```
+| Surface | Purpose |
+| --- | --- |
+| `skills/<name>/` | Agent Skills spec skill with `.mjs`/`.py` script twins under `scripts/` and a tool-contract reference |
+| `src/opencode.ts` | OpenCode plugin registering tools that spawn the skill scripts |
+| `src/deepseek.ts` + `cordis.patch.yml` | Cordis function plugin providing a service over the same scripts |
+| `.claude-plugin/`, `.codex-plugin/`, `.agents/plugins/`, `plugin.json` | Native manifests for Claude Code, Codex, and Antigravity marketplaces |
+| `.agents/skills/develop-<name>/` | Repository-maintenance skill so agents can develop the project recursively |
+| `.github/workflows/` | CI plus tag-triggered publish (`vX.Y.Z` → verify → npm provenance) |
 
-## Package Surfaces
+## Supported harnesses
 
-- npm binary: `harness-alchemist`
-- Shared Agent Skill: `skills/harness-alchemist/SKILL.md`
-- OpenCode package-root export: `harness-alchemist`
-- Cordis export: `harness-alchemist/deepseek`
-- DeepSeek bundle patch: `harness-alchemist/cordis.patch.yml`
+Install paths below are verified against real CLIs before shipping in the template.
 
-The runtime entrypoints are intentionally inert in v0.1.0. The CLI and Agent Skill are the implemented product surfaces.
+| Harness | Skills | Runtime | Install |
+| --- | --- | --- | --- |
+| Claude Code | bundled natively | — | `claude plugin install <name>@<marketplace>` |
+| Codex/ChatGPT | bundled natively | — | `codex plugin add <name>@<marketplace>` |
+| OpenCode | via `~/.agents/skills/` | npm package hooks | `"plugin": ["<package>"]` in `opencode.json` |
+| Google Antigravity | nested bundle | — | `agy plugin validate . && agy plugin install .` |
+| DeepSeek Harness | profile filesystem roots | Cordis service plugin | `dsh plugin --profile demo add <package-or-path>` |
 
-## Harness Installation
+## Skill script contract
 
-Claude Code:
+Product skills own their logic; adapters never do.
 
 ```bash
-claude plugin marketplace add lunarmoon26/harness-alchemist
-claude plugin install harness-alchemist@harness-alchemist-plugins
+echo '{"request": "hello"}' | node skills/<name>/scripts/main.mjs
+# {"ok":true,"plugin":"my-plugin","echo":{"request":"hello"}}
 ```
 
-Codex and ChatGPT:
+- One JSON object on stdin, one JSON result plus newline on stdout.
+- Non-zero exit with a stderr diagnostic on failure.
+- `scripts/main.py` is a stdlib-only behavioral twin of `scripts/main.mjs`.
 
-```bash
-codex plugin marketplace add lunarmoon26/harness-alchemist
-```
+## Validation tiers
 
-OpenCode shared skill:
-
-```bash
-npx skills add lunarmoon26/harness-alchemist --agent opencode
-```
+`npm run validate` always enforces Agent Skills frontmatter compliance, SKILL.md reference resolution, and twin parity. With the optional `pyodide` devDependency installed, Python entrypoints are additionally compiled and smoke-executed inside a WebAssembly CPython sandbox — no native Python required.
 
-DeepSeek Harness after npm publication:
+## Release automation
 
 ```bash
-dsh plugin --profile demo add harness-alchemist
-dsh --profile demo --dump-config
+# bump package.json version, then:
+npm run sync && npm run verify && git commit -am "Release vX.Y.Z" && git push
+git tag vX.Y.Z && git push origin vX.Y.Z   # publishes automatically
 ```
 
 ## License
 
-MIT
+[MIT](./LICENSE)

package/alchemy.schema.json

@@ -0,0 +1,54 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://unpkg.com/harness-alchemist/alchemy.schema.json",
+  "title": "Harness Alchemist layout manifest",
+  "description": "Declares how a repository adapts the Harness Alchemist universal plugin layout. Omitting the file selects the strict generated single-package layout.",
+  "type": "object",
+  "additionalProperties": false,
+  "properties": {
+    "$schema": {
+      "type": "string",
+      "description": "URL of this schema."
+    },
+    "runtime": {
+      "enum": ["npm", "skills"],
+      "default": "npm",
+      "description": "'npm' requires the full generated contract (npm package, OpenCode and Cordis adapters, Cordis patch, .mjs/.py script twins). 'skills' requires skills and harness manifests only and allows single-language scripts."
+    },
+    "pluginRoot": {
+      "type": "string",
+      "default": ".",
+      "pattern": "^(?!\\.{2}(/|\\\\))[^\\u0000]+",
+      "description": "Repository-relative directory containing the plugin manifests, product skills, runtime sources, Cordis patch, and npm metadata. Defaults to the repository root."
+    },
+    "opencodeExport": {
+      "enum": [".", "./server"],
+      "default": ".",
+      "description": "Package export key that exposes the OpenCode adapter. Only meaningful when runtime is 'npm'."
+    },
+    "template": {
+      "type": "string",
+      "pattern": "^v[0-9]+\\.[0-9]+\\.[0-9]+(-[0-9A-Za-z.-]+)?$",
+      "description": "Canonical template version the project was generated from."
+    },
+    "generator": {
+      "const": "harness-alchemist",
+      "description": "Tool that generated the project."
+    },
+    "generatorVersion": {
+      "type": "string",
+      "pattern": "^[0-9]+\\.[0-9]+\\.[0-9]+(-[0-9A-Za-z.-]+)?$",
+      "description": "Version of the generating harness-alchemist CLI."
+    },
+    "createdAt": {
+      "type": "string",
+      "format": "date-time",
+      "description": "ISO 8601 creation timestamp written by the generator."
+    }
+  },
+  "if": {
+    "properties": { "opencodeExport": { "const": "./server" } },
+    "required": ["opencodeExport"]
+  },
+  "then": { "properties": { "runtime": { "const": "npm" } } }
+}

package/bin/harness-alchemist.mjs

@@ -35,7 +35,7 @@ if (!command || command === "help" || command === "--help" || command === "-h")
 } else if (["create", "init", "new"].includes(command)) {
   process.exitCode = await runCreate(args)
 } else if (command === "validate") {
-  process.exitCode = await runValidate(args.length > 0 ? args : [process.cwd()])
+  process.exitCode = await runValidate(args)
 } else {
   console.error(`Unknown command: ${command}\n`)
   console.error(usage())

package/lib/create.mjs

@@ -237,6 +237,7 @@ export async function runCreate(argv) {
   const projectRoot = dirname(dirname(scriptPath))
   const canonicalRoot = join(projectRoot, "templates", options.templateVersion)
   const templateRoot = join(canonicalRoot, "universal-typescript")
+  const generatorVersion = JSON.parse(await readFile(join(projectRoot, "package.json"), "utf8")).version
   const state = await destinationState(options.output)
   if (state === "not-directory" || state === "non-empty") {
     console.error(`Destination must be missing or empty: ${options.output}`)
@@ -250,6 +251,9 @@ export async function runCreate(argv) {
     DISPLAY_NAME_JSON: JSON.stringify(options.displayName),
     DESCRIPTION: options.description,
     DESCRIPTION_JSON: JSON.stringify(options.description),
+    TEMPLATE_VERSION: options.templateVersion,
+    GENERATOR_VERSION: generatorVersion,
+    CREATED_AT: new Date().toISOString(),
     SHARED_SKILL_DESCRIPTION_JSON: JSON.stringify(
       `${options.description} Use when the user requests ${options.displayName} workflows or explicitly asks to use the ${options.name} plugin.`,
     ),

package/lib/validate.mjs

@@ -6,24 +6,32 @@ import { basename, dirname, join, resolve, sep } from "node:path"
 import { fileURLToPath } from "node:url"
 import { spawnSync } from "node:child_process"
 
-const REQUIRED_FILES = [
+const PROJECT_REQUIRED_FILES = [
   ".agents/plugins/marketplace.json",
   ".claude-plugin/marketplace.json",
-  ".claude-plugin/plugin.json",
-  ".codex-plugin/plugin.json",
   ".github/workflows/npm-publish.yml",
   ".gitignore",
   "AGENTS.md",
   "LICENSE",
   "README.md",
+]
+
+const PLUGIN_REQUIRED_FILES = [
+  ".claude-plugin/plugin.json",
+  ".codex-plugin/plugin.json",
+  "plugin.json",
+]
+
+const NPM_PLUGIN_REQUIRED_FILES = [
   "cordis.patch.yml",
   "package.json",
-  "plugin.json",
   "src/deepseek.ts",
   "src/opencode.ts",
   "tsconfig.json",
 ]
 
+const RUNTIME_MODES = ["npm", "skills"]
+
 function usage() {
   return `Usage: harness-alchemist validate [project-directory] [--external] [--json]
 
@@ -44,16 +52,19 @@ Options:
 
 function findProjectRoot(start) {
   let current = resolve(start)
+  let conventionalRoot
   while (true) {
+    if (existsSync(join(current, "alchemy.json"))) return current
     if (
+      !conventionalRoot &&
       existsSync(join(current, "package.json")) &&
       existsSync(join(current, ".claude-plugin")) &&
       existsSync(join(current, ".codex-plugin"))
     ) {
-      return current
+      conventionalRoot = current
     }
     const parent = dirname(current)
-    if (parent === current) return undefined
+    if (parent === current) return conventionalRoot
     current = parent
   }
 }
@@ -294,7 +305,7 @@ async function smokePythonScripts(scripts, errors, warnings) {
   instance.globals.delete("__ha_payload__")
 }
 
-async function checkProductSkillRuntime(skillFile, content, frontmatter, errors, pythonScripts) {
+async function checkProductSkillRuntime(skillFile, content, frontmatter, errors, pythonScripts, runtime) {
   if ((frontmatter.description?.length ?? 0) > 1024) {
     errors.push(`${skillFile}: description must be at most 1024 characters`)
   }
@@ -325,12 +336,12 @@ async function checkProductSkillRuntime(skillFile, content, frontmatter, errors,
     entries.filter((entry) => entry.endsWith(".mjs")).map((entry) => entry.slice(0, -4)),
   )
   for (const base of pythonBases) {
-    if (!mjsBases.has(base)) {
+    if (runtime === "npm" && !mjsBases.has(base)) {
       errors.push(`${skillFile}: scripts/${base}.py is missing its scripts/${base}.mjs twin`)
     }
   }
   for (const base of mjsBases) {
-    if (!pythonBases.has(base)) {
+    if (runtime === "npm" && !pythonBases.has(base)) {
       errors.push(`${skillFile}: scripts/${base}.mjs is missing its scripts/${base}.py twin`)
     }
   }
@@ -344,25 +355,107 @@ export async function validateProject(projectRoot, options = {}) {
   const errors = []
   const warnings = []
 
-  for (const file of REQUIRED_FILES) requirePath(root, file, errors)
+  const layoutPath = join(root, "alchemy.json")
+  const parsedLayout = existsSync(layoutPath) ? await readJson(layoutPath, errors) : {}
+  if (parsedLayout === undefined) return { root, errors, warnings }
+  if (
+    typeof parsedLayout !== "object" ||
+    parsedLayout === null ||
+    Array.isArray(parsedLayout)
+  ) {
+    errors.push("alchemy.json must contain a JSON object")
+    return { root, errors, warnings }
+  }
+  const layout = parsedLayout
+  const knownLayoutFields = [
+    "pluginRoot",
+    "opencodeExport",
+    "runtime",
+    "$schema",
+    "template",
+    "generator",
+    "generatorVersion",
+    "createdAt",
+  ]
+  const unknownLayoutFields = Object.keys(layout).filter(
+    (key) => !knownLayoutFields.includes(key),
+  )
+  if (unknownLayoutFields.length) {
+    errors.push(`alchemy.json has unknown fields: ${unknownLayoutFields.join(", ")}`)
+  }
+  if (layout.$schema !== undefined && typeof layout.$schema !== "string") {
+    errors.push("alchemy.json $schema must be a string")
+  }
+  if (layout.template !== undefined && !/^v[0-9]+\.[0-9]+\.[0-9]+(-[0-9A-Za-z.-]+)?$/.test(layout.template)) {
+    errors.push("alchemy.json template must be a 'vX.Y.Z' version")
+  }
+  if (layout.generator !== undefined && layout.generator !== "harness-alchemist") {
+    errors.push("alchemy.json generator must be 'harness-alchemist'")
+  }
+  if (
+    layout.generatorVersion !== undefined &&
+    !/^[0-9]+\.[0-9]+\.[0-9]+(-[0-9A-Za-z.-]+)?$/.test(layout.generatorVersion)
+  ) {
+    errors.push("alchemy.json generatorVersion must be an 'X.Y.Z' version")
+  }
+  if (layout.createdAt !== undefined) {
+    const createdAt = new Date(layout.createdAt)
+    if (typeof layout.createdAt !== "string" || Number.isNaN(createdAt.getTime())) {
+      errors.push("alchemy.json createdAt must be an ISO 8601 timestamp")
+    }
+  }
+  const runtime = layout.runtime ?? "npm"
+  if (!RUNTIME_MODES.includes(runtime)) {
+    errors.push(`alchemy.json runtime must be one of: ${RUNTIME_MODES.join(", ")}`)
+  }
+  const pluginRootRelative = layout.pluginRoot ?? "."
+  if (typeof pluginRootRelative !== "string" || !pluginRootRelative.trim()) {
+    errors.push("alchemy.json pluginRoot must be a non-empty relative path")
+  }
+  const pluginRoot = resolve(root, typeof pluginRootRelative === "string" ? pluginRootRelative : ".")
+  if (!(pluginRoot === root || pluginRoot.startsWith(`${root}${sep}`))) {
+    errors.push("alchemy.json pluginRoot escapes the project root")
+  } else if (existsSync(pluginRoot)) {
+    const [canonicalRoot, canonicalPluginRoot] = await Promise.all([
+      realpath(root),
+      realpath(pluginRoot),
+    ])
+    if (!(canonicalPluginRoot === canonicalRoot || canonicalPluginRoot.startsWith(`${canonicalRoot}${sep}`))) {
+      errors.push("alchemy.json pluginRoot resolves through a symlink outside the project root")
+    }
+  }
+  const opencodeExport = layout.opencodeExport ?? "."
+  if (![".", "./server"].includes(opencodeExport)) {
+    errors.push("alchemy.json opencodeExport must be '.' or './server'")
+  }
+  if (opencodeExport !== "." && runtime !== "npm") {
+    errors.push("alchemy.json opencodeExport requires runtime 'npm'")
+  }
   if (errors.length > 0) return { root, errors, warnings }
 
-  const packageJson = await readJson(join(root, "package.json"), errors)
-  const claudePlugin = await readJson(join(root, ".claude-plugin/plugin.json"), errors)
+  for (const file of PROJECT_REQUIRED_FILES) requirePath(root, file, errors)
+  const pluginRequiredFiles = runtime === "npm"
+    ? [...PLUGIN_REQUIRED_FILES, ...NPM_PLUGIN_REQUIRED_FILES]
+    : PLUGIN_REQUIRED_FILES
+  for (const file of pluginRequiredFiles) {
+    requirePath(root, join(pluginRootRelative, file), errors)
+  }
+  if (errors.length > 0) return { root, errors, warnings }
+
+  const claudePlugin = await readJson(join(pluginRoot, ".claude-plugin/plugin.json"), errors)
   const claudeMarketplace = await readJson(
     join(root, ".claude-plugin/marketplace.json"),
     errors,
   )
-  const codexPlugin = await readJson(join(root, ".codex-plugin/plugin.json"), errors)
+  const codexPlugin = await readJson(join(pluginRoot, ".codex-plugin/plugin.json"), errors)
   const codexMarketplace = await readJson(
     join(root, ".agents/plugins/marketplace.json"),
     errors,
   )
-  const antigravityPlugin = await readJson(join(root, "plugin.json"), errors)
+  const antigravityPlugin = await readJson(join(pluginRoot, "plugin.json"), errors)
 
   if (errors.length > 0) return { root, errors, warnings }
 
-  const packageBase = packageJson.name?.split("/").at(-1)
   const pluginName = claudePlugin.name
   const validName = /^[a-z0-9]+(?:-[a-z0-9]+)*$/
 
@@ -372,9 +465,6 @@ export async function validateProject(projectRoot, options = {}) {
   if ((pluginName?.length ?? 0) > 56) {
     errors.push("Plugin name must be at most 56 characters")
   }
-  if (packageBase !== pluginName) {
-    errors.push(`npm package basename '${packageBase}' must match plugin name '${pluginName}'`)
-  }
 
   for (const [label, value] of [
     ["Codex plugin", codexPlugin.name],
@@ -383,64 +473,104 @@ export async function validateProject(projectRoot, options = {}) {
     if (value !== pluginName) errors.push(`${label} name '${value}' does not match '${pluginName}'`)
   }
 
-  for (const [label, manifest] of [
-    ["Claude plugin", claudePlugin],
-    ["Codex plugin", codexPlugin],
-  ]) {
-    if (manifest.version !== packageJson.version) {
-      errors.push(`${label} version does not match package.json`)
+  if (runtime === "skills") {
+    for (const [label, manifest] of [["Codex plugin", codexPlugin]]) {
+      if (manifest.version !== claudePlugin.version) {
+        errors.push(`${label} version does not match the Claude plugin`)
+      }
+      if (manifest.description !== claudePlugin.description) {
+        errors.push(`${label} description does not match the Claude plugin`)
+      }
     }
-    if (manifest.description !== packageJson.description) {
-      errors.push(`${label} description does not match package.json`)
+    if (antigravityPlugin.description !== claudePlugin.description) {
+      errors.push("Antigravity description does not match the Claude plugin")
     }
-  }
-  if (antigravityPlugin.description !== packageJson.description) {
-    errors.push("Antigravity description does not match package.json")
-  }
+  } else {
+    const packageJson = await readJson(join(pluginRoot, "package.json"), errors)
+    if (errors.length > 0) return { root, errors, warnings }
 
-  if (packageJson.type !== "module") errors.push("package.json type must be 'module'")
-  if (packageJson.engines?.node !== ">=22.20.0") {
-    errors.push("package.json engines.node must be '>=22.20.0'")
-  }
-  const requiredExports = [
-    [".", "import", "./dist/opencode.js"],
-    [".", "types", "./dist/opencode.d.ts"],
-    ["./deepseek", "import", "./dist/deepseek.js"],
-    ["./deepseek", "types", "./dist/deepseek.d.ts"],
-    ["./cordis.patch.yml", "import", "./cordis.patch.yml"],
-  ]
-  for (const [key, field, expected] of requiredExports) {
-    const target = exportTarget(packageJson.exports, key, field)
-    if (target !== expected) {
-      errors.push(`package.json export '${key}' ${field} target must be '${expected}'`)
+    const packageBase = packageJson.name?.split("/").at(-1)
+    if (packageBase !== pluginName) {
+      errors.push(`npm package basename '${packageBase}' must match plugin name '${pluginName}'`)
+    }
+
+    for (const [label, manifest] of [
+      ["Claude plugin", claudePlugin],
+      ["Codex plugin", codexPlugin],
+    ]) {
+      if (manifest.version !== packageJson.version) {
+        errors.push(`${label} version does not match package.json`)
+      }
+      if (manifest.description !== packageJson.description) {
+        errors.push(`${label} description does not match package.json`)
+      }
+    }
+    if (antigravityPlugin.description !== packageJson.description) {
+      errors.push("Antigravity description does not match package.json")
+    }
+
+    if (packageJson.type !== "module") errors.push("package.json type must be 'module'")
+    if (opencodeExport === "." && packageJson.engines?.node !== ">=22.20.0") {
+      errors.push("package.json engines.node must be '>=22.20.0'")
+    }
+    const requiredExports = [
+      [opencodeExport, "import", "./dist/opencode.js"],
+      [opencodeExport, "types", "./dist/opencode.d.ts"],
+      ["./deepseek", "import", "./dist/deepseek.js"],
+      ["./deepseek", "types", "./dist/deepseek.d.ts"],
+      ["./cordis.patch.yml", "import", "./cordis.patch.yml"],
+    ]
+    for (const [key, field, expected] of requiredExports) {
+      const target = exportTarget(packageJson.exports, key, field)
+      if (target !== expected) {
+        errors.push(`package.json export '${key}' ${field} target must be '${expected}'`)
+      }
+    }
+    for (const entry of [
+      "dist",
+      "skills",
+      "alchemy.json",
+      "cordis.patch.yml",
+      ".claude-plugin/plugin.json",
+      ".codex-plugin/plugin.json",
+      "plugin.json",
+    ]) {
+      if (!packageJson.files?.includes(entry)) errors.push(`package.json files is missing '${entry}'`)
+    }
+    if (packageJson.dsh?.bundle?.patch !== "./cordis.patch.yml") {
+      errors.push("package.json dsh.bundle.patch must be './cordis.patch.yml'")
+    }
+
+    const patch = await readFile(join(pluginRoot, "cordis.patch.yml"), "utf8")
+    const expectedModule = `${packageJson.name}/deepseek`
+    const cordisEntries = parseCordisInsertEntries(patch)
+      .filter((entry) => entry.id === pluginName)
+    const cordisEntry = cordisEntries[0]
+    if (cordisEntries.length !== 1 || !cordisEntry?.valid) {
+      errors.push(`cordis.patch.yml must contain a valid insert entry for '${pluginName}'`)
+    } else if (cordisEntry.name !== expectedModule) {
+      errors.push(`cordis.patch.yml entry '${pluginName}' must load '${expectedModule}'`)
     }
-  }
-  for (const entry of [
-    "dist",
-    "skills",
-    "cordis.patch.yml",
-    ".claude-plugin/plugin.json",
-    ".codex-plugin/plugin.json",
-    "plugin.json",
-  ]) {
-    if (!packageJson.files?.includes(entry)) errors.push(`package.json files is missing '${entry}'`)
-  }
-  if (packageJson.dsh?.bundle?.patch !== "./cordis.patch.yml") {
-    errors.push("package.json dsh.bundle.patch must be './cordis.patch.yml'")
   }
 
-  await requireManifestPath(root, claudePlugin.skills, "Claude skills", errors)
-  await requireManifestPath(root, codexPlugin.skills, "Codex skills", errors)
+  await requireManifestPath(pluginRoot, claudePlugin.skills, "Claude skills", errors)
+  await requireManifestPath(pluginRoot, codexPlugin.skills, "Codex skills", errors)
+
+  const marketplaceSource = pluginRoot === root
+    ? "./"
+    : `./${pluginRootRelative.replaceAll("\\", "/").replace(/^\.\//, "")}`
 
   const claudeEntry = claudeMarketplace.plugins?.find((entry) => entry.name === pluginName)
   if (!claudeEntry) errors.push("Claude marketplace is missing the plugin entry")
-  else if (claudeEntry.source !== "./") errors.push("Claude marketplace source must be './'")
+  else if (claudeEntry.source !== marketplaceSource) {
+    errors.push(`Claude marketplace source must be '${marketplaceSource}'`)
+  }
 
   const codexEntry = codexMarketplace.plugins?.find((entry) => entry.name === pluginName)
   if (!codexEntry) errors.push("Codex marketplace is missing the plugin entry")
   else {
-    if (codexEntry.source?.source !== "local" || codexEntry.source?.path !== "./") {
-      errors.push("Codex marketplace source must be a local './' path")
+    if (codexEntry.source?.source !== "local" || codexEntry.source?.path !== marketplaceSource) {
+      errors.push(`Codex marketplace source must be a local '${marketplaceSource}' path`)
     }
     if (!codexEntry.policy?.installation || !codexEntry.policy?.authentication) {
       errors.push("Codex marketplace entry requires installation and authentication policies")
@@ -448,19 +578,9 @@ export async function validateProject(projectRoot, options = {}) {
     if (!codexEntry.category) errors.push("Codex marketplace entry requires a category")
   }
 
-  const patch = await readFile(join(root, "cordis.patch.yml"), "utf8")
-  const expectedModule = `${packageJson.name}/deepseek`
-  const cordisEntries = parseCordisInsertEntries(patch)
-    .filter((entry) => entry.id === pluginName)
-  const cordisEntry = cordisEntries[0]
-  if (cordisEntries.length !== 1 || !cordisEntry?.valid) {
-    errors.push(`cordis.patch.yml must contain a valid insert entry for '${pluginName}'`)
-  } else if (cordisEntry.name !== expectedModule) {
-    errors.push(`cordis.patch.yml entry '${pluginName}' must load '${expectedModule}'`)
-  }
 
   const maintenanceSkillFiles = await collectSkillFiles(root, ".agents/skills")
-  const productSkillFiles = await collectSkillFiles(root, "skills")
+  const productSkillFiles = await collectSkillFiles(pluginRoot, "skills")
   const skillFiles = [...productSkillFiles, ...maintenanceSkillFiles]
   if (skillFiles.length < 2) errors.push("Expected a shared skill and a project development skill")
 
@@ -479,7 +599,7 @@ export async function validateProject(projectRoot, options = {}) {
         errors.push(`${skillFile}: invalid Agent Skill name`)
       }
       if (productSkillFiles.includes(skillFile)) {
-        await checkProductSkillRuntime(skillFile, content, frontmatter, errors, pythonScripts)
+        await checkProductSkillRuntime(skillFile, content, frontmatter, errors, pythonScripts, runtime)
       }
     }
   }
@@ -493,7 +613,7 @@ export async function validateProject(projectRoot, options = {}) {
   }
 
   if (options.external) {
-    const result = spawnSync("claude", ["plugin", "validate", root, "--strict"], {
+    const result = spawnSync("claude", ["plugin", "validate", pluginRoot, "--strict"], {
       encoding: "utf8",
     })
     if (result.error?.code === "ENOENT") warnings.push("Claude CLI not found; skipped external validation")

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "harness-alchemist",
-  "version": "0.1.4",
+  "version": "0.1.6",
   "description": "Scaffold, validate, and publish portable coding-agent plugins across Claude Code, Codex, OpenCode, Antigravity, and DeepSeek Harness.",
   "type": "module",
   "bin": {
@@ -25,6 +25,7 @@
     "lib",
     "templates",
     "skills",
+    "alchemy.schema.json",
     "cordis.patch.yml",
     ".claude-plugin/plugin.json",
     ".codex-plugin/plugin.json",

package/skills/harness-alchemist/SKILL.md

@@ -16,7 +16,11 @@ replace the generated repository's local maintenance skill.
 2. Read [references/compatibility.md](references/compatibility.md) before choosing paths or manifests.
 3. For a new project, run `harness-alchemist create --help` and use the CLI instead of recreating the structure manually.
 4. After creation, load `.agents/skills/develop-<name>/` in the generated project before maintaining its files.
-5. Run `harness-alchemist validate` and the generated package's `verify` script before reporting completion.
+5. For an existing monorepo or SDK package, use the explicit
+   `alchemy.json` adaptation described in
+   [references/compatibility.md](references/compatibility.md); do not replace the
+   product package root merely to match the generated layout.
+6. Run `harness-alchemist validate` and the generated package's `verify` script before reporting completion.
 
 ## Create A Project
 

package/skills/harness-alchemist/references/codex.md

@@ -27,9 +27,13 @@ The rich `interface` object is recommended for public presentation but is not re
 
 ```bash
 codex plugin marketplace add owner/repo
+codex plugin add <plugin-name>@<marketplace-name>
+codex plugin list
 ```
 
-Open `/plugins` to install from a configured marketplace, then start a new session. Codex npm marketplace sources download packages without running lifecycle scripts, so published packages must already contain built runtime files.
+The `@marketplace` suffix is required for `codex plugin add`; a bare plugin
+name is rejected. Headless install works without opening `/plugins`, then
+start a new session. Codex npm marketplace sources download packages without running lifecycle scripts, so published packages must already contain built runtime files.
 
 Official references:
 

package/skills/harness-alchemist/references/compatibility.md

@@ -28,6 +28,20 @@ stdout), and `src/opencode.ts` and `src/deepseek.ts` stay thin adapters that
 spawn those scripts. See the generated project's tool contract reference for
 details.
 
+## Existing repositories
+
+Existing monorepos may declare `pluginRoot` and an optional `./server` OpenCode
+export in root `alchemy.json`. The repository root keeps marketplaces
+and maintenance guidance; the plugin package keeps product skills, host
+manifests, adapter sources, Cordis patch, and npm metadata. Generated repositories
+remain single-package and need no configuration file.
+
+The optional `runtime` field adapts the contract to the repository's language:
+`"npm"` (default) requires the full generated package; `"skills"` accepts
+skills and harness manifests alone — no npm package, adapters, Cordis patch,
+or `.mjs`/`.py` twins — so polyglot repositories can publish workflows to
+Claude Code, Codex, Antigravity, and DeepSeek without a JavaScript runtime.
+
 ## Capability Matrix
 
 | Artifact | Claude | Codex | OpenCode | Antigravity | DeepSeek |

package/skills/harness-alchemist/references/deepseek-harness.md

@@ -49,6 +49,12 @@ dsh plugin --profile demo add @scope/my-plugin
 dsh --profile demo --dump-config
 ```
 
+`dsh plugin add` forwards to pnpm in the profile directory, so an unpublished checkout can be installed by absolute path and stays linked to the working tree:
+
+```bash
+dsh plugin --profile demo add /absolute/path/to/my-plugin
+```
+
 Bundle membership changes require a profile restart. Profile patch edits may hot-reload.
 
 Shared Agent Skills are discovered from project `.agents/skills` and other configured filesystem roots. Package-relative skill assets are not automatically activated by a bundle; install repository skills separately when needed.

package/skills/harness-alchemist/references/opencode.md

@@ -33,12 +33,16 @@ OpenCode accepts npm package names in `opencode.json`:
 
 OpenCode installs npm plugins with Bun at startup. For local development, register an absolute `file://` URL to compiled JavaScript or a direct TypeScript file with all of its dependencies available.
 
-Skills are separate from the npm plugin. Install them from the Git repository:
+Skills are discovered from `~/.agents/skills/` (and project `.agents/skills/`), not from the OpenCode config directory, and symlinked skill directories are skipped. Install them from the Git repository or a checkout:
 
 ```bash
 npx skills add owner/repo --agent opencode
+# or, from a local clone:
+cp -R skills/<name> ~/.agents/skills/
 ```
 
+Verify discovery with `opencode debug skill`.
+
 ## Extension Rules
 
 - Return `{}` when no hooks are registered.

package/templates/v0.1.0/universal-typescript/.agents/skills/develop-template/references/compatibility.md.tpl

@@ -6,6 +6,16 @@
 - `.agents/skills/develop-{{NAME}}/` is repository-local development guidance and is discoverable by Vercel Skills.
 - OpenCode and DeepSeek users install shared skills separately from the npm runtime plugin.
 
+## Layout Manifest
+
+`alchemy.json` records this repository's layout: `runtime: "npm"`,
+the canonical `template` version, `generator`, `generatorVersion`, and
+`createdAt`. It is validated against the published JSON Schema referenced by
+`$schema`. `npm run sync` refreshes `generatorVersion` from `package.json`.
+If this project ever moves into a monorepo, add `pluginRoot` (and optionally
+`opencodeExport: "./server"` for SDK packages); `runtime: "skills"` adapts
+non-JavaScript repositories to skills-only validation.
+
 ## Harness-Specific Contract
 
 | Harness | Files | Rule |

package/templates/v0.1.0/universal-typescript/.agents/skills/develop-template/scripts/check-package.mjs.tpl

@@ -53,6 +53,7 @@ for (const required of [
   "cordis.patch.yml",
   "dist/deepseek.js",
   "dist/opencode.js",
+  "alchemy.json",
   "plugin.json",
 ]) {
   if (!files.has(required)) throw new Error(`npm package is missing ${required}`)

package/templates/v0.1.0/universal-typescript/.agents/skills/develop-template/scripts/sync-metadata.mjs.tpl

@@ -121,4 +121,13 @@ for (let index = 0; index < cordisLines.length; index += 1) {
 if (!updatedCordisEntry) throw new Error(`Could not find Cordis entry '${pluginName}' to update`)
 await writeFile(cordisPath, cordisLines.join("\n"))
 
+const layoutPath = join(root, "alchemy.json")
+if (existsSync(layoutPath)) {
+  const layout = await readJson(layoutPath)
+  if (layout.generatorVersion !== packageJson.version) {
+    layout.generatorVersion = packageJson.version
+    await writeJson(layoutPath, layout)
+  }
+}
+
 console.log(`Synchronized plugin manifests from ${packagePath}`)

package/templates/v0.1.0/universal-typescript/README.md.tpl

@@ -19,7 +19,7 @@ cordis.patch.yml             DeepSeek Harness bundle layer
 plugin.json                  Antigravity plugin manifest
 ```
 
-The initial runtime entrypoints are intentionally inert. Add only the hooks, tools, or services the plugin actually needs.
+The runtime entrypoints are thin adapters that delegate to skill scripts; see `skills/{{NAME}}/references/tool-contract.md` before extending them.
 
 ## Skill Boundaries
 
@@ -54,13 +54,13 @@ npm pack --dry-run
 
 ## GitHub Release Publishing
 
-`.github/workflows/npm-publish.yml` publishes when a GitHub release is
-published. Tag the release as `vX.Y.Z` (or a semver prerelease such as
-`vX.Y.Z-rc.1`); the workflow applies that version, synchronizes manifests,
+`.github/workflows/npm-publish.yml` publishes when a `vX.Y.Z` tag is pushed
+(or a GitHub release with a semver tag such as `vX.Y.Z-rc.1` is published);
+the workflow applies that version, synchronizes manifests,
 verifies the package, and publishes with npm provenance.
 
 Configure the repository `NPM_TOKEN` secret with an npm publish token before
-creating a release.
+pushing the tag.
 
 ## Claude Code
 
@@ -80,9 +80,11 @@ claude plugin validate . --strict
 
 ```bash
 codex plugin marketplace add {{REPOSITORY_SOURCE}}
+codex plugin add {{NAME}}@{{MARKETPLACE}}
+codex plugin list
 ```
 
-Open `/plugins`, install **{{DISPLAY_NAME}}**, and start a new session.
+The `@{{MARKETPLACE}}` suffix is required; a bare plugin name is rejected.
 
 ## OpenCode
 
@@ -95,12 +97,24 @@ After publishing `{{PACKAGE_NAME}}`, add it to `opencode.json`:
 }
 ```
 
-Install the shared skill separately:
+For an unpublished checkout, point the entry at the built adapter instead:
+
+```json
+{
+  "plugin": ["file:///absolute/path/to/{{NAME}}/dist/opencode.js"]
+}
+```
+
+Skills are discovered from `~/.agents/skills/`, not from the OpenCode config
+directory, and symlinked directories are skipped. Copy each shared skill you
+need:
 
 ```bash
-npx skills add {{REPOSITORY_SOURCE}} --agent opencode
+cp -R skills/{{NAME}} ~/.agents/skills/
 ```
 
+Verify with `opencode debug skill`.
+
 ## Google Antigravity
 
 Clone the repository and install its root as a plugin:
@@ -120,12 +134,18 @@ dsh plugin --profile demo add {{PACKAGE_NAME}}
 dsh --profile demo --dump-config
 ```
 
-The bundle loads `{{PACKAGE_NAME}}/deepseek`. Install the shared Agent Skill separately when the workflow needs it:
+For an unpublished checkout, `dsh plugin add` forwards to pnpm, so a local
+path works and stays linked to your working tree:
 
 ```bash
-npx skills add {{REPOSITORY_SOURCE}}
+dsh plugin --profile demo add /absolute/path/to/{{NAME}}
 ```
 
+The bundle loads `{{PACKAGE_NAME}}/deepseek` through `package.json`'s
+`dsh.bundle.patch` entry. Verify composition with
+`dsh --profile demo --dump-config`, which should list an insert for
+`{{NAME}}`.
+
 ## License
 
 {{LICENSE}}

package/templates/v0.1.0/universal-typescript/alchemy.json.tpl

@@ -0,0 +1,8 @@
+{
+  "$schema": "https://unpkg.com/harness-alchemist/alchemy.schema.json",
+  "runtime": "npm",
+  "template": "{{TEMPLATE_VERSION}}",
+  "generator": "harness-alchemist",
+  "generatorVersion": "{{GENERATOR_VERSION}}",
+  "createdAt": "{{CREATED_AT}}"
+}

package/templates/v0.1.0/universal-typescript/package.json.tpl

@@ -19,6 +19,7 @@
   "files": [
     "dist",
     "skills",
+    "alchemy.json",
     "cordis.patch.yml",
     ".claude-plugin/plugin.json",
     ".codex-plugin/plugin.json",