From 7cf7abb649dcdaf8932ce3202a17a77dc7f2fa7a Mon Sep 17 00:00:00 2001 From: Danil Silantyev Date: Sat, 18 Jul 2026 07:38:14 +0500 Subject: [PATCH] feat: complete the nddev-builder toolkit and document ZCode's real loading model The authoring skills taught the pre-fix loading model: they told developers to place components in ~/.zcode/marketplaces//plugins/, which ZCode 3.3.6 never loads. A developer following them reproduced the exact bug the installer's user-scope flatten fixed. This corrects the toolkit to teach the real model and fills its gaps. - Add nddev-builder-orientation: the single map of the toolkit and how ZCode discovers/loads skills/commands/agents at user scope, what the installer flattens (and what it does not), the install/remove/switch lifecycle, and the fail-closed cross-plugin basename collision rule. - Add add-instructions (AGENTS.md user/workspace scopes and merge order) and validate-components (static pre-install checks incl. the cross-plugin collision that aborts a build), each with a /nddev-* command. - Correct add-skill, add-plugin, add-tool, add-mcp-server, add-hook, add-command, add-agent, the README, and the zcode-native-format reference to state the user-scope flatten reality, the collision rule, absolute installed paths for tools/hooks (not flattened, no ${CLAUDE_PLUGIN_ROOT}), the correct strict hook output schema (allow/ask/deny/additionalContext), and disable-noninteractive. Claude-Session: https://claude.ai/code/session_01Y29c9sJRhChvxDcUjab5Xo --- build/release-evidence.json | 8 +- .../nddev-builder/plugins/core/README.md | 17 ++-- .../core/commands/nddev-add-instructions.md | 11 +++ .../plugins/core/commands/nddev-orient.md | 12 +++ .../plugins/core/commands/nddev-validate.md | 11 +++ .../core/references/zcode-native-format.md | 7 ++ .../plugins/core/skills/add-agent/SKILL.md | 16 ++-- .../plugins/core/skills/add-command/SKILL.md | 5 +- .../plugins/core/skills/add-hook/SKILL.md | 22 +++-- .../core/skills/add-instructions/SKILL.md | 46 ++++++++++ .../core/skills/add-mcp-server/SKILL.md | 7 +- .../plugins/core/skills/add-plugin/SKILL.md | 14 ++- .../plugins/core/skills/add-skill/SKILL.md | 30 +++++-- .../plugins/core/skills/add-tool/SKILL.md | 9 +- .../skills/nddev-builder-orientation/SKILL.md | 87 +++++++++++++++++++ .../core/skills/validate-components/SKILL.md | 44 ++++++++++ 16 files changed, 311 insertions(+), 35 deletions(-) create mode 100644 zcode_tools/marketplaces/nddev-builder/plugins/core/commands/nddev-add-instructions.md create mode 100644 zcode_tools/marketplaces/nddev-builder/plugins/core/commands/nddev-orient.md create mode 100644 zcode_tools/marketplaces/nddev-builder/plugins/core/commands/nddev-validate.md create mode 100644 zcode_tools/marketplaces/nddev-builder/plugins/core/skills/add-instructions/SKILL.md create mode 100644 zcode_tools/marketplaces/nddev-builder/plugins/core/skills/nddev-builder-orientation/SKILL.md create mode 100644 zcode_tools/marketplaces/nddev-builder/plugins/core/skills/validate-components/SKILL.md diff --git a/build/release-evidence.json b/build/release-evidence.json index ea64c5d..dd39000 100644 --- a/build/release-evidence.json +++ b/build/release-evidence.json @@ -2,11 +2,11 @@ "schema_version": 2, "module": { "repository": "NDDev-it-com/nddev-zcode-app", - "setup_digest": "sha256:1ae439320693f777e93ae341cc4b2341a006bb6abe6fa417abdfcba8860bc072" + "setup_digest": "sha256:bba623d9aa81f6934ebe77dd5a635fc3544b5304a211b021401c4568bdffb511" }, "harness": { "repository": "NDDev-it-com/nddev-harnesses", - "commit": "1254bf60ddc5e50017b761f837893b85709ebe9f" + "commit": "df99892732c0b9ebaa8906773ec8d36e1521d960" }, "adapter": { "id": "zcode", @@ -30,8 +30,8 @@ } ], "lanes": [], - "generated_at_utc": "2026-07-18T01:26:53Z", - "expires_at_utc": "2027-01-14T01:26:53Z", + "generated_at_utc": "2026-07-18T02:35:51Z", + "expires_at_utc": "2027-01-14T02:35:51Z", "promotion": { "decision": "pending", "waivers": [] diff --git a/zcode_tools/marketplaces/nddev-builder/plugins/core/README.md b/zcode_tools/marketplaces/nddev-builder/plugins/core/README.md index 681a87a..fb12e71 100644 --- a/zcode_tools/marketplaces/nddev-builder/plugins/core/README.md +++ b/zcode_tools/marketplaces/nddev-builder/plugins/core/README.md @@ -38,9 +38,14 @@ the private `nddev-harnesses` control plane. ## Install -Add the local `nddev-builder` marketplace in ZCode Plugin Management, or use the -repository installer to place it under -`~/.zcode/marketplaces/nddev-builder/plugins/core/`. - -Plugin manifests are metadata-only; ZCode discovers skills, commands, agents, -references, and tools by convention. +Install with the repository installer (`install.sh install --setup nddev-builder`). +It places the marketplace under `~/.zcode/marketplaces/nddev-builder/` **and** +flattens each plugin's `skills/`, `commands/`, and `agents/` into +`~/.zcode/{skills,commands,agents}` — the flattened copy is what ZCode 3.3.6 +loads, because it never reads the `marketplaces/.../plugins/` tree on a headless +install. Adding the marketplace through the ZCode UI (Plugin Management) is the +alternative that registers it as a live plugin. + +Plugin manifests are metadata-only. `references/` and `tools/` are authoring +material and are not flattened. See the `nddev-builder-orientation` skill for the +full loading model. diff --git a/zcode_tools/marketplaces/nddev-builder/plugins/core/commands/nddev-add-instructions.md b/zcode_tools/marketplaces/nddev-builder/plugins/core/commands/nddev-add-instructions.md new file mode 100644 index 0000000..59025f1 --- /dev/null +++ b/zcode_tools/marketplaces/nddev-builder/plugins/core/commands/nddev-add-instructions.md @@ -0,0 +1,11 @@ +--- +description: Author or maintain ZCode AGENTS.md instruction files (user or workspace scope). +--- + +Add or maintain ZCode AGENTS.md instructions. + +Follow the `add-instructions` skill exactly: decide user vs workspace scope from +the rule's reach, edit the marketplace `AGENTS.md` (renders to user scope) or the +workspace `AGENTS.md` (via `/init`), keep instructions concise and imperative, +respect any managed begin/end markers, and keep skills/commands/hooks/MCP out of +the instruction file. diff --git a/zcode_tools/marketplaces/nddev-builder/plugins/core/commands/nddev-orient.md b/zcode_tools/marketplaces/nddev-builder/plugins/core/commands/nddev-orient.md new file mode 100644 index 0000000..da27adb --- /dev/null +++ b/zcode_tools/marketplaces/nddev-builder/plugins/core/commands/nddev-orient.md @@ -0,0 +1,12 @@ +--- +description: Orient in the nddev-builder toolkit and how ZCode actually loads extensions (read this first). +--- + +Explain how this toolkit and ZCode extension loading work. + +Follow the `nddev-builder-orientation` skill exactly: read it and summarize for +the user the marketplace layout, how ZCode 3.3.6 discovers and loads +skills/commands/agents at user scope, what the installer flattens (and what it +does not), the install/remove/switch lifecycle, and the global-uniqueness +collision rule. Then route them to the right `add-*` / `validate-components` +skill for their task. diff --git a/zcode_tools/marketplaces/nddev-builder/plugins/core/commands/nddev-validate.md b/zcode_tools/marketplaces/nddev-builder/plugins/core/commands/nddev-validate.md new file mode 100644 index 0000000..8146591 --- /dev/null +++ b/zcode_tools/marketplaces/nddev-builder/plugins/core/commands/nddev-validate.md @@ -0,0 +1,11 @@ +--- +description: Statically pre-check a marketplace's components before install (frontmatter, names, cross-plugin collisions). +--- + +Validate a marketplace's components before install. + +Follow the `validate-components` skill exactly: check skill/command/agent +frontmatter and name patterns, description length (≤1024), JSON validity, and — +most importantly — that no two plugins share a skill/command/agent basename +(the installer flattens to user scope and fails closed on a collision). Finish +with `install.sh install --setup --plan` as a non-mutating gate. 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 b2baa8c..43ca9b3 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 @@ -49,6 +49,13 @@ 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). +**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. + ## Commands ``` diff --git a/zcode_tools/marketplaces/nddev-builder/plugins/core/skills/add-agent/SKILL.md b/zcode_tools/marketplaces/nddev-builder/plugins/core/skills/add-agent/SKILL.md index 9ef8797..fe05bca 100644 --- a/zcode_tools/marketplaces/nddev-builder/plugins/core/skills/add-agent/SKILL.md +++ b/zcode_tools/marketplaces/nddev-builder/plugins/core/skills/add-agent/SKILL.md @@ -32,11 +32,17 @@ description: ## Frontmatter rules -- `name` (required) — must match the filename (without `.md`). -- `model` (required) — pin the model. Use `GLM-5.2` (the ZCode runtime baseline) - unless there is a deliberate reason for a different model. -- `description` (recommended) — English, trigger-rich. Explains WHEN to delegate. -- No other fields. +- `name` — must match the filename (without `.md`). +- `model` — pin the model; this toolkit's house rule is `GLM-5.2` (the ZCode + runtime baseline). ZCode publishes no subagent file schema, so treat `model` + as our convention, not a documented ZCode requirement. +- `description` — English, trigger-rich. Explains WHEN to delegate; also drives + automatic selection. + +Keep the frontmatter minimal and consistent across the marketplace. A subagent +loads only after the installer flattens it to `~/.zcode/agents/`, so its +basename must be unique across every plugin (the flatten fails closed on a +collision). ## Body: the system prompt diff --git a/zcode_tools/marketplaces/nddev-builder/plugins/core/skills/add-command/SKILL.md b/zcode_tools/marketplaces/nddev-builder/plugins/core/skills/add-command/SKILL.md index 42f2af1..3c2dfa4 100644 --- a/zcode_tools/marketplaces/nddev-builder/plugins/core/skills/add-command/SKILL.md +++ b/zcode_tools/marketplaces/nddev-builder/plugins/core/skills/add-command/SKILL.md @@ -53,9 +53,12 @@ Recognized keys (all **hyphenated**, NOT snake_case): - `allowed-tools` (optional) — inline comma list, e.g. `Read, Bash`. NOT multi-line. - `model` (optional) — model override. - `skills` (optional) — auto-mounted skills. +- `disable-noninteractive` (optional) — hide the command from headless/ + non-interactive runs. **Do NOT use snake_case** (`allowed_tools`, `argument_hint`) — they are silently -ignored. No `version`, `name`, or `tags`. +ignored. No `version`, `name`, or `tags`. A command whose name collides with a +built-in reserved name is filtered from the live `/` menu. ## Argument substitution 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 bcdfd89..719f03e 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 @@ -100,10 +100,16 @@ a command hook but 500ms (half a second) for a process hook. Default is 60000ms ### Output and exit codes -- **stdout** is parsed as **strict JSON** — any extra/unknown key fails validation. - Use the documented keys only (e.g. `{"decision": "block", "reason": "..."}`). -- **exit codes**: `0` = pass, `2` = block (deny for PreToolUse/PermissionRequest), - any other non-zero = error. Non-JSON stdout is shown to the model as context. +- **stdout** is parsed as **strict JSON** — any extra/unknown key fails validation + (the effect is discarded and the run marked failed). Emit only the recognized + keys, or emit nothing and rely on exit codes. The documented keys are: + `additionalContext` (injected into the conversation, any event); for + `PreToolUse`, a permission **decision** of `allow` / `ask` / `deny`; for + `Stop`, a continuation request. `decision: "block"` is **not** a recognized + key — use exit code `2` or a `deny` decision to block. +- **exit codes**: `0` = pass, `2` = block (a deny for + `PreToolUse`/`PermissionRequest`), any other non-zero = error. Empty stdout is + fine. ## Procedure @@ -111,7 +117,11 @@ a command hook but 500ms (half a second) for a process hook. Default is 60000ms 2. Write the hook command — a shell one-liner or a script path. If the logic is non-trivial, put it in a script under the marketplace (e.g. `zcode_tools/marketplaces//scripts/.sh`) and reference it - by path. + 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. 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. @@ -129,7 +139,7 @@ a command hook but 500ms (half a second) for a process hook. Default is 60000ms { "matcher": "Bash", "hooks": [ - { "type": "command", "command": "scripts/block-dangerous.sh" } + { "type": "command", "command": "~/.zcode/marketplaces//scripts/block-dangerous.sh" } ] } ] diff --git a/zcode_tools/marketplaces/nddev-builder/plugins/core/skills/add-instructions/SKILL.md b/zcode_tools/marketplaces/nddev-builder/plugins/core/skills/add-instructions/SKILL.md new file mode 100644 index 0000000..9e697e1 --- /dev/null +++ b/zcode_tools/marketplaces/nddev-builder/plugins/core/skills/add-instructions/SKILL.md @@ -0,0 +1,46 @@ +--- +name: add-instructions +description: Author or maintain ZCode AGENTS.md instruction files at user or workspace scope. Use when adding default agent instructions, editing AGENTS.md, deciding user-vs-workspace scope, or understanding the load and merge order of instruction files in ZCode. +--- + +# Add or maintain AGENTS.md instructions + +`AGENTS.md` is ZCode's instruction surface — broad behavior rules injected into +the model context. It is not a skill, command, hook, MCP server, or plugin; it +has its own two scopes and a defined merge order. + +## Scopes and load order + +| Scope | File | Applies to | Loads | +|---|---|---|---| +| User | `~/.zcode/AGENTS.md` | every workspace | first | +| Workspace | `/AGENTS.md` | that project only | after user (can narrow/override) | + +ZCode injects `~/.zcode/AGENTS.md` first, then the workspace `AGENTS.md` resolved +from the current directory upward to the project root — so workspace rules +appear later and take precedence for that repo. + +A marketplace ships its own `AGENTS.md` at its root; the installer renders it to +`~/.zcode/AGENTS.md` (user scope). Edit the marketplace's `AGENTS.md` to change +the installed user-scope defaults. + +## Choosing scope + +- **User** (`~/.zcode/AGENTS.md`, i.e. the marketplace `AGENTS.md`): personal or + setup-wide defaults — preferred language, review style, local conventions. +- **Workspace** (`/AGENTS.md`): repository rules shared with the team — + architecture boundaries, logging, testing, commit/MR policy. Create or update + it with ZCode's built-in `/init` (it targets the workspace file, never the + user default). + +## Procedure + +1. Decide scope from the rule's reach (setup-wide vs repository-specific). +2. Keep it concise and imperative; state rules the model must follow, not prose. +3. If a marketplace uses managed begin/end markers around a generated block, + keep edits inside the markers so the installer can re-render cleanly. +4. Do not put skills, commands, hooks, MCP, or plugin config here — those are + separate resources (see `nddev-builder-orientation`). AGENTS.md is + instructions only. +5. Verify the file is valid Markdown and loads (open ZCode, or check the + rendered `~/.zcode/AGENTS.md` after install). 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 5fc76e0..15f2be1 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 @@ -111,9 +111,10 @@ 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 automatically. At runtime, the agent references them via -`${CLAUDE_PLUGIN_ROOT}/tools//