john/claude-engineering-plugin
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

refactor(install): prefer native plugin install across targets (#609)
Some checks failed
CI / pr-title (push) Has been cancelled
Details
CI / test (push) Has been cancelled
Details
Release PR / release-pr (push) Has been cancelled
Details
Release PR / publish-cli (push) Has been cancelled
Details

Browse Source 
Co-authored-by: John Cavanaugh <cavanaug@users.noreply.github.com>
This commit is contained in:
Trevin Chow
2026-04-20 18:47:07 -07:00
committed by GitHub
parent 9497a00d90
commit c2d60b47be
104 changed files with 7073 additions and 7068 deletions
Download Patch File Download Diff File Expand all files Collapse all files

25
docs/specs/codex.md
View File

@@ -1,6 +1,6 @@
# Codex Spec (Config, Prompts, Skills, MCP)
# Codex Spec (Config, Prompts, Skills, Subagents, MCP)
Last verified: 2026-01-21
Last verified: 2026-04-19
## Primary sources
@@ -10,6 +10,7 @@ https://developers.openai.com/codex/config-advanced
https://developers.openai.com/codex/custom-prompts
https://developers.openai.com/codex/skills
https://developers.openai.com/codex/skills/create-skill
https://developers.openai.com/codex/subagents
https://developers.openai.com/codex/guides/agents-md
https://developers.openai.com/codex/mcp
```
@@ -49,10 +50,28 @@ https://developers.openai.com/codex/mcp
- Required fields are single-line with length limits (name ≤ 100 chars, description ≤ 500 chars). citeturn3view4
- At startup, Codex loads only each skill’s name/description; full content is injected when invoked. citeturn3view3turn3view4
- Skills can be repo-scoped in `.agents/skills/` and are discovered from the current working directory up to the repository root. User-scoped skills live in `~/.agents/skills/`. citeturn1view1turn1view4
- Inference: some existing tooling and user setups still use `.codex/skills/` and `~/.codex/skills/` as legacy compatibility paths, but those locations are not documented in the current OpenAI Codex skills docs linked above.
- Inference: some existing tooling and user setups still use `.codex/skills/` and `~/.codex/skills/` as compatibility paths, but those locations are not documented in the current OpenAI Codex skills docs linked above.
- Compound Engineering should avoid `~/.agents/skills` for managed installs because that shared root can shadow Copilot's native plugin skills. Use the Codex-specific compatibility root `~/.codex/skills/compound-engineering/<skill-name>/SKILL.md` for CE Codex skills, and track generated files with a CE manifest.
- Codex also supports admin-scoped skills in `/etc/codex/skills` plus built-in system skills bundled with Codex. citeturn1view4
- Skills can be invoked explicitly using `/skills` or `$skill-name`. citeturn3view3
## Subagents and custom agents
- Codex subagent workflows are enabled by default in current releases.
- Codex only spawns subagents when explicitly asked.
- Custom agent files are standalone TOML files under `~/.codex/agents/` for personal agents or `.codex/agents/` for project-scoped agents.
- Each TOML file defines one custom agent. Required fields:
- `name`
- `description`
- `developer_instructions`
- Optional fields can include `nickname_candidates`, `model`, `model_reasoning_effort`, `sandbox_mode`, `mcp_servers`, and `skills.config`.
- The TOML `name` field is the source of truth; matching the filename to the agent name is only a convention.
- CE converts Claude Markdown agents into Codex custom-agent TOML files under `~/.codex/agents/compound-engineering/`.
- CE keeps generated agents under `~/.codex/agents`, not `~/.agents/skills`, because `~/.agents` is shared across harnesses and can shadow native plugin installs.
- Generated TOML agent names preserve CE's hyphenated naming and include the source category, such as `review-ce-correctness-reviewer` and `research-ce-repo-research-analyst`.
- Empirical test on 2026-04-19 confirmed Codex discovers nested custom-agent TOML files under `~/.codex/agents/compound-engineering/` and accepts hyphenated TOML `name` values.
- Empirical plugin test on 2026-04-19 found Codex native plugins did not register custom agents bundled under plugin-local `agents/`, plugin-local `.codex/agents/`, or an undocumented plugin manifest `agents` field. Therefore CE still needs the custom Bun Codex installer for agent-heavy workflows.
## MCP (Model Context Protocol)
- MCP configuration lives in `~/.codex/config.toml` and is shared by the CLI and IDE extension. citeturn3view2turn3view5

56
docs/specs/copilot.md
View File

@@ -1,10 +1,14 @@
# GitHub Copilot Spec (Agents, Skills, MCP)
Last verified: 2026-02-14
Last verified: 2026-04-18
## Primary sources
```
https://docs.github.com/en/copilot/how-tos/copilot-cli/customize-copilot/create-custom-agents-for-cli
https://docs.github.com/en/copilot/reference/copilot-cli-reference/cli-command-reference
https://docs.github.com/en/copilot/reference/copilot-cli-reference/cli-plugin-reference
https://docs.github.com/en/copilot/concepts/agents/copilot-cli/about-cli-plugins
https://docs.github.com/en/copilot/reference/custom-agents-configuration
https://docs.github.com/en/copilot/concepts/agents/about-agent-skills
https://docs.github.com/en/copilot/concepts/agents/coding-agent/mcp-and-coding-agent
@@ -15,19 +19,50 @@ https://docs.github.com/en/copilot/concepts/agents/coding-agent/mcp-and-coding-a
| Scope | Path |
|-------|------|
| Project agents | `.github/agents/*.agent.md` |
| Project agents (Claude-compatible) | `.claude/agents/*.md` |
| Personal agents | `~/.copilot/agents/*.agent.md` |
| Personal agents (Claude-compatible) | `~/.claude/agents/*.md` |
| Plugin agents | `agents/` by default, overridable in plugin manifest |
| Project skills | `.github/skills/*/SKILL.md` |
| Project skills (auto-discovery) | `.agents/skills/*/SKILL.md` |
| Project instructions | `.github/copilot-instructions.md` |
| Path-specific instructions | `.github/instructions/*.instructions.md` |
| Project prompts | `.github/prompts/*.prompt.md` |
| Org/enterprise agents | `.github-private/agents/*.agent.md` |
| Personal skills | `~/.copilot/skills/*/SKILL.md` |
| Personal skills (auto-discovery) | `~/.agents/skills/*/SKILL.md` |
| Directory instructions | `AGENTS.md` (nearest ancestor wins) |
## Agents (.agent.md files)
- Custom agents are Markdown files with YAML frontmatter stored in `.github/agents/`.
- File extension is `.agent.md` (or `.md`). Filenames may only contain: `.`, `-`, `_`, `a-z`, `A-Z`, `0-9`.
- The documented custom-agent extension is singular `.agent.md`, not `.agents.md`.
- `description` is the only required frontmatter field.
- Current Copilot CLI docs do not list `.agents/agents` or `~/.agents/agents` as custom-agent discovery paths. The `.agents/*` convention is documented for skills (`.agents/skills`, `~/.agents/skills`), not agents.
- Copilot CLI also loads Claude-compatible agent directories (`.claude/agents`, `~/.claude/agents`) after native Copilot agent directories and before plugin agents.
- `AGENTS.md` files are supported as custom instruction/context files, not as custom-agent profile files.
## Plugins
- Copilot CLI plugins bundle reusable agents, skills, hooks, MCP servers, and related configuration.
- Install from a registered marketplace with:
```text
/plugin marketplace add EveryInc/compound-engineering-plugin
/plugin install compound-engineering@compound-engineering-plugin
```
- The terminal equivalents are:
```bash
copilot plugin marketplace add EveryInc/compound-engineering-plugin
copilot plugin install compound-engineering@compound-engineering-plugin
```
- Copilot CLI looks for plugin manifests at `.plugin/plugin.json`, `plugin.json`, `.github/plugin/plugin.json`, or `.claude-plugin/plugin.json`.
- Copilot CLI looks for marketplace manifests at `marketplace.json`, `.plugin/marketplace.json`, `.github/plugin/marketplace.json`, or `.claude-plugin/marketplace.json`.
- Therefore the existing repository-level `.claude-plugin/marketplace.json` and plugin-level `plugins/compound-engineering/.claude-plugin/plugin.json` are expected to be sufficient for Copilot native plugin install. Do not add a parallel `.github/plugin` surface unless Copilot requires a Copilot-only manifest field in the future.
### Frontmatter fields
@@ -72,6 +107,7 @@ Agent body content is limited to **30,000 characters**.
| Project (Claude-compatible) | `.claude/skills/*/SKILL.md` |
| Project (auto-discovery) | `.agents/skills/*/SKILL.md` |
| Personal | `~/.copilot/skills/*/SKILL.md` |
| Personal (auto-discovery) | `~/.agents/skills/*/SKILL.md` |
## MCP (Model Context Protocol)
@@ -115,8 +151,20 @@ Agent body content is limited to **30,000 characters**.
## Precedence
1. Repository-level agents
2. Organization-level agents (`.github-private`)
3. Enterprise-level agents (`.github-private`)
1. Built-in agents
2. `~/.copilot/agents`
3. `<project>/.github/agents`
4. `<parents>/.github/agents`
5. `~/.claude/agents`
6. `<project>/.claude/agents`
7. `<parents>/.claude/agents`
8. Plugin `agents/` directories
9. Remote organization/enterprise agents
Within a repo, `AGENTS.md` files in directories provide nearest-ancestor-wins instructions.
Skills use separate first-found-wins precedence. Current docs list project `.github/skills`, `.agents/skills`, `.claude/skills`, inherited project skills, personal `~/.copilot/skills`, personal `~/.agents/skills`, personal `~/.claude/skills`, then plugin skill directories.
Skills are deduplicated by the `name` field inside `SKILL.md`, not by directory name. If a personal or project skill has the same `name` as a plugin skill, Copilot uses the first-loaded personal/project skill and silently ignores the plugin skill. For example, a stale `~/.agents/skills/ce-plan/SKILL.md` with `name: ce-plan` would shadow the native plugin's `ce-plan`; it should not show as two separate skills in Copilot CLI. Use `/skills info ce-plan` to confirm which location won.
This makes Copilot cleanup different from Codex duplicate cleanup: stale CE skills in `~/.agents/skills`, `~/.copilot/skills`, `.agents/skills`, or `.github/skills` may not create visible duplicates, but they can silently override newer plugin-provided CE skills.

23
docs/specs/cursor.md
View File

@@ -1,4 +1,4 @@
# Cursor Spec (Rules, Commands, Skills, MCP)
# Cursor Spec (Plugin Marketplace, Rules, Commands, Skills, MCP)
Last verified: 2026-02-12
@@ -10,6 +10,27 @@ https://docs.cursor.com/context/rules-for-ai
https://docs.cursor.com/customize/model-context-protocol
```
## Plugin Marketplace
Compound Engineering is published through the Cursor Plugin Marketplace.
In Cursor Agent chat, install with:
```text
/add-plugin compound-engineering
```
Users can also search for "compound engineering" in the plugin marketplace.
The repo-owned marketplace files are:
```text
.cursor-plugin/marketplace.json
plugins/compound-engineering/.cursor-plugin/plugin.json
```
Do not use the old custom Bun converter/install path for Cursor.
## Config locations
| Scope | Path |

184
docs/specs/gemini.md
View File

@@ -1,6 +1,6 @@
# Gemini CLI Spec (GEMINI.md, Commands, Skills, MCP, Settings)
# Gemini CLI Spec (GEMINI.md, Commands, Skills, Subagents, Extensions)
Last verified: 2026-02-14
Last verified: 2026-04-18
## Primary sources
@@ -10,7 +10,9 @@ https://geminicli.com/docs/get-started/configuration/
https://geminicli.com/docs/cli/custom-commands/
https://geminicli.com/docs/cli/skills/
https://geminicli.com/docs/cli/creating-skills/
https://geminicli.com/docs/extensions/writing-extensions/
https://geminicli.com/docs/core/subagents/
https://geminicli.com/docs/extensions/reference/
https://developers.googleblog.com/subagents-have-arrived-in-gemini-cli/
https://google-gemini.github.io/gemini-cli/docs/tools/mcp-server.html
```
@@ -53,7 +55,10 @@ User request: {{args}}
## Skills (SKILL.md standard)
- A skill is a folder containing `SKILL.md` plus optional supporting files.
- Skills live in `.gemini/skills/`.
- Workspace skills live in `.gemini/skills/` or the `.agents/skills/` alias.
- User skills live in `~/.gemini/skills/` or the `~/.agents/skills/` alias.
- Extension skills live in an installed extension's `skills/` directory.
- Compound Engineering managed Gemini installs should use Gemini-owned roots (`~/.gemini/skills`, `~/.gemini/agents`, `~/.gemini/commands`) rather than `~/.agents/skills`, because `~/.agents/skills` can shadow Copilot plugin skills.
- `SKILL.md` uses YAML frontmatter with `name` and `description` fields.
- Gemini activates skills on demand via `activate_skill` tool based on description matching.
- The `description` field is critical — Gemini uses it to decide when to activate the skill.
@@ -71,6 +76,34 @@ description: Review code for security vulnerabilities and OWASP compliance
Detailed instructions for security review...
```
## Subagents
- Gemini CLI supports custom subagents as Markdown files with YAML frontmatter.
- Project subagents live in `.gemini/agents/*.md`.
- User subagents live in `~/.gemini/agents/*.md`.
- Extension subagents live in an installed extension's `agents/*.md` directory.
- Current Gemini docs, `/agents reload` command text, and Gemini CLI 0.38.2 implementation name only `.gemini/agents` and `~/.gemini/agents` for local subagent discovery. The `.agents/skills` and `~/.agents/skills` aliases apply to skills; Gemini does not currently read `~/.agents/agents` or `.agents/agents` as subagent discovery paths.
- Subagents can be invoked explicitly with `@agent-name` or selected automatically by description.
- Subagents run in isolated context loops and can have restricted tool access.
- Subagents cannot call other subagents, even if granted wildcard tool access.
Example:
```yaml
---
name: security-auditor
description: Specialized in finding security vulnerabilities in code.
kind: local
tools:
- read_file
- grep_search
model: inherit
max_turns: 10
---
You are a ruthless Security Auditor.
```
## MCP server configuration
- MCP servers are configured in `settings.json` under the `mcpServers` key.
@@ -103,8 +136,147 @@ Detailed instructions for security review...
## Extensions
- Extensions are distributable packages for Gemini CLI.
- They extend functionality with custom tools, hooks, and commands.
- Not used for plugin conversion (different purpose from Claude Code plugins).
- Install with `gemini extensions install <github-url-or-local-path>`.
- Unlike `gemini skills install`, current Gemini extension docs and local `gemini extensions install --help` output do not list a `--path` flag for installing an extension from a monorepo subdirectory.
- Remote extension installs are not local-only. Gemini supports Git repository distribution and GitHub Releases.
- For public gallery discovery and normal remote install, `gemini-extension.json` must be at the absolute root of the GitHub repository or release archive.
- Gemini CLI copies installed extensions under `~/.gemini/extensions`.
- `gemini extensions link <path>` creates a symlink for local development instead of copying the extension.
- Extension management commands run from the shell, not inside Gemini's interactive mode. Restart the Gemini session after install/update for commands and extension changes to take effect.
- Extensions can bundle commands, skills, subagents, hooks, MCP servers, context files, policies, settings, and themes.
- Every extension root must contain `gemini-extension.json`.
- Extension commands live in `commands/*.toml`.
- Extension skills live in `skills/<name>/SKILL.md`.
- Extension subagents live in `agents/*.md`.
- For Compound Engineering, native extension packaging is now the likely primary Gemini distribution path because it can preserve commands, skills, and subagents. Direct `.gemini/` writes should be treated as a legacy/custom install path unless retained for local development.
- Because this repo is a monorepo with the plugin under `plugins/compound-engineering/`, public Gemini extension distribution likely needs a generated extension-root source, a dedicated extension repo, or a distribution branch whose root is the Gemini extension root.
- Interim CE distribution should keep using the Bun installer, but change the writer to install into `~/.gemini/{skills,agents,commands}` with a manifest under `~/.gemini/compound-engineering`.
### Extension root shape
A distributable Gemini extension source should look like:
```text
gemini-extension.json
GEMINI.md # optional context file
skills/<skill-name>/SKILL.md
commands/<command>.toml
agents/<agent-name>.md
hooks/hooks.json # optional
policies/*.toml # optional
package.json # optional, if the extension has runtime code
```
Minimal manifest:
```json
{
"name": "compound-engineering",
"version": "1.0.0",
"description": "Compound Engineering workflows for Gemini CLI",
"contextFileName": "GEMINI.md"
}
```
Relevant manifest fields:
- `name`: Required. Local CLI validation allows letters, numbers, and dashes; docs recommend lowercase numbers/dashes and expect the extension directory name to match.
- `version`: Required. Validation warns if it is not standard semver.
- `description`: Optional but used by the public gallery.
- `contextFileName`: Optional. Defaults to `GEMINI.md` when present.
- `mcpServers`: Optional. Loaded like user `settings.json` MCP servers, except `trust` is ignored for extension MCP config.
- `settings`: Optional install-time/user configuration prompts; values are stored in extension `.env` or keychain for sensitive values.
- `excludeTools`, `migratedTo`, `plan`, `themes`: Optional target-specific behavior.
### Install commands
Install from a GitHub repository whose root is the extension root:
```bash
gemini extensions install https://github.com/EveryInc/compound-engineering-gemini
```
Install from a branch, tag, or commit:
```bash
gemini extensions install https://github.com/EveryInc/compound-engineering-gemini --ref stable
```
Install from a local extension root:
```bash
gemini extensions install ./dist/gemini-extension
```
Link a local extension root for development:
```bash
gemini extensions link ./dist/gemini-extension
```
Validate a local extension root:
```bash
gemini extensions validate ./dist/gemini-extension
```
Uninstall:
```bash
gemini extensions uninstall compound-engineering
```
### Release options
Gemini supports two remote release shapes:
1. **Git repository:** Users install the repository URL. The repository root must contain `gemini-extension.json`.
2. **GitHub Releases:** Users still install the repository URL. Gemini can use the latest release archive or a release tag via `--ref`; custom archives must be self-contained with `gemini-extension.json` at the archive root.
The public Gemini extension gallery indexes public GitHub repositories with the `gemini-cli-extension` topic when `gemini-extension.json` is at the repository or release archive root.
### Compound Engineering packaging implications
The current `plugins/compound-engineering/` source root is not currently a valid Gemini extension root because it lacks `gemini-extension.json`:
```bash
gemini extensions validate plugins/compound-engineering
# Configuration file not found at .../plugins/compound-engineering/gemini-extension.json
```
Adding only that manifest would make the root validate, but it would not be enough for correct agent packaging:
- CE agents currently live in nested category directories such as `agents/review/correctness-reviewer.md`.
- Gemini's local loader in `@google/gemini-cli` 0.38.2 reads only direct `*.md` files under the extension `agents/` directory.
- Gemini agent frontmatter is strict. CE's Claude-authored agent frontmatter can include Claude-only fields such as `color`, and some files use Claude string-form `tools: Read, Grep, Glob, Bash`; Gemini expects `tools` to be an array of valid Gemini tool names.
Therefore a proper CE Gemini extension should be generated or normalized, not just the Claude plugin root plus a manifest. This does not mean rewriting agent prompts into bespoke Gemini-only instructions. The agent bodies and most `name`/`description`/`model` frontmatter can usually pass through. The generated extension should:
- Copy pass-through `skills/<skill>/SKILL.md` directories that are not excluded for Gemini.
- Convert Claude agents into flat Gemini-compatible subagents under `agents/<agent-name>.md`.
- Strip or translate Claude-only frontmatter fields.
- Convert Claude tool names to Gemini tool names, or omit tools when there is no reliable mapping.
- Generate Gemini `commands/*.toml` only if CE ships source commands again.
- Include a `gemini-extension.json` at the generated extension root.
- Use `gemini extensions validate <generated-root>` in tests.
The same normalization is needed for the interim Bun installer, except the output root is `~/.gemini` instead of an extension root:
```text
~/.gemini/skills/<skill-name>/SKILL.md
~/.gemini/agents/<agent-name>.md
~/.gemini/commands/*.toml
~/.gemini/compound-engineering/install-manifest.json
```
Local smoke test on 2026-04-18 with Gemini CLI 0.38.2:
- A direct extension agent using CE/Claude-style `tools: Read, Grep, Glob, Bash` plus `color: blue` failed to load with Gemini validation errors: `tools: Expected array, received string` and `Unrecognized key(s) in object: 'color'`.
- A nested extension agent under `agents/review/nested-agent.md` produced no validation error because the loader only scans direct files under `agents/`; it was not discovered.
Do not place CE agents in `~/.agents/agents` as a shared cross-harness agent root. Gemini does not currently read it, and if Gemini adds that alias later, Claude/Copilot-shaped frontmatter could become a compatibility problem. For Gemini, use either a native extension with normalized `agents/*.md` files or a legacy/custom install under `~/.gemini/agents` with cleanup.
If the same Gemini agent name exists in multiple Gemini-read locations, Gemini registers user agents first, project agents next, and extension agents last. Later registrations override earlier ones by name. This avoids duplicate visible agent tools, but stale CE files in `~/.gemini/agents` can still emit validation errors or mask behavior when an extension is disabled, so cleanup remains necessary.
## Settings.json structure

83
docs/specs/opencode.md
View File

@@ -1,57 +1,92 @@
# OpenCode Spec (Config, Agents, Plugins)
Last verified: 2026-01-21
Last verified: 2026-04-19
## Primary sources
```
https://opencode.ai/docs/config
https://opencode.ai/docs/config/
https://opencode.ai/docs/tools
https://opencode.ai/docs/permissions
https://opencode.ai/docs/plugins/
https://opencode.ai/docs/agents/
https://opencode.ai/docs/commands/
https://opencode.ai/docs/skills
https://opencode.ai/config.json
```
## Config files and precedence
- OpenCode supports JSON and JSONC configs. citeturn10view0
- Config sources are merged (not replaced), with a defined precedence order from remote → global → custom → project → `.opencode` directories → inline overrides. citeturn10view0
- Global config is stored at `~/.config/opencode/opencode.json`, and project config is `opencode.json` in the project root. citeturn10view0
- Custom config file and directory can be provided via `OPENCODE_CONFIG` and `OPENCODE_CONFIG_DIR`. citeturn10view0
- The `.opencode` and `~/.config/opencode` directories use plural subdirectory names (`agents/`, `commands/`, `modes/`, `plugins/`, `skills/`, `tools/`, `themes/`), but singular names are also supported for backwards compatibility. citeturn10view0
- OpenCode supports JSON and JSONC configs.
- Config sources are merged rather than replaced, with global and project config both participating in the final config.
- Global config is stored at `~/.config/opencode/opencode.json`, and project config is `opencode.json` in the project root.
- Custom config file and directory can be provided via `OPENCODE_CONFIG` and `OPENCODE_CONFIG_DIR`.
- The `.opencode` and `~/.config/opencode` directories use plural subdirectory names (`agents/`, `commands/`, `modes/`, `plugins/`, `skills/`, `tools/`, `themes/`).
## Core config keys
- `model` and `small_model` set the primary and lightweight models; `provider` configures provider options. citeturn10view0
- `tools` is still supported but deprecated; permissions are now the canonical control surface. citeturn1search0
- `permission` controls tool approvals and can be configured globally or per tool, including pattern-based rules. citeturn1search0
- `mcp`, `instructions`, and `disabled_providers` are supported config sections. citeturn1search5
- `plugin` can list npm packages to load at startup. citeturn1search2
- `model` and `small_model` set the primary and lightweight models; `provider` configures provider options.
- `tools` is still supported but deprecated as of OpenCode v1.1.1; permissions are now the canonical control surface.
- `permission` controls tool approvals and can be configured globally or per tool, including pattern-based rules.
- `mcp`, `instructions`, `disabled_providers`, `enabled_providers`, and `plugin` are supported config sections.
- `plugin` can list npm packages to load at startup.
- `skills.paths` and `skills.urls` can add extra skill discovery locations, but CE should not depend on them until the layout is smoke-tested locally with OpenCode.
## Tools
- OpenCode ships with built-in tools, and permissions determine whether each tool runs automatically, requires approval, or is denied. citeturn1search3turn1search0
- Tools are enabled by default; permissions provide the gating mechanism. citeturn1search3
- OpenCode ships with built-in tools, and permissions determine whether each tool runs automatically, requires approval, or is denied.
- Tools are enabled by default; permissions provide the gating mechanism.
## Permissions
- Permissions resolve to `allow`, `ask`, or `deny` and can be configured globally or per tool, with pattern-based rules. citeturn1search0
- Defaults are permissive, with special cases such as `.env` file reads. citeturn1search0
- Agent-level permissions override the global permission block. citeturn1search1turn1search0
- Permissions resolve to `allow`, `ask`, or `deny` and can be configured globally or per tool, with pattern-based rules.
- Defaults are permissive, with special cases such as `.env` file reads.
- Agent-level permissions override the global permission block.
## Agents
- Agents can be configured in `opencode.json` or as markdown files in `~/.config/opencode/agents/` or `.opencode/agents/`. citeturn1search1turn10view0
- Agent config supports `mode`, `model`, `temperature`, `tools`, and `permission`, and agent configs override global settings. citeturn1search1
- Model IDs use the `provider/model-id` format. citeturn1search1
- Agents can be configured in `opencode.json` or as markdown files in `~/.config/opencode/agents/` or `.opencode/agents/`.
- Agent config supports `mode`, `model`, `variant`, `temperature`, `top_p`, `hidden`, `steps`, `options`, `permission`, and other schema fields. `tools` still exists but is deprecated.
- `mode` can be `primary`, `subagent`, or `all`; omitted mode defaults to `all`.
- `hidden: true` hides subagents from the `@` autocomplete menu.
- `permission.task` controls which subagents an agent may invoke.
- Model IDs use the `provider/model-id` format.
## Skills
- Skills are reusable `SKILL.md` definitions loaded on demand through OpenCode's native `skill` tool.
- OpenCode searches direct child skill directories in its built-in roots:
- `.opencode/skills/<name>/SKILL.md`
- `~/.config/opencode/skills/<name>/SKILL.md`
- `.claude/skills/<name>/SKILL.md`
- `~/.claude/skills/<name>/SKILL.md`
- `.agents/skills/<name>/SKILL.md`
- `~/.agents/skills/<name>/SKILL.md`
- The config schema also exposes `skills.paths` and `skills.urls` for extra skill sources. Do not switch CE to those until tested against a local OpenCode install; direct `~/.config/opencode/skills/<name>/SKILL.md` remains the stable writer shape.
- Skill frontmatter recognizes `name`, `description`, `license`, `compatibility`, and `metadata`; unknown fields are ignored.
- Skill names must be lowercase alphanumeric with single hyphen separators and must match the directory name.
## Commands
- Commands can be configured in `opencode.json` or as Markdown files in `~/.config/opencode/commands/` or `.opencode/commands/`.
- Markdown command frontmatter can include fields such as `description`, `agent`, `model`, and `subtask`; the body becomes the prompt template.
- If a command targets an agent whose mode is `subagent`, OpenCode invokes it as a subagent by default. `subtask: true` can force subagent invocation.
## Plugins and events
- Local plugins are loaded from `.opencode/plugin/` (project) and `~/.config/opencode/plugin/` (global). npm plugins can be listed in `plugin` in `opencode.json`. citeturn1search2
- Plugins are loaded in a defined order across config and plugin directories. citeturn1search2
- Plugins export a function that returns a map of event handlers; the plugins doc lists supported event categories. citeturn1search2
- Local plugins are loaded from `.opencode/plugins/` and `~/.config/opencode/plugins/`. npm plugins can be listed in `plugin` in `opencode.json`.
- Plugins are JavaScript/TypeScript modules. Each exported plugin function receives OpenCode context and returns hooks/event handlers.
- Local plugins and custom tools can use npm dependencies declared in a `package.json` in the OpenCode config directory; OpenCode runs `bun install` at startup.
## Notes for this repository
- Config docs describe plural subdirectory names, while the plugins doc uses `.opencode/plugin/`. This implies singular paths remain accepted for backwards compatibility, but plural paths are the canonical structure. citeturn10view0turn1search2
- The current documented global CE install root should stay `~/.config/opencode`, not `~/.agents`, to avoid conflicts with harnesses that also read `~/.agents`.
- The current CE writer shape is still appropriate in April 2026:
- `~/.config/opencode/opencode.json`
- `~/.config/opencode/agents/*.md`
- `~/.config/opencode/commands/*.md` only when a source plugin ships commands
- `~/.config/opencode/plugins/*.ts`
- `~/.config/opencode/skills/*/SKILL.md`
- OpenCode's plugin system is useful for JS/TS hooks and custom tools, but current docs do not describe a native marketplace command that consumes CE's `.claude-plugin/marketplace.json` and installs the full skills/agents/commands payload.
- Keep the custom Bun writer until OpenCode documents a native distribution path for packaged skills and agents.
- The `compound-engineering` plugin currently emits skills and subagent Markdown files for OpenCode. It should not emit deprecated `tools` config; permission config is enough for non-default permission modes.

477
docs/specs/windsurf.md
View File

@@ -1,477 +0,0 @@
# Windsurf Editor Global Configuration Guide
> **Purpose**: Technical reference for programmatically creating and managing Windsurf's global Skills, Workflows, and Rules.
>
> **Source**: Official Windsurf documentation at [docs.windsurf.com](https://docs.windsurf.com) + local file analysis.
>
> **Last Updated**: February 2026
---
## Table of Contents
1. [Overview](#overview)
2. [Base Directory Structure](#base-directory-structure)
3. [Skills](#skills)
4. [Workflows](#workflows)
5. [Rules](#rules)
6. [Memories](#memories)
7. [System-Level Configuration (Enterprise)](#system-level-configuration-enterprise)
8. [Programmatic Creation Reference](#programmatic-creation-reference)
9. [Best Practices](#best-practices)
---
## Overview
Windsurf provides three main customization mechanisms:
| Feature | Purpose | Invocation |
|---------|---------|------------|
| **Skills** | Complex multi-step tasks with supporting resources | Automatic (progressive disclosure) or `@skill-name` |
| **Workflows** | Reusable step-by-step procedures | Slash command `/workflow-name` |
| **Rules** | Behavioral guidelines and preferences | Trigger-based (always-on, glob, manual, or model decision) |
All three support both **workspace-level** (project-specific) and **global** (user-wide) scopes.
---
## Base Directory Structure
### Global Configuration Root
| OS | Path |
|----|------|
| **Windows** | `C:\Users\{USERNAME}\.codeium\windsurf\` |
| **macOS** | `~/.codeium/windsurf/` |
| **Linux** | `~/.codeium/windsurf/` |
### Directory Layout
```
~/.codeium/windsurf/
├── skills/ # Global skills (directories)
│ └── {skill-name}/
│ └── SKILL.md
├── global_workflows/ # Global workflows (flat .md files)
│ └── {workflow-name}.md
├── rules/ # Global rules (flat .md files)
│ └── {rule-name}.md
├── memories/
│ ├── global_rules.md # Always-on global rules (plain text)
│ └── *.pb # Auto-generated memories (protobuf)
├── mcp_config.json # MCP server configuration
└── user_settings.pb # User settings (protobuf)
```
---
## Skills
Skills bundle instructions with supporting resources for complex, multi-step tasks. Cascade uses **progressive disclosure** to automatically invoke skills when relevant.
### Storage Locations
| Scope | Location |
|-------|----------|
| **Global** | `~/.codeium/windsurf/skills/{skill-name}/SKILL.md` |
| **Workspace** | `.windsurf/skills/{skill-name}/SKILL.md` |
### Directory Structure
Each skill is a **directory** (not a single file) containing:
```
{skill-name}/
├── SKILL.md # Required: Main skill definition
├── references/ # Optional: Reference documentation
├── assets/ # Optional: Images, diagrams, etc.
├── scripts/ # Optional: Helper scripts
└── {any-other-files} # Optional: Templates, configs, etc.
```
### SKILL.md Format
```markdown
---
name: skill-name
description: Brief description shown to model to help it decide when to invoke the skill
---
# Skill Title
Instructions for the skill go here in markdown format.
## Section 1
Step-by-step guidance...
## Section 2
Reference supporting files using relative paths:
- See [deployment-checklist.md](./deployment-checklist.md)
- Run script: [deploy.sh](./scripts/deploy.sh)
```
### Required YAML Frontmatter Fields
| Field | Required | Description |
|-------|----------|-------------|
| `name` | **Yes** | Unique identifier (lowercase letters, numbers, hyphens only). Must match directory name. |
| `description` | **Yes** | Explains what the skill does and when to use it. Critical for automatic invocation. |
### Naming Convention
- Use **lowercase-kebab-case**: `deploy-to-staging`, `code-review`, `setup-dev-environment`
- Name must match the directory name exactly
### Invocation Methods
1. **Automatic**: Cascade automatically invokes when request matches skill description
2. **Manual**: Type `@skill-name` in Cascade input
### Example: Complete Skill
```
~/.codeium/windsurf/skills/deploy-to-production/
├── SKILL.md
├── deployment-checklist.md
├── rollback-procedure.md
└── config-template.yaml
```
**SKILL.md:**
```markdown
---
name: deploy-to-production
description: Guides the deployment process to production with safety checks. Use when deploying to prod, releasing, or pushing to production environment.
---
## Pre-deployment Checklist
1. Run all tests
2. Check for uncommitted changes
3. Verify environment variables
## Deployment Steps
Follow these steps to deploy safely...
See [deployment-checklist.md](./deployment-checklist.md) for full checklist.
See [rollback-procedure.md](./rollback-procedure.md) if issues occur.
```
---
## Workflows
Workflows define step-by-step procedures invoked via slash commands. They guide Cascade through repetitive tasks.
### Storage Locations
| Scope | Location |
|-------|----------|
| **Global** | `~/.codeium/windsurf/global_workflows/{workflow-name}.md` |
| **Workspace** | `.windsurf/workflows/{workflow-name}.md` |
### File Format
Workflows are **single markdown files** (not directories):
```markdown
---
description: Short description of what the workflow does
---
# Workflow Title
> Arguments: [optional arguments description]
Step-by-step instructions in markdown.
1. First step
2. Second step
3. Third step
```
### Required YAML Frontmatter Fields
| Field | Required | Description |
|-------|----------|-------------|
| `description` | **Yes** | Short title/description shown in UI |
### Invocation
- Slash command: `/workflow-name`
- Filename becomes the command (e.g., `deploy.md` → `/deploy`)
### Constraints
- **Character limit**: 12,000 characters per workflow file
- Workflows can call other workflows: Include instructions like "Call `/other-workflow`"
### Example: Complete Workflow
**File**: `~/.codeium/windsurf/global_workflows/address-pr-comments.md`
```markdown
---
description: Address all PR review comments systematically
---
# Address PR Comments
> Arguments: [PR number]
1. Check out the PR branch: `gh pr checkout [id]`
2. Get comments on PR:
```bash
gh api --paginate repos/[owner]/[repo]/pulls/[id]/comments | jq '.[] | {user: .user.login, body, path, line}'
```
3. For EACH comment:
a. Print: "(index). From [user] on [file]:[lines] — [body]"
b. Analyze the file and line range
c. If unclear, ask for clarification
d. Make the change before moving to next comment
4. Summarize what was done and which comments need attention
```
---
## Rules
Rules provide persistent behavioral guidelines that influence how Cascade responds.
### Storage Locations
| Scope | Location |
|-------|----------|
| **Global** | `~/.codeium/windsurf/rules/{rule-name}.md` |
| **Workspace** | `.windsurf/rules/{rule-name}.md` |
### File Format
Rules are **single markdown files**:
```markdown
---
description: When to use this rule
trigger: activation_mode
globs: ["*.py", "src/**/*.ts"]
---
Rule instructions in markdown format.
- Guideline 1
- Guideline 2
- Guideline 3
```
### YAML Frontmatter Fields
| Field | Required | Description |
|-------|----------|-------------|
| `description` | **Yes** | Describes when to use the rule |
| `trigger` | Optional | Activation mode (see below) |
| `globs` | Optional | File patterns for glob trigger |
### Activation Modes (trigger field)
| Mode | Value | Description |
|------|-------|-------------|
| **Manual** | `manual` | Activated via `@mention` in Cascade input |
| **Always On** | `always` | Always applied to every conversation |
| **Model Decision** | `model_decision` | Model decides based on description |
| **Glob** | `glob` | Applied when working with files matching pattern |
### Constraints
- **Character limit**: 12,000 characters per rule file
### Example: Complete Rule
**File**: `~/.codeium/windsurf/rules/python-style.md`
```markdown
---
description: Python coding standards and style guidelines. Use when writing or reviewing Python code.
trigger: glob
globs: ["*.py", "**/*.py"]
---
# Python Coding Guidelines
- Use type hints for all function parameters and return values
- Follow PEP 8 style guide
- Use early returns when possible
- Always add docstrings to public functions and classes
- Prefer f-strings over .format() or % formatting
- Use pathlib instead of os.path for file operations
```
---
## Memories
### Global Rules (Always-On)
**Location**: `~/.codeium/windsurf/memories/global_rules.md`
This is a special file for rules that **always apply** to all conversations. Unlike rules in the `rules/` directory, this file:
- Does **not** require YAML frontmatter
- Is plain text/markdown
- Is always active (no trigger configuration)
**Format:**
```markdown
Plain text rules that always apply to all conversations.
- Rule 1
- Rule 2
- Rule 3
```
### Auto-Generated Memories
Cascade automatically creates memories during conversations, stored as `.pb` (protobuf) files in `~/.codeium/windsurf/memories/`. These are managed by Windsurf and should not be manually edited.
---
## System-Level Configuration (Enterprise)
Enterprise organizations can deploy system-level configurations that apply globally and cannot be modified by end users.
### System-Level Paths
| Type | Windows | macOS | Linux/WSL |
|------|---------|-------|-----------|
| **Rules** | `C:\ProgramData\Windsurf\rules\*.md` | `/Library/Application Support/Windsurf/rules/*.md` | `/etc/windsurf/rules/*.md` |
| **Workflows** | `C:\ProgramData\Windsurf\workflows\*.md` | `/Library/Application Support/Windsurf/workflows/*.md` | `/etc/windsurf/workflows/*.md` |
### Precedence Order
When items with the same name exist at multiple levels:
1. **System** (highest priority) - Organization-wide, deployed by IT
2. **Workspace** - Project-specific in `.windsurf/`
3. **Global** - User-defined in `~/.codeium/windsurf/`
4. **Built-in** - Default items provided by Windsurf
---
## Programmatic Creation Reference
### Quick Reference Table
| Type | Path Pattern | Format | Key Fields |
|------|--------------|--------|------------|
| **Skill** | `skills/{name}/SKILL.md` | YAML frontmatter + markdown | `name`, `description` |
| **Workflow** | `global_workflows/{name}.md` (global) or `workflows/{name}.md` (workspace) | YAML frontmatter + markdown | `description` |
| **Rule** | `rules/{name}.md` | YAML frontmatter + markdown | `description`, `trigger`, `globs` |
| **Global Rules** | `memories/global_rules.md` | Plain text/markdown | None |
### Minimal Templates
#### Skill (SKILL.md)
```markdown
---
name: my-skill
description: What this skill does and when to use it
---
Instructions here.
```
#### Workflow
```markdown
---
description: What this workflow does
---
1. Step one
2. Step two
```
#### Rule
```markdown
---
description: When this rule applies
trigger: model_decision
---
- Guideline one
- Guideline two
```
### Validation Checklist
When programmatically creating items:
- [ ] **Skills**: Directory exists with `SKILL.md` inside
- [ ] **Skills**: `name` field matches directory name exactly
- [ ] **Skills**: Name uses only lowercase letters, numbers, hyphens
- [ ] **Workflows/Rules**: File is `.md` extension
- [ ] **All**: YAML frontmatter uses `---` delimiters
- [ ] **All**: `description` field is present and meaningful
- [ ] **All**: File size under 12,000 characters (workflows/rules)
---
## Best Practices
### Writing Effective Descriptions
The `description` field is critical for automatic invocation. Be specific:
**Good:**
```yaml
description: Guides deployment to staging environment with pre-flight checks. Use when deploying to staging, testing releases, or preparing for production.
```
**Bad:**
```yaml
description: Deployment stuff
```
### Formatting Guidelines
- Use bullet points and numbered lists (easier for Cascade to follow)
- Use markdown headers to organize sections
- Keep rules concise and specific
- Avoid generic rules like "write good code" (already built-in)
### XML Tags for Grouping
XML tags can effectively group related rules:
```markdown
<coding_guidelines>
- Use early returns when possible
- Always add documentation for new functions
- Prefer composition over inheritance
</coding_guidelines>
<testing_requirements>
- Write unit tests for all public methods
- Maintain 80% code coverage
</testing_requirements>
```
### Skills vs Rules vs Workflows
| Use Case | Recommended |
|----------|-------------|
| Multi-step procedure with supporting files | **Skill** |
| Repeatable CLI/automation sequence | **Workflow** |
| Coding style preferences | **Rule** |
| Project conventions | **Rule** |
| Deployment procedure | **Skill** or **Workflow** |
| Code review checklist | **Skill** |
---
## Additional Resources
- **Official Documentation**: [docs.windsurf.com](https://docs.windsurf.com)
- **Skills Specification**: [agentskills.io](https://agentskills.io/home)
- **Rule Templates**: [windsurf.com/editor/directory](https://windsurf.com/editor/directory)