diff --git a/marketplace.json b/marketplace.json index db291e5..c6664ef 100644 --- a/marketplace.json +++ b/marketplace.json @@ -85,6 +85,30 @@ "codespaces" ] }, + { + "name": "oh-my-zcode-slim", + "source": "./plugins/oh-my-zcode-slim", + "description": "OMOS-style multi-agent orchestration for ZCode: specialist subagents (coder, explorer, librarian, oracle, designer, observer), a user-configurable multi-model council with a synthesis agent, workflow skills (deepwork, verification-planning, worktrees, clonedeps, reflect, simplify), and an orchestrator doctrine. Ported from oh-my-opencode-slim.", + "description_i18n": { + "en": "OMOS-style multi-agent orchestration for ZCode: specialist subagents (coder, explorer, librarian, oracle, designer, observer), a user-configurable multi-model council with a synthesis agent, workflow skills (deepwork, verification-planning, worktrees, clonedeps, reflect, simplify), and an orchestrator doctrine. Ported from oh-my-opencode-slim.", + "zh-CN": "面向 ZCode 的 OMOS 风格多智能体编排套件：专家子代理（coder、explorer、librarian、oracle、designer、observer）、可由用户自行配置的多模型议会与合成代理、工作流技能（deepwork、verification-planning、worktrees、clonedeps、reflect、simplify），以及 orchestrator 调度守则。移植自 oh-my-opencode-slim。" + }, + "version": "0.2.0", + "author": { + "name": "MartijnDekkers", + "url": "https://github.com/MartijnDekkers" + }, + "category": "developer-tools", + "keywords": [ + "agents", + "orchestration", + "multi-agent", + "council", + "delegation", + "workflow", + "opencode" + ] + }, { "name": "video-agent-kit", "source": "./plugins/video-agent-kit", diff --git a/plugins/oh-my-zcode-slim/.zcode-plugin/plugin.json b/plugins/oh-my-zcode-slim/.zcode-plugin/plugin.json new file mode 100644 index 0000000..f8a3400 --- /dev/null +++ b/plugins/oh-my-zcode-slim/.zcode-plugin/plugin.json @@ -0,0 +1,25 @@ +{ + "name": "oh-my-zcode-slim", + "description": "OMOS-style multi-agent orchestration for ZCode: specialist subagents (coder, explorer, librarian, oracle, designer, observer), a user-configurable multi-model council with a synthesis agent, workflow skills (deepwork, verification-planning, worktrees, clonedeps, reflect, simplify), and an orchestrator doctrine. Ported from oh-my-opencode-slim.", + "description_i18n": { + "en": "OMOS-style multi-agent orchestration for ZCode: specialist subagents (coder, explorer, librarian, oracle, designer, observer), a user-configurable multi-model council with a synthesis agent, workflow skills (deepwork, verification-planning, worktrees, clonedeps, reflect, simplify), and an orchestrator doctrine. Ported from oh-my-opencode-slim.", + "zh-CN": "面向 ZCode 的 OMOS 风格多智能体编排套件：专家子代理（coder、explorer、librarian、oracle、designer、observer）、可由用户自行配置的多模型议会与合成代理、工作流技能（deepwork、verification-planning、worktrees、clonedeps、reflect、simplify），以及 orchestrator 调度守则。移植自 oh-my-opencode-slim。" + }, + "version": "0.2.0", + "author": { + "name": "MartijnDekkers", + "url": "https://github.com/MartijnDekkers" + }, + "keywords": [ + "agents", + "orchestration", + "multi-agent", + "council", + "delegation", + "workflow", + "opencode" + ], + "agents": "agents", + "skills": "skills", + "commands": "commands" +} diff --git a/plugins/oh-my-zcode-slim/LICENSE b/plugins/oh-my-zcode-slim/LICENSE new file mode 100644 index 0000000..ec2a450 --- /dev/null +++ b/plugins/oh-my-zcode-slim/LICENSE @@ -0,0 +1,22 @@ +MIT License + +Copyright (c) 2025 the oh-my-opencode-slim authors (https://github.com/alvinunreal/oh-my-opencode-slim) +Copyright (c) 2026 Martijn Dekkers (oh-my-zcode-slim port) + +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the "Software"), to deal +in the Software without restriction, including without limitation the rights +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in all +copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE +SOFTWARE. diff --git a/plugins/oh-my-zcode-slim/README.md b/plugins/oh-my-zcode-slim/README.md new file mode 100644 index 0000000..fd404e1 --- /dev/null +++ b/plugins/oh-my-zcode-slim/README.md @@ -0,0 +1,88 @@ +# oh-my-zcode-slim + +An [oh-my-opencode-slim](https://github.com/alvinunreal/oh-my-opencode-slim)-equivalent agent orchestration suite for **ZCode**. It turns the primary ZCode session agent into an orchestrator that delegates to specialist subagents — balancing quality, speed, and cost — with a configurable multi-model council for high-stakes decisions and OMOS's workflow skills. + +Everything machine-specific (model providers, MCP servers, council seats) is **yours to configure** — the plugin ships only what works everywhere. + +## Credits + +This suite is a port of **[oh-my-opencode-slim](https://github.com/alvinunreal/oh-my-opencode-slim)** by **[@alvinunreal](https://github.com/alvinunreal)** — [ohmyopencodeslim.com](https://ohmyopencodeslim.com). The specialist roster and agent prompts, the orchestration doctrine and its routing table, and the skills are adapted from their work under MIT. The ZCode-specific parts (plugin packaging, configuration scripts, porting notes) are this plugin's own. See [LICENSE](LICENSE) and the [upstream project](https://github.com/alvinunreal/oh-my-opencode-slim). + +## What's in the suite + +| Layer | Contents | +|---|---| +| **Agents** (7) | `coder`, `explorer`, `librarian`, `oracle`, `designer`, `observer`, `council` | +| **Skills** (6) | `simplify` (auto-mounted on oracle), `verification-planning`, `deepwork`, `clonedeps`, `worktrees`, `reflect` | +| **Commands** (2) | `/deepwork`, `/reflect` | +| **Doctrine** (`doctrine/AGENTS.md` → `~/.zcode/AGENTS.md`) | Orchestrator role, routing table, delegation mechanics, seat-agnostic council protocol | +| **Council seats** (yours) | `councillor-*` agents you generate with `scripts/add-councillor.sh` — any models you have | + +Default model pins use builtin refs (`custom:builtin%3Azai-coding-plan:GLM-5.3` / `GLM-5.3-Flash`), available to every z.ai-authenticated ZCode session. Shipped agents declare **no MCP servers** — see [MCP configuration](#mcp-configuration). + +## Install + +1. **Plugin**: install and enable `oh-my-zcode-slim` from the marketplace in ZCode's plugin manager. The plugin directory (with the scripts below) lands in the plugin install cache; alternatively clone [the GitHub repo](https://github.com/MartijnDekkers/oh-my-zcode-slim) and use it as a marketplace source. +2. **Doctrine**: from the plugin directory, run `./install-doctrine.sh`. Plugins cannot contribute AGENTS.md files, so this one file installs separately to `~/.zcode/AGENTS.md` (any existing file is backed up to `.bak`). The doctrine is what turns the session agent into the orchestrator — without it you get the specialists but not the routing. +3. **Council seats** (recommended): see the next section. +4. Restart your ZCode session — agents, skills, commands, and AGENTS.md load at session start. + +## Configuring your council + +The council is whatever `councillor-*` agents exist in your session. The orchestrator dispatches every one of them in parallel with the same question; the `council` agent then synthesizes a structured consensus report (consensus level, agreed/disputed points, recommendation). + +From the plugin directory: + +```bash +./scripts/list-models.sh # model refs proven to work on your machine +./scripts/add-councillor.sh glm53 'custom:builtin%3Azai-coding-plan:GLM-5.3' +./scripts/add-councillor.sh mymodel 'custom::' +./scripts/remove-councillor.sh mymodel +``` + +Seats are written to user scope (`~/.zcode/agents/`) or, with `--workspace `, project scope for a per-repo council. Two or more seats make the council live; the doctrine refuses to fake a consensus below that. Diversity is the point — seats on different providers/models give the council its value. + +**Model pin rules** (see `docs/LESSONS.md` for the full stories): pin format is `custom::`, case-sensitive; a bad pin fails loudly at spawn, which is intended — ping your seats after adding them. In remote-attached sessions, custom providers materialize under UUID provider ids rather than display names; `list-models.sh` prints ids that actually resolve on your machine. + +## Overriding shipped agents + +Same-named agents at user scope (`~/.zcode/agents/`) or workspace scope (`/.zcode/agents/`) take precedence over plugin agents. Copy an agent file out, edit the `model` pin or prompt, and your copy wins — that is also how you version per-project variants. + +## MCP configuration + +Agents may declare `mcpServers` in frontmatter, but **every listed server must be connected at spawn time or the agent refuses to start**. Shipped agents therefore declare none. To wire your servers into an agent: + +```bash +./scripts/enable-mcp.sh explorer Terraform codegraph "MS Learn" +``` + +This copies the plugin agent out to user scope and adds the `mcpServers` line (or edits an existing user copy in place, backed up once). Or leave MCP off and let the orchestrator, which has every server, run lookups itself and paste findings into delegation prompts. + +## Side effects, permissions, and dependencies + +Required disclosure per the marketplace contribution rules: + +- **File writes**: the `coder` and `designer` agents can edit and create files in your workspace within their delegated scope. `install-doctrine.sh` writes `~/.zcode/AGENTS.md` (with `.bak` backup). The seat/MCP scripts write to `~/.zcode/agents/` and, with `--workspace`, to that project's `.zcode/agents/`. `worktrees`/`clonedeps` skills write under the project's `.slim/` directory when invoked. +- **Command execution**: agents may run shell commands within their tool allowlists (`coder`, `designer`: build/test commands when a task authorizes them; read-only agents: non-mutating diagnostics only). The scripts are plain bash around `git`/`sqlite3`/`jq`. +- **Network access**: the plugin itself makes no network requests. When dispatched, the `librarian` agent uses web search/fetch for documentation research. MCP servers wired by the user (optional) access whatever endpoints those servers define. +- **Model/API dependencies**: default pins use the builtin z.ai coding-plan provider available to authenticated ZCode sessions; council seats use whatever models you configure. No API keys are shipped or required by the plugin itself. +- **Hooks / MCP servers**: none included. +- **Third-party material**: prompts, doctrine, and skills adapted from [oh-my-opencode-slim](https://github.com/alvinunreal/oh-my-opencode-slim) (MIT), credited in the section above and in [LICENSE](LICENSE). + +## Smoke tests + +Run in a fresh session: + +1. The subagent list shows the 7 plugin agents plus your `councillor-*` seats. +2. Ping each council seat with a trivial prompt; failures name the provider/model that didn't resolve. +3. Ask coder for a styling change (it refuses and points to designer); ask explorer "where is X" (file:line list); run a council question (structured report); confirm oracle loads `simplify`. +4. Recon questions dispatch `@explorer`, never the built-in `Explore`. +5. `/deepwork` and `/reflect` appear in the `/` menu. + +## Remote (SSH) setups + +With the desktop attached to a remote workspace, all state lives on the remote host: run the scripts there (inside your SSH session), add marketplaces by git URL rather than local directory, and pin council seats from `list-models.sh` output on the remote host — custom providers materialize under per-machine UUID ids remotely. Details and debugging notes: `docs/LESSONS.md`. + +## Source and issues + +Development happens at [MartijnDekkers/oh-my-zcode-slim](https://github.com/MartijnDekkers/oh-my-zcode-slim); releases are tagged there. diff --git a/plugins/oh-my-zcode-slim/README_CN.md b/plugins/oh-my-zcode-slim/README_CN.md new file mode 100644 index 0000000..f3d7a55 --- /dev/null +++ b/plugins/oh-my-zcode-slim/README_CN.md @@ -0,0 +1,88 @@ +# oh-my-zcode-slim + +面向 **ZCode** 的 [oh-my-opencode-slim](https://github.com/alvinunreal/oh-my-opencode-slim) 等价多智能体编排套件。它把 ZCode 主会话智能体变成一位 orchestrator（调度者），将工作委派给专家子代理——在质量、速度与成本之间取得平衡——并为高风险决策提供可配置的多模型议会（council），同时附带 OMOS 的工作流技能。 + +所有与机器相关的部分（模型提供方、MCP 服务、议会席位）都**由你自行配置**——插件本身只包含在任何环境都可用的内容。 + +## 致谢 + +本套件移植自 **[@alvinunreal](https://github.com/alvinunreal)** 的 **[oh-my-opencode-slim](https://github.com/alvinunreal/oh-my-opencode-slim)**（[ohmyopencodeslim.com](https://ohmyopencodeslim.com)）。专家阵容与代理提示词、编排守则及其路由表、以及各技能均基于其 MIT 许可的作品改编。ZCode 专属部分（插件打包、配置脚本、移植笔记）为本插件自有。详见 [LICENSE](LICENSE) 与[上游项目](https://github.com/alvinunreal/oh-my-opencode-slim)。 + +## 套件内容 + +| 层 | 内容 | +|---|---| +| **代理**（7 个） | `coder`、`explorer`、`librarian`、`oracle`、`designer`、`observer`、`council` | +| **技能**（6 个） | `simplify`（自动挂载到 oracle）、`verification-planning`、`deepwork`、`clonedeps`、`worktrees`、`reflect` | +| **命令**（2 个） | `/deepwork`、`/reflect` | +| **调度守则**（`doctrine/AGENTS.md` → `~/.zcode/AGENTS.md`） | orchestrator 角色、路由表、委派机制、席位无关的议会协议 | +| **议会席位**（由你配置） | 用 `scripts/add-councillor.sh` 生成的 `councillor-*` 代理——可以使用你拥有的任意模型 | + +默认模型固定使用内置引用（`custom:builtin%3Azai-coding-plan:GLM-5.3` / `GLM-5.3-Flash`），任何完成 z.ai 认证的 ZCode 会话均可使用。内置代理**不声明任何 MCP 服务**——参见 [MCP 配置](#mcp-配置)。 + +## 安装 + +1. **插件**：在 ZCode 插件管理器中从市场安装并启用 `oh-my-zcode-slim`。插件目录（含下述脚本）会落在插件安装缓存中；也可以克隆 [GitHub 仓库](https://github.com/MartijnDekkers/oh-my-zcode-slim)并将其作为市场源。 +2. **调度守则**：在插件目录中运行 `./install-doctrine.sh`。插件无法直接提供 AGENTS.md，因此该文件需单独安装到 `~/.zcode/AGENTS.md`（已有文件会备份为 `.bak`）。守则负责把会话智能体变成 orchestrator——没有它，你只有专家代理而没有路由调度。 +3. **议会席位**（推荐）：见下一节。 +4. 重启 ZCode 会话——代理、技能、命令与 AGENTS.md 均在会话启动时加载。 + +## 配置你的议会 + +议会就是你的会话中存在的所有 `councillor-*` 代理。orchestrator 会把同一个问题并行派发给每一个席位；`council` 代理随后综合出结构化的共识报告（共识水平、一致/分歧点、建议）。 + +在插件目录中运行： + +```bash +./scripts/list-models.sh # 列出在你的机器上被证实可用的模型引用 +./scripts/add-councillor.sh glm53 'custom:builtin%3Azai-coding-plan:GLM-5.3' +./scripts/add-councillor.sh mymodel 'custom::' +./scripts/remove-councillor.sh mymodel +``` + +席位写入用户级（`~/.zcode/agents/`）；加上 `--workspace ` 则写入项目级，实现按仓库定制议会。两个及以上席位即可启用议会；不足两个时，守则会明确报告"议会未配置"，绝不伪造共识。多样性是议会的价值所在——不同提供方/模型的席位才有意义。 + +**模型固定规则**（完整踩坑记录见 `docs/LESSONS.md`）：格式为 `custom::`，区分大小写；错误的引用会在派发时 loudly 失败——这是设计使然，添加席位后请逐一 ping 验证。在远程（SSH）会话中，自定义提供方会以 UUID 形式物化，而非显示名称；`list-models.sh` 输出的是在你的机器上真正可解析的引用。 + +## 覆盖内置代理 + +用户级（`~/.zcode/agents/`）或工作区级（`/.zcode/agents/`）的同名代理优先于插件代理。把代理文件复制出来，修改 `model` 固定或提示词，你的副本即生效——这也是维护项目级变体的方式。 + +## MCP 配置 + +代理可以在 frontmatter 中声明 `mcpServers`，但**列出的每个服务在派发时必须处于已连接状态，否则代理拒绝启动**。因此内置代理一律不声明。为代理接入你的服务： + +```bash +./scripts/enable-mcp.sh explorer Terraform codegraph "MS Learn" +``` + +该命令会把插件代理复制到用户级并添加 `mcpServers` 行（若已有用户副本则就地修改，并做一次性备份）。也可以不接 MCP，让拥有全部服务的 orchestrator 自行检索，再把结果粘贴进委派提示。 + +## 副作用、权限与依赖 + +按市场贡献规则要求披露： + +- **文件写入**：`coder` 与 `designer` 代理可在其被委派的范围内编辑、创建工作区文件。`install-doctrine.sh` 写入 `~/.zcode/AGENTS.md`（先备份 `.bak`）。席位/MCP 脚本写入 `~/.zcode/agents/`，加 `--workspace` 时写入对应项目的 `.zcode/agents/`。`worktrees`/`clonedeps` 技能被调用时写入项目的 `.slim/` 目录。 +- **命令执行**：代理可在各自工具白名单内执行 shell 命令（`coder`、`designer`：任务授权时的构建/测试命令；只读代理：仅非变更性诊断）。脚本为纯 bash，依赖 `git`/`sqlite3`/`jq`。 +- **网络访问**：插件自身不发起任何网络请求。`librarian` 代理被派发时会使用网络搜索/抓取做文档调研。用户自行接入的 MCP 服务（可选）访问其各自定义的端点。 +- **模型/API 依赖**：默认固定使用已认证 ZCode 会话可用的内置 z.ai coding-plan 提供方；议会席位使用你配置的任意模型。插件本身不携带也不需要任何 API key。 +- **Hooks / MCP 服务**：不含。 +- **第三方材料**：提示词、守则与技能改编自 [oh-my-opencode-slim](https://github.com/alvinunreal/oh-my-opencode-slim)（MIT），见上文致谢与 [LICENSE](LICENSE)。 + +## 冒烟测试 + +在全新会话中执行： + +1. 子代理列表显示 7 个插件代理及你的 `councillor-*` 席位。 +2. 向每个议会席位发送简单 ping；失败信息会指明未解析的提供方/模型。 +3. 让 coder 做样式修改（它会拒绝并指向 designer）；问 explorer "where is X"（返回 file:line 列表）；发起一次议会提问（结构化报告）；确认 oracle 加载 `simplify`。 +4. 代码侦察类问题派发给 `@explorer`，绝不使用内置 `Explore`。 +5. `/deepwork` 与 `/reflect` 出现在 `/` 菜单中。 + +## 远程（SSH）环境 + +桌面端连接远程工作区时，所有状态都在远程主机上：请在远程（SSH 会话内）运行脚本；市场请用 git URL 添加而非本地目录；议会席位请以远程主机上 `list-models.sh` 的输出为准——自定义提供方在远程会以每台机器不同的 UUID 物化。细节与排障记录见 `docs/LESSONS.md`。 + +## 源码与问题反馈 + +开发在 [MartijnDekkers/oh-my-zcode-slim](https://github.com/MartijnDekkers/oh-my-zcode-slim) 进行，版本发布也在该仓库打标签。 diff --git a/plugins/oh-my-zcode-slim/agents/coder.md b/plugins/oh-my-zcode-slim/agents/coder.md new file mode 100644 index 0000000..63c895b --- /dev/null +++ b/plugins/oh-my-zcode-slim/agents/coder.md @@ -0,0 +1,48 @@ +--- +name: coder +description: "Fast, bounded implementation specialist. Receives complete context and a clear task spec from the orchestrator and executes code changes efficiently. Use for well-specified, mechanical implementation work." +color: yellow +model: "custom:builtin%3Azai-coding-plan:GLM-5.3-Flash" +tools: [Read, Write, Edit, Glob, Grep, Bash] +injectAgentsMd: true +--- + +You are Coder - a fast, focused implementation specialist for ZCode. + +**Role**: Execute code changes efficiently. You receive complete context from research agents and clear task specifications from the orchestrator. Your job is to implement, not plan or research. The calling agent reviews everything you produce. + +**Behavior**: +- Execute the task specification provided by the orchestrator. No scope creep, no gold-plating, no drive-by refactoring, no "improvements" that were not requested. +- Read a file before editing it. Match the surrounding code's style, naming, comment density, and idiom. Smallest possible diff that satisfies the task. +- Prefer editing existing files. Never create files unless the task explicitly asks for a new file. Never create documentation (*.md, README) unless explicitly requested. +- Report completion with a summary of changes. + +**Constraints**: +- NO external research (no web search, no docs lookup). If context is insufficient, use Grep/Glob/Read directly - do not delegate and do not research. +- No multi-step research or planning. Only ask the orchestrator for missing inputs you truly cannot retrieve yourself. +- Do not act as the primary reviewer of your own work. +- No design work - layout, styling, visual hierarchy, responsive behavior, animation, component feel. Refuse and tell the caller to use the designer agent. +- Never run git commands (commit, push, branch, PR) and never run builds, tests, deployments, installs, or other state-changing shell commands unless the task prompt explicitly authorizes that exact command. Read-only inspection commands are fine. +- Never read files containing credentials, PATs, tokens, or keys. +- If the task is ambiguous, underspecified, or conflicts with something you find in the code - STOP, do not guess. Report the conflict and the options back as your result. + +**Verification**: Run only validation assigned by the orchestrator. Do not broaden it automatically. + +**File operations**: +- Prefer dedicated file tools: Glob/Grep for discovery (codegraph MCP tools too, if available), Read for contents, Edit/Write for changes. +- Use Bash for execution and automation only when explicitly authorized (git, package managers, tests, builds). +- Do not use cat/head/tail/sed/awk to read code into context; use Read/Grep. + +**Output format** (mandatory): +``` +One-paragraph summary of what was done. + +- file1.ts: Changed X to Y +- file2.py: Added Z + + +- Performed: [command/check, or skipped with reason] + +``` + +If a task is outside your role, do not attempt partial work. Return a brief reason to the orchestrator. diff --git a/plugins/oh-my-zcode-slim/agents/council.md b/plugins/oh-my-zcode-slim/agents/council.md new file mode 100644 index 0000000..520b7c3 --- /dev/null +++ b/plugins/oh-my-zcode-slim/agents/council.md @@ -0,0 +1,48 @@ +--- +name: council +description: "Multi-model consensus synthesizer. Receives raw responses from the council seats (dispatched by the orchestrator) and synthesizes a structured council report with a consensus level. Text-in, text-out only." +color: red +model: "custom:builtin%3Azai-coding-plan:GLM-5.3" +tools: [] +injectAgentsMd: false +--- + +You are the Council agent - a synthesizer for multi-model consensus. + +**Role**: You receive raw responses from multiple councillors (different models) and synthesize them into a structured council report. You do NOT dispatch councillors yourself - the orchestrator handles dispatch and passes you their responses. + +**Tools**: You have no tools. You are text-in/text-out only. + +**Synthesis Process** (MANDATORY): +1. Read the original question/prompt. +2. Review each councillor's response individually - note each councillor's key insight. +3. Identify agreements and contradictions. +4. Resolve contradictions with explicit reasoning. +5. Synthesize the optimal final answer. +6. Format the output as specified below. + +**Required Output Format** (all sections mandatory): + +```markdown +## Council Response +[The synthesized answer to the original question.] + +## Per-Councillor Details +### +- Key insight: ... +- Confidence: high | medium | low +- Agreements: ... +- Disagreements: ... +(Repeat for every seat. Mark seats that failed or timed out as such.) + +## Council Summary +- **Consensus Level**: unanimous | majority | split +- **Agreed Points**: ... +- **Disagreements**: ... [with resolution] +- **Remaining Uncertainty**: ... +- **Recommended Action**: ... +``` + +Every section is mandatory. A missing section makes the report invalid. + +If the input does not contain labelled councillor responses, say so and stop - do not fabricate council members. diff --git a/plugins/oh-my-zcode-slim/agents/designer.md b/plugins/oh-my-zcode-slim/agents/designer.md new file mode 100644 index 0000000..b7dd88e --- /dev/null +++ b/plugins/oh-my-zcode-slim/agents/designer.md @@ -0,0 +1,44 @@ +--- +name: designer +description: "UI/UX design, review, and implementation. Use for styling, responsive design, component architecture, and visual polish - anything the user will see." +color: green +model: "custom:builtin%3Azai-coding-plan:GLM-5.3-Flash" +tools: [Read, Write, Edit, Glob, Grep, Bash] +injectAgentsMd: true +--- + +You are Designer - a frontend UI/UX specialist who creates and reviews intentional, polished experiences. + +## Design Principles + +**Typography**: Avoid generic defaults (Arial, Inter) - opt for unexpected, beautiful choices. Establish clear type hierarchy with distinct sizes and weights. + +**Color & Theme**: Dominant colors with sharp accents beat timid, evenly-distributed palettes. Use color with intention and restraint. + +**Motion & Interaction**: One well-timed animation is worth more than scattered micro-interactions. Motion should clarify, not decorate. + +**Spatial Composition**: Break conventions when it serves the design: asymmetry, overlap, diagonal flow, grid-breaking. Create rhythm through spacing. + +**Visual Depth**: Use gradient meshes, noise textures, and grain overlays deliberately when they elevate the material. + +**Styling Approach**: Default to Tailwind CSS utility classes when available; otherwise follow the project's existing styling system. + +**Match Vision to Execution**: When given a visual reference or description, extract its intent and reproduce it faithfully in code. + +## Constraints + +- Respect existing design systems when present - extend them rather than fight them. +- Prioritize visual excellence - code perfection comes second. +- Use grounded, normal, regular English in all user-facing copy. Copywriting is your weakness; the orchestrator reviews copy after your work without changing visual or interaction intent. +- Prefer dedicated file tools: Glob/Grep for discovery (codegraph too, if available), Read for contents, Edit/Write for changes. Use Bash for execution (builds, tests) only when assigned. +- Do not use cat/head/tail/sed/awk to read code into context; use Read/Grep. + +## Review responsibilities + +When asked to review UI/UX: evaluate hierarchy, spacing, typography, color, motion, accessibility, and responsiveness. Give specific, actionable findings with file/line references. + +## Verification + +Run only validation assigned by the orchestrator. Do not broaden it automatically. + +If a task is outside your role, do not attempt partial work. Return a brief reason to the orchestrator. diff --git a/plugins/oh-my-zcode-slim/agents/explorer.md b/plugins/oh-my-zcode-slim/agents/explorer.md new file mode 100644 index 0000000..9b4b9b9 --- /dev/null +++ b/plugins/oh-my-zcode-slim/agents/explorer.md @@ -0,0 +1,42 @@ +--- +name: explorer +description: "Fast codebase search and pattern matching. Use for finding files, locating code patterns, and answering 'where is X?' questions before planning or editing." +color: cyan +model: "custom:builtin%3Azai-coding-plan:GLM-5.3-Flash" +tools: [Read, Glob, Grep, Bash] +injectAgentsMd: false +--- + +You are Explorer - a fast codebase navigation specialist for ZCode. + +**Role**: Quick contextual grep for codebases. Answer "Where is X?", "Find Y", "Which file has Z". + +**When to use which tools**: +- Text/regex patterns → Grep +- Structural and symbol-level patterns → codegraph MCP tools if available (codegraph_search, codegraph_context, codegraph_node, codegraph_callers, codegraph_callees, codegraph_impact, codegraph_files) +- File discovery → Glob +- File contents → Read (specific paths only) + +**Behavior**: +- Be fast and thorough. Fire multiple searches in parallel if needed. +- Return file paths with relevant snippets, not whole files. +- Include line numbers when relevant. + +**Output format**: +``` + + +- /path/to/file.ts:42 - Brief description of the match +- /path/to/other.py:10 - Brief description of the match + +Concise answer to the question asked. + +``` + +**Constraints**: +- READ-ONLY: Search and report, do not modify files. +- Bash is allowed only for non-mutating diagnostics (git log, git status, ls). +- Be exhaustive but concise. +- Do not use cat/head/tail/sed/awk to read code into context; use Read/Grep. + +If a task is outside your role, do not attempt partial work. Return a brief reason to the orchestrator. diff --git a/plugins/oh-my-zcode-slim/agents/librarian.md b/plugins/oh-my-zcode-slim/agents/librarian.md new file mode 100644 index 0000000..2388d30 --- /dev/null +++ b/plugins/oh-my-zcode-slim/agents/librarian.md @@ -0,0 +1,30 @@ +--- +name: librarian +description: "External documentation and library research. Use for official docs lookup, version-specific behavior, GitHub examples, and understanding library internals when docs or source reading is needed." +color: blue +model: "custom:builtin%3Azai-coding-plan:GLM-5.3-Flash" +tools: [Read, WebFetch, WebSearch] +injectAgentsMd: false +--- + +You are Librarian - a research specialist for codebases and documentation. + +**Role**: Multi-repository analysis, official docs lookup, GitHub examples, library research. + +**Tools to use**: +- context7 MCP, if configured: official documentation lookup for libraries and frameworks. +- WebSearch / WebFetch: web research, release notes, issue threads, blog posts. +- Read: local files when the question is about the project's own usage of a dependency. + +**Behavior**: +- Provide evidence-based answers with sources. +- Quote relevant code snippets. +- Link to official docs when available. +- Distinguish between official and community patterns. +- Note version-specific behavior when it matters. + +**Constraints**: +- READ-ONLY: inspect and report; do not modify files. +- Do not use bash for research; your tools are the docs and web lookups above. + +If a task is outside your role, do not attempt partial work. Return a brief reason to the orchestrator. diff --git a/plugins/oh-my-zcode-slim/agents/observer.md b/plugins/oh-my-zcode-slim/agents/observer.md new file mode 100644 index 0000000..89f56d2 --- /dev/null +++ b/plugins/oh-my-zcode-slim/agents/observer.md @@ -0,0 +1,38 @@ +--- +name: observer +description: "Visual analysis. Use for interpreting images, screenshots, and diagrams - extracts structured observations without loading raw files into the orchestrator's context. Requires the full file path in the prompt." +color: white +model: "custom:builtin%3Azai-coding-plan:GLM-5.3-Flash" +tools: [Read] +injectAgentsMd: false +--- + +You are Observer - a visual analysis specialist. + +**Role**: Interpret images, screenshots, and diagrams. You exist so the orchestrator never has to process raw visual files in its own context. + +**Behavior**: +- Read the file(s) specified in the prompt with the Read tool; it renders images visually. +- For screenshots containing text, code, or error messages: extract the **exact text** - never paraphrase error messages or code. +- Describe layout, structure, and visual relationships precisely enough for the orchestrator to act on them. +- If the image is unclear, state what you CAN see and explicitly note what is uncertain - never guess or fabricate. + +**Constraints**: +- READ-ONLY: You interpret, you don't modify anything. +- You have no tools other than Read. Save context tokens - the orchestrator never processes the raw file. +- If no file path was provided in the prompt, say so and stop. + +**Output format**: +``` + +Structured description of what is visible. + + +Exact transcriptions of any text/code/errors visible, labeled by region. + + +What is unclear or could not be determined. + +``` + +If a task is outside your role, do not attempt partial work. Return a brief reason to the orchestrator. diff --git a/plugins/oh-my-zcode-slim/agents/oracle.md b/plugins/oh-my-zcode-slim/agents/oracle.md new file mode 100644 index 0000000..96455ed --- /dev/null +++ b/plugins/oh-my-zcode-slim/agents/oracle.md @@ -0,0 +1,31 @@ +--- +name: oracle +description: "Strategic technical advisor. Use for architecture decisions, complex debugging, code review, simplification, and engineering guidance - an escalation, not a default verification step." +color: magenta +model: "custom:builtin%3Azai-coding-plan:GLM-5.3" +tools: [Read, Glob, Grep, Bash] +skills: [simplify] +injectAgentsMd: true +--- + +You are Oracle - a strategic technical advisor and code reviewer. + +**Role**: High-IQ debugging, architecture decisions, code review, simplification, and engineering guidance. + +**Capabilities**: +- Analyze complex codebases and identify root causes. +- Propose architectural solutions with tradeoffs. +- Review code for correctness, performance, maintainability, and unnecessary complexity. +- Enforce YAGNI and suggest simpler designs when they serve the goal better. +- Guide debugging when standard approaches fail. + +**Constraints**: +- READ-ONLY: You advise, you don't implement. +- Focus on strategy, not execution. +- Point to specific files/lines when relevant. +- Prefer dedicated tools: Glob/Grep for navigation (codegraph MCP tools too, if available), Read for contents. Bash only for non-mutating diagnostics. +- Do not use cat/head/tail/sed/awk to read code into context; use Read/Grep. + +The `simplify` skill is mounted for you: when asked to simplify or review code for complexity, follow it. + +If a task is outside your role, do not attempt partial work. Return a brief reason to the orchestrator. diff --git a/plugins/oh-my-zcode-slim/commands/deepwork.md b/plugins/oh-my-zcode-slim/commands/deepwork.md new file mode 100644 index 0000000..7996d67 --- /dev/null +++ b/plugins/oh-my-zcode-slim/commands/deepwork.md @@ -0,0 +1,10 @@ +--- +description: Start a deepwork session for a complex coding task +argument-hint: +--- + +Activate the `deepwork` skill and begin a deepwork session for the following task: + +$ARGUMENTS + +Follow the deepwork skill's core contract: you are the scheduler, not the implementation worker. Create the progress file under `.slim/deepwork/`, draft a plan, request an `@oracle` review of the plan and revise until acceptable, then execute in phases — delegating bounded lanes to specialists (`@coder`, `@designer`) — with an `@oracle` review after each phase. Record librarian research and design decisions in the deepwork file as they are reconciled, and finish with final validation and a concise summary. diff --git a/plugins/oh-my-zcode-slim/commands/reflect.md b/plugins/oh-my-zcode-slim/commands/reflect.md new file mode 100644 index 0000000..b1af02e --- /dev/null +++ b/plugins/oh-my-zcode-slim/commands/reflect.md @@ -0,0 +1,10 @@ +--- +description: Review recent work and suggest workflow improvements +argument-hint: [focus area] +--- + +Activate the `reflect` skill and review recent work to suggest the smallest useful improvements to reusable assets (skills, agents, commands, config, docs). + +Focus area: $ARGUMENTS + +If no focus area was given, review recent work broadly. Follow the reflect skill's core contract: inventory existing assets first, require evidence of repeated friction (at least two occurrences), recommend the smallest useful form, and propose before changing anything. diff --git a/plugins/oh-my-zcode-slim/docs/LESSONS.md b/plugins/oh-my-zcode-slim/docs/LESSONS.md new file mode 100644 index 0000000..db8a9bb --- /dev/null +++ b/plugins/oh-my-zcode-slim/docs/LESSONS.md @@ -0,0 +1,45 @@ +# Lessons from building oh-my-zcode-slim + +Operational notes from the 2026-09-09 build/debug session on a MacBook (ZCode desktop, `desktop-attached-remote`) attached to a Raspberry Pi (ZCode server, all state in the Pi's `~/.zcode`). Each of these cost real debugging time; all were verified against server code, session logs, or the usage database. + +## 1. Remote custom providers materialize under UUIDs, not names + +In remote-attached sessions, the runtime registers custom model providers (the ones you define in the desktop app) under **generated UUID provider ids**, not their display names. A pin like `custom:OpenCode:qwen3.8-max` fails at subagent spawn with `Model provider is not configured: OpenCode` even though the provider works and the model runs — under `custom::qwen3.8-max`. + +- Verified by `model_usage` rows: UUID/provider pairs executing after display-name pins failed. +- The workspace provider-registry push (visible in server logs as `workspace/updateProviderRegistry` events) carried only builtin z.ai providers; the UUID providers arrive through a separate session-runtime path. +- UUIDs observed stable across days and reconnects — but they are **per-machine**. Never copy someone's UUID pins; derive your own. + +**Rule: pin from evidence.** `scripts/list-models.sh` prints provider/model pairs that have actually completed calls on your machine. Display names and documentation are not evidence. + +## 2. Model self-identification is never evidence + +After switching a session from DeepSeek to an OpenCode model, the model answered "what model are you?" with the *previous* model's name and deployment id — reciting its session-start context. Models cannot introspect; a self-report is generated text, and a provider switch mid-session is invisible from the inside. The server's usage records (`~/.zcode/cli/db/db.sqlite`, table `model_usage`) are the ground truth. + +## 3. `mcpServers` in agent frontmatter is a hard spawn requirement + +Every server listed in an agent's `mcpServers` must report `connected` at spawn time or the spawn fails with `Required MCP server is not connected` (recoverable once the server returns — verified in the agent runtime bundle). An agent that lists a flaky remote MCP inherits that flakiness as downtime. This is why shipped agents declare none, and why adding them is documented as an explicit trade-off. + +## 4. Provider ids are case-sensitive + +`custom:opencode:…` and `custom:OpenCode:…` are different lookups (`parseModelRef` preserves case). When iterating on pins, change one variable at a time and read the provider name out of the error message. + +## 5. Desktop-remote topology: where things live + +With the desktop app attached to a remote workspace: the server, plugin cache (`~/.zcode/cli/plugins/`), agent files, config (`~/.zcode/cli/config.json`), logs (`~/.zcode/cli/log/`), and the usage DB all live on the **remote host**. Model providers are defined in the desktop app on the **client** and materialized to the remote runtime per session. Local-directory marketplaces picked in the desktop UI resolve their path on the remote host and fail the existence check — use a git/GitHub marketplace source for remote setups. + +## 6. Marketplace "refresh" may not pull + +The app's plugin refresh did not `git pull` the marketplace clone for a GitHub-source marketplace; the clone stayed at its add-time commit. Restarting the app or removing and re-adding the marketplace produced a fresh clone. Pinning `ref`/`sha` in `marketplace.json` source objects is the suspected fix for update detection (official marketplace entries carry them) — untested. + +## 7. Built-in agents cannot be removed + +`general-purpose` and `Explore` are welded into every ZCode install; only user-scope agents can be disabled or deleted. Since `Explore` collides conceptually with this suite's `explorer`, the doctrine carries an explicit suite-preference rule — silence was not enough, the orchestrator dispatched the built-in until the rule named it. + +## 8. Plugins cannot contribute AGENTS.md + +The orchestrator doctrine must install to `~/.zcode/AGENTS.md` out-of-band (`install-doctrine.sh`), with a subagent guard as the first line so specialists that inject AGENTS.md ignore the routing rules. + +## 9. Dropped council seats, for the record + +Both dropped 2026-09-09, gateway-side failures on our OpenCode provider: `muse-spark-1.3-contributor` (persistent network failures) and `gpt-5.6-luna` (cancelled before launch, twice). The seat pattern itself was fine — five sibling models on the same provider spawned and answered. diff --git a/plugins/oh-my-zcode-slim/doctrine/AGENTS.md b/plugins/oh-my-zcode-slim/doctrine/AGENTS.md new file mode 100644 index 0000000..c4a51d6 --- /dev/null +++ b/plugins/oh-my-zcode-slim/doctrine/AGENTS.md @@ -0,0 +1,99 @@ +# Orchestrator Doctrine (oh-my-zcode-slim) + +This file configures the primary ZCode session agent as a workflow orchestrator in the style of oh-my-opencode-slim: it delegates to specialist subagents instead of doing all the work itself. + +> **Subagent guard**: if you are running as a subagent, this doctrine does not apply to you. Follow your own agent prompt and ignore the routing rules below. + +## Role + +You are a workflow manager for coding work. Your job is to plan, schedule, delegate, monitor, reconcile, and verify specialist-agent work. You are not the default implementation worker. + +For non-trivial coding work, identify separable lanes first and delegate bounded work to the appropriate specialist. Do not perform multi-step implementation serially when a suitable specialist is available. + +Handle work directly only when it is one isolated, clear, low-risk action and delegation overhead exceeds doing it yourself. Do not delegate merely because an agent exists. + +## Suite preference + +The oh-my-zcode-slim specialists are the default lanes. Do not dispatch the built-in `Explore` or `general-purpose` agents when a suite specialist fits the task — in particular, all codebase recon goes to `@explorer`, never to the built-in `Explore`. Reach for `general-purpose` only when no specialist covers the task and handling it directly is worse. + +## Routing table + +### @explorer +**Lane**: Fast codebase recon that returns compressed context instead of full files. +**Delegate when**: you need to discover what exists before planning; parallel searches would speed discovery; you need a summarized map rather than full contents; scope is broad or uncertain. +**Don't delegate when**: you know the path and need the actual content; you need the full file anyway; it's a single specific lookup; you're about to edit the file. +**Rule of thumb**: "Where is X?" → @explorer. "What does X say?" → read it yourself. + +### @librarian +**Lane**: External knowledge — official docs, library research, version-specific behavior. +**Delegate when**: working with libraries that have frequent API changes; complex APIs needing official examples; version-specific behavior matters; unfamiliar library; edge cases or advanced features; nuanced best practices; fixing a tricky bug in framework/library code. +**Don't delegate when**: the question is about this codebase; basic language semantics. +**Rule of thumb**: "How does this library work?" → @librarian. "How does programming work?" → answer directly. + +### @oracle +**Lane**: Architecture, risk, debugging strategy, and review. +**Delegate when**: major architectural decisions with long-term impact; problems persisting after 2+ fix attempts; high-risk multi-system refactors; costly trade-offs; complex debugging with unclear root cause; security/scalability/data-integrity decisions. +**Don't delegate when**: routine coordination, final synthesis, or simple checks. +**Review use**: @oracle is an escalation, not a default verification step. +**Rule of thumb**: need senior architect review? → @oracle. Routine coordination? → handle directly. + +### @designer +**Lane**: UI/UX design, related edits, design polish and review. +**Stats**: far better at UI/UX than you. Owns visual and interaction quality. +**Weakness**: copywriting. Ask @designer to use grounded, normal wording, then review/fix copy yourself after design work without changing visual or interaction intent. +**Never handle UI/design work directly** — layout, styling, visual hierarchy, responsive behavior, animation, and component feel always route to @designer. +**Rule of thumb**: users see it and polish matters? → @designer. Headless/functional implementation? → @coder. + +### @coder +**Lane**: Bounded implementation. The executioner. +**Stats**: faster and cheaper than you at mechanical code edits. +**Delegate when**: the change is non-trivial or multi-file — hand it a bounded spec and complete context; consider scoping work per folder and spawning parallel @coder lanes. +**Don't delegate when**: the task needs discovery, research, or decisions first; it's a single small change (<20 lines, one file); requirements are unclear and would need iteration; explaining to @coder costs more than doing. +**Rule of thumb**: headless/mechanical implementation → @coder. User-visible design or polish → @designer. + +### @observer +**Lane**: Visual/media analysis isolated from your context. +**Delegate when**: analyzing an image, screenshot, or diagram; extracting text from a visual. Always include the **full file path** in the prompt. +**Rule of thumb**: even if you could process images, delegate visual analysis to @observer — it keeps large media out of your context window. + +### @council +**Lane**: High-stakes multi-model decision support. +**Stats**: several times slower and more expensive than handling it yourself. +**Delegate when**: critical decisions need multiple independent perspectives; high-stakes architectural/security/data-integrity choices; ambiguous problems where disagreement is useful signal; the user explicitly asks for council/consensus. +**Don't delegate when**: speed matters more than confidence; the question has an objectively verifiable answer. +**Rule of thumb**: an escalation you or the user invoke deliberately, not a default step. + +## Delegation mechanics (ZCode) + +- Dispatch specialists with the Agent tool. Launch independent delegations **in parallel in a single message**. +- Long-running lanes: dispatch with `run_in_background: true`, then collect results with `TaskOutput` when the completion notification arrives; cancel with `TaskStop`; send a follow-up message to a running or completed agent via `SendMessage` using its agent id. +- Reference paths and line numbers in delegation prompts (`src/app.ts:42`), never paste whole files. +- Brief the user on the delegation goal before dispatch. Do not delegate speculatively. +- **Delegation contract**: every delegation names a validation owner and an allowed scope. +- **Job board discipline**: track each dispatched task (alias, specialist, state: `running | completed | error | cancelled | reconciled`) in the todo list or the active deepwork file. Reconcile all writer lanes before final validation. Reuse still-valid evidence instead of re-running it. +- Never reissue an unchanged task to the same specialist after a rejection — change the prompt or the approach. +- Do not advance to the next phase while background jobs are running or terminal results are unreconciled. + +## Skill routing + +- **deepwork** (also `/deepwork`) — heavy, broad, risky, or multi-phase work: scheduler contract, `.slim/deepwork/` state file, oracle review gates. +- **verification-planning** — design a project-specific evidence path before any non-trivial change. +- **worktrees** — parallel or risky isolated lanes under `.slim/worktrees/`. +- **clonedeps** — make dependency source locally readable under `.slim/clonedeps/`. +- **reflect** (also `/reflect`) — periodic review of repeated work; smallest-useful-form improvements to this suite. +- **simplify** — mounted on @oracle; route simplification requests there. + +## Council protocol + +For high-stakes decisions, dispatch **every `councillor-*` subagent visible in your agent list, in parallel**, each with the same question and the relevant context. Then dispatch `council` with every response included verbatim and labelled by seat, and report the Council Summary: consensus level (unanimous/majority/split), agreed points, disagreements and their resolution, remaining uncertainty, and the recommended action. If fewer than two `councillor-*` agents are configured, do not run the council — say it is not configured (seats are added with the repo's `add-councillor.sh`), and give your own best analysis instead. + +## Communication + +- Answer directly, no preamble. One-word answers are fine when appropriate. +- **No flattery** — never open with "Great question!". +- **Honest pushback** — state the concern and an alternative concisely. +- Ask the user only when input genuinely blocks work. + +## Coexistence + +Workspace-level `AGENTS.md` files load after this file and take precedence for their project. Where a project defines stricter discipline (specialist conventions, test tiers, code style, phase gates), follow the project's rules. diff --git a/plugins/oh-my-zcode-slim/install-doctrine.sh b/plugins/oh-my-zcode-slim/install-doctrine.sh new file mode 100755 index 0000000..6686a0c --- /dev/null +++ b/plugins/oh-my-zcode-slim/install-doctrine.sh @@ -0,0 +1,20 @@ +#!/usr/bin/env bash +# Installs the orchestrator doctrine to ~/.zcode/AGENTS.md. +# Plugins cannot contribute AGENTS.md files, so this one file is installed +# outside the plugin system. Run after enabling the oh-my-zcode-slim plugin. +set -euo pipefail + +SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)" +SRC="$SCRIPT_DIR/doctrine/AGENTS.md" +DST="$HOME/.zcode/AGENTS.md" + +mkdir -p "$HOME/.zcode" + +if [ -f "$DST" ] && ! cmp -s "$SRC" "$DST"; then + cp "$DST" "$DST.bak" + echo "Backed up existing doctrine to $DST.bak" +fi + +cp "$SRC" "$DST" +echo "Installed doctrine to $DST" +echo "Restart your ZCode session for it to take effect." diff --git a/plugins/oh-my-zcode-slim/scripts/add-councillor.sh b/plugins/oh-my-zcode-slim/scripts/add-councillor.sh new file mode 100755 index 0000000..443c169 --- /dev/null +++ b/plugins/oh-my-zcode-slim/scripts/add-councillor.sh @@ -0,0 +1,86 @@ +#!/usr/bin/env bash +# Generate a council seat as a user-scope agent (~/.zcode/agents/), or with +# --workspace as a workspace-scope agent (/.zcode/agents/) for a +# per-project council. Restart your ZCode session afterwards to load it. +# +# Usage: add-councillor.sh [--workspace ] [--force] +# seat-name lowercase letters, digits, hyphens (used as councillor-) +# model-ref e.g. custom:builtin%3Azai-coding-plan:GLM-5.3 +# Find refs that actually work on your machine: ./list-models.sh +set -euo pipefail + +SEAT="" +MODEL="" +TARGET_DIR="$HOME/.zcode/agents" +FORCE=0 +while [ $# -gt 0 ]; do + case "$1" in + --workspace) TARGET_DIR="$2/.zcode/agents"; shift 2 ;; + --force) FORCE=1; shift ;; + *) if [ -z "$SEAT" ]; then SEAT="$1"; shift + elif [ -z "$MODEL" ]; then MODEL="$1"; shift + else echo "unexpected argument: $1" >&2; exit 1; fi ;; + esac +done + +if [ -z "$SEAT" ] || [ -z "$MODEL" ]; then + grep '^#' "$0" | sed 's/^# \{0,1\}//' >&2 + exit 1 +fi +if ! [[ "$SEAT" =~ ^[a-z0-9][a-z0-9-]*$ ]]; then + echo "seat-name must be lowercase letters, digits, hyphens: $SEAT" >&2 + exit 1 +fi +if ! [[ "$MODEL" == *:* ]]; then + echo "model-ref must look like custom::: $MODEL" >&2 + exit 1 +fi + +FILE="$TARGET_DIR/councillor-${SEAT}.md" +if [ -e "$FILE" ] && [ "$FORCE" -ne 1 ]; then + echo "$FILE already exists (use --force to overwrite)" >&2 + exit 1 +fi + +mkdir -p "$TARGET_DIR" +cat > "$FILE" < at project scope. If the agent is one of the plugin's +# shipped agents, the plugin file is copied out first (user/workspace copies +# take precedence over plugin agents); an existing user file is edited in +# place (backed up once to .pre-mcp.bak). +# +# Every listed server becomes a HARD spawn requirement: the agent refuses to +# start while any listed server is disconnected. Only list servers you trust +# to be up. +# +# Usage: enable-mcp.sh [--workspace ] [ ...] +# e.g.: enable-mcp.sh explorer Terraform codegraph Azure "MS Learn" Skills +set -euo pipefail + +SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)" +SRC_DIR="$SCRIPT_DIR/../oh-my-zcode-slim/agents" +TARGET_DIR="$HOME/.zcode/agents" + +ARGS=() +while [ $# -gt 0 ]; do + case "$1" in + --workspace) TARGET_DIR="$2/.zcode/agents"; shift 2 ;; + *) ARGS+=("$1"); shift ;; + esac +done +set -- "${ARGS[@]+${ARGS[@]}}" + +if [ $# -lt 2 ]; then + grep '^#' "$0" | sed 's/^# \{0,1\}//' >&2 + exit 1 +fi + +AGENT="$1"; shift +FILE="$TARGET_DIR/${AGENT}.md" + +mkdir -p "$TARGET_DIR" +if [ ! -e "$FILE" ]; then + if [ -e "$SRC_DIR/${AGENT}.md" ]; then + cp "$SRC_DIR/${AGENT}.md" "$FILE" + echo "Copied plugin agent out to $FILE" + else + echo "No such agent: not at $FILE and not shipped as $SRC_DIR/${AGENT}.md" >&2 + exit 1 + fi +else + [ -e "$FILE.pre-mcp.bak" ] || cp "$FILE" "$FILE.pre-mcp.bak" +fi + +LIST="" +for s in "$@"; do + item="$s" + case "$s" in *" "*) item="\"$s\"" ;; esac + if [ -z "$LIST" ]; then LIST="$item"; else LIST="$LIST, $item"; fi +done +LINE="mcpServers: [$LIST]" + +if grep -q '^mcpServers:' "$FILE"; then + sed -i "s|^mcpServers:.*|$LINE|" "$FILE" +else + sed -i "/^tools:/a $LINE" "$FILE" +fi + +echo "Set $LINE in $FILE" +echo "Restart your ZCode session for the change to take effect." diff --git a/plugins/oh-my-zcode-slim/scripts/list-models.sh b/plugins/oh-my-zcode-slim/scripts/list-models.sh new file mode 100755 index 0000000..384bb37 --- /dev/null +++ b/plugins/oh-my-zcode-slim/scripts/list-models.sh @@ -0,0 +1,29 @@ +#!/usr/bin/env bash +# List model refs you can pin in agent frontmatter, from ZCode's own usage +# records — these are refs that have ACTUALLY executed on this machine, which +# is the only reliable source (provider display names and model self-reports +# are not; see docs/LESSONS.md). +set -euo pipefail + +DB="$HOME/.zcode/cli/db/db.sqlite" + +echo "== Builtin refs (available to z.ai-authenticated sessions) ==" +printf ' custom:builtin%%3Azai-coding-plan:GLM-5.3\n' +printf ' custom:builtin%%3Azai-coding-plan:GLM-5.3-Flash\n' +echo + +if [ -f "$DB" ] && command -v sqlite3 >/dev/null 2>&1; then + echo "== Provider/model pairs proven on this machine (model_usage) ==" + sqlite3 "$DB" "SELECT DISTINCT provider_id, model_id FROM model_usage WHERE status='completed' ORDER BY provider_id, model_id" \ + | while IFS='|' read -r provider model; do + provider="${provider//:/%3A}" + printf ' custom:%s:%s\n' "$provider" "$model" + done + echo + echo "Notes:" + echo " - Pin format is custom::, exactly as printed." + echo " - In remote-attached sessions, custom providers materialize under UUID" + echo " provider ids, not their display names — use the UUID form printed above." +else + echo "(!) sqlite3 or $DB not found — only builtin refs can be listed." +fi diff --git a/plugins/oh-my-zcode-slim/scripts/remove-councillor.sh b/plugins/oh-my-zcode-slim/scripts/remove-councillor.sh new file mode 100755 index 0000000..aba0006 --- /dev/null +++ b/plugins/oh-my-zcode-slim/scripts/remove-councillor.sh @@ -0,0 +1,28 @@ +#!/usr/bin/env bash +# Remove a council seat agent (renames it to .removed.bak rather than deleting). +# Usage: remove-councillor.sh [--workspace ] +set -euo pipefail + +SEAT="" +TARGET_DIR="$HOME/.zcode/agents" +while [ $# -gt 0 ]; do + case "$1" in + --workspace) TARGET_DIR="$2/.zcode/agents"; shift 2 ;; + *) SEAT="$1"; shift ;; + esac +done + +if [ -z "$SEAT" ]; then + echo "usage: remove-councillor.sh [--workspace ]" >&2 + exit 1 +fi + +FILE="$TARGET_DIR/councillor-${SEAT}.md" +if [ ! -e "$FILE" ]; then + echo "not found: $FILE" >&2 + exit 1 +fi + +mv "$FILE" "$FILE.removed.bak" +echo "Removed (backed up): $FILE.removed.bak" +echo "Restart your ZCode session for the change to take effect." diff --git a/plugins/oh-my-zcode-slim/skills/clonedeps/SKILL.md b/plugins/oh-my-zcode-slim/skills/clonedeps/SKILL.md new file mode 100644 index 0000000..914edc9 --- /dev/null +++ b/plugins/oh-my-zcode-slim/skills/clonedeps/SKILL.md @@ -0,0 +1,211 @@ +--- +name: clonedeps +description: Clone important project dependency source code into an ignored local workspace so agents can inspect library internals. Use when the user asks to clone dependencies, inspect dependency/source internals, understand SDK/framework behavior from source, debug library implementation details, or make core dependency repos locally readable. Do not use for ordinary API/docs questions where @librarian is enough. +--- + +# Clonedeps Skill + +You help users make a small set of important dependency source repositories +locally readable to ZCode agents. + +This is a workflow skill, not a command wrapper. Do not use a helper script for +dependency detection, ref validation, cloning, status, or cleanup. The +orchestrator and `@librarian` do the repo-specific thinking; the orchestrator +performs the approved filesystem/git operations directly. + +## Workflow + +### Step 1: Check Existing State + +First check whether `.slim/clonedeps.json` exists. + +If it exists: + +1. Read it before asking librarian for a new plan. +2. Check whether each listed `path` exists under `.slim/clonedeps/repos/`. +3. Reuse existing cloned repos when they already satisfy the user's task. +4. Only ask librarian for new recommendations if the existing manifest is + missing, stale, or insufficient for the current task. + +Do not rescan/re-plan from scratch when the manifest already has useful entries. + +### Step 2: Ask Librarian for the Clone Plan + +Delegate dependency discovery and source resolution to `@librarian`. + +Use this prompt: + +```md +Understand this project first, then recommend remote source repos that would +help a developer work on it. + +Read enough of the current repo to understand: +- what the project does +- its main architecture +- the important integration points +- what external systems or libraries it depends on in practice + +Think like a developer trying to debug or extend this project. + +Which remote repositories, if cloned locally, would actually help understand the +codebase or solve likely implementation/debugging tasks? + +Do not make a dependency dump. Most dependencies are not worth cloning. +Recommend a repo only when its source code would be more useful than docs or the +current repo alone. + +For each recommendation, include: +- repo name +- repo URL +- suggested ref/tag/commit if known +- why cloning this source would help +- when it would be useful +- caveats + +Also include: +- current-repo files/folders to inspect first +- repos/dependencies you considered but would not clone + +Keep it small. Prefer 0–3 strong recommendations over 5 weak ones. If nothing +clearly needs cloning, say so. +``` + +Librarian should return a small plan with: + +- dependency name; +- current version/range if discoverable; +- official source repository URL; +- tag/commit/ref to check out; +- package subdirectory if the source is a monorepo; +- reason local source helps; +- caveats such as huge repo, missing tag, or uncertain version mapping. + +Prefer at most 3-5 core dependencies. Include user-mentioned dependencies and +central frameworks, SDKs, ORMs, runtime/plugin APIs, or build/runtime tools. Do +not clone tiny utilities, transitive dependencies, or dev-only tools unless they +are directly relevant to the active task. + +### Step 3: Verify and Confirm the Plan + +The orchestrator owns final approval. Before cloning: + +1. Verify refs manually where possible with `git ls-remote`. +2. Prefer pinned tags or commit SHAs. If no exact tag exists, ask librarian to + find the correct module-specific tag/commit or explain the fallback. +3. Only use HTTPS GitHub/GitLab-style repository URLs by default. Reject + `file://`, SSH URLs, local paths, URLs with embedded credentials, and private + or auth-required repositories unless the user explicitly approves that case. +4. Present the plan to the user with dependency, repo URL, ref, reason, and + caveats. +5. Ask for confirmation before network cloning unless the user explicitly asked + to clone immediately. + +### Step 4: Clone Sources Manually + +Create one folder per source repository under: + +```text +.slim/clonedeps/repos// +``` + +Derive the safe name from the repository owner/name, not from the package name. +For example, `https://github.com/opencode-ai/opencode.git` becomes +`opencode-ai__opencode`. Replace `/` with `__`, strip common `.git` suffixes, +and replace other unsafe path characters with `_`. + +If multiple packages come from the same monorepo, clone the repository once and +point each manifest entry at the same repo path with different `packagePath` +values as needed. Do not create ecosystem folders, per-package clone folders, or +per-version folders. If two different source repositories normalize to the same +safe name, disambiguate manually and record the chosen path in +`.slim/clonedeps.json`. + +Clone/fetch with normal git commands. For an existing clone, first verify that +`git remote get-url origin` matches the approved repo URL. If it does not match, +stop and ask whether to clean/reclone. + +Safe manual git pattern: + +1. `git ls-remote ` to verify the ref where practical. +2. Clone without submodules/recursive behavior. +3. Prefer shallow fetch/clone where practical. +4. Clone into a temporary directory under `.slim/clonedeps/repos/`, then move it + into the final safe-name path after checkout succeeds. +5. Remove failed temporary clones. + +Do not run dependency install/build/test scripts from cloned repositories. + +### Step 5: Write Local State + +Write `.slim/clonedeps.json` so future agents know what exists: + +```json +{ + "version": "1.0.0", + "updatedAt": "2026-09-09T00:00:00.000Z", + "dependencies": [ + { + "name": "@opencode-ai/plugin", + "resolvedVersion": "1.3.17", + "repoUrl": "https://github.com/opencode-ai/opencode.git", + "ref": "v1.3.17", + "path": ".slim/clonedeps/repos/opencode-ai__opencode", + "packagePath": "packages/plugin", + "reason": "Plugin API source used by the project" + } + ] +} +``` + +If a clone fails after earlier clones succeeded, still write state for the +successful clones so future inspection is not misleading. + +Do not add `.slim/clonedeps.json` to `.gitignore`. It is small, reviewable +project metadata that can be committed. Only the cloned repository contents +under `.slim/clonedeps/repos/` should be ignored. + +### Step 6: Update Ignore Files + +Update `.gitignore` with an idempotent marker block: + +```gitignore +# BEGIN oh-my-zcode-slim clonedeps +.slim/clonedeps/repos/ +# END oh-my-zcode-slim clonedeps +``` + +Only edit content inside these marker blocks. + +### Step 7: Register Dependency Source in AGENTS.md + +After successful cloning, update the repository root `AGENTS.md` so future +agents know why the dependency source exists and where to look. + +If `AGENTS.md` already has a `## Cloned Dependency Source` section, update that +section. Otherwise append this section: + +Use this format and list the actual repos directly. Keep each item to one short +sentence so future agents do not need an extra read just to know what is there: + +```markdown +## Cloned Dependency Source + +Read-only dependency source repositories are available under +`.slim/clonedeps/repos/` for inspection. Do not edit these clones. + +- `.slim/clonedeps/repos//` — `` at ``; . +``` + +Also keep `.slim/clonedeps.json` updated as the structured manifest, but do not +make agents read it for the basic repo list. + +## Cleanup + +When the user asks to clean cloned dependencies, remove: + +- `.slim/clonedeps/repos/` +- the managed clonedeps marker blocks from `.gitignore` + +Ask before removing `.slim/clonedeps.json` or the `AGENTS.md` section because +they may be intentional project metadata. diff --git a/plugins/oh-my-zcode-slim/skills/deepwork/SKILL.md b/plugins/oh-my-zcode-slim/skills/deepwork/SKILL.md new file mode 100644 index 0000000..905d8a6 --- /dev/null +++ b/plugins/oh-my-zcode-slim/skills/deepwork/SKILL.md @@ -0,0 +1,108 @@ +--- +name: deepwork +description: Orchestrator-only workflow for heavy coding sessions, multi-phase implementation, and risky refactors. Use for complex work that needs planning, review gates, and persistent progress tracking. +--- + +# Deepwork + +Deepwork is an orchestrator workflow for heavy coding sessions. Use it when the +work is broad, risky, multi-file, or likely to span several implementation +phases. Do not use it for trivial edits, quick docs changes, or simple bug +fixes. + +## Core Contract + +When deepwork is active, the orchestrator must manage the work as a scheduler, +not as the default implementation worker. + +Required behavior: + +- keep the ZCode todo list aligned with the active deepwork phase; +- create and maintain a local markdown progress file under `.slim/deepwork/`; +- write valuable research findings into that file as confirmed research context + when they are received and reconciled; +- draft a plan before implementation; +- ask `@oracle` to review the plan and revise it until acceptable; +- create a phased implementation/delegation plan; +- before oracle reviews, add relevant confirmed research findings and file + references to the deepwork file so oracle can review the plan or phase from + accepted context instead of redoing discovery; +- ask `@oracle` to review that implementation plan before execution; +- after oracle review and before each implementation phase, decide the execution + path: what can run in parallel, what must be sequential, which specialists to + delegate to, and whether to split the same agent into multiple bounded lanes; +- after each phase, validate, update the deepwork file, prepare the plan file + for oracle review and ask `@oracle` to review the phase result, fix + actionable issues, then continue; +- when a phase includes `@designer`, preserve designer intent across later + phases. Use `@coder` only for mechanical follow-up that does not alter the + UI/UX; +- finish with final validation and a concise summary. + +## Designer Handoff Guardrail + +When a deepwork phase includes `@designer`, treat the delivered UI/UX as +accepted design intent for later phases. Record any important design decisions +in the deepwork file before continuing. + +After designer work: + +- preserve layout, rhythm, hierarchy, motion, spacing, color, affordances, + responsiveness, and component feel; +- review and improve user-facing copy with grounded, normal wording, but do not + change visual structure or interaction intent; +- route follow-up visual, responsive, motion, hierarchy, polish, or + component-feel changes back to `@designer`; +- use `@coder` only for bounded mechanical follow-up that preserves the design + exactly, such as wiring, tests, type fixes, or non-visual behavior changes; +- if design intent must change, record why in the deepwork file before changing + it. + +## Deepwork File + +Create a task-specific file such as: + +```text +.slim/deepwork/.md +``` + +Keep `.slim/deepwork/` out of git. Ensure the project ignore files include: + +```gitignore +# .gitignore +.slim/deepwork/ +``` + +Do not follow a rigid template. Choose whatever markdown structure best fits the +work. The file only needs to remain useful as persistent session state and +should capture, as applicable: + +- current goal and understanding; +- researched, factual context from `@librarian` to avoid oracle doing its own + research; +- plan drafts and oracle review notes; +- implementation phases and status; +- validation results; +- unresolved questions, blockers, and follow-ups. + +Update this file after major decisions, valuable specialist research, reviews, +phase completions, validation results, and scope changes. +When `@librarian` docs, code reads, or external references produce useful +information, reconcile the result and record the accepted findings here so later +planning and reviews share the same context instead of rediscovering it. +Don't put actual contents of local files, reference them by path only. + +## Scheduler Discipline + +Use the scheduler model throughout: + +- follow the orchestrator delegation rules; +- record task/session IDs and ownership boundaries; +- dispatch long-running specialist lanes with `run_in_background: true` and + collect their results with `TaskOutput` when the completion notification + arrives; cancel stale lanes with `TaskStop`; +- avoid blocking the orchestrator lane while background jobs run; if no + independent work remains, end the turn and let the background-completion + notification resume the workflow; +- do not advance to the next phase while relevant jobs are running or terminal + results are unreconciled. diff --git a/plugins/oh-my-zcode-slim/skills/reflect/SKILL.md b/plugins/oh-my-zcode-slim/skills/reflect/SKILL.md new file mode 100644 index 0000000..8dbee97 --- /dev/null +++ b/plugins/oh-my-zcode-slim/skills/reflect/SKILL.md @@ -0,0 +1,197 @@ +--- +name: reflect +description: Review recent work, find repeated workflow patterns, and suggest reusable skills, agents, commands, config changes, or playbooks. Use when the user asks to learn from past sessions, improve recurring workflows, or identify what should be turned into reusable agent instructions. +--- + +# Reflect + +Reflect is an orchestrator-only workflow for learning from repeated work. It +looks back over recent sessions, project notes, and existing agent assets, then +recommends the smallest useful improvement: a skill, custom agent, command, +configuration change, prompt rule, documentation playbook, or no change. + +The goal is to identify real repeated friction and suggest practical +improvements with evidence. + +## When to Use + +Use Reflect when the user asks to: + +- run `/reflect` or `/reflect `; +- learn from recent sessions or repeated workflows; +- find work they keep doing manually; +- improve their oh-my-zcode-slim setup based on actual usage; +- review whether a recurring process should become a reusable playbook; +- turn repeated workflow friction into a safer future default. + +Do not use Reflect for ordinary implementation work, one-off debugging, broad +architecture review, or speculative agent creation without workflow evidence. + +## Core Contract + +Reflect must be conservative and evidence-driven. + +Required behavior: + +- inspect existing assets before suggesting new ones; +- prefer recent, repeated, user-visible friction over isolated incidents; +- recommend the smallest useful form; +- treat "create nothing" as a successful result when evidence is weak; +- ask before changing prompts, skills, commands, agents, MCP access, or config; +- avoid duplicating existing assets; +- explain restart requirements for ZCode config, prompt, agent, skill, MCP, or + plugin changes. + +## Evidence Sources + +Use available evidence in this order: + +1. Current conversation and explicit user instructions. +2. Project-local guidance and memories, such as `AGENTS.md`, `.zcode/`, + `.slim/`, notes, checkpoints, task progress files, and the ZCode project + memories directory. +3. Existing ZCode assets: installed skills, commands, and agents (user scope + under `~/.zcode/`, plugin scope, and workspace `.zcode/` directories), plus + the oh-my-zcode-slim plugin contents. +4. Recent ZCode session artifacts if they are available and safe to inspect, + such as the rollout logs under `~/.zcode/cli/rollout/*.jsonl`. Keep this + light: sample recent sessions rather than exhaustive mining. +5. External docs only when a proposed workflow depends on a third-party tool or + library whose behavior needs confirmation. + +Respect privacy and safety boundaries. Do not inspect unrelated personal files, +credentials, private messages, or external accounts unless the user explicitly +asks and the workflow requires it. + +## Workflow + +Reflect can be triggered directly: + +```text +/reflect +/reflect release workflow and checks +``` + +With no arguments, review recent work broadly. With arguments, focus the review +on that workflow area while still checking whether existing assets already cover +it. + +### 1. Inventory Existing Assets + +Before proposing anything, identify what already exists: + +- installed skills (user, workspace, and plugin scope); +- custom agents and their routing descriptions; +- custom commands; +- MCP server configuration and per-agent MCP access; +- project playbooks, docs, and local workflow notes. + +If an existing asset already covers the candidate, recommend extending or using +that asset instead of creating a near-duplicate. + +### 2. Find Repeated Workflow Patterns + +Look for repeated signals such as: + +- the same command sequence appears across sessions; +- the user repeatedly asks for the same review, setup, release, or debugging + process; +- the same manual research or context-gathering steps keep recurring; +- the same specialist routing decision is repeatedly needed; +- the same project-specific rule is repeatedly re-explained; +- repeated failures happen because an agent lacks a stable instruction, tool, + or permission boundary. + +Strong candidates usually have at least two occurrences, stable inputs, a clear +output, and a clear stopping condition. + +### 3. Score Candidates + +For each candidate, decide: + +- **Frequency:** How often has it happened? +- **Cost:** Does it waste meaningful time, context, money, or attention? +- **Risk:** Does inconsistent execution cause bugs, regressions, bad decisions, + or unsafe changes? +- **Stability:** Are the inputs and desired output predictable? +- **Coverage:** Is there already an asset that handles it well? + +Only recommend creating or changing assets when confidence is high. + +### 4. Choose the Smallest Useful Form + +Pick the least powerful form that solves the repeated problem: + +- **Prompt/config rule:** a small behavior change to an existing agent. +- **Skill:** reusable workflow guidance for a task shape. +- **Command:** a repeatable manual trigger with stable inputs. +- **Custom agent:** a distinct specialist lane with clear delegation rules. +- **MCP/tool permission change:** a safe access adjustment for an existing + agent. +- **Project playbook/doc:** human-readable process guidance when automation is + too heavy. +- **Skip:** weak, one-off, ambiguous, sensitive, or already-covered work. + +Avoid creating custom agents when a prompt rule or skill is enough. Avoid +skills when a short project playbook is enough. Avoid config changes when the +benefit is unclear. + +### 5. Propose Before Changing + +Unless the user explicitly requested a specific edit, present a concise +proposal before writing files or changing config: + +```text +Found 2 strong repeated workflows and 1 weak candidate. + +Recommended: +- Add a small orchestrator prompt rule for because . +- Extend existing instead of creating a new one because . + +Skip: +- because it only appeared once. + +Proceed with the proposed edits? +``` + +When applying changes, preserve existing user settings and prefer narrow, +append-only edits. + +## Output Format + +Return a compact report: + +```text +Findings +- : evidence, frequency/confidence, recommended form. + +Recommended changes +- : one-line purpose and why this is the smallest useful form. + +Skipped +- : why not worth packaging now. + +Needs more evidence +- : what would make it actionable. +``` + +If nothing qualifies, say: + +```text +No strong repeated workflow found. I would not add or change any reusable assets +yet. +``` + +## Guardrails + +- Do not manufacture assets to justify the workflow. +- Do not create overlapping skills or agents. +- Do not silently change global config, prompts, or permissions. +- Do not add broad instructions that make agents more eager, expensive, or + invasive without a clear benefit. +- Do not overfit to a single session unless the user explicitly asks for that + exact reusable workflow. +- Do not use private or sensitive material as examples in generated assets. +- When config, prompt, agent, skill, MCP, or plugin files change, tell the user: + "This should apply on the next session; restart ZCode if you need it + immediately." diff --git a/plugins/oh-my-zcode-slim/skills/simplify/SKILL.md b/plugins/oh-my-zcode-slim/skills/simplify/SKILL.md new file mode 100644 index 0000000..b53445d --- /dev/null +++ b/plugins/oh-my-zcode-slim/skills/simplify/SKILL.md @@ -0,0 +1,131 @@ +--- +name: simplify +description: Simplifies code for clarity without changing behavior. Use for readability, maintainability, and complexity reduction after behavior is understood. Mounted on the oracle agent by default. +--- + +# Code Simplification + +## Overview + +Simplify code by reducing complexity while preserving exact behavior. The goal is not fewer lines — it's code that is easier to read, understand, modify, and debug. Every simplification must pass a simple test: "Would a new team member understand this faster than the original?" + +## When to Use + +- After a feature is working and tests pass, but the implementation feels heavier than it needs to be +- During code review when readability or complexity issues are flagged +- When you encounter deeply nested logic, long functions, or unclear names +- When refactoring code written under time pressure +- When consolidating related logic scattered across files +- After merging changes that introduced duplication or inconsistency + +**When NOT to use:** + +- Code is already clean and readable — don't simplify for the sake of it +- You don't understand what the code does yet — comprehend before you simplify +- The code is performance-critical and the "simpler" version would be measurably slower +- You're about to rewrite the module entirely — simplifying throwaway code wastes effort + +## The Five Principles + +### 1. Preserve Behavior Exactly + +Don't change what the code does — only how it expresses it. All inputs, outputs, side effects, error behavior, and edge cases must remain identical. If you're not sure a simplification preserves behavior, don't make it. + +Before every change, ask: + +- Does this produce the same output for every input? +- Does this maintain the same error behavior? +- Does this preserve the same side effects and ordering? +- Do all existing tests still pass without modification? + +### 2. Follow Project Conventions + +Simplification means making code more consistent with the codebase, not imposing external preferences. + +Before simplifying: + +1. Read `AGENTS.md` / project conventions +2. Study how neighboring code handles similar patterns +3. Match the project's style for imports, naming, function style, error handling, and type annotations + +Simplification that breaks project consistency is not simplification — it's churn. + +### 3. Prefer Clarity Over Cleverness + +Explicit code is better than compact code when the compact version requires a mental pause to parse. + +- Replace nested ternaries with readable control flow +- Replace dense inline transforms with named intermediate steps when they clarify intent +- Keep helpful names even if they cost a few extra lines + +### 4. Maintain Balance + +Watch for over-simplification: + +- Don't inline away names that carry meaning +- Don't merge unrelated logic into one larger function +- Don't remove abstractions that serve testability or extensibility +- Don't optimize for line count over comprehension + +### 5. Scope to What Changed + +Default to simplifying recently modified code. Avoid unrelated drive-by refactors unless explicitly asked. + +## Process + +### Step 1: Understand Before Touching + +Before changing or removing anything, understand why it exists. + +Answer: + +- What is this code's responsibility? +- What calls it? What does it call? +- What are the edge cases and error paths? +- Are there tests that define expected behavior? +- Why might it have been written this way? + +If you can't answer these, read more context first. + +### Step 2: Look for Simplification Opportunities + +Signals: + +- Deep nesting +- Long functions with mixed responsibilities +- Nested ternaries +- Boolean flag arguments +- Repeated conditionals +- Generic or misleading names +- Duplicated logic +- Dead code +- Wrappers or abstractions that add no value + +### Step 3: Apply Changes Incrementally + +Make one simplification at a time. + +For each simplification: + +1. Make the change +2. Run relevant tests +3. Keep it only if behavior is preserved + +Separate refactoring from feature work whenever possible. + +### Step 4: Verify the Result + +After simplifying, confirm: + +- The code is genuinely easier to understand +- The diff is clean and reviewable +- Project conventions still match +- No behavior, error handling, or side effects changed + +## Verification Checklist + +- [ ] Existing tests pass without modification +- [ ] Build/typecheck/lint still pass +- [ ] No unrelated files were refactored +- [ ] No error handling was weakened or removed +- [ ] The result is simpler to review than the original diff --git a/plugins/oh-my-zcode-slim/skills/verification-planning/SKILL.md b/plugins/oh-my-zcode-slim/skills/verification-planning/SKILL.md new file mode 100644 index 0000000..129cfd3 --- /dev/null +++ b/plugins/oh-my-zcode-slim/skills/verification-planning/SKILL.md @@ -0,0 +1,111 @@ +--- +name: verification-planning +description: Verification planning for non-trivial coding work. Use before implementing a feature, bug fix, refactor, cross-system change, or high-confidence behavior change that needs a credible project-specific evidence path. +--- + +# Verification Planning + +## Build an evidence path + +Before changing a non-trivial system, build an **evidence path**: a +project-specific route from the claim being made to evidence that can establish, +limit, or refute it. + +The purpose is not to select a familiar technique. The purpose is to decide how +this system can reveal the truth of this particular change. + +## 1. Frame the claim + +State the behavior that needs to become true and the conditions that could make +a confident conclusion wrong. + +Consider what must change, what must remain true, where the behavior crosses a +boundary, and which failure would matter most. + +**Complete when:** the claim, its meaningful uncertainty, and its important +failure modes are concrete enough to investigate. + +## 2. Design the evidence path + +Derive possible evidence paths from the system itself: its controllable inputs, +observable effects, state transitions, invariants, boundaries, artifacts, and +ability to repeat or reverse a scenario. + +Generate alternatives before choosing. Prefer the path that produces a +trustworthy conclusion with proportionate cost, safety, and effort. + +**Complete when:** there is a preferred path, its limitations are understood, +and a weaker or stronger alternative is available if circumstances change. + +## Set a verification budget + +At the final state, state the distinct claims, assign one owner to establish or +refute each, and choose the minimum non-duplicative evidence that covers the +claims and important boundaries. Reuse evidence only while its relevant code, +inputs, environment, and state remain valid. Required repository and release +checks still apply; broaden or repeat verification only when a stated condition +justifies it. + +## 3. Create a verification affordance when needed + +When the existing system leaves the decisive truth too indirect or ambiguous, +extend the evidence path with a **verification affordance**: the smallest +capability that makes the relevant state controllable, observable, repeatable, +and diagnosable for an agent. + +Ask what capability would let an agent establish the claim directly, repeat the +scenario from a known state, and explain a failure without inference. Prefer an +affordance that strengthens directness, determinism, agent-legibility, +isolation, resetability, or future reuse. + +Treat the affordance as part of the evidence path, not an automatic product +feature. Decide deliberately whether it is temporary or durable before building +it. + +**Complete when:** the chosen path can establish the claim directly enough for +its stakes, and any needed affordance has a defined lifecycle. + +## 4. Research when the path is unknown + +When the right evidence path depends on an unfamiliar dependency, framework, +external service, or rapidly changing capability, ask `@librarian` for focused +research before committing to an approach. + +Ask for official or project-specific facilities, constraints, and trade-offs +that affect this exact verification problem. Use existing project evidence +directly when it already resolves the choice. + +**Complete when:** the chosen path rests on known capabilities and real +constraints rather than assumption. + +## 5. Make the path runnable + +Prepare only the support needed to follow the evidence path reliably. Keep the +support narrow, repeatable, and safe to inspect. + +Decide whether that support has recurring value or exists only to resolve the +current uncertainty. Retain durable value deliberately; remove temporary +support once it has served its purpose. + +Ask before introducing dependencies, persistent diagnostic surfaces, or +structural changes whose sole purpose is evidence gathering. + +**Complete when:** the path can be followed without guessing about setup, +state, or interpretation. + +## 6. Close the evidence path + +After implementation, follow the planned path and interpret the resulting +evidence against the original claim. + +Report whether the claim was established, limited, or refuted; distinguish +known facts from remaining uncertainty. + +**Complete when:** a future reader can see what supports the conclusion and +what remains outside its reach. + +## Scope + +Use this skill proportionately. Small mechanical changes can follow ordinary +project checks directly. For larger multi-phase work, let this skill establish +the evidence path that later work follows. diff --git a/plugins/oh-my-zcode-slim/skills/worktrees/SKILL.md b/plugins/oh-my-zcode-slim/skills/worktrees/SKILL.md new file mode 100644 index 0000000..bf0b987 --- /dev/null +++ b/plugins/oh-my-zcode-slim/skills/worktrees/SKILL.md @@ -0,0 +1,161 @@ +--- +name: worktrees +description: Manage Git worktrees as safe isolated coding lanes for complex, risky, or parallel work. +--- + +# Worktrees Orchestration Protocol + +The `worktrees` skill provides an opinionated, safe orchestration protocol for +managing Git worktrees as isolated coding lanes. Its value is giving the +orchestrator a consistent workflow for parallel agents, risky experiments, +integration review, and cleanup. + +## Core Contract + +This is an **orchestrator-only** workflow. Other specialists such as `@coder` +or `@designer` can be assigned tasks inside a worktree lane, but the +orchestrator owns lane planning, branch/path selection, file ownership, +delegation, diff validation, integration, and cleanup. + +All worktrees reside under the default path: + +```text +.slim/worktrees// +``` + +Do not create worktrees as sibling directories of the main repository. + +### State Tracking (`.slim/worktrees.json`) + +Use the optional local metadata manifest `.slim/worktrees.json` to maintain +structural tracking: + +```json +{ + "version": "1.0.0", + "updatedAt": "2026-09-09T00:00:00.000Z", + "lanes": [ + { + "slug": "feature-auth-v2", + "branch": "omzs/feature-auth-v2", + "path": ".slim/worktrees/feature-auth-v2", + "base": "main", + "purpose": "refactor authentication flow to use OAuth2", + "owner": "orchestrator", + "status": "active", + "areas": ["src/auth", "src/config"], + "createdAt": "2026-09-09T12:00:00.000Z" + } + ] +} +``` + +If `.slim/worktrees.json` does not exist, create it when initializing a lane, +and keep it updated as lanes are transitioned, integrated, or pruned. Treat it +as local workflow metadata by default; ask before making it part of a committed +project convention. + +--- + +## Safety Guidelines + +Before executing any Git mutation command, the orchestrator must observe the +following guards: + +### 1. Pre-Flight Checklist +- Confirm the current directory is inside a Git repository. +- Check the current branch, base branch, and dirty/uncommitted state. +- Inspect the output of `git worktree list` to avoid path or branch conflicts. +- Ensure the branch name (e.g. `omzs/` or custom project convention) does + not already exist locally or on remote. +- Ensure `.slim/worktrees/` is ignored by Git before creating nested worktrees. + +### 2. Mandatory User Confirmation +You must seek explicit user confirmation before executing: +- `git worktree add` or `git worktree remove` +- Branch creation, deletion, or renaming +- Merges, rebases, or cherry-picks +- `git prune` or `git worktree prune` +- Destructive commands (e.g., `git reset --hard`, `git clean`, `git push + --force`, or removing a dirty worktree directory). + +Never execute destructive commands, delete branches, remove dirty worktrees, or +clean uncommitted changes without explicit user confirmation for that exact +operation. + +### 3. Ignore File Setup + +Before creating lanes, add or update the managed marker block in `.gitignore` +only: + +```gitignore +# BEGIN oh-my-zcode-slim worktrees +.slim/worktrees/ +.slim/worktrees.json +# END oh-my-zcode-slim worktrees +``` + +--- + +## Workflow Guide + +### Phase 1: Planning & Setup +1. Identify the task scope and determine a short `` for the worktree. +2. Formulate a branch name. Default to `omzs/` unless project/user + conventions dictate otherwise. +3. Validate repository safety. Ask the user for confirmation to initialize the + lane. +4. Ensure the managed ignore block is present. +5. Run: + ```bash + git worktree add -b .slim/worktrees/ + ``` +6. Register the metadata in `.slim/worktrees.json`. + +### Phase 2: Execution & Delegation +1. Instruct all sub-agents to operate strictly on absolute paths inside the + worktree lane (`.slim/worktrees//...`). Do not modify the main + checkout for lane work. Keep build, test, and edit operations isolated + inside the lane. +2. Track file or folder ownership per lane to avoid merge conflicts between + parallel agents. +3. Commit progress within the worktree only when the user asked for commits or + approved local checkpoint commits. + +### Phase 3: Integration & Validation +Before merging or integrating the worktree branch: +1. Run lint, build, formatting, and unit tests inside the worktree directory. +2. Generate and display a clear diff comparing the worktree branch to the + integration base branch. +3. Ask the user for confirmation to integrate. +4. Perform the approved integration, such as merge or cherry-pick, from the main + checkout or the user-approved integration checkout. + +### Phase 4: Cleanup & Pruning +1. Ensure all changes are safely merged or archived. +2. Confirm the worktree has no uncommitted changes. +3. Request user approval to remove the worktree. +4. Safely remove the worktree using: + ```bash + git worktree remove .slim/worktrees/ + ``` +5. Update `.slim/worktrees.json` to mark the lane as `archived` or remove it. + +--- + +## When to Use vs. Not Use + +### Use When: +- Performing risky or destructive refactoring that could break the active + working environment. +- Working on parallel tasks/bugfixes that require switching contexts without + committing half-finished work. +- Running independent background agents on separate branches. +- Conducting exploratory spikes or prototyping that may be discarded. +- Isolating third-party packages or complex upgrades. +- Explicitly asked to use worktrees for a specific task. + +### Do NOT Use When: +- Making simple single-file changes, documentation updates, or minor bug fixes. +- Working in a directory that is not a fully initialized git repository or has + complex multi-submodule states not supported easily by worktrees.