draft: request feedback on install-managed plugin support direction

[lgaudez]

Draft PR

This pull request is intentionally opened as a draft because I am primarily looking for feedback on the feature direction and maintenance model, not just code review.

The main question behind this PR is:

Does this plugin-installation paradigm belong in Rulesync, and is it something you would want to maintain if we move forward with it?

What this PR is trying to introduce

This branch introduces a new install-managed plugin model alongside the existing generate/fetch workflows.

Today, Rulesync already handles:

• generating project files from unified rules
• fetching curated skills into .rulesync/skills/.curated/

This PR explores a new category:

• declaring plugin artifacts in rulesync.jsonc
• resolving them from external repositories
• materializing them under .rulesync/plugins/.curated/
• deploying them into the appropriate user skill/plugin directory via rulesync install
• recording deployment state in rulesync-plugins.lock.yaml

This is why I consider it a new paradigm rather than a small feature addition.

The problem this is trying to solve

For some ecosystems, a generated project file is not the right delivery model. The useful artifact is instead a bundle that needs to be installed into a user-level tool directory.

Examples in this branch are skill-bundle style integrations for:

• Codex CLI
• Claude Code
• Gemini CLI

Without a first-class install model, that workflow stays ad hoc:

• users fetch or copy artifacts manually
• there is no lockfile-backed deployment state
• there is no clear precedence between local vs curated plugin definitions
• Rulesync can describe the source, but not the installation lifecycle

What is implemented in this draft

• sources[].plugins[] declarations in rulesync.jsonc
• plugin manifest schema + validation
• install-managed deployment through rulesync install
• support for skillsBundle -> userSkillsDir as the first install strategy
• support in this branch for codexcli, claudecode, and geminicli targets
• curated plugin materialization in .rulesync/plugins/.curated/
• local plugin precedence over curated plugin payloads
• plugin deployment lockfile/state tracking via rulesync-plugins.lock.yaml
• CLI, config, docs, and supported-tools matrix updates
• tests for config parsing, install flows, precedence, and multi-target installs

Conceptual model

1. Source declaration -> curated materialization -> user install

flowchart LR
    A["rulesync.jsonc\nplugin declarations in sources"] --> B["Resolve source and ref"]
    B --> C["Materialize curated plugin\n.rulesync/plugins/.curated/plugin-name/"]
    C --> D["rulesync install"]
    D --> E["Deploy artifact to user dir\n~/.codex/skills\n~/.claude/skills\n~/.gemini/skills"]
    D --> F["Record state in\nrulesync-plugins.lock.yaml"]

Loading

2. Precedence model

flowchart TD
    A["Local plugin\n.rulesync/plugins/plugin-name/"] --> C{"Same plugin name?"}
    B["Curated plugin\n.rulesync/plugins/.curated/plugin-name/"] --> C
    C -->|yes| D["Local plugin wins"]
    C -->|no conflict| E["Use declared plugin as-is"]

Loading

Why I thought this might fit Rulesync

My reasoning was:

1. Rulesync already acts as a normalization layer across multiple AI tooling ecosystems.
2. Some of those ecosystems are better served by install-managed artifacts than by generated project files.
3. If Rulesync can already unify source declaration and artifact fetching, it may also be a natural place to unify installation semantics.

But I do not want to assume that this is a good long-term product direction without your feedback.

Scope choices in this V1

This draft intentionally keeps the first version narrow:

• plugin declarations are explicit rather than auto-discovered
• only one artifact/install pattern is implemented: skillsBundle -> userSkillsDir
• the current target support is limited to Codex CLI, Claude Code, and Gemini CLI
• deployment is user-scope oriented in this branch

The intent was to validate the model first before generalizing it.

The feedback I would especially like from you

I would really value your opinion on these points:

1. Does this belong in Rulesync at all?
   Is install-managed plugin deployment aligned with the project vision, or does it make Rulesync responsible for too much lifecycle/state management?

2. Is the abstraction boundary reasonable?
   Is sources[].plugins[] the right place for this concept, or does it overload the current sources model?

3. Is the maintenance surface acceptable?
   Even if the implementation works, do you want Rulesync to own ongoing support for per-tool plugin install semantics?

4. Is V1 scoped correctly?
   Does starting with skillsBundle -> userSkillsDir make sense as an experiment, or is that already too specific or too tool-shaped?

5. Should this move forward here, move elsewhere, or stop?

If your answer is “the feature works but I do not want Rulesync to go in this direction,” that is completely useful feedback for me.

Validation

• pnpm cicheck passed locally under Node v22.22.2 on this branch
• the branch includes dedicated tests for plugin manifest validation, install deployment, precedence, lockfile behavior, and multi-target support

CI context

One GitHub Actions workflow seen on the fork (E2E Tests on Cross-Platform) currently fails before this plugin code path is exercised because of pre-existing CI/tooling drift around mise or pnpm latest and ignored build scripts. That issue reproduces on the fork main branch as well and does not appear to be introduced by this feature branch.

Related context

• Fork draft PR used for iteration: [codex] feat: add geminicli plugin install support lgaudez/rulesync#2
• No upstream issue is linked yet for this proposal

[github-actions]

Thank you for your contribution! Unfortunately, this PR has 2027 added lines, which exceeds the limit of 1000 lines for external contributors.

Please split your changes into smaller PRs. See CONTRIBUTING.md for details.

[lgaudez]

@dyoshikawa I opened this as a draft primarily to get your feedback on the feature direction, not only on the implementation details.

The main question for me is whether this new plugins support actually belongs in Rulesync:

• install-managed plugin artifacts declared from sources
• curated vs local plugin precedence
• user-directory deployment plus lockfile/state tracking

If you think this direction is not something you want Rulesync to own long-term, that is completely valid and very useful feedback for me.

Also, I saw the external contributor policy bot comment about PR size. If the direction itself makes sense to you, I can absolutely split this into smaller follow-up PRs. But before doing that, I wanted to check whether you even want this paradigm in the project.

[dyoshikawa-claw]

Thank you, let's proceed with this. However, please note that the install-related parts may undergo breaking changes in the future.

[lgaudez]

Thank you, that makes sense.

I understand your feedback as:

• the overall direction is okay to move forward with
• but the install-related surface should be treated as still evolving and potentially subject to breaking changes

Given the external contributor size limit, I will split this into smaller follow-up PRs and keep the install-facing parts as minimal and flexible as possible.

My current thought is to separate:

1. the foundational install-managed plugin support
2. the target-specific integrations on top of it

Thanks again for clarifying the direction.

[lgaudez]

One more question on how you would like me to proceed from here.

The external contributor limit is the main practical blocker now: even the foundational commit (feat: add install-managed plugin support) is already too large on its own (1311 added lines), so simply splitting Claude Code and Gemini CLI into separate PRs is not sufficient.

I see two realistic ways forward:

1. Split by layering

   • PR 1: core install-managed plugin foundation only
     • sources[].plugins[]
     • manifest / lockfile / install pipeline
     • minimal CLI + config wiring
   • PR 2: follow-up docs / tests / support-matrix updates for that foundation
   • PR 3+: target-specific integrations (claudecode, geminicli, etc.)

2. Split by minimal vertical slice

   • PR 1: the smallest end-to-end version that introduces the paradigm for one target only
   • PR 2+: extend that same model to additional targets

My concern with option 1 is that the first PR may feel infrastructure-heavy.
My concern with option 2 is that it may hide some of the reusable abstraction until later.

Since you already said we can proceed with the direction, could you let me know which split you would prefer for external-contributor-sized PRs?

If you want, I can also prepare a very small first PR focused only on the install-managed foundation and leave most docs and target expansions for follow-ups.