From 6be3b41ca66f2b2394533d04a5462f752d43508e Mon Sep 17 00:00:00 2001 From: Chris <16280532+chrisl10@users.noreply.github.com> Date: Wed, 9 Sep 2026 02:37:55 -0700 Subject: [PATCH 1/3] feat: add ZCode harness adapter for project agents ZCode loads project agents from .zcode/agents and project skills from the .agents/skills layer, but the generator emitted no ZCode output, so the Bees were unreachable in ZCode beyond the generic fallback agent. - generate_agents() now writes .zcode/agents/*.md via the existing populate_markdown_agents helper with a zcode branch in normalized_agent_text that rewrites .claude/skills/ and ../skills/ references to .agents/skills/ - .gitignore harness block gains .zcode/ - README, GETTING-STARTED, HARNESS-COMPATIBILITY, and AGENTS guides document the adapter, its two scopes (project .zcode/agents and user-level ~/.zcode/agents symlinks), and its honest limits Verified: 113 agents generated with valid name/description frontmatter, 0 stale .claude/skills or ../skills references remain, generator is idempotent, and .zcode/ stays ignored. --- .gitignore | 1 + README.md | 4 ++-- learn/guides/AGENTS.md | 5 +++-- learn/guides/GETTING-STARTED.md | 3 ++- learn/guides/HARNESS-COMPATIBILITY.md | 25 +++++++++++++++---------- learn/scripts/generate-harnesses.py | 16 ++++++++++++++-- 6 files changed, 37 insertions(+), 17 deletions(-) diff --git a/.gitignore b/.gitignore index de453646..18eef2ac 100644 --- a/.gitignore +++ b/.gitignore @@ -122,6 +122,7 @@ _library-private/ .roo/ .trae/ .windsurf/ +.zcode/ # Root harness manifests and generated entry files /.claude-plugin/ diff --git a/README.md b/README.md index b516df61..447e5d71 100644 --- a/README.md +++ b/README.md @@ -116,13 +116,13 @@ The portable source lives in [`src/`](src/). A clone contains the source assets **Claude Code and Claude Cowork.** Use an appropriate release package for installation. The portable agents, skills, commands, hooks, and rules live under `src`; shared entry templates live under `src/harnesses`. -**Cursor and Codex.** To build the local adapters from source, run: +**Cursor, Codex, and ZCode.** To build the local adapters from source, run: ```powershell python learn/scripts/generate-harnesses.py ``` -The generator creates ignored `.cursor`, `.codex`, and `.agents` output. Codex receives repository skills, native agent TOMLs, and a separate plugin skill layer. Edit the source and regenerate when needed; local adapters are disposable. +The generator creates ignored `.cursor`, `.codex`, `.agents`, and `.zcode` output. Codex receives repository skills, native agent TOMLs, and a separate plugin skill layer. ZCode receives project agents in `.zcode/agents` and reuses the `.agents/skills` repository skills. Edit the source and regenerate when needed; local adapters are disposable. Existing release archives and SHA-256 checksums are in [`learn/packages/`](learn/packages/). They are versioned snapshots and do not automatically include later source changes. diff --git a/learn/guides/AGENTS.md b/learn/guides/AGENTS.md index ccc25446..1642c5e7 100644 --- a/learn/guides/AGENTS.md +++ b/learn/guides/AGENTS.md @@ -58,8 +58,9 @@ The three unpaired utility skills coordinate the system rather than represent a | Claude Code | `.claude/agents/*.md` | | Cursor | `.cursor/agents/*.md` | | Codex | `.codex/agents/*.toml` | +| ZCode | `.zcode/agents/*.md` | -Codex TOML files contain `name`, `description`, and `developer_instructions`. They preserve the Bee's full instructions in Codex's supported project-agent format. The generator creates all 82 from the canonical `src/agents/` sources. +Codex TOML files contain `name`, `description`, and `developer_instructions`. They preserve the Bee's full instructions in Codex's supported project-agent format. The generator creates all 82 from the canonical `src/agents/` sources. ZCode keeps the Markdown format and points agent bodies at the `.agents/skills` repository skills. ## Safe delegation @@ -82,7 +83,7 @@ Do not have several agents edit the same file at once. Do not use delegation to 4. Add the canonical Markdown agent under `src/agents/`. 5. Register the pair in `beekeeper-suit`. 6. Run `python learn/scripts/generate-harnesses.py`. -7. Verify the Claude, Cursor, and Codex versions preserve the same intent. +7. Verify the Claude, Cursor, Codex, and ZCode versions preserve the same intent. 8. Test a positive trigger, a negative trigger, and a boundary case. 9. Run security, then quality. diff --git a/learn/guides/GETTING-STARTED.md b/learn/guides/GETTING-STARTED.md index 3403735e..1c292069 100644 --- a/learn/guides/GETTING-STARTED.md +++ b/learn/guides/GETTING-STARTED.md @@ -11,11 +11,12 @@ The safest setup is additive. It inspects the target repository, preserves exist ## Step 1: choose a harness -This repository tracks portable source under `src/`. Installed harness folders are ignored local outputs. Generate the Cursor and Codex adapters with `python learn/scripts/generate-harnesses.py` before using those local paths, or install an appropriate versioned release package. +This repository tracks portable source under `src/`. Installed harness folders are ignored local outputs. Generate the Cursor, Codex, and ZCode adapters with `python learn/scripts/generate-harnesses.py` before using those local paths, or install an appropriate versioned release package. - **Claude Code:** Install an appropriate versioned Claude release package using your normal plugin workflow. - **Codex:** Generate the local `.agents/skills` and `.codex/agents` adapters before opening the checkout, or install an appropriate release package. A marketplace descriptor is generated only when its source template exists under `src/harnesses/codex/`. - **Cursor:** Open the checkout or copy/install the `.cursor` package into the target repository. +- **ZCode:** Generate the local `.zcode/agents` and `.agents/skills` adapters before opening the checkout. To use the Bees in every project instead of just this checkout, symlink the generated `.agents/agents/*.md` files into `~/.zcode/agents/`. ## Step 2: initialize the target repository diff --git a/learn/guides/HARNESS-COMPATIBILITY.md b/learn/guides/HARNESS-COMPATIBILITY.md index d14653c0..147dcc84 100644 --- a/learn/guides/HARNESS-COMPATIBILITY.md +++ b/learn/guides/HARNESS-COMPATIBILITY.md @@ -2,15 +2,19 @@ Vibe Coding Tools preserves each capability using the format its harness actually supports. Compatibility means the behavior survives, not that every directory name is identical. -| Capability | Claude Code | Codex | Cursor | -|---|---|---|---| -| 82 agents | Markdown agents | 82 project TOML agents | Markdown agents | -| 85 core skills | Native plugin skills | Repository skills plus plugin skills | Native skills | -| 2 commands | Native commands | Translated into 2 explicit-invocation skills in both Codex layers | Native commands | -| 4 rules | `CLAUDE.md` and `.md` rules | Project developer instructions | Native `.mdc` rules | -| Dash guard | Blocking PreToolUse hook | Blocking PreToolUse adapter parses patches | Blocking preToolUse hook | -| Component validation | Advisory PostToolUse hook | Advisory PostToolUse patch adapter | Advisory postToolUse hook | -| Package manifest | `.claude-plugin/plugin.json` | `.codex-plugin/plugin.json` | `.cursor-plugin/plugin.json` | +| Capability | Claude Code | Codex | Cursor | ZCode | +|---|---|---|---|---| +| 82 agents | Markdown agents | 82 project TOML agents | Markdown agents | Markdown agents in `.zcode/agents` | +| 85 core skills | Native plugin skills | Repository skills plus plugin skills | Native skills | Repository skills (`.agents/skills`) | +| 2 commands | Native commands | Translated into 2 explicit-invocation skills in both Codex layers | Native commands | Consumed as skills from `.agents/skills` | +| 4 rules | `CLAUDE.md` and `.md` rules | Project developer instructions | Native `.mdc` rules | Not generated | +| Dash guard | Blocking PreToolUse hook | Blocking PreToolUse adapter parses patches | Blocking preToolUse hook | Not generated | +| Component validation | Advisory PostToolUse hook | Advisory PostToolUse patch adapter | Advisory postToolUse hook | Not generated | +| Package manifest | `.claude-plugin/plugin.json` | `.codex-plugin/plugin.json` | `.cursor-plugin/plugin.json` | Not generated | + +## ZCode has two scopes + +ZCode loads project agents from `.zcode/agents` inside the checkout and project skills from the `.agents/skills` layer, so a source checkout works after generation. ZCode also reads user-scope agents from `~/.zcode/agents`; symlink the generated `.agents/agents/*.md` files there to use the Bees in every project. ## Codex has two layers @@ -18,12 +22,13 @@ The Codex plugin provides skills and hooks in the ChatGPT desktop app and Codex ## Source and generation -The `src` tree is canonical. Harness folders are ignored build outputs; shared entry templates and manifests live under `src/harnesses/`. `learn/scripts/generate-harnesses.py` removes unsupported shared agent metadata, translates active Cursor paths, creates Codex TOML agents, and refreshes the same 87 Codex-facing skills in `.agents/skills` and the plugin. +The `src` tree is canonical. Harness folders are ignored build outputs; shared entry templates and manifests live under `src/harnesses/`. `learn/scripts/generate-harnesses.py` removes unsupported shared agent metadata, translates active Cursor paths, creates Codex TOML agents, refreshes the same 87 Codex-facing skills in `.agents/skills` and the plugin, and writes ZCode project agents with skill paths pointed at `.agents/skills`. ## Honest limits - A Codex plugin does not contain the 82 custom-agent TOMLs. The project adapter does. - Codex does not use a repository `.codex/commands` directory. The two shared command workflows are explicit-invocation skills named `$the-beekeeper` and `$the-smoker`. +- The ZCode adapter covers agents only. ZCode reuses the `.agents/skills` repository skills; rules, hooks, and a package manifest are not generated for ZCode. - Cursor and Claude hook payloads are not interchangeable, even when they call the same script. - A model name from one provider is not copied into another provider's configuration. - Installed hooks require each harness's trust and reload process. diff --git a/learn/scripts/generate-harnesses.py b/learn/scripts/generate-harnesses.py index 2cc9a232..9895d3e1 100644 --- a/learn/scripts/generate-harnesses.py +++ b/learn/scripts/generate-harnesses.py @@ -1,5 +1,5 @@ #!/usr/bin/env python3 -"""Generate Cursor and Codex distributions from the canonical source package. +"""Generate Cursor, Codex, and ZCode distributions from the canonical source package. Run from the repository root. The script deliberately keeps research archives unchanged while translating active instructions and component metadata. @@ -25,6 +25,7 @@ CURSOR = ROOT / ".cursor" CODEX = ROOT / ".codex" AGENTS = ROOT / ".agents" +ZCODE = ROOT / ".zcode" CODEX_PLUGIN = CODEX / "plugins" / "vibe-coding-tools" CODEX_COMMAND_TRANSLATIONS = { "the-beekeeper": "beekeeper.md", @@ -126,6 +127,12 @@ def normalized_agent_text(path: Path, harness: str) -> str: ) if harness == "cursor": body = body.replace(".claude/", ".cursor/") + elif harness == "zcode": + # ZCode loads project skills from the .agents/skills layer, so agent + # bodies point there instead of the Claude-shaped source paths. + body = body.replace(".claude/skills/", ".agents/skills/").replace( + "../skills/", ".agents/skills/" + ) return f"---\n{frontmatter}\n---\n\n{body}" @@ -185,6 +192,7 @@ def generate_agents() -> None: cursor_agents = CURSOR / "agents" codex_agents = CODEX / "agents" repository_agents = AGENTS / "agents" + zcode_agents = ZCODE / "agents" agents = sorted((CLAUDE / "agents").glob("*.md")) native_codex_agents = sorted((CLAUDE / "agents").glob("*.toml")) @@ -223,6 +231,10 @@ def populate_codex_agents(target: Path) -> None: replace_generated_directory(codex_agents, populate_codex_agents) + replace_generated_directory( + zcode_agents, lambda target: populate_markdown_agents(target, "zcode") + ) + def generate_cursor() -> None: def populate_skills(target: Path) -> None: @@ -525,7 +537,7 @@ def main() -> None: generate_codex_project() generate_codex_plugin() generate_catalog() - print("Generated Cursor mirror, Codex agents, repository skills, and plugin skills.") + print("Generated Cursor mirror, Codex agents, ZCode agents, repository skills, and plugin skills.") if __name__ == "__main__": From ec2fdbebc52192455ff94bc28cc3631475175fb3 Mon Sep 17 00:00:00 2001 From: Chris <16280532+chrisl10@users.noreply.github.com> Date: Wed, 9 Sep 2026 02:44:39 -0700 Subject: [PATCH 2/3] fix(docs): user-scope ZCode agents need real copies, not symlinks ZCode's agent scanner iterates ~/.zcode/agents with readdir withFileTypes and keeps only entries passing isFile(); Dirents report symlinks as isSymbolicLink, not isFile, so symlinked agent files are invisible. Document copying instead, and re-copying after regen. --- learn/guides/GETTING-STARTED.md | 2 +- learn/guides/HARNESS-COMPATIBILITY.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/learn/guides/GETTING-STARTED.md b/learn/guides/GETTING-STARTED.md index 1c292069..31bbc6fc 100644 --- a/learn/guides/GETTING-STARTED.md +++ b/learn/guides/GETTING-STARTED.md @@ -16,7 +16,7 @@ This repository tracks portable source under `src/`. Installed harness folders a - **Claude Code:** Install an appropriate versioned Claude release package using your normal plugin workflow. - **Codex:** Generate the local `.agents/skills` and `.codex/agents` adapters before opening the checkout, or install an appropriate release package. A marketplace descriptor is generated only when its source template exists under `src/harnesses/codex/`. - **Cursor:** Open the checkout or copy/install the `.cursor` package into the target repository. -- **ZCode:** Generate the local `.zcode/agents` and `.agents/skills` adapters before opening the checkout. To use the Bees in every project instead of just this checkout, symlink the generated `.agents/agents/*.md` files into `~/.zcode/agents/`. +- **ZCode:** Generate the local `.zcode/agents` and `.agents/skills` adapters before opening the checkout. To use the Bees in every project instead of just this checkout, copy the generated `.agents/agents/*.md` files into `~/.zcode/agents/` (real copies; ZCode's agent scanner ignores symlinked entries) and re-copy after regenerating. ## Step 2: initialize the target repository diff --git a/learn/guides/HARNESS-COMPATIBILITY.md b/learn/guides/HARNESS-COMPATIBILITY.md index 147dcc84..8dda6960 100644 --- a/learn/guides/HARNESS-COMPATIBILITY.md +++ b/learn/guides/HARNESS-COMPATIBILITY.md @@ -14,7 +14,7 @@ Vibe Coding Tools preserves each capability using the format its harness actuall ## ZCode has two scopes -ZCode loads project agents from `.zcode/agents` inside the checkout and project skills from the `.agents/skills` layer, so a source checkout works after generation. ZCode also reads user-scope agents from `~/.zcode/agents`; symlink the generated `.agents/agents/*.md` files there to use the Bees in every project. +ZCode loads project agents from `.zcode/agents` inside the checkout and project skills from the `.agents/skills` layer, so a source checkout works after generation. ZCode also reads user-scope agents from `~/.zcode/agents`; copy the generated `.agents/agents/*.md` files there to use the Bees in every project. Use real copies, not symlinks — ZCode's agent scanner only picks up regular files — and re-copy after regenerating. ## Codex has two layers From a6e77cbaff8fcf41fb3ad80cf3feecf735f03c83 Mon Sep 17 00:00:00 2001 From: Chris <16280532+chrisl10@users.noreply.github.com> Date: Wed, 9 Sep 2026 02:48:47 -0700 Subject: [PATCH 3/3] feat: add install-zcode-agents.py for user-scope deployment Copying generated agents into ~/.zcode/agents by hand is easy to get wrong (symlinks are invisible to ZCode's scanner, and the verbatim .agents/agents bodies keep source-relative skill paths). Add an opt-in installer that deploys the generated .zcode/agents output as real files; it refuses to run before generation, replaces matching names, and leaves unrelated files in ~/.zcode/agents alone. The generator itself stays repo-bound by design. Documented in README, GETTING-STARTED, and HARNESS-COMPATIBILITY. --- README.md | 2 +- learn/guides/GETTING-STARTED.md | 2 +- learn/guides/HARNESS-COMPATIBILITY.md | 2 +- learn/scripts/install-zcode-agents.py | 45 +++++++++++++++++++++++++++ 4 files changed, 48 insertions(+), 3 deletions(-) create mode 100755 learn/scripts/install-zcode-agents.py diff --git a/README.md b/README.md index 447e5d71..cc3069d5 100644 --- a/README.md +++ b/README.md @@ -122,7 +122,7 @@ The portable source lives in [`src/`](src/). A clone contains the source assets python learn/scripts/generate-harnesses.py ``` -The generator creates ignored `.cursor`, `.codex`, `.agents`, and `.zcode` output. Codex receives repository skills, native agent TOMLs, and a separate plugin skill layer. ZCode receives project agents in `.zcode/agents` and reuses the `.agents/skills` repository skills. Edit the source and regenerate when needed; local adapters are disposable. +The generator creates ignored `.cursor`, `.codex`, `.agents`, and `.zcode` output. Codex receives repository skills, native agent TOMLs, and a separate plugin skill layer. ZCode receives project agents in `.zcode/agents` and reuses the `.agents/skills` repository skills; run `python learn/scripts/install-zcode-agents.py` after generating to copy them into `~/.zcode/agents` for use in every project. Edit the source and regenerate when needed; local adapters are disposable. Existing release archives and SHA-256 checksums are in [`learn/packages/`](learn/packages/). They are versioned snapshots and do not automatically include later source changes. diff --git a/learn/guides/GETTING-STARTED.md b/learn/guides/GETTING-STARTED.md index 31bbc6fc..cb76aa35 100644 --- a/learn/guides/GETTING-STARTED.md +++ b/learn/guides/GETTING-STARTED.md @@ -16,7 +16,7 @@ This repository tracks portable source under `src/`. Installed harness folders a - **Claude Code:** Install an appropriate versioned Claude release package using your normal plugin workflow. - **Codex:** Generate the local `.agents/skills` and `.codex/agents` adapters before opening the checkout, or install an appropriate release package. A marketplace descriptor is generated only when its source template exists under `src/harnesses/codex/`. - **Cursor:** Open the checkout or copy/install the `.cursor` package into the target repository. -- **ZCode:** Generate the local `.zcode/agents` and `.agents/skills` adapters before opening the checkout. To use the Bees in every project instead of just this checkout, copy the generated `.agents/agents/*.md` files into `~/.zcode/agents/` (real copies; ZCode's agent scanner ignores symlinked entries) and re-copy after regenerating. +- **ZCode:** Generate the local `.zcode/agents` and `.agents/skills` adapters before opening the checkout. To use the Bees in every project instead of just this checkout, run `python learn/scripts/install-zcode-agents.py`, which copies the generated agents into `~/.zcode/agents/` as real files (ZCode's agent scanner ignores symlinks). Re-run it after every regeneration. ## Step 2: initialize the target repository diff --git a/learn/guides/HARNESS-COMPATIBILITY.md b/learn/guides/HARNESS-COMPATIBILITY.md index 8dda6960..71fe0ae2 100644 --- a/learn/guides/HARNESS-COMPATIBILITY.md +++ b/learn/guides/HARNESS-COMPATIBILITY.md @@ -14,7 +14,7 @@ Vibe Coding Tools preserves each capability using the format its harness actuall ## ZCode has two scopes -ZCode loads project agents from `.zcode/agents` inside the checkout and project skills from the `.agents/skills` layer, so a source checkout works after generation. ZCode also reads user-scope agents from `~/.zcode/agents`; copy the generated `.agents/agents/*.md` files there to use the Bees in every project. Use real copies, not symlinks — ZCode's agent scanner only picks up regular files — and re-copy after regenerating. +ZCode loads project agents from `.zcode/agents` inside the checkout and project skills from the `.agents/skills` layer, so a source checkout works after generation. ZCode also reads user-scope agents from `~/.zcode/agents`; run `python learn/scripts/install-zcode-agents.py` after generating to copy the agents there for use in every project. The installer writes real files — ZCode's agent scanner only picks up regular files, not symlinks — and is additive: unrelated files in `~/.zcode/agents` are left alone. ## Codex has two layers diff --git a/learn/scripts/install-zcode-agents.py b/learn/scripts/install-zcode-agents.py new file mode 100755 index 00000000..14e09f59 --- /dev/null +++ b/learn/scripts/install-zcode-agents.py @@ -0,0 +1,45 @@ +#!/usr/bin/env python3 +"""Copy generated ZCode agents into ~/.zcode/agents for user-scope use. + +ZCode loads user-scope agents from ~/.zcode/agents, and its scanner only +picks up regular files: symlinked entries are ignored. Run +learn/scripts/generate-harnesses.py first; this script then deploys the +generated .zcode/agents output as real copies. Re-run it after every +regeneration to pick up new or changed Bees. + +The install is additive: existing files with matching names are replaced +and unrelated files in ~/.zcode/agents are left alone. +""" + +from __future__ import annotations + +import shutil +from pathlib import Path + + +ROOT = Path(__file__).resolve().parents[2] +SOURCE = ROOT / ".zcode" / "agents" +TARGET = Path.home() / ".zcode" / "agents" + + +def main() -> None: + if not SOURCE.is_dir(): + raise SystemExit( + "No generated .zcode/agents found. " + "Run 'python learn/scripts/generate-harnesses.py' first." + ) + files = sorted(SOURCE.glob("*.md")) + if not files: + raise SystemExit("Generated .zcode/agents is empty; nothing to install.") + TARGET.mkdir(parents=True, exist_ok=True) + for path in files: + target = TARGET / path.name + if target.is_symlink(): + target.unlink() + shutil.copy2(path, target) + print(f"Installed {len(files)} ZCode agents into {TARGET}.") + print("Restart ZCode to load them.") + + +if __name__ == "__main__": + main()