docs(skills): document ZCode's executed-vs-recorded component boundary#28
Merged
Conversation
ZCode 3.3.6 executes only the commands/skills/hooks/mcpServers plugin-manifest fields (plus agents, which load from user scope via the installer flatten). Its own built-in guide (zcode-configuration-guide, diagnosing-plugins) states that `channels`, `lspServers`, `outputStyles`, and `settings` are recorded but never executed. Authoring any of those yields dead config. In particular there is no loadable LSP component on this runtime, so an `add-lsp` skill would teach a non-feature — the same "installed but not loading" trap already fixed for skills. Document the boundary instead: - references/zcode-native-format.md: add a "Component execution model" section; fix a stale skill name (repo-orientation -> nddev-builder-orientation). - nddev-builder-orientation: add "Fields ZCode records but never executes". - add-plugin: extend the manifest guardrail to the four inert fields. Locked in by test_execution_boundary_is_documented (harness side). Prose only; no component, command, agent, or runtime behavior changed. Refresh the release-evidence digest. Claude-Session: https://claude.ai/code/session_01Y29c9sJRhChvxDcUjab5Xo
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What
Documents which ZCode 3.3.6 plugin-manifest fields actually execute, and which are recorded but inert — so the toolkit is honest about its coverage and no agent authors dead config.
Why (the LSP question, settled)
ZCode's own built-in guide (
zcode-guide→zcode-configuration-guide,diagnosing-plugins) states, twice:So there is no loadable LSP component on this runtime. An
add-lspskill would teach a non-feature — the same "installed but not loading" trap already fixed for skills. The correct fix is documentation, not a new skill. This means the marketplace already covers 100% of the executable extension surface (skills, commands, agents, hooks, MCP servers).Changes
references/zcode-native-format.md: new Component execution model section (executed vs recorded-but-not-executed, with thev2-settingvs inert-settingsdistinction called out); fixed a stale skill name (repo-orientation→nddev-builder-orientation).nddev-builder-orientation: new "Fields ZCode records but never executes" subsection.add-plugin: manifest guardrail extended to the four inert fields.test_execution_boundary_is_documented(harness side, same PR wave).Scope
Prose only — no component, command, agent, path, or runtime behavior changed.
release-evidence.jsondigest refreshed (pending, bound to a stable harnessorigin/mainancestor).Validation
test_marketplace_structure.py: 13 passed (incl. the new boundary test)validate_zcode_components.py/validate_skills.py/ markdown fences: PASSvalidate_public_contracts.py: PASSemit_evidence.py --check: valid (pending)https://claude.ai/code/session_01Y29c9sJRhChvxDcUjab5Xo