@rbbtsn0w/adg 0.1.0-beta.3 → 0.1.1

package/README.md

@@ -67,6 +67,62 @@ install. To hack on the CLI itself, see [Developing from source](#developing-fro
 
 ---
 
+# Works with existing ecosystems
+
+ADG is **not** a new plugin format you have to migrate to. Any repo that already
+ships `.claude-plugin/` or `.codex-plugin/` manifests is ingested as-is: on the
+way in, `add` discovers each native manifest and **reverse-adapts** it into a
+canonical `.agents/.plugin.json` (the inverse of `adapt`), then ADG manages and
+re-projects it like any first-party plugin. No fork, no edits upstream.
+
+The two examples below are real, popular repositories — neither is ADG-native.
+
+### Example 1 — `anthropics/knowledge-work-plugins` (a category monorepo)
+
+A marketplace monorepo where each top-level category (`engineering/`,
+`marketing/`, `legal/`, …) is its own plugin with a `.claude-plugin/plugin.json`
+and a `skills/` tree. Pull the whole thing, or sparse-checkout just the
+categories you want:
+
+```bash
+# whole marketplace into the global store
+adg plugins add anthropics/knowledge-work-plugins --ref main --global
+
+# or fetch only one category from the large monorepo
+adg plugins add anthropics/knowledge-work-plugins --ref main --sparse engineering --global
+
+# each category's .claude-plugin manifest is reverse-adapted on import,
+# then projected back onto the runtimes you use
+adg plugins link --target claude --global   # → ~/.claude/skills/<plugin>:<skill>
+adg plugins link --target codex  --global   # native, zero-copy
+adg plugins list --global
+```
+
+### Example 2 — `obra/superpowers` (a single multi-runtime plugin)
+
+A single skills plugin that already ships `.claude-plugin/`, `.codex-plugin/` and
+a `skills/` library. Because the native manifests are already present, ADG simply
+adopts it — discovery picks up the existing manifest, records provenance and a
+content hash in the lock, and from then on it updates like any ADG plugin:
+
+```bash
+adg plugins add obra/superpowers --ref main --global
+
+# now under management — same lifecycle as a first-party plugin
+adg plugins list --global
+adg plugins update --global
+adg plugins link --target claude --global
+```
+
+> Both repos are pulled by `owner/repo` shorthand over a shallow clone (sparse
+> checkout when `--sparse` is given). Provenance — `{type:"github",repo,ref,path}`
+> — plus a `sha256` integrity hash land in `.plugin-lock.json`, so the install is
+> reproducible regardless of which ecosystem the plugin originally came from. See
+> [Importing existing inventory (via `add`)](#importing-existing-inventory-via-add)
+> for the discovery and reverse-adaptation details.
+
+---
+
 # Concepts (common)
 
 These apply the same whether you run a released build or the source tree.

package/dist/src/adapters/openai.js

@@ -4,16 +4,28 @@ import { isExposed } from "../components.js";
 /**
  * Generate a Codex (.codex-plugin/plugin.json) manifest from an ADG manifest.
  *
- * Codex's minimal manifest requires name, version, description and skills. The
- * skills field is emitted as an explicit array of skill identifiers. An optional
- * `selection` narrows the exposed skills (Codex only consumes skills).
+ * Codex's minimal manifest requires name, version, description and skills.
+ * In the default strict case a declared skills *root* string (e.g. `"./skills/"`)
+ * is passed through — Codex consumes the directory form natively, so it
+ * discovers new skills without the manifest enumerating them. Every other case
+ * (an explicit `skills` array, a partial install `selection`, or `strict: false`)
+ * emits the bare skill-id array Codex expects: `manifest.skills` arrays are
+ * declared as *paths* (`./skills/foo`), so they are resolved to identifiers
+ * rather than passed through. Codex only consumes skills.
  */
 export function toCodexManifest(pluginDir, manifest, selection) {
-    const skills = !selection
-        ? resolveSkills(pluginDir, manifest)
-        : isExposed(selection, "skills")
+    let skills;
+    if (selection) {
+        skills = isExposed(selection, "skills")
             ? selection.skills ?? resolveSkills(pluginDir, manifest)
             : [];
+    }
+    else {
+        const strict = manifest.strict !== false;
+        skills = strict && typeof manifest.skills === "string"
+            ? manifest.skills
+            : resolveSkills(pluginDir, manifest);
+    }
     const out = {
         name: manifest.name,
         version: manifest.version,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rbbtsn0w/adg",
-  "version": "0.1.0-beta.3",
+  "version": "0.1.1",
   "description": "Agent Directory Group (ADG) toolkit — two domains: plugins and skills.",
   "type": "module",
   "license": "MIT",