From f2ebf5b748a80fbc9843d33906bf8928e366f9d5 Mon Sep 17 00:00:00 2001 From: Danil Silantyev Date: Sun, 19 Jul 2026 14:50:13 +0500 Subject: [PATCH] feat(builder): enrich for the verified current ZCode 3.3.6 surface (2.1.6) Comprehensive upgrade of the nddev-builder core toolkit against the verified current ZCode 3.3.6 / CLI 0.15.2 surface (3.3.6 is the latest release, so the runtime pin is unchanged). Two new workflow skills plus matching commands: - publish-marketplace: distribute a marketplace via a GitHub repo, Git URL, or ZIP URL for install through the ZCode Marketplace tab. - orchestrate-subagents: design multi-subagent workflows within ZCode's limits (user-scope, foreground, parallel-yes/background-no). Enrichments across the format reference and existing skills: remote marketplace distribution and the {source:"github",repo} entry; the engine-verified ${ZCODE_PLUGIN_ROOT} plugin-root variable (replacing ${CLAUDE_PLUGIN_ROOT}); MCP transports stdio/http/sse with OAuth (3.3.2), cross-agent import, and the strict schema; the marketplace-root mcp.json vs plugin .mcp.json distinction; the expanded provider matrix; dual .zcode-plugin/.claude-plugin manifest portability; and richer validate-components checks (hook and MCP schema, placeholder integrity, inert-field warnings). No publish-portal, managed-requirements, or npm sources were added -- those do not exist on this runtime. Toolkit is now 21 skills / 21 commands; module and marketplace versions advance to 2.1.6. Claude-Session: https://claude.ai/code/session_01Y29c9sJRhChvxDcUjab5Xo --- CHANGELOG.md | 24 +++ README.md | 4 +- VERSION | 2 +- build/manifest.json | 2 +- build/release-evidence.json | 10 +- build/version.json | 2 +- docs/architecture.md | 2 +- .../nddev-builder/marketplace.json | 2 +- .../plugins/core/.zcode-plugin/plugin.json | 2 +- .../nddev-builder/plugins/core/README.md | 13 +- .../core/commands/nddev-orchestrate.md | 11 ++ .../plugins/core/commands/nddev-publish.md | 12 ++ .../core/references/zcode-native-format.md | 157 ++++++++++++++---- .../plugins/core/skills/add-hook/SKILL.md | 6 +- .../core/skills/add-marketplace/SKILL.md | 10 ++ .../core/skills/add-mcp-server/SKILL.md | 30 +++- .../plugins/core/skills/add-plugin/SKILL.md | 6 + .../plugins/core/skills/add-provider/SKILL.md | 12 ++ .../plugins/core/skills/add-tool/SKILL.md | 9 +- .../skills/nddev-builder-orientation/SKILL.md | 27 ++- .../skills/orchestrate-subagents/SKILL.md | 49 ++++++ .../core/skills/publish-marketplace/SKILL.md | 50 ++++++ .../core/skills/scaffold-plugin/SKILL.md | 3 +- .../core/skills/validate-components/SKILL.md | 27 ++- 24 files changed, 403 insertions(+), 69 deletions(-) create mode 100644 zcode_tools/marketplaces/nddev-builder/plugins/core/commands/nddev-orchestrate.md create mode 100644 zcode_tools/marketplaces/nddev-builder/plugins/core/commands/nddev-publish.md create mode 100644 zcode_tools/marketplaces/nddev-builder/plugins/core/skills/orchestrate-subagents/SKILL.md create mode 100644 zcode_tools/marketplaces/nddev-builder/plugins/core/skills/publish-marketplace/SKILL.md diff --git a/CHANGELOG.md b/CHANGELOG.md index e41e39e..c7ff382 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -6,6 +6,30 @@ adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). ## [Unreleased] +## [2.1.6] - 2026-07-19 + +### Added + +- Two new `nddev-builder` workflow skills (plus matching commands): + `publish-marketplace` (distribute a marketplace via a GitHub repo, Git URL, or + ZIP URL for install through the ZCode Marketplace tab) and + `orchestrate-subagents` (design multi-subagent workflows within ZCode 3.3.6's + limits: user-scope, foreground, parallel-yes/background-no). Toolkit is now 21 + skills / 21 slash commands. + +### Changed + +- Enriched the builder against the verified current ZCode 3.3.6 / CLI 0.15.2 + surface (3.3.6 is the latest release, so no version-pin change): remote + marketplace distribution (GitHub/Git/ZIP-URL via the Marketplace tab and + `{"source":"github","repo":...}` entries), the engine-verified + `${ZCODE_PLUGIN_ROOT}` plugin-root variable, MCP transports (stdio/http/sse) + with OAuth (3.3.2) and cross-agent import and strict-schema rules, the expanded + provider matrix, dual `.zcode-plugin`/`.claude-plugin` manifest portability, and + richer `validate-components` checks (hook and MCP schema, placeholder integrity, + inert-field warnings). No publish-portal, managed-requirements, or npm sources + were added — those do not exist on this runtime. + ## [2.1.5] - 2026-07-19 ### Added diff --git a/README.md b/README.md index b51adbd..6149138 100644 --- a/README.md +++ b/README.md @@ -8,7 +8,7 @@ changes. - **Author:** Danil Silantyev (github:rldyourmnd), CEO NDDev - **License:** AGPL-3.0-or-later -- **Build version:** 2.1.5 +- **Build version:** 2.1.6 - **Verified ZCode runtime:** app 3.3.6, CLI 0.15.2, model GLM-5.2 ## What this repository contains @@ -69,7 +69,7 @@ restore, remove, and custom-target usage. Each directory under `zcode_tools/marketplaces/` is a complete setup: -- `nddev-builder` enables its reusable 19-skill, 19-command `core` toolkit for +- `nddev-builder` enables its reusable 21-skill, 21-command `core` toolkit for creating and managing ZCode marketplaces, plugins, and components. - `nddev-designer` is a deliberately lean product-design profile focused on design-system consistency, accessibility, responsive states, and diff --git a/VERSION b/VERSION index cd57a8b..399088b 100644 --- a/VERSION +++ b/VERSION @@ -1 +1 @@ -2.1.5 +2.1.6 diff --git a/build/manifest.json b/build/manifest.json index 5804750..82c3cd1 100644 --- a/build/manifest.json +++ b/build/manifest.json @@ -1,6 +1,6 @@ { "name": "nddev-zcode-app", - "build_version": "2.1.5", + "build_version": "2.1.6", "source_root": "zcode_tools/marketplaces/", "installer": "cli-tools/scripts/install.sh install --setup ", "layout": { diff --git a/build/release-evidence.json b/build/release-evidence.json index feb74de..3d9dfc5 100644 --- a/build/release-evidence.json +++ b/build/release-evidence.json @@ -2,15 +2,15 @@ "schema_version": 2, "module": { "repository": "NDDev-it-com/nddev-zcode-app", - "setup_digest": "sha256:7da756e9cd3e22080d2ac0d44ae9a55bfbcef7f248877058eb1e13898ae2ed0a" + "setup_digest": "sha256:41478eecc5c2f3a32d2e45cb8e656979c8468926e49dd7fc2f303e3f3dd7ff3e" }, "harness": { "repository": "NDDev-it-com/nddev-harnesses", - "commit": "3fa150a3215943e32778f956282d75e4cbc0af32" + "commit": "466f683d8336d5bcb921b06f021cb977704a6ca0" }, "adapter": { "id": "zcode", - "version": "2.1.5" + "version": "2.1.6" }, "vendor": { "app_version": "3.3.6", @@ -30,8 +30,8 @@ } ], "lanes": [], - "generated_at_utc": "2026-07-19T08:34:26Z", - "expires_at_utc": "2027-01-15T08:34:26Z", + "generated_at_utc": "2026-07-19T09:49:42Z", + "expires_at_utc": "2027-01-15T09:49:42Z", "promotion": { "decision": "pending", "waivers": [] diff --git a/build/version.json b/build/version.json index 3c2484d..7a42500 100644 --- a/build/version.json +++ b/build/version.json @@ -1,5 +1,5 @@ { - "build_version": "2.1.5", + "build_version": "2.1.6", "zcode_app_version": "3.3.6", "zcode_cli_version": "0.15.2", "zcode_runtime": "GLM-5.2", diff --git a/docs/architecture.md b/docs/architecture.md index 7929a21..04e9b07 100644 --- a/docs/architecture.md +++ b/docs/architecture.md @@ -52,7 +52,7 @@ prefix. ### Setup profiles - `nddev-builder` enables `core@nddev-builder`, a native component-authoring - toolkit with 19 skills, 19 matching commands, and one reviewer agent. + toolkit with 21 skills, 21 matching commands, and one reviewer agent. - `nddev-designer` is a production-ready minimal design profile. Its empty extension maps are intentional; project-specific design tools come from the active workspace. diff --git a/zcode_tools/marketplaces/nddev-builder/marketplace.json b/zcode_tools/marketplaces/nddev-builder/marketplace.json index 8f9d52f..55547ad 100644 --- a/zcode_tools/marketplaces/nddev-builder/marketplace.json +++ b/zcode_tools/marketplaces/nddev-builder/marketplace.json @@ -10,7 +10,7 @@ "name": "core", "source": "./plugins/core", "description": "Reusable toolkit: skills, slash commands, and a reviewer subagent for building plugins, managing MCP servers and providers, authoring skills, and listing or removing components.", - "version": "2.1.5", + "version": "2.1.6", "author": { "name": "Danil Silantyev (github:rldyourmnd), CEO NDDev" }, diff --git a/zcode_tools/marketplaces/nddev-builder/plugins/core/.zcode-plugin/plugin.json b/zcode_tools/marketplaces/nddev-builder/plugins/core/.zcode-plugin/plugin.json index 106c34c..40d930e 100644 --- a/zcode_tools/marketplaces/nddev-builder/plugins/core/.zcode-plugin/plugin.json +++ b/zcode_tools/marketplaces/nddev-builder/plugins/core/.zcode-plugin/plugin.json @@ -1,6 +1,6 @@ { "name": "core", - "version": "2.1.5", + "version": "2.1.6", "description": "Reusable ZCode toolkit: skills, slash commands, and a reviewer subagent for building plugins, managing MCP servers and providers, authoring skills, and listing or removing components.", "author": { "name": "Danil Silantyev (github:rldyourmnd), CEO NDDev", diff --git a/zcode_tools/marketplaces/nddev-builder/plugins/core/README.md b/zcode_tools/marketplaces/nddev-builder/plugins/core/README.md index b10de21..07c2f01 100644 --- a/zcode_tools/marketplaces/nddev-builder/plugins/core/README.md +++ b/zcode_tools/marketplaces/nddev-builder/plugins/core/README.md @@ -3,18 +3,19 @@ The `core` plugin is a reusable ZCode-native toolkit for creating and managing marketplaces, plugins, and convention-discovered components. -- **19 skills**: `add-marketplace`, `add-plugin`, `add-skill`, `add-command`, +- **21 skills**: `add-marketplace`, `add-plugin`, `add-skill`, `add-command`, `add-agent`, `add-hook`, `add-mcp-server`, `add-provider`, `add-reference`, `add-tool`, `add-instructions`, `list-components`, `remove-component`, `enable-plugin`, `nddev-builder-orientation`, `validate-components`, - `scaffold-plugin`, `devtest-plugin`, and `release-review`. -- **19 slash commands**: `/nddev-add-marketplace`, `/nddev-add-plugin`, + `scaffold-plugin`, `devtest-plugin`, `release-review`, `publish-marketplace`, + and `orchestrate-subagents`. +- **21 slash commands**: `/nddev-add-marketplace`, `/nddev-add-plugin`, `/nddev-add-skill`, `/nddev-add-command`, `/nddev-add-agent`, `/nddev-add-hook`, `/nddev-add-mcp`, `/nddev-add-provider`, `/nddev-add-reference`, `/nddev-add-tool`, `/nddev-add-instructions`, `/nddev-list`, `/nddev-remove`, `/nddev-enable`, `/nddev-orient`, - `/nddev-validate`, `/nddev-scaffold`, `/nddev-devtest`, and - `/nddev-release-review`. + `/nddev-validate`, `/nddev-scaffold`, `/nddev-devtest`, + `/nddev-release-review`, `/nddev-publish`, and `/nddev-orchestrate`. - **1 subagent**: `nddev-native-reviewer` (GLM-5.2). ## Capabilities @@ -37,6 +38,8 @@ marketplaces, plugins, and convention-discovered components. | `scaffold-plugin` | Compose a whole plugin from an intent | | `devtest-plugin` | Isolated install-and-verify loop in throwaway state | | `release-review` | Gate a whole marketplace for release readiness | +| `publish-marketplace` | Distribute a marketplace via GitHub/Git/ZIP URL for UI install | +| `orchestrate-subagents` | Design multi-subagent workflows within ZCode limits | | `nddev-native-reviewer` | Review ZCode-native format correctness | Development-only test, benchmark, release, and repository-doctor capabilities diff --git a/zcode_tools/marketplaces/nddev-builder/plugins/core/commands/nddev-orchestrate.md b/zcode_tools/marketplaces/nddev-builder/plugins/core/commands/nddev-orchestrate.md new file mode 100644 index 0000000..d4122d4 --- /dev/null +++ b/zcode_tools/marketplaces/nddev-builder/plugins/core/commands/nddev-orchestrate.md @@ -0,0 +1,11 @@ +--- +description: Design a multi-subagent workflow for a plugin within ZCode 3.3.6 limits (user-scope, foreground, parallel-yes/background-no). +--- + +Design how several subagents cooperate in a plugin. + +Follow the `orchestrate-subagents` skill exactly: choose a shape (recon→act with +`Explore`, parallel fan-out, or a critic panel with on-disk evidence receipts), +author each agent with `add-agent` (focused description, least-privilege tools, +unique basename), and validate. Never design for background subagents — they run +foreground on 3.3.6. diff --git a/zcode_tools/marketplaces/nddev-builder/plugins/core/commands/nddev-publish.md b/zcode_tools/marketplaces/nddev-builder/plugins/core/commands/nddev-publish.md new file mode 100644 index 0000000..f01b398 --- /dev/null +++ b/zcode_tools/marketplaces/nddev-builder/plugins/core/commands/nddev-publish.md @@ -0,0 +1,12 @@ +--- +description: Distribute a ZCode marketplace via a GitHub repo, Git URL, local path, or ZIP URL for install through the ZCode Marketplace tab. +--- + +Distribute a marketplace beyond this repo's installer. + +Follow the `publish-marketplace` skill exactly: pass `validate-components` and +`release-review`, make the root `marketplace.json` self-describing (local `source` +for the headless installer, remote `{source:"github",repo:...}` for UI install), +ship portable `.zcode-plugin` (+ optional `.claude-plugin`) manifests, push to a +GitHub repo / Git URL / ZIP URL, and document adding it via the ZCode Marketplace +tab. There is no CLI `plugin add`. diff --git a/zcode_tools/marketplaces/nddev-builder/plugins/core/references/zcode-native-format.md b/zcode_tools/marketplaces/nddev-builder/plugins/core/references/zcode-native-format.md index f640716..a739378 100644 --- a/zcode_tools/marketplaces/nddev-builder/plugins/core/references/zcode-native-format.md +++ b/zcode_tools/marketplaces/nddev-builder/plugins/core/references/zcode-native-format.md @@ -2,7 +2,8 @@ A condensed reference for the rules every component in this repository must follow. Authoritative source: the `nddev-builder-orientation` skill and the built-in -`zcode-configuration-guide` / `diagnosing-plugins` skills (the ZCode runtime's own guide). +`zcode-configuration-guide` / `diagnosing-plugins` skills (the ZCode runtime's own +guide), corroborated against the pinned ZCode 3.3.6 / CLI 0.15.2 engine. ## Marketplaces and plugin bundles @@ -15,12 +16,14 @@ marketplaces// marketplace.json ← the marketplace root manifest plugins/ / - .zcode-plugin/plugin.json ← metadata only + .zcode-plugin/plugin.json ← metadata only (ZCode reads this first) + .claude-plugin/plugin.json ← optional portability fallback (see below) skills//SKILL.md commands/.md agents/.md .mcp.json ← only on the MCP transport plugin references/ + tools/ ← optional CLI tools (not flattened) README.md ``` @@ -36,12 +39,20 @@ marketplaces// | `homepage` | no | plugin path in the repo | | `repository` | no | the GitHub repo URL | | `keywords` | no | English tags | -| `dependencies` | no | other plugin names this one requires | +| `dependencies` | no | `name@marketplace` strings this plugin requires | Never add component arrays (`commands`, `skills`, `hooks`, `mcpServers`, `agents`) or the inert fields listed below — the manifest is metadata-only and discovery is by convention. +**Manifest search order (portability).** ZCode resolves a plugin manifest in the +order `.zcode-plugin/plugin.json` → `.claude-plugin/plugin.json` → +`.codex-plugin/plugin.json`. ZCode's plugin/marketplace/skill/command/hook formats +are the Claude Code formats with ZCode-specific runtime differences (below). To +make one bundle run in both tools, you may ship **both** `.zcode-plugin/plugin.json` +(ZCode-first) and an identical `.claude-plugin/plugin.json` (Claude Code fallback). +ZCode-only bundles need only `.zcode-plugin`. + ## Component execution model (ZCode 3.3.6) The pinned ZCode 3.3.6 runtime **executes only four plugin-manifest component @@ -51,16 +62,27 @@ execute only from user scope (which is why the installer flattens `agents/` into **Recorded but NOT executed** as plugin.json fields (declaring them has no runtime effect, so never author them expecting behavior): `channels`, -`lspServers`, `outputStyles`, `settings`. In particular an -`lspServers` / `.lsp.json` block is **inert** on this runtime — there is **no -loadable LSP component**, so this toolkit ships no `add-lsp` skill by design. -(The desktop `v2-setting` file this repo renders is a different surface: it is -the ZCode app's own settings, written directly to `~/.zcode/v2/`, not the inert -plugin.json `settings` field.) If a future pinned runtime executes these fields, -this reference and the runtime pin move together. - -Authoritative source: the built-in `zcode-guide` plugin -(`zcode-configuration-guide`, `diagnosing-plugins`). +`lspServers`, `outputStyles`, `settings`. The public Plugin doc lists **LSP** as a +bundleable component, but on this runtime an `lspServers` / `.lsp.json` block is +**inert** (LSP is delivered through a hook, not a native component) — there is **no +loadable LSP component**, so this toolkit ships no `add-lsp` skill by design. This +is a documented-surface-vs-executed-runtime gap; if a future pinned runtime +executes these fields, this reference and the runtime pin move together. (The +desktop `v2-setting` file this repo renders is a different surface: the ZCode app's +own settings, written to `~/.zcode/v2/`, not the inert plugin.json `settings`.) + +### Plugin-root variable + +The engine-verified ZCode-native plugin-root substitution is +**`${ZCODE_PLUGIN_ROOT}`** (use it in hook commands and any path that must resolve +to a plugin's installed root). `${CLAUDE_PLUGIN_ROOT}` is the Claude Code spelling +and may resolve as a compat alias, but prefer `${ZCODE_PLUGIN_ROOT}` and confirm +resolution with `devtest-plugin` before relying on it. **Caveat for this repo's +headless flatten install:** only `skills/`, `commands/`, and `agents/` are +flattened to user scope; `references/` and `tools/` are not, and a plugin-root +variable may be unset for a file-installed (non-UI) marketplace — a companion skill +should reference a tool by its absolute installed path +(`~/.zcode/marketplaces//plugins//tools/...`) when in doubt. ## Skills @@ -68,15 +90,21 @@ Authoritative source: the built-in `zcode-guide` plugin skills//SKILL.md ``` -Frontmatter: `name` (matches dir), `description` (English, trigger-rich). Body is markdown. -The first same-named skill in discovery order wins (user > workspace > plugin). +Frontmatter (ZCode-required): `name` (matches dir), `description` (English, +trigger-rich, ≤1024 chars; the first ~250 characters carry the routing weight, so +front-load a concrete "Use when …"). Body is markdown. Prefer **progressive +disclosure**: keep `SKILL.md` short and push detail into bundled scripts, `tools/`, +and `references/` loaded on demand. Extended frontmatter keys from the Claude Code +lineage (`allowed-tools`, `disable-model-invocation`, `${…SKILL_DIR}`, +`` !`cmd` `` injection) are not in ZCode's public docs — confirm with +`devtest-plugin` before depending on them. **Loading reality (ZCode 3.3.6):** ZCode loads skills/commands/agents only from user scope (`~/.zcode/{skills,commands,agents}`, `~/.agents/skills`), never from `~/.zcode/marketplaces/.../plugins/`. The installer flattens each plugin's `skills/`, `commands/`, and `agents/` into user scope; basenames must be unique -across every plugin (the flatten fails closed on a collision). `references/` and -`tools/` are not flattened. +across every plugin (the flatten fails closed on a collision). Skills are invoked +by typing `$`; the first same-named skill in discovery order wins. ## Commands @@ -84,36 +112,95 @@ across every plugin (the flatten fails closed on a collision). `references/` and commands/.md ← becomes / ``` -Frontmatter: `description`. Nested dirs join with a colon: `review/code.md` → `/review:code`. +Frontmatter: `description` (and optional `argument-hint`, `allowed-tools`, `model`, +`skills`, `disable-noninteractive`). Nested dirs join with a **colon**: +`review/code.md` → `/review:code` (not a slash). Arguments interpolate as +`$ARGUMENTS`, `$1`, `$2`. Invoked with `/`. Built-ins include `/goal` and +`/compact`. ZCode keeps Commands and Skills distinct (unlike current Claude Code, +which is moving commands into skills). -## Agents +## Agents (subagents) ``` agents/.md ``` -Frontmatter: `name`, `model` (e.g. `GLM-5.2`). +Frontmatter: `name`, `model` (`GLM-5.2`, `GLM-5-Turbo`, or "inherit"), +`description` (drives auto-selection). Built-in agents: **General-Purpose** and +**Explore** (read-only — use it for recon before writes). Invoked automatically or +explicitly with `@`. **Beta constraints (3.3.6):** user-level only, foreground, +**parallel supported but no background execution**. Plugin-bundled `agents/` are +diagnostic-only until flattened to `~/.zcode/agents/`. ## MCP servers -Centralized in ONE file per MCP transport plugin: -`marketplaces//plugins//.mcp.json`, shape `{"mcpServers": {}}`. -Each entry is either: - -- stdio: `{"command": "...", "args": [...], "env": {...}}` -- http: `{"type": "http", "url": "..."}` - -Secrets use `${VAR}` placeholders, rendered from `build/.env` at install time. +Two authoring modes — pick per `add-mcp-server` (standard MCP) or `add-tool` +(CLI-tool-as-alternative): + +**Standard MCP.** This repo's setup-level MCP config is a **`mcp.json` at the +marketplace root** (`marketplaces//mcp.json`, shape +`{"mcpServers": {}}`); the installer merges its `mcpServers` into +`~/.zcode/cli/config.json` under **`mcp.servers`** (the ZCode-native config key). +A plugin-scoped `.mcp.json` inside a plugin directory is the Claude-Code +plugin-level form, used by UI-installed plugins. See `add-mcp-server`. +Transports: **stdio** (default; `command` **must be a string**, plus `args`, `env`), +**http**/**sse** (`type` + `url`, plus `headers` for auth). `type` is inferred from +`command`/`url`. Strict rules (getting these wrong drops the server silently or +crashes the parser): `command` is a string not an array; exact field names +`env`/`headers`/`enabled`; **no unknown top-level keys**; default timeout +`timeoutMs` 30000. Remote auth uses a `headers` `Authorization` entry or **MCP +OAuth** (since 3.3.2); local MCP config can sync to an SSH remote (3.3.0). ZCode +can import MCP from Claude Code / Codex / OpenCode configs and `~/.agents/mcp.json`. +Secrets use `${VAR}` placeholders — they expand in a plugin `.mcp.json` but **not** +in `cli/config.json`, so this repo renders them from `build/.env` at install time. + +**CLI-tool alternative.** A small script in `plugins/

/tools//` plus a +token-thin companion skill (see `add-tool`). Prefer it for local-dev token economy, +deterministic composition (pipes/loops/files), and simple process-env secrets; +prefer standard MCP for cross-agent tool discovery or a constrained permission +model. ## Hooks -Live in `~/.zcode/cli/config.json` under `hooks` (requires `hooks.enabled: true`). The -seven supported events: `SessionStart`, `UserPromptSubmit`, `PreToolUse`, -`PermissionRequest`, `PostToolUse`, `PostToolUseFailure`, `Stop`. +Live in `~/.zcode/cli/config.json` under `hooks` (requires `hooks.enabled: true`). +The **seven** supported events: `SessionStart`, `UserPromptSubmit`, `PreToolUse`, +`PermissionRequest`, `PostToolUse`, `PostToolUseFailure`, `Stop` +(`SubagentStop`/`PreCompact`/`Notification`/`SessionEnd` are **not** supported). +Handler types: `type:"command"` (shell; `timeout` in **seconds**) and +`type:"process"` (no shell; `timeoutMs` in **milliseconds**; cross-platform — +prefer it). `matcher` is a **case-sensitive regex** (aliases `Task↔Agent`, +`Write/Edit↔ApplyPatch`). Stdout is a **strict schema** (`additionalContext`, or +`decision`/`reason` for `Stop`); a `Stop` block re-continues at most 3 times. Use +`${ZCODE_PLUGIN_ROOT}` to resolve a plugin-relative command. ## Marketplace -`zcode_tools/marketplaces//marketplace.json` — one root manifest per marketplace, -with `name`, `owner`, `description`, and a -`plugins[]` array. Each entry: `name`, `source` (relative `./plugins/`), -`description`, `version`, `author`, `category`, `tags`, `license`. +`zcode_tools/marketplaces//marketplace.json` — one root manifest per +marketplace, with `name`, `owner`, `description`, and a `plugins[]` array. Each +entry: `name`, `source`, `description`, `version`, `author`, `category`, `tags`, +`license`. + +**`source` — local vs remote.** For this repo's **headless flatten install**, use a +**local** relative `source` (`./plugins/`) that exists on disk — the installer +flattens local plugin dirs and cannot fetch remote ones. For **UI distribution**, +ZCode 3.3.6 also accepts remote plugins: a `source` object `{"source":"github", +"repo":"owner/repo"}`, and users can add a whole marketplace from a **GitHub repo, +Git URL, local path, or ZIP URL** through the Marketplace tab (npm is not a +supported source). See `publish-marketplace` for the distribution story and +`validate-components` for which `source` forms each path requires. + +**Maturity and sync.** The plugin/marketplace system is **Beta** (introduced in +ZCode 3.2.0) and still evolving: skill sync over SSH landed in 3.2.5, MCP-config +sync in 3.3.0, and plugin + marketplace sync in 3.3.4 — relevant to multi-machine +authoring. Expect the surface to keep hardening; re-verify against the changelog +when the runtime pin advances. + +## Providers (model configuration) + +Rendered into `~/.zcode/v2/config.json` (see `add-provider`). ZCode 3.3.6 documents +**GLM Coding Plan (Z.ai / BigModel), Anthropic, OpenAI, OpenRouter, Moonshot, +MiniMax, Xiaomi MiMo**, and custom Anthropic/OpenAI-compatible providers. Auth is +account **OAuth** ("Continue with Z.ai / BigModel") or an **API key**. Models: +`GLM-5.2` and `GLM-5-Turbo`; Z.ai Anthropic base `https://api.z.ai/api/anthropic`, +BigModel `https://open.bigmodel.cn/api/anthropic`. Custom API-key providers must +never reuse ZCode-owned `builtin:*` identities. diff --git a/zcode_tools/marketplaces/nddev-builder/plugins/core/skills/add-hook/SKILL.md b/zcode_tools/marketplaces/nddev-builder/plugins/core/skills/add-hook/SKILL.md index bbc95fb..1a27a3a 100644 --- a/zcode_tools/marketplaces/nddev-builder/plugins/core/skills/add-hook/SKILL.md +++ b/zcode_tools/marketplaces/nddev-builder/plugins/core/skills/add-hook/SKILL.md @@ -120,8 +120,10 @@ a command hook but 500ms (half a second) for a process hook. Default is 60000ms by its **absolute installed path** `~/.zcode/marketplaces//scripts/.sh`. A config-file hook is merged into `~/.zcode/cli/config.json`; it does not run from the marketplace - directory and does not expand `${CLAUDE_PLUGIN_ROOT}` (that is plugin-hook - only), so a relative path silently fails to resolve. + directory and does not expand a plugin-root variable — `${ZCODE_PLUGIN_ROOT}` + (the engine-verified ZCode-native plugin-hook variable; `${CLAUDE_PLUGIN_ROOT}` + is at most a compat alias, confirm with `devtest-plugin`) resolves only for a + UI-installed plugin hook, so here a relative path silently fails to resolve. 3. Open `hooks.json` in the active marketplace and add the entry to the matching event array. Strip the `_comment` key mentally — the installer drops it at merge time. diff --git a/zcode_tools/marketplaces/nddev-builder/plugins/core/skills/add-marketplace/SKILL.md b/zcode_tools/marketplaces/nddev-builder/plugins/core/skills/add-marketplace/SKILL.md index dfb142e..e626f28 100644 --- a/zcode_tools/marketplaces/nddev-builder/plugins/core/skills/add-marketplace/SKILL.md +++ b/zcode_tools/marketplaces/nddev-builder/plugins/core/skills/add-marketplace/SKILL.md @@ -75,6 +75,16 @@ the installer merges them into `cli/config.json` if present): marketplace `core` entry, and the core plugin manifest; also update `CHANGELOG.md`. +## Distribution + +This repo installs a marketplace headlessly (`install.sh install --setup `), +which requires local `./plugins/` sources on disk. To let others install it, +ZCode 3.3.6 also supports UI distribution: a user adds the marketplace through +Plugin Management → Marketplace from a **GitHub repo, Git URL, local path, or ZIP +URL**, and a plugin `source` may be a remote object +`{"source":"github","repo":"owner/repo"}` (npm is not a supported source). See the +`publish-marketplace` skill for the full distribution flow. + ## Rules - Every marketplace is self-contained — it owns its AGENTS.md and all config diff --git a/zcode_tools/marketplaces/nddev-builder/plugins/core/skills/add-mcp-server/SKILL.md b/zcode_tools/marketplaces/nddev-builder/plugins/core/skills/add-mcp-server/SKILL.md index 144b458..dc9e2c9 100644 --- a/zcode_tools/marketplaces/nddev-builder/plugins/core/skills/add-mcp-server/SKILL.md +++ b/zcode_tools/marketplaces/nddev-builder/plugins/core/skills/add-mcp-server/SKILL.md @@ -72,6 +72,16 @@ http server: } ``` +sse server (long-lived event stream): + +```json +{ + "mcpServers": { + "": { "type": "sse", "url": "https://...", "headers": {}, "timeoutMs": 30000 } + } +} +``` + ### Strict schema rules (violations silently drop the server) - **`command` MUST be a string** (not an array). `command: ["npx", "..."]` crashes @@ -95,11 +105,24 @@ the installer resolves them, not ZCode. For reference (if editing `cli/config.json` directly, bypassing the installer): config-file servers do NOT expand `${...}` — use absolute values or env vars read by the server process itself. Plugin `.mcp.json` servers (inside a plugin -directory) DO expand `${CLAUDE_PLUGIN_ROOT}`, `${ZCODE_PROJECT_DIR}`, etc. +directory) DO expand `${ZCODE_PLUGIN_ROOT}` (the engine-verified ZCode-native +plugin-root variable; `${CLAUDE_PLUGIN_ROOT}` may be a compat alias — confirm with +`devtest-plugin`), `${ZCODE_PROJECT_DIR}`, etc. Add the matching `VAR=` key (empty) to `build/.env.example` (committed) and `build/.env` (gitignored real value). +### Remote auth, OAuth, and cross-agent import + +- A remote (http/sse) server authenticates with a `headers` `Authorization` + entry. For local development, ZCode supports **MCP OAuth** (since 3.3.2) — the + runtime drives the OAuth flow, so never hard-code a token. +- ZCode can **import** MCP servers already configured for other tools instead of + duplicating them: Claude Code (`~/.claude/settings.json`), Codex, OpenCode, and + a generic `~/.agents/mcp.json`. +- Local MCP config can **sync to an SSH remote** (since 3.3.0) for multi-machine + authoring. + ## Path B: CLI + skill (the lean alternative) Instead of an MCP server, create a small CLI tool (a shell or node script) plus @@ -111,8 +134,9 @@ demand. CLI tools live **inside the plugin** in a `tools/` directory. The installer copies the whole marketplace (including plugins) into `~/.zcode/marketplaces/`, -so tools arrive there — but `tools/` is **not** flattened to user scope, and -`${CLAUDE_PLUGIN_ROOT}` is unset for a file-installed marketplace. At runtime the +so tools arrive there — but `tools/` is **not** flattened to user scope, and a +plugin-root variable (`${ZCODE_PLUGIN_ROOT}`) is unset for a file-installed +marketplace. At runtime the companion skill must reference the tool by its **absolute installed path**, `~/.zcode/marketplaces//plugins//tools//