agkit 0.8.0 → 0.9.0

package/README.md

@@ -30,14 +30,14 @@ Think **`ng` for Angular, but for agent plugin marketplaces**: `init` gives you
 - 🌐 **Forge‑agnostic** — distribute via GitHub, GitLab, Bitbucket, Gitea, or self‑hosted, with a plain `git push`.
 - 📁 **One source of truth** — a single canonical `.claude-plugin/marketplace.json`; generated registries derive from it and never drift.
 - 🔁 **Full lifecycle** — `init`, `add`, `build`, `sync`, `bump`, `validate`, `list`.
-- 🧬 **Remote & local templates** — pull plugin templates from any git repo (`gh:` / `gl:` / URL) or a local path.
+- 🔗 **Reference, vendor, or scaffold** — catalog a remote plugin **by reference** (no clone, the default), **vendor** a remote template into your repo with `--vendor`, or **scaffold** from a built-in / local template. Create a standalone plugin (no marketplace) with `init --plugin`.
 - ✅ **CI‑ready** — generated GitHub Actions / GitLab CI, with `validate` + `build --check` gates.
 
 ---
 
 ## 📦 Installation
 
-Requires **Node.js ≥ 18**. Run it on demand with `npx` (nothing to install), or install the CLI globally:
+Requires **Node.js ≥ 22**. Run it on demand with `npx` (nothing to install), or install the CLI globally:
 
 ```bash
 npx agkit --help          # run without installing
@@ -61,6 +61,8 @@ git add -A && git commit -m "feat: initial marketplace" && git push -u origin ma
 
 That's the whole loop — once pushed, anyone can install your plugins straight from the repo (the per‑agent install command is in the **Create a marketplace for your agent** section below). `init` targets **Claude Code** and **GitHub Copilot** by default; add `--agents codex,cursor` to serve more.
 
+Step 2 has more shapes — reference a remote plugin without cloning it, vendor a template into your repo, or scaffold a plugin on its own with `agkit init --plugin`. All of them are laid out in **[Adding plugins](#-adding-plugins)**.
+
 ---
 
 ## 🧩 How agents consume your marketplace
@@ -211,8 +213,8 @@ git add -A && git commit -m "feat: initial marketplace" && git push -u origin ma
 
 | Command | What it does |
 | :------ | :----------- |
-| `agkit init [dir]` | Scaffolds a git-first marketplace: `.claude-plugin/marketplace.json` (with `$schema`, `pluginRoot`, `targets`), `plugins/`, `AGENTS.md`, a per-agent README, `examples/team-settings.json`, CI (GitHub Actions or GitLab CI), `.gitignore`, `git init`. Pick target agents with `--agents` (see the **Target agents** section). Non-interactive with `-y`. |
-| `agkit add <template\|spec> <name>` | Scaffolds a plugin from a built-in template (`skill`, `command`, `agent`, `hook`, `mcp`) **or a remote/local one** — `gh:owner/repo/dir#ref`, `gl:owner/repo`, any git URL with `//subdir` and `#ref`, or a local path. Registers it in the catalog and refreshes the README table and `AGENTS.md`. |
+| `agkit init [dir]` | Scaffolds a git-first marketplace: `.claude-plugin/marketplace.json` (with `$schema`, `pluginRoot`, `targets`), `plugins/`, `AGENTS.md`, a per-agent README, `examples/team-settings.json`, CI (GitHub Actions or GitLab CI), `.gitignore`, `git init`. Pick target agents with `--agents` (see the **Target agents** section). Non-interactive with `-y`. Use **`--plugin [template]`** to instead scaffold a **standalone plugin** in `[dir]` — just `.claude-plugin/plugin.json` + content, its own git repo, **no marketplace** — ready to reference from any catalog (see **Adding plugins**). |
+| `agkit add <template\|spec> <name>` | Registers a plugin in the catalog and refreshes the README table and `AGENTS.md`. A **remote git source** — bare `owner/repo`, `gh:owner/repo`, `gl:owner/repo`, or any git URL (`//subdir`, `#ref` supported) — is **referenced by default** as an object `source` (`github` / `url` / `git-subdir`): nothing is cloned, the agent fetches it at install time. Pin it with `--ref <branch\|tag>` / `--sha <commit>`. A **built-in template** (`skill`, `command`, `agent`, `hook`, `mcp`) or a **local path** is scaffolded into `plugins/<name>/`. Add **`--vendor`** to a remote source to clone and scaffold from it (treat the repo as a template) instead of referencing it. |
 | `agkit build [--target] [--check]` | Generates the registries for **Codex** and **Cursor** from the catalog: their committed `marketplace.json` + per-plugin manifest mirrors. Default targets are the ones in `metadata.targets`; `--target codex,cursor` overrides. `--check` fails on drift (CI). |
 | `agkit bump [plugin] [level]` | Bumps a plugin version from conventional commits scoped to its directory since the last `<plugin>@x.y.z` tag (`feat`→minor, breaking→major, else patch), or an explicit `major\|minor\|patch`. Prepends a dated entry to `plugins/<name>/CHANGELOG.md` from those commits. `--tag` commits and tags; `--dry-run` previews. Catalog, README, `AGENTS.md`, and any built registries stay in sync. |
 | `agkit sync` | Reconciles the catalog with what's on disk. Source of truth: each plugin's `.claude-plugin/plugin.json`. Adds missing entries, fixes drift, flags orphans, regenerates the README table and the `AGENTS.md` plugin list, and refreshes any already-built Codex/Cursor registry. |
@@ -251,17 +253,74 @@ Everything derives from `.claude-plugin/marketplace.json` and the per-plugin man
 
 ---
 
-## 🧬 Team templates (remote or local)
+## 📥 Adding plugins
+
+A plugin can live **inside** your marketplace (its files committed next to the catalog) or **outside** it (kept in its own repo and fetched by the agent at install time). `agkit add` handles both; `agkit init --plugin` scaffolds a plugin as a standalone repo. The table maps each intent to a command and the `source` it writes to `marketplace.json`:
+
+| You want to… | Command | Resulting `source` | Files copied in? |
+| :----------- | :------ | :----------------- | :--------------- |
+| Scaffold a new plugin from a **built-in** template | `agkit add skill my-skill` | `"./plugins/my-skill"` | ✅ scaffolded |
+| Scaffold from a **local** template directory | `agkit add ./templates/hook-guard no-secrets` | `"./plugins/no-secrets"` | ✅ scaffolded |
+| Create a plugin **without a marketplace** | `agkit init --plugin skill my-skill` | *(its own repo)* | ✅ scaffolded |
+| Reference a repo that **is a plugin** (GitHub) | `agkit add acme/deploy deploy` | `{ "source": "github", "repo": … }` | ❌ referenced |
+| Reference a repo that **is a plugin** (any forge) | `agkit add https://gitlab.com/team/plugin.git gl` | `{ "source": "url", "url": … }` | ❌ referenced |
+| Reference a plugin **inside a marketplace/monorepo** | `agkit add "https://gitlab.com/team/marketplace.git//my-plugin" my-plugin` | `{ "source": "git-subdir", "url": …, "path": "my-plugin" }` | ❌ referenced |
+| **Vendor** a remote template into your marketplace | `agkit add gh:my-org/templates/kata-fr gilded-rose --vendor` | `"./plugins/gilded-rose"` | ✅ cloned + scaffolded |
+
+Rule of thumb: **a remote git source is referenced by default** (no clone); pass **`--vendor`** only when you want its files copied into your repo.
+
+### Local plugins (scaffolded)
 
-Version your team's plugin templates in any git repository and consume them from every marketplace:
+Built-in templates (`skill`, `command`, `agent`, `hook`, `mcp`) and local paths are scaffolded into `plugins/<name>/` and registered with a relative `"./plugins/<name>"` source:
 
 ```bash
-agkit add gh:my-org/plugin-templates/kata-fr gilded-rose
-agkit add "https://gitlab.company.io/craft/templates//skill-ddd#v2" tactical-ddd
-agkit add ./shared-templates/hook-guard no-secrets
+agkit add skill tdd-coach                       # built-in template
+agkit add ./shared-templates/hook-guard guard   # a local template directory
 ```
 
-A template is any directory containing `.claude-plugin/plugin.json` (adopted, `name` rewritten) or `plugin.json.tpl`. Files ending in `.tpl` are rendered with `{{pluginName}}`, `{{pluginTitle}}`, `{{description}}`, `{{authorName}}` — in contents **and** in file/directory names. Executable bits are preserved.
+A **template** is any directory containing `.claude-plugin/plugin.json` (adopted, `name` rewritten) or `plugin.json.tpl`. Files ending in `.tpl` are rendered with `{{pluginName}}`, `{{pluginTitle}}`, `{{description}}`, `{{authorName}}` — in contents **and** in file/directory names. Executable bits are preserved.
+
+To create a plugin on its own, **outside any marketplace**, use `init --plugin`. It writes just `.claude-plugin/plugin.json` + the template content and makes the folder its own git repo (unless it's already inside one, e.g. dropped into a marketplace's `plugins/`):
+
+```bash
+agkit init --plugin skill ./my-skill            # standalone plugin repo, no marketplace
+# push it somewhere, then reference it from any marketplace:
+agkit add my-org/my-skill my-skill              # (run inside a marketplace project)
+```
+
+### Remote plugins (referenced — the default)
+
+When the spec is a **remote git repo**, agkit writes an object `source` the agent resolves at install time — **nothing is cloned**, no files are added to your marketplace. The spec grammar (bare `owner/repo`, `gh:`/`gl:` shorthands, git URLs, `//subdir`, `#ref`) maps to the schema's three git forms:
+
+```bash
+# The repo IS the plugin (its .claude-plugin/plugin.json is at the root):
+agkit add acme/deploy-plugin deploy                    # → { "source": "github", "repo": "acme/deploy-plugin" }
+agkit add https://gitlab.com/team/plugin.git gl-tools  # → { "source": "url", "url": "https://gitlab.com/team/plugin.git" }
+
+# The plugin is a SUBDIRECTORY of a bigger repo — a marketplace or a monorepo.
+# Point at the plugin's folder (it must contain .claude-plugin/plugin.json):
+agkit add "https://gitlab.com/team/marketplace.git//my-plugin" my-plugin
+#   → { "source": "git-subdir", "url": "https://gitlab.com/team/marketplace.git", "path": "my-plugin" }
+```
+
+Pin any referenced source to a branch/tag with `--ref` (or `#ref` in the spec) and to an exact commit with `--sha <40-hex>`:
+
+```bash
+agkit add acme/deploy-plugin deploy --ref v2.0.0 --sha a1b2c3…  # or  agkit add acme/deploy-plugin#v2.0.0 deploy
+```
+
+> **Referencing vs. consuming.** `git-subdir` points **directly at a plugin folder** — it does *not* read that repo's own `marketplace.json`. Use it to **re-catalog one plugin** from someone else's marketplace into yours. If you only want to *use* their plugins, add their marketplace directly instead: `/plugin marketplace add team/marketplace` then `/plugin install my-plugin@their-marketplace`.
+
+### Vendoring a remote template (`--vendor`)
+
+Add **`--vendor`** to a remote spec to treat the repo as a **template**: agkit clones it (shallow), renders its `.tpl` files, and copies the result into `plugins/<name>/` — so the plugin now lives in, and releases with, your marketplace (relative `"./plugins/<name>"` source). Use it to seed a plugin from a shared team template:
+
+```bash
+agkit add gh:my-org/plugin-templates/kata-fr gilded-rose --vendor
+agkit add "https://gitlab.company.io/craft/templates//skill-ddd#v2" tactical-ddd --vendor
+```
+
+Pin the vendored clone with `#ref` in the spec (as above). The clone's `.git` is never copied into the plugin.
 
 ---
 
@@ -277,6 +336,23 @@ A template is any directory containing `.claude-plugin/plugin.json` (adopted, `n
 
 ---
 
+## 🧪 Development
+
+Requires **Node.js ≥ 22**. Clone, install, and run the same gate CI does:
+
+```bash
+npm install
+npm run typecheck     # tsc --noEmit
+npm run lint          # biome check   (lint:fix to autofix)
+npm test              # vitest run
+npm run build         # tsup → dist/index.js
+node dist/index.js --help   # run the built CLI
+```
+
+Tests live next to the code as `*.test.ts` and cover both the pure `lib/` helpers and the command layer (`add`, `init --plugin`, `sync`, `validate`) via temp-directory fixtures — the Claude CLI is stubbed in `validate` tests so the suite stays hermetic. CI runs the gate on Node 22.x and 24.x.
+
+---
+
 ## 📄 License
 
 [MIT](LICENSE) © fair3n

package/dist/index.js

@@ -183,6 +183,73 @@ function parseGitSpec(spec) {
   }
   return void 0;
 }
+function isRemoteSpec(spec) {
+  if (PLUGIN_TEMPLATES.includes(spec)) return false;
+  return !(spec.startsWith("./") || spec.startsWith("../") || spec.startsWith("path:") || path3.isAbsolute(spec));
+}
+function resolveRemoteSource(spec, opts = {}) {
+  if (spec.startsWith("./") || spec.startsWith("../") || spec.startsWith("path:") || path3.isAbsolute(spec)) {
+    throw new Error(
+      `--link needs a remote git source, but "${spec}" is a local path. Drop --link to scaffold from a local template.`
+    );
+  }
+  if (PLUGIN_TEMPLATES.includes(spec)) {
+    throw new Error(
+      `--link needs a remote git source, but "${spec}" is a built-in template. Drop --link to scaffold it locally.`
+    );
+  }
+  if (opts.sha && !/^[0-9a-f]{40}$/i.test(opts.sha)) {
+    throw new Error(
+      `--sha must be a full 40-character commit hash: "${opts.sha}"`
+    );
+  }
+  let body = spec;
+  let hashRef;
+  const hash = body.lastIndexOf("#");
+  if (hash > 0) {
+    hashRef = body.slice(hash + 1) || void 0;
+    body = body.slice(0, hash);
+  }
+  const git2 = parseGitSpec(spec);
+  const ref = opts.ref ?? git2?.ref ?? hashRef;
+  const pin = (base) => {
+    if (ref) base.ref = ref;
+    if (opts.sha) base.sha = opts.sha;
+    return base;
+  };
+  if (git2) {
+    if (git2.subdir) {
+      return {
+        source: pin({
+          source: "git-subdir",
+          url: git2.cloneUrl,
+          path: git2.subdir
+        }),
+        label: spec
+      };
+    }
+    const gh = git2.cloneUrl.match(
+      /^https:\/\/github\.com\/([^/]+)\/(.+?)(?:\.git)?$/
+    );
+    if (gh) {
+      return {
+        source: pin({ source: "github", repo: `${gh[1]}/${gh[2]}` }),
+        label: spec
+      };
+    }
+    return { source: pin({ source: "url", url: git2.cloneUrl }), label: spec };
+  }
+  const bare = body.match(/^([\w][\w.-]*)\/([\w][\w.-]*)$/);
+  if (bare) {
+    return {
+      source: pin({ source: "github", repo: `${bare[1]}/${bare[2]}` }),
+      label: spec
+    };
+  }
+  throw new Error(
+    `Unrecognized remote source "${spec}". Use owner/repo, gh:owner/repo[/dir], gl:owner/repo[/dir], or a git URL[//dir][#ref].`
+  );
+}
 function assertTemplateDir(dir, label) {
   const hasManifest = fs3.existsSync(path3.join(dir, ".claude-plugin", "plugin.json.tpl")) || fs3.existsSync(path3.join(dir, ".claude-plugin", "plugin.json"));
   if (!hasManifest) {
@@ -630,6 +697,7 @@ async function addPlugin(startDir, templateArg, nameArg, opts = {}) {
     if (p3.isCancel(answer)) return cancel2();
     templateSpec = answer;
   }
+  const reference = isRemoteSpec(templateSpec) && opts.vendor !== true;
   let name = nameArg;
   if (!name) {
     const answer = await p3.text({
@@ -651,12 +719,6 @@ async function addPlugin(startDir, templateArg, nameArg, opts = {}) {
     process.exitCode = 1;
     return;
   }
-  const destDir = path7.join(pluginRootDir(root, mp), name);
-  if (fs6.existsSync(destDir)) {
-    p3.log.error(`Directory already exists: ${destDir}`);
-    process.exitCode = 1;
-    return;
-  }
   let description = opts.description;
   if (description === void 0 && opts.interactive !== false) {
     const answer = await p3.text({
@@ -668,6 +730,39 @@ async function addPlugin(startDir, templateArg, nameArg, opts = {}) {
     description = answer;
   }
   description = description || `TODO: describe what ${name} does.`;
+  if (reference) {
+    let remote;
+    try {
+      remote = resolveRemoteSource(templateSpec, {
+        ref: opts.ref,
+        sha: opts.sha
+      });
+    } catch (err) {
+      p3.log.error(err.message);
+      process.exitCode = 1;
+      return;
+    }
+    mp.plugins.push({ name, source: remote.source, description });
+    writeMarketplace(root, mp);
+    await syncCommand(root, { quiet: true });
+    p3.log.success(
+      `Registered ${pc2.cyan(name)} as a remote plugin (${remote.label}) in marketplace.json \u2014 nothing was cloned.`
+    );
+    p3.log.info(
+      `Claude Code fetches it from the source at install time:
+  claude
+  /plugin marketplace add ${root}
+  /plugin install ${name}@${mp.name}
+(pass --vendor to clone it into ${mp.metadata?.pluginRoot ?? "./plugins"} instead)`
+    );
+    return;
+  }
+  const destDir = path7.join(pluginRootDir(root, mp), name);
+  if (fs6.existsSync(destDir)) {
+    p3.log.error(`Directory already exists: ${destDir}`);
+    process.exitCode = 1;
+    return;
+  }
   const vars = {
     pluginName: name,
     pluginTitle: titleCase(name),
@@ -1087,6 +1182,15 @@ function isGitAvailable() {
 function isGitRepo(dir) {
   return fs8.existsSync(path9.join(dir, ".git"));
 }
+function isInsideGitRepo(dir) {
+  let d = path9.resolve(dir);
+  for (; ; ) {
+    if (fs8.existsSync(path9.join(d, ".git"))) return true;
+    const parent = path9.dirname(d);
+    if (parent === d) return false;
+    d = parent;
+  }
+}
 function gitInit(dir) {
   execFileSync3("git", ["init", "--initial-branch=main"], {
     cwd: dir,
@@ -1131,6 +1235,9 @@ function parseRemoteUrl(raw) {
 }
 
 // src/commands/init.ts
+function titleCase2(kebab) {
+  return kebab.split("-").map((w) => w.charAt(0).toUpperCase() + w.slice(1)).join(" ");
+}
 function validateName(name) {
   if (!KEBAB_CASE_RE.test(name)) {
     return "Name must be kebab-case (lowercase letters, digits, hyphens)";
@@ -1157,9 +1264,132 @@ function teamSource(remote) {
   };
   return JSON.stringify(source, null, 2).split("\n").map((line, i) => i === 0 ? line : `      ${line}`).join("\n");
 }
+async function initPlugin(targetDir, templateSpec, opts) {
+  p5.intro(pc4.bgCyan(pc4.black("  agkit init --plugin  ")));
+  const defaultName = path10.basename(targetDir).toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "");
+  let spec = typeof templateSpec === "string" ? templateSpec : void 0;
+  if (!spec) {
+    if (opts.yes) {
+      spec = "skill";
+    } else {
+      const answer = await p5.select({
+        message: "Plugin template",
+        options: PLUGIN_TEMPLATES.map((t) => ({
+          value: t,
+          label: t,
+          hint: TEMPLATE_DESCRIPTIONS[t]
+        }))
+      });
+      if (p5.isCancel(answer)) return cancel5();
+      spec = answer;
+    }
+  }
+  let name = opts.name;
+  if (!name && !opts.yes) {
+    const answer = await p5.text({
+      message: "Plugin name (kebab-case)",
+      initialValue: defaultName,
+      validate: (v) => KEBAB_CASE_RE.test(v) ? void 0 : "Must be kebab-case (lowercase, digits, hyphens)"
+    });
+    if (p5.isCancel(answer)) return cancel5();
+    name = answer;
+  }
+  name = name || defaultName;
+  if (!KEBAB_CASE_RE.test(name)) {
+    p5.log.error(`Plugin name "${name}" must be kebab-case.`);
+    process.exitCode = 1;
+    return;
+  }
+  let description = opts.description;
+  if (description === void 0 && !opts.yes) {
+    const answer = await p5.text({
+      message: "One-line description",
+      defaultValue: "",
+      placeholder: `What does ${name} do?`
+    });
+    if (p5.isCancel(answer)) return cancel5();
+    description = answer;
+  }
+  description = description || `TODO: describe what ${name} does.`;
+  const manifestPath = path10.join(targetDir, ".claude-plugin", "plugin.json");
+  if (fs9.existsSync(manifestPath)) {
+    p5.log.error(`A plugin already exists here: ${manifestPath}`);
+    process.exitCode = 1;
+    return;
+  }
+  const s = p5.spinner();
+  s.start("Scaffolding plugin");
+  fs9.mkdirSync(targetDir, { recursive: true });
+  const vars = {
+    pluginName: name,
+    pluginTitle: titleCase2(name),
+    description,
+    authorName: opts.owner || "Unknown"
+  };
+  let resolved;
+  try {
+    resolved = resolveTemplate(spec);
+  } catch (err) {
+    s.stop("Scaffolding failed");
+    p5.log.error(err.message);
+    process.exitCode = 1;
+    return;
+  }
+  try {
+    copyTemplateDir(resolved.dir, targetDir, vars);
+  } finally {
+    if (resolved.cleanup)
+      fs9.rmSync(resolved.cleanup, { recursive: true, force: true });
+  }
+  if (!resolved.builtin && fs9.existsSync(manifestPath)) {
+    try {
+      const manifest = readJson(manifestPath);
+      manifest.name = name;
+      if (opts.description) manifest.description = description;
+      writeJson(manifestPath, manifest);
+    } catch {
+      p5.log.warn("Template plugin.json could not be parsed; left as-is.");
+    }
+  }
+  const standalone = !isInsideGitRepo(targetDir);
+  if (standalone) {
+    const gitignore = path10.join(targetDir, ".gitignore");
+    if (!fs9.existsSync(gitignore)) {
+      fs9.writeFileSync(
+        gitignore,
+        ["node_modules/", ".DS_Store", "*.log", ""].join("\n")
+      );
+    }
+    if (isGitAvailable()) {
+      try {
+        gitInit(targetDir);
+      } catch {
+        p5.log.warn("git init failed; initialize the repository manually.");
+      }
+    }
+  }
+  s.stop("Plugin scaffolded");
+  const rel = path10.relative(process.cwd(), targetDir) || ".";
+  p5.note(
+    [
+      `Standalone plugin "${name}" (${resolved.label}) \u2014 no marketplace was created.`,
+      "",
+      "Distribute it either way:",
+      "  \u2022 Push this folder to its own git repo, then reference it from a",
+      `    marketplace:  agkit add <owner/repo> ${name}`,
+      "  \u2022 Or drop it into an existing marketplace's plugins/ and run:",
+      "    agkit sync"
+    ].join("\n"),
+    `Next steps  (cd ${rel})`
+  );
+  p5.outro("Done \u2714");
+}
 async function initCommand(dirArg, opts) {
-  p5.intro(pc4.bgCyan(pc4.black("  agkit init  ")));
   const targetDir = path10.resolve(dirArg ?? ".");
+  if (opts.plugin) {
+    return initPlugin(targetDir, opts.plugin, opts);
+  }
+  p5.intro(pc4.bgCyan(pc4.black("  agkit init  ")));
   const defaultName = path10.basename(targetDir).toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "");
   const gitAvailable = isGitAvailable();
   const existingRemote = gitAvailable && fs9.existsSync(targetDir) ? getOriginUrl(targetDir) : void 0;
@@ -1596,21 +1826,41 @@ var program = new Command();
 program.name("agkit").description(
   "Scaffold and manage plugin marketplaces for Claude Code and GitHub Copilot, distributed via any Git host."
 ).version(version);
-program.command("init").argument("[dir]", "target directory (default: current directory)").description("Scaffold a new plugin marketplace (git-first)").option("-n, --name <name>", "marketplace name (kebab-case)").option("-o, --owner <owner>", "owner name").option("-e, --email <email>", "owner email").option("-d, --description <text>", "marketplace description").option("-r, --repo <url>", "git remote URL (any forge)").option("--ci <ci>", "CI workflow: github | gitlab | none").option(
+program.command("init").argument("[dir]", "target directory (default: current directory)").description(
+  "Scaffold a new plugin marketplace (git-first), or a standalone plugin with --plugin"
+).option(
+  "-n, --name <name>",
+  "marketplace (or plugin, with --plugin) name (kebab-case)"
+).option("-o, --owner <owner>", "owner / plugin author name").option("-e, --email <email>", "owner email").option(
+  "-d, --description <text>",
+  "marketplace (or plugin, with --plugin) description"
+).option("-r, --repo <url>", "git remote URL (any forge)").option("--ci <ci>", "CI workflow: github | gitlab | none").option(
   "--agents <list>",
   "comma-separated target agents (e.g. claude-code,copilot,codex)"
+).option(
+  "--plugin [template]",
+  "scaffold a standalone plugin (skill|command|agent|hook|mcp, or a template spec) in [dir] instead of a marketplace"
 ).option("-y, --yes", "non-interactive, accept defaults").action(async (dir, opts) => {
   await initCommand(dir, opts);
 });
 program.command("add").argument(
   "[template]",
-  "template name, local path, gh:/gl: shorthand, or git URL (see `agkit list`)"
+  "built-in template name, local path, or remote git source (owner/repo, gh:/gl: shorthand, git URL). Remote sources are referenced, not cloned (see --vendor)."
 ).argument("[name]", "plugin name (kebab-case)").description(
-  "Scaffold a plugin from a template and register it in the catalog"
-).option("-d, --description <text>", "one-line plugin description").action(async (template, name, opts) => {
+  "Register a plugin in the catalog: reference a remote git repo, or scaffold from a built-in/local template"
+).option("-d, --description <text>", "one-line plugin description").option(
+  "--vendor",
+  "clone the remote repo and scaffold from its files into the marketplace, instead of referencing it"
+).option("--ref <ref>", "branch or tag to pin a referenced remote source to").option(
+  "--sha <sha>",
+  "commit hash (40 hex) to pin a referenced remote source to"
+).action(async (template, name, opts) => {
   await addPlugin(process.cwd(), template, name, {
     description: opts.description,
-    interactive: opts.description === void 0
+    interactive: opts.description === void 0,
+    vendor: opts.vendor,
+    ref: opts.ref,
+    sha: opts.sha
   });
 });
 program.command("sync").description("Reconcile marketplace.json and README with the plugins on disk").action(async () => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agkit",
-  "version": "0.8.0",
+  "version": "0.9.0",
   "description": "Scaffold and manage plugin marketplaces for Claude Code and GitHub Copilot, distributed via any Git host (GitHub, GitLab, Bitbucket, Gitea, self-hosted). Init, add plugins from built-in or remote templates, sync, validate, bump.",
   "license": "MIT",
   "author": "fair3n <fairen.dev@gmail.com>",
@@ -21,7 +21,7 @@
     "LICENSE"
   ],
   "engines": {
-    "node": ">=18.0.0"
+    "node": ">=22.0.0"
   },
   "scripts": {
     "build": "tsup",