feat(spexcode-atlas): add SpexCode Atlas plugin

marketplace.json

@@ -504,6 +504,35 @@
         "calendar",
         "messaging"
       ]
+    },
+    {
+      "name": "spexcode-atlas",
+      "source": "./plugins/spexcode-atlas",
+      "description": "Read a repository into a SpexCode spec tree, draw an architecture diagram for each part worth one (each checked until it passes), and hand over the whole tree as one browsable page. A whole repository runs as one dynamic workflow.",
+      "description_i18n": {
+        "en": "Read a repository into a SpexCode spec tree, draw an architecture diagram for each part worth one (each checked until it passes), and hand over the whole tree as one browsable page. A whole repository runs as one dynamic workflow.",
+        "zh-CN": "把代码仓库整理成 SpexCode 规格树，给值得配图的部分画架构图（每张图都检查到通过为止），最后交出一个可以浏览的单文件网页。整个仓库的任务作为一个动态工作流运行。"
+      },
+      "version": "0.1.0",
+      "author": {
+        "name": "SpexCode",
+        "url": "https://spexcode.net"
+      },
+      "icon": "https://cdn-zcode.z.ai/zcode/official-plugin/assets/spexcode-atlas/icon.png",
+      "category": "developer-tools",
+      "keywords": [
+        "spexcode",
+        "spec",
+        "architecture",
+        "diagrams",
+        "documentation",
+        "dynamic-workflow"
+      ],
+      "displayName": "SpexCode Atlas",
+      "displayName_i18n": {
+        "en": "SpexCode Atlas",
+        "zh-CN": "SpexCode 图集"
+      }
     }
   ]
 }

plugins/spexcode-atlas/.zcode-plugin/plugin.json

@@ -0,0 +1,24 @@
+{
+  "name": "spexcode-atlas",
+  "version": "0.1.0",
+  "description": "Read a repository into a SpexCode spec tree, draw an architecture diagram for each part worth one (each checked until it passes), and hand over the whole tree as one browsable page. A whole repository runs as one dynamic workflow.",
+  "description_i18n": {
+    "en": "Read a repository into a SpexCode spec tree, draw an architecture diagram for each part worth one (each checked until it passes), and hand over the whole tree as one browsable page. A whole repository runs as one dynamic workflow.",
+    "zh-CN": "把代码仓库整理成 SpexCode 规格树，给值得配图的部分画架构图（每张图都检查到通过为止），最后交出一个可以浏览的单文件网页。整个仓库的任务作为一个动态工作流运行。"
+  },
+  "author": {
+    "name": "SpexCode",
+    "url": "https://spexcode.net"
+  },
+  "homepage": "https://spexcode.net",
+  "repository": "https://github.com/shuxueshuxue/spexcode",
+  "license": "MIT",
+  "keywords": [
+    "spexcode",
+    "spec",
+    "architecture",
+    "diagrams",
+    "documentation",
+    "dynamic-workflow"
+  ]
+}

plugins/spexcode-atlas/README.md

@@ -0,0 +1,55 @@
+# SpexCode Atlas
+
+[中文文档](./README_CN.md)
+
+This plugin gives ZCode one skill, `atlas`, that reads a repository into a [SpexCode](https://spexcode.net) spec tree and
+draws its architecture. The result is a `.spec/` folder in the repository, with one `spec.md` per part stating what
+that part is for and which file it governs, a diagram beside each node worth one, and a single HTML page that shows
+the whole tree and its diagrams and opens straight from disk.
+
+Maintained by the SpexCode authors, version 0.1.0.
+
+## What it does
+
+For a whole repository the skill submits one dynamic workflow (`skills/atlas/atlas.dwf.ts`) with `CreateWorkflow`.
+The agent sets its language and phase names and changes nothing else. The run:
+
+1. surveys the repository and plans its parts;
+2. writes the spec for each part in parallel;
+3. gates on `spex spec lint` (no errors, 90% coverage) and repairs until it passes;
+4. chooses the nodes worth a picture;
+5. draws each picture in parallel, each gated on `spex diagram check`;
+6. has an independent reader check the top of the tree against the code, each finding re-read by another subagent;
+7. commits `.spec/` and publishes the page as the run's `atlas` artifact with a report.
+
+On a ZCode build without `CreateWorkflow`, the skill does the same job turn by turn and says so. For one node or a
+subtree it draws with `spex diagram scaffold` and `spex diagram check` until each diagram passes.
+
+## Usage
+
+In a repository, ask for example:
+
+- "Make a SpexCode atlas of this repository." / "给这个仓库做一份 SpexCode 图集。"
+- "Draw a diagram for the session node."
+
+## Requirements and side effects
+
+- **Node.js 22 or newer and npm** on PATH. Nothing is installed globally: every SpexCode command runs as
+  `npx -y -p spexcode@next spex <command>`, which downloads the `spexcode` package from the npm registry into npm's
+  cache on first use. The page step also downloads `@spexcode/spec-dashboard`.
+- **Network:** the npm registry only. No MCP server, no hooks, no remote service, no telemetry. The model is the
+  one the ZCode session already uses.
+- **Files written:** `.spec/` in the current repository (`spec.md` and `diagram.json` files and `.spec/spexcode.json`),
+  committed to git with `.spec` as the only path, and `spexcode-atlas.html` at the repository root, left
+  uncommitted. `spex spec lint` also keeps a small history cache (about 8 KB) under `~/.spexcode/projects/`.
+- **Commands run:** `spex` subcommands through npx (`spec lint`, `diagram scaffold`, `diagram check`,
+  `graph --public --html`, `guide`), `git add .spec` and `git commit`, and read-only inspection of the repository.
+- **Cost:** the workflow runs many subagents in parallel. On psf/requests (19 source files) it took about two hours
+  and 43M tokens with GLM-5.2; the runtime lowers and raises its concurrency with the model's rate limits.
+
+## Source and license
+
+SpexCode is MIT-licensed: <https://github.com/shuxueshuxue/spexcode>. The diagram renderer (archify) ships inside
+the `spexcode` npm package.
+
+Open a new ZCode session after enabling or updating the plugin so the Skill catalog is refreshed.

plugins/spexcode-atlas/README_CN.md

@@ -0,0 +1,51 @@
+# SpexCode 图集
+
+[English](./README.md)
+
+这个插件给 ZCode 加一个 skill：`atlas`。它把代码仓库整理成 [SpexCode](https://spexcode.net) 规格树并画出架构。
+结果是仓库里的一个 `.spec/` 目录：每个部分一个 `spec.md`，写明这部分做什么、管哪个文件；值得配图的节点旁边有一张图；
+另外还有一个单文件 HTML 网页，展示整棵树和所有图，直接从磁盘打开即可。
+
+由 SpexCode 作者维护，版本 0.1.0。
+
+## 做什么
+
+对整个仓库，skill 用 `CreateWorkflow` 提交一个动态工作流（`skills/atlas/atlas.dwf.ts`）。
+agent 只改其中的语言和阶段名，别的不动。运行过程：
+
+1. 通读仓库，规划各个部分；
+2. 并行撰写各部分的规格；
+3. 用 `spex spec lint` 把关（0 个错误、覆盖率 90%），不通过就修复；
+4. 挑出值得配图的节点；
+5. 并行画图，每张图都要通过 `spex diagram check`；
+6. 由独立读者对照代码核查规格树的上层，每条发现再交给另一个子代理复核；
+7. 提交 `.spec/`，把网页作为这次运行的 `atlas` 产物交出，附一份报告。
+
+如果 ZCode 版本里没有 `CreateWorkflow`，skill 会逐步完成同样的工作，并告诉用户走的是这条路。
+只画一个节点或一棵子树时，用 `spex diagram scaffold` 和 `spex diagram check`，每张图检查到通过为止。
+
+## 用法
+
+在仓库里这样说，例如：
+
+- “给这个仓库做一份 SpexCode 图集。” / "Make a SpexCode atlas of this repository."
+- “给 session 节点画一张图。”
+
+## 依赖与副作用
+
+- **需要 Node.js 22 或更高版本和 npm**。不做全局安装：每条 SpexCode 命令都以
+  `npx -y -p spexcode@next spex <命令>` 运行，第一次使用时会从 npm 仓库把 `spexcode` 包下载进 npm 缓存。
+  生成网页那一步还会下载 `@spexcode/spec-dashboard`。
+- **网络：** 只访问 npm 仓库。没有 MCP server、没有 hook、没有远程服务、没有遥测。模型就是当前 ZCode 会话用的模型。
+- **写入的文件：** 当前仓库的 `.spec/`（`spec.md`、`diagram.json` 和 `.spec/spexcode.json`），以 `.spec` 为唯一路径提交到 git；
+  仓库根目录的 `spexcode-atlas.html`，不提交。`spex spec lint` 还会在 `~/.spexcode/projects/` 下留一份很小的历史缓存（约 8 KB）。
+- **执行的命令：** 通过 npx 运行的 `spex` 子命令（`spec lint`、`diagram scaffold`、`diagram check`、
+  `graph --public --html`、`guide`），`git add .spec` 和 `git commit`，以及对仓库的只读查看。
+- **开销：** 工作流会并行运行很多子代理。在 psf/requests（19 个源文件）上用 GLM-5.2 跑了约两小时、4300 万 token；
+  运行时会根据模型限流自动调低、调高并发。
+
+## 来源与许可证
+
+SpexCode 采用 MIT 许可证：<https://github.com/shuxueshuxue/spexcode>。图表渲染器（archify）随 `spexcode` npm 包一起发布。
+
+启用或更新插件后，请开一个新的 ZCode 会话，让 Skill 列表刷新。

plugins/spexcode-atlas/skills/atlas/SKILL.md

@@ -0,0 +1,74 @@
+---
+name: atlas
+description: "Use when the user wants the atlas of a repository or its spec tree — read the codebase into a SpexCode spec tree, draw its architecture diagrams and hand over a browsable page (提取 .spec、画架构图、做成可浏览网页), draw the atlas, 画规格图, give node X a diagram, diagram this subtree. For a whole repository it runs one dynamic workflow (turn by turn where ZCode has no CreateWorkflow); for a node or subtree it draws with spex diagram scaffold and check until each passes."
+---
+
+# atlas
+
+## Before you start
+
+This skill draws with SpexCode's command line and needs nothing installed or configured on this machine.
+
+- Run SpexCode through npx: `npx -y -p spexcode@next spex <command>` (Node 22 or newer). Wherever a step below says
+  `spex …`, run it that way; a `spex` already on the PATH works the same.
+- A diagram draws one node of the repository's spec tree, the `.spec/` folder. If the repository has none, write
+  only what the drawing needs: `.spec/<project>/spec.md` describing the project, and one folder beside it per part
+  worth a box, each with its own `spec.md` — a `title:` and a `code:` line naming the file it is about in the
+  frontmatter, a sentence or two below. That is the whole setup: no `spex init`, no hooks, no agent configuration.
+  `spex guide spec` has the full file format if you need more.
+- `spex guide diagram` is the manual for the diagram format and the loop; read it once.
+
+## In ZCode: the whole repository as one dynamic workflow
+
+When the job is a whole repository — read it into a spec tree, draw its pictures, hand over a page to browse
+(提取 .spec、画架构图、做成可浏览网页) — do not work through it turn by turn: run it as one dynamic workflow.
+`${ZCODE_SKILL_DIR}/atlas.dwf.ts` is that workflow, already written and checked by the workflow compiler.
+
+1. Read the script. Set `LANGUAGE` to the language the user is speaking and rewrite each `phase("...")` name into
+   that language. Change nothing else.
+2. Submit it with the `CreateWorkflow` tool as its `script` — not the legacy `Workflow` tool, not `Agent`.
+3. The run surveys the repository and writes the spec for each part in parallel; gates on `spex spec lint` until it
+   reports no errors and 90% coverage; chooses the nodes worth a picture, draws them in parallel and gates each on
+   `spex diagram check`; has an independent reader check the top of the tree against the code; commits `.spec/`;
+   and publishes the page as its `atlas` artifact, with a report beside it.
+4. When it finishes, relay the report: coverage, which pictures pass, what was skipped and why, and every claim the
+   reader found the code does not bear out. If a subagent escalates, answer it, or fix the script and resubmit with
+   `resume_from` — the `dynamic-workflows` skill has both.
+
+A repository that already has a `.spec/` tree keeps it: the workflow skips the survey and starts at the gate. For
+one node or one subtree the steps below are enough; the workflow is for the whole job.
+
+If this ZCode has no `CreateWorkflow` tool (dynamic workflows ship in newer builds), do the same job turn by turn
+with the steps below: the setup above for a repository without `.spec/`, `spex spec lint` until it reports no
+errors, then each picture worth drawing, checked until it passes. Tell the user this is the turn-by-turn path; a
+ZCode build with dynamic workflows runs the same job in parallel.
+
+Draw the spec tree's pictures: one `diagram.json` beside each node's `spec.md` that is worth one.
+The format, the rules and the loop for a single diagram live in `spex guide diagram` — read it before drawing.
+This skill is the campaign around that loop.
+
+1. **Scope.** The user names one node, a subtree, or the whole tree. `spex graph` lists the tree;
+   `spex spec search <topic>` finds a node by what it is about.
+2. **Choose what deserves a picture.** A node whose body explains how its children fit together gets an
+   architecture diagram of those children. A node whose body is a process, a protocol, a data path or a
+   lifecycle gets that kind instead. Skip leaves with nothing to show, and nodes that already carry a
+   `diagram.json` unless the user asked for a redraw. Say what you skipped and why.
+3. **Draw each node.** Go top-down, one node at a time; if your harness can run sub-agents, give each node to its
+   own, handing it only that node's context — its body, its children's titles and descriptions, and these steps.
+   For one node:
+   - read its `spec.md` and its children's, and choose the kind from what the body spends its words on;
+   - `spex diagram scaffold <node>` (add `--type <kind>` for anything but architecture);
+   - draw: place the boxes, connect what the body says is connected and name each edge by what crosses it,
+     group with regions, add cards, and write `meta.note` — what was folded, which relation is an inference;
+   - `spex diagram check <node>`, and repair from its findings until it passes.
+   Put no numbers on a picture that move on their own — node counts, drift, commit or import counts.
+4. **Keep the spec honest.** What drawing reveals about the spec — a claim the code does not bear out, a
+   relation the body never states — goes into an issue or your report, never into the picture.
+5. **Land it.** `spex spec lint`, then commit the diagrams, together with any spec change they belong to.
+6. **Report** which nodes got which kind of diagram, which were skipped and why, and anything you filed.
+
+## Hand over the page
+
+`npx -y -p spexcode@next -p @spexcode/spec-dashboard@next spex graph --public --html spexcode-atlas.html` writes the whole tree — every body and
+every picture — as one self-contained page that opens in any browser, straight from disk. Offer it with the report;
+it is a product of the tree, not part of it, so leave it uncommitted.