Skip to content

draft: request feedback on install-managed plugin support direction #1596

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Draft
lgaudez wants to merge 5 commits into
base: main
Choose a base branch
from
Draft

draft: request feedback on install-managed plugin support direction #1596

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
3b2a7a5
docs: add plugins v1 design spec
lgaudez May 1, 2026
6a993e7
docs: format plugins design spec
lgaudez May 1, 2026
5343a3f
feat: add install-managed plugin support
lgaudez May 1, 2026
efa3e65
feat: add claudecode plugin install support
lgaudez May 1, 2026
7d05938
feat: add geminicli plugin install support
lgaudez May 2, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 2 additions & 0 deletions .gitignore
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -223,6 +223,8 @@ docs/.vitepress/cache

# Generated by Rulesync
.rulesync/skills/.curated/
.rulesync/plugins/.curated/
rulesync-plugins.lock.yaml
.rulesync/rules/*.local.md
rulesync.local.jsonc
**/AGENTS.local.md
Expand Down
59 changes: 30 additions & 29 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -70,40 +70,41 @@ See [Quick Start guide](https://dyoshikawa.github.io/rulesync/getting-started/qu

## Supported Tools and Features

| Tool | --targets | rules | ignore | mcp | commands | subagents | skills | hooks | permissions |
| ------------------- | ------------ | :---: | :----: | :------: | :------: | :-------: | :----: | :---: | :---------: |
| AGENTS.md | agentsmd | ✅ | | | 🎮 | 🎮 | 🎮 | | |
| AgentsSkills | agentsskills | | | | | | ✅ | | |
| Claude Code | claudecode | ✅ 🌏 | ✅ | ✅ 🌏 | ✅ 🌏 | ✅ 🌏 | ✅ 🌏 | ✅ 🌏 | ✅ 🌏 |
| Codex CLI | codexcli | ✅ 🌏 | | ✅ 🌏 🔧 | 🌏 | ✅ 🌏 | ✅ 🌏 | ✅ 🌏 | ✅ 🌏 |
| Gemini CLI | geminicli | ✅ 🌏 | ✅ | ✅ 🌏 | ✅ 🌏 | ✅ | ✅ 🌏 | ✅ 🌏 | ✅ 🌏 |
| Goose | goose | ✅ 🌏 | ✅ | | | | | | |
| GitHub Copilot | copilot | ✅ 🌏 | | ✅ | ✅ | ✅ | ✅ | ✅ | |
| GitHub Copilot CLI | copilotcli | ✅ 🌏 | | ✅ 🌏 | | ✅ 🌏 | | ✅ 🌏 | |
| Cursor | cursor | ✅ | ✅ | ✅ 🌏 | ✅ 🌏 | ✅ 🌏 | ✅ 🌏 | ✅ 🌏 | ✅ 🌏 |
| deepagents-cli | deepagents | ✅ | | ✅ 🌏 | | ✅ | ✅ | 🌏 | |
| Factory Droid | factorydroid | ✅ 🌏 | | ✅ 🌏 | 🎮 | 🎮 | 🎮 | ✅ 🌏 | |
| OpenCode | opencode | ✅ 🌏 | | ✅ 🌏 🔧 | ✅ 🌏 | ✅ 🌏 | ✅ 🌏 | ✅ 🌏 | ✅ 🌏 |
| Cline | cline | ✅ | ✅ | ✅ | ✅ 🌏 | | ✅ 🌏 | | ✅ |
| Kilo Code | kilo | ✅ 🌏 | ✅ | ✅ | ✅ 🌏 | | ✅ 🌏 | | ✅ 🌏 |
| Roo Code | roo | ✅ | ✅ | ✅ | ✅ | 🎮 | ✅ 🌏 | | |
| Rovodev (Atlassian) | rovodev | ✅ 🌏 | | 🌏 | | ✅ 🌏 | ✅ 🌏 | | |
| Takt | takt | ✅ 🌏 | | | ✅ 🌏 | ✅ 🌏 | ✅ 🌏 | | |
| Qwen Code | qwencode | ✅ | ✅ | | | | | | ✅ 🌏 |
| Kiro | kiro | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | | ✅ |
| Google Antigravity | antigravity | ✅ | | | ✅ | | ✅ 🌏 | | |
| JetBrains Junie | junie | ✅ | ✅ | ✅ | ✅ 🌏 | ✅ | ✅ | | |
| AugmentCode | augmentcode | ✅ | ✅ | | | | | | ✅ 🌏 |
| Windsurf | windsurf | ✅ | ✅ | | | | ✅ 🌏 | | |
| Warp | warp | ✅ | | | | | | | |
| Replit | replit | ✅ | | | | | ✅ | | |
| Pi Coding Agent | pi | ✅ 🌏 | | | ✅ 🌏 | | ✅ 🌏 | | |
| Zed | zed | | ✅ | | | | | | |
| Tool | --targets | rules | ignore | mcp | commands | subagents | skills | hooks | permissions | plugins |
| ------------------- | ------------ | :---: | :----: | :------: | :------: | :-------: | :----: | :---: | :---------: | :-----: |
| AGENTS.md | agentsmd | ✅ | | | 🎮 | 🎮 | 🎮 | | | |
| AgentsSkills | agentsskills | | | | | | ✅ | | | |
| Claude Code | claudecode | ✅ 🌏 | ✅ | ✅ 🌏 | ✅ 🌏 | ✅ 🌏 | ✅ 🌏 | ✅ 🌏 | ✅ 🌏 | 📦 🌏 |
| Codex CLI | codexcli | ✅ 🌏 | | ✅ 🌏 🔧 | 🌏 | ✅ 🌏 | ✅ 🌏 | ✅ 🌏 | ✅ 🌏 | 📦 🌏 |
| Gemini CLI | geminicli | ✅ 🌏 | ✅ | ✅ 🌏 | ✅ 🌏 | ✅ | ✅ 🌏 | ✅ 🌏 | ✅ 🌏 | 📦 🌏 |
| Goose | goose | ✅ 🌏 | ✅ | | | | | | | |
| GitHub Copilot | copilot | ✅ 🌏 | | ✅ | ✅ | ✅ | ✅ | ✅ | | |
| GitHub Copilot CLI | copilotcli | ✅ 🌏 | | ✅ 🌏 | | ✅ 🌏 | | ✅ 🌏 | | |
| Cursor | cursor | ✅ | ✅ | ✅ 🌏 | ✅ 🌏 | ✅ 🌏 | ✅ 🌏 | ✅ 🌏 | ✅ 🌏 | |
| deepagents-cli | deepagents | ✅ | | ✅ 🌏 | | ✅ | ✅ | 🌏 | | |
| Factory Droid | factorydroid | ✅ 🌏 | | ✅ 🌏 | 🎮 | 🎮 | 🎮 | ✅ 🌏 | | |
| OpenCode | opencode | ✅ 🌏 | | ✅ 🌏 🔧 | ✅ 🌏 | ✅ 🌏 | ✅ 🌏 | ✅ 🌏 | ✅ 🌏 | |
| Cline | cline | ✅ | ✅ | ✅ | ✅ 🌏 | | ✅ 🌏 | | ✅ | |
| Kilo Code | kilo | ✅ 🌏 | ✅ | ✅ | ✅ 🌏 | | ✅ 🌏 | | ✅ 🌏 | |
| Roo Code | roo | ✅ | ✅ | ✅ | ✅ | 🎮 | ✅ 🌏 | | | |
| Rovodev (Atlassian) | rovodev | ✅ 🌏 | | 🌏 | | ✅ 🌏 | ✅ 🌏 | | | |
| Takt | takt | ✅ 🌏 | | | ✅ 🌏 | ✅ 🌏 | ✅ 🌏 | | | |
| Qwen Code | qwencode | ✅ | ✅ | | | | | | ✅ 🌏 | |
| Kiro | kiro | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | | ✅ | |
| Google Antigravity | antigravity | ✅ | | | ✅ | | ✅ 🌏 | | | |
| JetBrains Junie | junie | ✅ | ✅ | ✅ | ✅ 🌏 | ✅ | ✅ | | | |
| AugmentCode | augmentcode | ✅ | ✅ | | | | | | ✅ 🌏 | |
| Windsurf | windsurf | ✅ | ✅ | | | | ✅ 🌏 | | | |
| Warp | warp | ✅ | | | | | | | | |
| Replit | replit | ✅ | | | | | ✅ | | | |
| Pi Coding Agent | pi | ✅ 🌏 | | | ✅ 🌏 | | ✅ 🌏 | | | |
| Zed | zed | | ✅ | | | | | | | |

- ✅: Supports project mode
- 🌏: Supports global mode
- 🎮: Supports simulated commands/subagents/skills (Project mode only)
- 🔧: Supports MCP tool config (`enabledTools`/`disabledTools`)
- 📦: Install-managed via `rulesync install` rather than `rulesync generate`

Some features accept per-feature options (e.g., Claude Code's `ignore` feature supports `fileMode: "local"` to write to `settings.local.json` instead of `settings.json`). See [Configuration > Per-feature options](https://dyoshikawa.github.io/rulesync/guide/configuration#per-feature-options) for details.

Expand Down
1 change: 1 addition & 0 deletions cspell.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -194,6 +194,7 @@
"opencode",
"opencommit",
"OPENROUTER",
"obra",
"ovpn",
"oxfmt",
"oxfmtrc",
Expand Down
21 changes: 20 additions & 1 deletion docs/guide/configuration.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -70,12 +70,31 @@ Example:
// unconditionally to prevent accidental commits of generated rule files.
"gitignoreTargetsOnly": true,

// Declarative skill sources — installed via 'rulesync install'
// Declarative sources for external skills/plugins — installed via 'rulesync install'
// See the "Declarative Skill Sources" section for details.
// "sources": [
// { "source": "owner/repo" },
// { "source": "org/repo", "skills": ["specific-skill"] },
// {
// "source": "obra/superpowers",
// "plugins": [
// {
// "name": "superpowers",
// "targets": ["codexcli"],
// "codexcli": {
// "artifact": { "kind": "skillsBundle", "path": "skills" },
// "install": { "strategy": "userSkillsDir" },
// },
// },
// ],
// },
// ],

// Optional per-target feature override. When present, this replaces the
// root `features` array for that tool.
// "targetFeatures": {
// "codexcli": ["skills", "mcp", "plugins"],
// },
}
```

Expand Down
52 changes: 38 additions & 14 deletions docs/guide/declarative-sources.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
# Declarative Skill Sources
# Declarative Sources

Rulesync can fetch skills from external repositories using the `install` command. Instead of manually running `fetch` for each skill source, declare them in your `rulesync.jsonc` and run `rulesync install` to resolve and fetch them. Then `rulesync generate` picks them up as local curated skills. Typical workflow: `rulesync install && rulesync generate`.
Rulesync can fetch skills and install plugins from external repositories using the `install` command. Instead of manually running `fetch` for each source, declare them in your `rulesync.jsonc` and run `rulesync install`. For curated skills, `rulesync generate` then picks them up as local curated skills. For install-managed plugins, `rulesync install` performs the target deployment directly.

## Configuration

Expand All @@ -18,6 +18,22 @@ Add a `sources` array to your `rulesync.jsonc`:
// Fetch only specific skills by name
{ "source": "anthropics/skills", "skills": ["skill-creator"] },

// Install a codexcli plugin from an explicit plugin declaration
{
"source": "obra/superpowers",
"ref": "main",
"plugins": [
{
"name": "superpowers",
"targets": ["codexcli"],
"codexcli": {
"artifact": { "kind": "skillsBundle", "path": "skills" },
"install": { "strategy": "userSkillsDir" },
},
},
],
},

// With ref pinning and subdirectory path (same syntax as fetch command)
{ "source": "owner/repo@v1.0.0:path/to/skills" },

Expand All @@ -37,13 +53,14 @@ Add a `sources` array to your `rulesync.jsonc`:

Each entry in `sources` accepts:

| Property | Type | Description |
| ----------- | ---------- | -------------------------------------------------------------------------------------------------------------------------------- |
| `source` | `string` | Repository source. For GitHub transport: `owner/repo` or `owner/repo@ref:path`. For git transport: a full git URL. |
| `skills` | `string[]` | Optional list of skill names to fetch. If omitted, all skills are fetched. |
| `transport` | `string` | `"github"` (default) uses the GitHub REST API. `"git"` uses git CLI and works with any git remote. |
| `ref` | `string` | Branch, tag, or ref to fetch from. Defaults to the remote's default branch. For GitHub transport, use the `@ref` source syntax. |
| `path` | `string` | Path to the skills directory within the repository. Defaults to `"skills"`. For GitHub transport, use the `:path` source syntax. |
| Property | Type | Description |
| ----------- | ---------- | ---------------------------------------------------------------------------------------------------------------------------------- |
| `source` | `string` | Repository source. For GitHub transport: `owner/repo` or `owner/repo@ref:path`. For git transport: a full git URL. |
| `skills` | `string[]` | Optional list of skill names to fetch. If omitted, all skills are fetched. |
| `plugins` | `object[]` | Optional explicit plugin declarations. V1 supports `codexcli` plugins with `skillsBundle` artifacts installed via `userSkillsDir`. |
| `transport` | `string` | `"github"` (default) uses the GitHub REST API. `"git"` uses git CLI and works with any git remote. |
| `ref` | `string` | Branch, tag, or ref to fetch from. Defaults to the remote's default branch. For GitHub transport, use the `@ref` source syntax. |
| `path` | `string` | Path to the skills directory within the repository. Defaults to `"skills"`. For GitHub transport, use the `:path` source syntax. |

## How It Works

Expand All @@ -57,15 +74,22 @@ When `rulesync install` runs and `sources` is configured:
- **First-declared source wins** — If two sources provide a skill with the same name, the one declared first in the `sources` array is used.
5. **Output** — Fetched skills are written to `.rulesync/skills/.curated/<skill-name>/`. This directory is automatically added to `.gitignore` by `rulesync gitignore`.

For V1 plugins:

1. **Explicit declaration** — RuleSync reads `sources[].plugins[]`; plugin packages are not auto-discovered.
2. **Curated materialization** — External plugin payloads are written to `.rulesync/plugins/.curated/<plugin-name>/`.
3. **Precedence rules** — Local plugins in `.rulesync/plugins/<plugin-name>/` override curated plugins with the same name.
4. **Install-managed deployment** — For `codexcli`, `rulesync install` deploys `skillsBundle` payloads into the Codex user skills directory and records deployment state in `rulesync-plugins.lock.yaml`.

## Install Modes

`rulesync install` supports three install modes via `--mode <mode>`:

| Mode | Manifest input | Lockfile | Skill output layout |
| ---------- | ---------------------------- | ------------------------ | ---------------------------------------------------------------------------- |
| `rulesync` | `rulesync.jsonc` `sources` | `rulesync.lock` | `.rulesync/skills/.curated/<name>/` (then re-emitted by `rulesync generate`) |
| `apm` | `apm.yml` `dependencies.apm` | `rulesync-apm.lock.yaml` | `.github/instructions/`, `.github/skills/` (APM v1 layout) |
| `gh` | `rulesync.jsonc` `sources` | `rulesync-gh.lock.yaml` | Per-agent / per-scope dirs (matching `gh skill install`) |
| Mode | Manifest input | Lockfile | Output layout |
| ---------- | ---------------------------- | ------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------- |
| `rulesync` | `rulesync.jsonc` `sources` | `rulesync.lock` and `rulesync-plugins.lock.yaml` | Skills: `.rulesync/skills/.curated/<name>/`; Plugins: `.rulesync/plugins/.curated/<name>/` plus target deployment |
| `apm` | `apm.yml` `dependencies.apm` | `rulesync-apm.lock.yaml` | `.github/instructions/`, `.github/skills/` (APM v1 layout) |
| `gh` | `rulesync.jsonc` `sources` | `rulesync-gh.lock.yaml` | Per-agent / per-scope dirs (matching `gh skill install`) |

When `--mode` is omitted, rulesync defaults to `rulesync` mode. If `apm.yml` is present and `sources` is also defined, you must pass `--mode apm` or `--mode rulesync` to disambiguate.

Expand Down
Loading
Loading