feat: add ZCode harness adapter for project agents

.gitignore

@@ -122,6 +122,7 @@ _library-private/
 .roo/
 .trae/
 .windsurf/
+.zcode/
 
 # Root harness manifests and generated entry files
 /.claude-plugin/

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; 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.
 

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.
 

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, 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
 

learn/guides/HARNESS-COMPATIBILITY.md

@@ -2,28 +2,33 @@
 
 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`; 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
 
 The Codex plugin provides skills and hooks in the ChatGPT desktop app and Codex CLI. The generator builds `.agents/skills`, `.codex/agents`, and a separate plugin skill layer under `.codex/plugins/vibe-coding-tools/skills` as ignored local output. Generate these from `src` before using a source checkout as an installed adapter.
 
 ## 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.

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__":

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()