From fd7a5b02d4303d98d07c2687a808ac100b6be307 Mon Sep 17 00:00:00 2001 From: Zach Fuller Date: Tue, 13 Oct 2026 17:15:13 -0700 Subject: [PATCH 1/2] fix(z-agent): find the highest installed z-mode without a path Adapts pstack PR #597. --- .claude-plugin/plugin.json | 2 +- .codex-plugin/plugin.json | 2 +- agents/claude/z-agent.md | 2 +- agents/codex/z-agent.toml | 2 +- docs/provenance.md | 2 ++ docs/validation.md | 6 ++++++ plugin.yaml | 2 +- 7 files changed, 13 insertions(+), 5 deletions(-) diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.json index 98960be..5334c5a 100644 --- a/.claude-plugin/plugin.json +++ b/.claude-plugin/plugin.json @@ -1,6 +1,6 @@ { "name": "zstack", - "version": "0.6.3", + "version": "0.6.4", "description": "Evidence-driven engineering workflows, scoped agents, and task-sized verification for Claude Code.", "author": { "name": "Zach Fuller", diff --git a/.codex-plugin/plugin.json b/.codex-plugin/plugin.json index 349a974..e03fc0b 100644 --- a/.codex-plugin/plugin.json +++ b/.codex-plugin/plugin.json @@ -1,6 +1,6 @@ { "name": "zstack", - "version": "0.6.3", + "version": "0.6.4", "description": "Evidence-driven engineering workflows, scoped agents, and task-sized verification for Codex.", "author": { "name": "Zach Fuller", diff --git a/agents/claude/z-agent.md b/agents/claude/z-agent.md index 5409f21..cf75c0c 100644 --- a/agents/claude/z-agent.md +++ b/agents/claude/z-agent.md @@ -4,7 +4,7 @@ description: Scoped engineering worker following z-mode. Start fresh for new wor model: inherit --- -Read z-mode's SKILL.md from the absolute path your parent gave you. If that path is missing, relative, or unreadable on this machine, locate the installed z-mode SKILL.md yourself and report the bad path. If you cannot find it, stop and report; do not work without z-mode. Then read the relevant playbook. Resolve its relative links from that file's real location, independently of target cwd. +Read z-mode's SKILL.md from the absolute path your parent gave you. If that path is missing, relative, or unreadable on this machine, report the bad path and, before other work, search for files ending in `skills/z-mode/SKILL.md` under `~/.claude/plugins/`, `~/.claude/skills/`, and any local marketplace directory recorded in `~/.claude/plugins/known_marketplaces.json`. If several match, use the copy whose plugin manifest (`.claude-plugin/plugin.json` or `plugin.yaml` beside its `skills/` directory) declares the highest version. z-mode is explicit-only, so a missing skill-catalog entry does not mean it is absent. If no copy exists, stop and report; do not work without z-mode. Then read the relevant playbook. Resolve its relative links from that file's real location, independently of target cwd. The parent's goal, scope, permissions, and acceptance criteria govern work. Simple tasks run directly. Do not recursively spawn another z-agent merely because the mode is active. diff --git a/agents/codex/z-agent.toml b/agents/codex/z-agent.toml index 378636a..9999cab 100644 --- a/agents/codex/z-agent.toml +++ b/agents/codex/z-agent.toml @@ -1,7 +1,7 @@ name = "z-agent" description = "Scoped engineering worker following z-mode. Start fresh for new work; reuse only for costly agent-held state under the native host contract. Preserve concurrent work and return verifiable results." developer_instructions = """ -Read z-mode's SKILL.md from the absolute path your parent gave you. If that path is missing, relative, or unreadable on this machine, locate the installed z-mode SKILL.md yourself and report the bad path. If you cannot find it, stop and report; do not work without z-mode. Then read the playbook relevant to the brief. Resolve its relative links from that file's real location, not the target cwd. +Read z-mode's SKILL.md from the absolute path your parent gave you. If that path is missing, relative, or unreadable on this machine, report the bad path and, before other work, search for files ending in `skills/z-mode/SKILL.md` under `~/.codex/plugins/`, `~/.agents/skills/`, and `~/.codex/skills/`. If several match, use the copy whose plugin manifest (`.codex-plugin/plugin.json` or `plugin.yaml` beside its `skills/` directory) declares the highest version. z-mode is explicit-only, so a missing skill-catalog entry does not mean it is absent. If no copy exists, stop and report; do not work without z-mode. Then read the playbook relevant to the brief. Resolve its relative links from that file's real location, not the target cwd. The parent's explicit goal, scope, permissions, and acceptance criteria govern your work. Simple tasks run directly. Do not recursively spawn another z-agent merely because this mode is active. You are not alone in the codebase. Preserve others' edits and write only to your assigned files or isolated worktree. Read-only briefs prohibit edits and external writes. Do not commit, push, open PRs, message people, or merge unless specifically delegated. Inherit the host model. Return status, files or symbols, evidence/checks, actual changes, and gaps. Verify artifacts rather than trusting self-reports. diff --git a/docs/provenance.md b/docs/provenance.md index 67950ae..96f4f46 100644 --- a/docs/provenance.md +++ b/docs/provenance.md @@ -57,3 +57,5 @@ PR #31 review also corrected two retained example issues: valid empty-result ass Reviewed the October 13 pstack changes that reached manifest `0.15.23`: PRs [#595](https://github.com/cursor/plugins/pull/595), [#597](https://github.com/cursor/plugins/pull/597), [#602](https://github.com/cursor/plugins/pull/602), [#604](https://github.com/cursor/plugins/pull/604), [#606](https://github.com/cursor/plugins/pull/606), and [#609](https://github.com/cursor/plugins/pull/609). Each adopted change lands as one layer of a stacked PR series and adds its own paragraph below. Cursor manifests, the Cursor README, and `poteto-help` routing tables are excluded; each layer updates the local docs it affects. **Deep-dig signal.** [PR #604](https://github.com/cursor/plugins/pull/604), merge [36cecbf2](https://github.com/cursor/plugins/commit/36cecbf2b5089b275254d59cb4612d6f96f00fbd), adds one rule to fix-root-causes: when the deciding fact took a deep dig, propose the cheap, always-on signal that would have shown it at first look. The port adopts it verbatim and states that a proposal does not authorize adding the signal outside task scope. The principles reference example gains a matching sentence. Native manifests advance to `0.6.3` as a patch: the rule extends an existing principle's debugging guidance, while the README reserves MINOR bumps for skill, agent, invocation-policy, hook, and stored-state contract changes. + +**z-agent discovery.** [PR #597](https://github.com/cursor/plugins/pull/597), merge [b93e8117](https://github.com/cursor/plugins/commit/b93e8117880f695bc49ef7b1ef72c09bfcc7c1de), lets poteto-agent find poteto-mode without a supplied path and choose the highest installed version. Both native z-agent roles already fell back to a local search; the port names where to search on each host, selects the copy whose sibling plugin manifest declares the highest version, and notes that explicit-only z-mode can be missing from the skill catalog while installed. The parent still supplies the absolute path under the delegation contract. Upstream's removal of ignored `mode` and `reminder` frontmatter needs no port: z-mode never carried those keys, and the validator rejects unsupported frontmatter. Upstream's slash-menu note is Cursor-specific; local docs already direct Codex users to the skill picker and Claude Code users to `/zstack:z-mode`. Native manifests advance to `0.6.4` as a compatible fix. diff --git a/docs/validation.md b/docs/validation.md index c5b44f0..43bc1b6 100644 --- a/docs/validation.md +++ b/docs/validation.md @@ -6,6 +6,12 @@ outline: [2, 3] Historical observations below retain the names used during those runs (`pstack`, `poteto-mode`, and `poteto-agent`). Current equivalents are `zstack`, `z-mode`, and `z-agent`; those earlier observations do not establish live behavior under the new names. +## pstack 0.15.23: z-agent discovery — 2026-10-13 {#pstack-0-15-23-z-agent} + +Adapted [upstream PR #597](https://github.com/cursor/plugins/pull/597) at merge `b93e8117880f695bc49ef7b1ef72c09bfcc7c1de` as the second layer of the [pstack 0.15.23 stack](provenance.md#pstack-0-15-23). Both z-agent roles now name per-host search roots for a missing or unusable z-mode path and pick the highest declared version. Manifests declare `0.6.4`. + +A script following the Claude Code search rule on this macOS host found four copies: a stale `0.1.0` plugin cache, two packaged `dist` copies without a sibling Claude manifest, and the in-place checkout. It selected the checkout. That run simulated the procedure; no z-agent was launched without a path, and the Codex roots were not exercised. In a clean detached worktree of the layer commit, structural validation reported 52 skills and zero problems; all 15 Node tests and 120 Python tests passed; `git diff --check` passed. + ## pstack 0.15.23: deep-dig signal — 2026-10-13 {#pstack-0-15-23-signal} Adapted [upstream PR #604](https://github.com/cursor/plugins/pull/604) at merge `36cecbf2b5089b275254d59cb4612d6f96f00fbd`, starting from main `caf7a1f`, as the bottom layer of the [pstack 0.15.23 stack](provenance.md#pstack-0-15-23). fix-root-causes now proposes a cheap, always-on signal when the deciding fact took a deep dig; the principles reference example matches. Manifests declare `0.6.3`. diff --git a/plugin.yaml b/plugin.yaml index 8fd33df..e6e51cb 100644 --- a/plugin.yaml +++ b/plugin.yaml @@ -1,5 +1,5 @@ name: zstack -version: 0.6.3 +version: 0.6.4 description: Evidence-driven engineering skills and task-sized verification for Hermes Agent. author: Zach Fuller license: MIT From df6bd2012c6941da66d4bc7bd3963ad09ec9f4f0 Mon Sep 17 00:00:00 2001 From: Zach Fuller Date: Tue, 13 Oct 2026 17:31:13 -0700 Subject: [PATCH 2/2] fix(z-agent): follow linked and configured z-mode installs --- agents/claude/z-agent.md | 2 +- agents/codex/z-agent.toml | 2 +- docs/provenance.md | 2 +- docs/validation.md | 4 ++++ 4 files changed, 7 insertions(+), 3 deletions(-) diff --git a/agents/claude/z-agent.md b/agents/claude/z-agent.md index cf75c0c..9ea6418 100644 --- a/agents/claude/z-agent.md +++ b/agents/claude/z-agent.md @@ -4,7 +4,7 @@ description: Scoped engineering worker following z-mode. Start fresh for new wor model: inherit --- -Read z-mode's SKILL.md from the absolute path your parent gave you. If that path is missing, relative, or unreadable on this machine, report the bad path and, before other work, search for files ending in `skills/z-mode/SKILL.md` under `~/.claude/plugins/`, `~/.claude/skills/`, and any local marketplace directory recorded in `~/.claude/plugins/known_marketplaces.json`. If several match, use the copy whose plugin manifest (`.claude-plugin/plugin.json` or `plugin.yaml` beside its `skills/` directory) declares the highest version. z-mode is explicit-only, so a missing skill-catalog entry does not mean it is absent. If no copy exists, stop and report; do not work without z-mode. Then read the relevant playbook. Resolve its relative links from that file's real location, independently of target cwd. +Read z-mode's SKILL.md from the absolute path your parent gave you. If no path was given, or it is relative or unreadable on this machine, report that and, before other work, search for files ending in `skills/z-mode/SKILL.md`, following symlinks (for example, `find -L`). Search `plugins/` and `skills/` under `$CLAUDE_CONFIG_DIR` (default `~/.claude`), the target project's `.claude/skills/`, and any local marketplace directory recorded in that configuration root's `plugins/known_marketplaces.json`. Resolve each match to its real path, then read the version from the plugin manifest (`.claude-plugin/plugin.json` or `plugin.yaml`) beside that real path's `skills/` directory. Use the highest version, comparing MAJOR.MINOR.PATCH numerically; copies without a readable version rank last, and report any tie. z-mode is explicit-only, so a missing skill-catalog entry does not mean it is absent. If no copy exists, stop and report; do not work without z-mode. Then read the relevant playbook. Resolve its relative links from that file's real location, independently of target cwd. The parent's goal, scope, permissions, and acceptance criteria govern work. Simple tasks run directly. Do not recursively spawn another z-agent merely because the mode is active. diff --git a/agents/codex/z-agent.toml b/agents/codex/z-agent.toml index 9999cab..a246eb2 100644 --- a/agents/codex/z-agent.toml +++ b/agents/codex/z-agent.toml @@ -1,7 +1,7 @@ name = "z-agent" description = "Scoped engineering worker following z-mode. Start fresh for new work; reuse only for costly agent-held state under the native host contract. Preserve concurrent work and return verifiable results." developer_instructions = """ -Read z-mode's SKILL.md from the absolute path your parent gave you. If that path is missing, relative, or unreadable on this machine, report the bad path and, before other work, search for files ending in `skills/z-mode/SKILL.md` under `~/.codex/plugins/`, `~/.agents/skills/`, and `~/.codex/skills/`. If several match, use the copy whose plugin manifest (`.codex-plugin/plugin.json` or `plugin.yaml` beside its `skills/` directory) declares the highest version. z-mode is explicit-only, so a missing skill-catalog entry does not mean it is absent. If no copy exists, stop and report; do not work without z-mode. Then read the playbook relevant to the brief. Resolve its relative links from that file's real location, not the target cwd. +Read z-mode's SKILL.md from the absolute path your parent gave you. If no path was given, or it is relative or unreadable on this machine, report that and, before other work, search for files ending in `skills/z-mode/SKILL.md`, following symlinks (for example, `find -L`). Search `plugins/` and `skills/` under `$CODEX_HOME` (default `~/.codex`), `~/.agents/skills/`, and the target project's `.agents/skills/`. Resolve each match to its real path, then read the version from the plugin manifest (`.codex-plugin/plugin.json` or `plugin.yaml`) beside that real path's `skills/` directory. Use the highest version, comparing MAJOR.MINOR.PATCH numerically; copies without a readable version rank last, and report any tie. z-mode is explicit-only, so a missing skill-catalog entry does not mean it is absent. If no copy exists, stop and report; do not work without z-mode. Then read the playbook relevant to the brief. Resolve its relative links from that file's real location, not the target cwd. The parent's explicit goal, scope, permissions, and acceptance criteria govern your work. Simple tasks run directly. Do not recursively spawn another z-agent merely because this mode is active. You are not alone in the codebase. Preserve others' edits and write only to your assigned files or isolated worktree. Read-only briefs prohibit edits and external writes. Do not commit, push, open PRs, message people, or merge unless specifically delegated. Inherit the host model. Return status, files or symbols, evidence/checks, actual changes, and gaps. Verify artifacts rather than trusting self-reports. diff --git a/docs/provenance.md b/docs/provenance.md index 96f4f46..1c18659 100644 --- a/docs/provenance.md +++ b/docs/provenance.md @@ -58,4 +58,4 @@ Reviewed the October 13 pstack changes that reached manifest `0.15.23`: PRs [#59 **Deep-dig signal.** [PR #604](https://github.com/cursor/plugins/pull/604), merge [36cecbf2](https://github.com/cursor/plugins/commit/36cecbf2b5089b275254d59cb4612d6f96f00fbd), adds one rule to fix-root-causes: when the deciding fact took a deep dig, propose the cheap, always-on signal that would have shown it at first look. The port adopts it verbatim and states that a proposal does not authorize adding the signal outside task scope. The principles reference example gains a matching sentence. Native manifests advance to `0.6.3` as a patch: the rule extends an existing principle's debugging guidance, while the README reserves MINOR bumps for skill, agent, invocation-policy, hook, and stored-state contract changes. -**z-agent discovery.** [PR #597](https://github.com/cursor/plugins/pull/597), merge [b93e8117](https://github.com/cursor/plugins/commit/b93e8117880f695bc49ef7b1ef72c09bfcc7c1de), lets poteto-agent find poteto-mode without a supplied path and choose the highest installed version. Both native z-agent roles already fell back to a local search; the port names where to search on each host, selects the copy whose sibling plugin manifest declares the highest version, and notes that explicit-only z-mode can be missing from the skill catalog while installed. The parent still supplies the absolute path under the delegation contract. Upstream's removal of ignored `mode` and `reminder` frontmatter needs no port: z-mode never carried those keys, and the validator rejects unsupported frontmatter. Upstream's slash-menu note is Cursor-specific; local docs already direct Codex users to the skill picker and Claude Code users to `/zstack:z-mode`. Native manifests advance to `0.6.4` as a compatible fix. +**z-agent discovery.** [PR #597](https://github.com/cursor/plugins/pull/597), merge [b93e8117](https://github.com/cursor/plugins/commit/b93e8117880f695bc49ef7b1ef72c09bfcc7c1de), lets poteto-agent find poteto-mode without a supplied path and choose the highest installed version. Both native z-agent roles already fell back to a local search; the port names where to search on each host, including configured host roots and project-scoped installs, follows symlinked installs to their real paths, selects the highest numerically compared manifest version with unversioned copies last, and notes that explicit-only z-mode can be missing from the skill catalog while installed. The parent still supplies the absolute path under the delegation contract. Upstream's removal of ignored `mode` and `reminder` frontmatter needs no port: z-mode never carried those keys, and the validator rejects unsupported frontmatter. Upstream's slash-menu note is Cursor-specific; local docs already direct Codex users to the skill picker and Claude Code users to `/zstack:z-mode`. Native manifests advance to `0.6.4` as a compatible fix. diff --git a/docs/validation.md b/docs/validation.md index 43bc1b6..253bf18 100644 --- a/docs/validation.md +++ b/docs/validation.md @@ -12,6 +12,10 @@ Adapted [upstream PR #597](https://github.com/cursor/plugins/pull/597) at merge A script following the Claude Code search rule on this macOS host found four copies: a stale `0.1.0` plugin cache, two packaged `dist` copies without a sibling Claude manifest, and the in-place checkout. It selected the checkout. That run simulated the procedure; no z-agent was launched without a path, and the Codex roots were not exercised. In a clean detached worktree of the layer commit, structural validation reported 52 skills and zero problems; all 15 Node tests and 120 Python tests passed; `git diff --check` passed. +### PR #36 review repairs + +Review found that the fallback missed symlinked installs, configured host roots, and project-scoped installs. Its version rule also gave no way to rank a copy found through a link. The roles now search `$CLAUDE_CONFIG_DIR` or `$CODEX_HOME` and the target project's skill directory, follow symlinks, read manifests from real paths, compare versions numerically, and rank unversioned copies last. A script following the revised Claude rule picked a linked `0.10.0` checkout over a cached `0.1.0` copy in two fixtures, one with a custom `CLAUDE_CONFIG_DIR` and one with a project-scoped link. On this host it again picked the in-place checkout. Plain `find` returned nothing for a symlinked skill directory; `find -L` found it. The Codex rule and a live z-agent launch without a path remain unexercised. + ## pstack 0.15.23: deep-dig signal — 2026-10-13 {#pstack-0-15-23-signal} Adapted [upstream PR #604](https://github.com/cursor/plugins/pull/604) at merge `36cecbf2b5089b275254d59cb4612d6f96f00fbd`, starting from main `caf7a1f`, as the bottom layer of the [pstack 0.15.23 stack](provenance.md#pstack-0-15-23). fix-root-causes now proposes a cheap, always-on signal when the deciding fact took a deep dig; the principles reference example matches. Manifests declare `0.6.3`.