Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
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
4 changes: 2 additions & 2 deletions .claude/ecosystems/bash.yaml
Original file line number Diff line number Diff line change
Expand Up @@ -18,7 +18,7 @@ check-cmd: |
fix-cmd: null
code-fix-cmd: null
opt-in: "shellcheck and bash -n always apply to CI's shell file list"
install-hint: "shellcheck with no version pin: CI runs sudo apt-get install -y shellcheck on ubuntu-latest (pr-require-checks.yml:96, :102-103) and verifies no checksum. winget install ShellCheck.ShellCheck | brew install shellcheck. The sync-local suite also needs git and python3 (AGENTS.md:36, :93-96), and pwsh for its PowerShell half."
install-hint: "shellcheck with no version pin: CI runs sudo apt-get install -y shellcheck on ubuntu-latest (pr-require-checks.yml:96, :102-103) and verifies no checksum. winget install ShellCheck.ShellCheck | brew install shellcheck. The sync-local suite also needs git and python3 (AGENTS.md:36, :97-100), and pwsh for its PowerShell half."
tool-pin: {}
gates: []
notes: "No tool-pin: CI installs Ubuntu's shellcheck package, so its version follows the runner image (pr-require-checks.yml:102-103). check-cmd lints CI's file list, not <files>: CI runs shellcheck and bash -n over scripts/*.sh and .cursor/install.sh on every change (:105-109) and leaves out .claude/cloud-bootstrap.sh, a standards-synced file (.github/workflows/pr-check-managed-files-hosted.yml:39), which <files> would lint. No --rcfile: shellcheck reads the root .shellcheckrc by itself, as in CI. AGENTS.md's shell line names only scripts/sync-local.sh and .cursor/install.sh (AGENTS.md:42-43); this record follows CI. CI stops at its first failing step; check-cmd runs shellcheck and bash -n over every listed file and fails when any fails. The two test steps run in order with no continue-on-error (:113-117), so CI stops at the first failure and test-cmd chains them with &&. test-sync-local.sh exits 0 when pwsh is missing: the PowerShell half reports as skipped and the bash half still runs (scripts/test-sync-local.sh:10-12, :99-100, :498-504); read its skipped count. Both suites build their fixtures under TMPDIR (scripts/test-sync-local.sh:38, scripts/test-check-docs-naming.sh:10). scripts/check-docs-naming.sh --check, the last step of the same job (:119-120), runs from cross-cutting.yaml, so a docs/ change triggers it. Glob gaps: no job in this workflow has a path filter (:15-37), so CI runs these steps on every change; these globs select only *.sh and *.bash, so a change to another file the suites read runs no local test, for example scripts/sync-local.ps1, the twin the sync-local suite runs (scripts/test-sync-local.sh:28), or .cursor-plugin/marketplace.json and the plugins/ tree, which its repo-dry-run case syncs from (:198)."
notes: "No tool-pin: CI installs Ubuntu's shellcheck package, so its version follows the runner image (pr-require-checks.yml:102-103). check-cmd lints CI's file list, not <files>: CI runs shellcheck and bash -n over scripts/*.sh and .cursor/install.sh on every change (:105-109) and leaves out .claude/cloud-bootstrap.sh, a standards-synced file (.github/workflows/pr-check-managed-files-hosted.yml:39), which <files> would lint. No --rcfile: shellcheck reads the root .shellcheckrc by itself, as in CI. CI stops at its first failing step; check-cmd runs shellcheck and bash -n over every listed file and fails when any fails. The two test steps run in order with no continue-on-error (:113-117), so CI stops at the first failure and test-cmd chains them with &&. test-sync-local.sh exits 0 when pwsh is missing: the PowerShell half reports as skipped and the bash half still runs (scripts/test-sync-local.sh:10-12, :99-100, :498-504); read its skipped count. Both suites build their fixtures under TMPDIR (scripts/test-sync-local.sh:38, scripts/test-check-docs-naming.sh:10). scripts/check-docs-naming.sh --check, the last step of the same job (:119-120), runs from cross-cutting.yaml, so a docs/ change triggers it. Glob gaps: no job in this workflow has a path filter (:15-37), so CI runs these steps on every change; these globs select only *.sh and *.bash, so a change to another file the suites read runs no local test, for example scripts/sync-local.ps1, the twin the sync-local suite runs (scripts/test-sync-local.sh:28), or .cursor-plugin/marketplace.json and the plugins/ tree, which its repo-dry-run case syncs from (:198)."
29 changes: 17 additions & 12 deletions AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -35,19 +35,21 @@ and the `scripts/sync-local.*` sync tooling. See `README.md` and

Only `bash`, `git`, `python3` and `jq` are relied on at runtime; everything in that
table is for checking the repo, not for using it.
- There **is** a test suite: `bash scripts/test-sync-local.sh`. See "Test" below.
- Test suites: `bash scripts/test-sync-local.sh` and
`bash scripts/test-check-docs-naming.sh`. See "Test" below.

### Lint / validate (there is no configured linter — use these proxies)
### Lint / validate

- Shell: prefer `shellcheck scripts/sync-local.sh .cursor/install.sh` **whenever
the tool is available**.
- Shell: prefer `shellcheck scripts/*.sh .cursor/install.sh` **whenever
the tool is available**; it is CI's command.
`bash -n` only *parses* — it exited clean over a path traversal, a silently swallowed
failure, and a GNU-only `find` builtin that all had to be found and fixed by hand.
`shellcheck` catches that class. It is packaged for Debian/Ubuntu, so if it is missing
install it (`sudo apt-get install -y shellcheck`) when the network allows. Do **not**
assume it is preinstalled: probe with `command -v shellcheck` first.
Only if it can be neither found nor installed, fall back to
`bash -n scripts/sync-local.sh .cursor/install.sh` as the floor — a syntax check, not a lint.
`for f in scripts/*.sh .cursor/install.sh; do bash -n "$f"; done` as the floor — a
syntax check, not a lint. `bash -n` parses only its first file argument, hence the loop.
The default rule set must stay at zero findings; a repo-root `.shellcheckrc`, if
present, records which *optional* checks were considered and deliberately declined.
- JSON manifests: `jq empty .cursor-plugin/marketplace.json` and
Expand All @@ -74,11 +76,13 @@ and the `scripts/sync-local.*` sync tooling. See `README.md` and
never touches your real `~/.cursor`.
- `pwsh` is optional: without it the PowerShell half reports as skipped and the bash half
still runs.
- Add a case whenever you fix a defect here. The suite already pins the ones that were
found the hard way: path traversal via a plugin `name` and via an entry `source`, a
`pluginRoot` that escapes the repo, an empty `plugins/` and `"plugins": []` (which used
to exit 0 printing `Synced (0)`), a nameless marketplace entry (which used to dump a
Python traceback), prefix-name sort order, a symlinked plugin directory (which must
- `bash scripts/test-check-docs-naming.sh` — the regression suite for
`scripts/check-docs-naming.sh`.
- Add a case whenever you fix a defect here. The sync-local suite pins: path traversal
via a plugin `name` and via an entry `source`, a `pluginRoot` that escapes the repo, an
empty `plugins/` and `"plugins": []` (exit 1, never `Synced (0)`), a nameless
marketplace entry (exit 1 with no Python traceback), prefix-name sort order, a
symlinked plugin directory (which must
install as a **real** directory, not a link), implicit source (no path/URL), and
local-git update (fast-forward a behind checkout, leave a dirty tree and a
`--no-update` / `--dry-run` run behind, and update a submodule gitlink after
Expand Down Expand Up @@ -122,7 +126,8 @@ and the `scripts/sync-local.*` sync tooling. See `README.md` and

### CI

`.github/workflows/pr-require-checks.yml` runs the checks above on every push and pull request: shell
`.github/workflows/pr-require-checks.yml` runs the checks above on every pull request
and every push to `main`: shell
lint of `scripts/*.sh` **and** `.cursor/install.sh`, plus the regression suite,
PSScriptAnalyzer, JSON and schema validation of the manifests and
`.cursor/environment.json`, internal markdown link integrity (a relative-link
Expand Down Expand Up @@ -192,4 +197,4 @@ Each line names a rule CI does not enforce; the linked file states it in full.
blockers) in the PR: [trust review](docs/migration-playbook.md#trust-review-mcp--hooks).
- A sync-local defect fix adds a regression case to the twin suite: [test](#test).
- A PSScriptAnalyzer suppression carries a written Justification:
[lint](#lint--validate-there-is-no-configured-linter--use-these-proxies).
[lint](#lint--validate).
6 changes: 6 additions & 0 deletions docs/plugin-philosophy.md
Original file line number Diff line number Diff line change
Expand Up @@ -14,6 +14,12 @@ it. Publisher metadata may identify its source; runtime behavior must not depend
on publisher names, organization-specific environment variables, repository
names, absolute machine paths, or an undocumented consumer layout.

Recorded exception: the `plugin-ops` `sync-local` skill and the repo-root
`scripts/sync-local.*` it runs. When no source is passed and the open workspace is
not a plugin or marketplace, they fall back to this marketplace's own checkout:
`MELODIC_CURSOR_PLUGINS`, a short list of known checkout paths, then the repository
URL. An explicit path or URL needs none of them.

Keep plugins horizontally decoupled:

- A plugin owns its skills, rules, agents, hooks, MCP config, scripts, and state.
Expand Down
6 changes: 3 additions & 3 deletions plugins/automations/skills/design-automation/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -96,13 +96,13 @@ it.

## Compose the prompt

Skip this section on the managed-agent path. Otherwise, structure the prompt in this
order:
Skip this section on the managed-agent path. Otherwise the prompt covers each of these,
in the order that reads best for the lane:

1. Role and goal (one paragraph).
2. Inputs the run can rely on: trigger payload, repository, config keys and where they are
bound (env var name, rule name, MCP lookup).
3. Procedure as numbered steps, each verifiable.
3. The procedure, each step verifiable; number steps only where their order matters.
4. Decision rules: the do-nothing conditions first, then act conditions.
5. Guardrails from *Guardrails baked into every generated prompt* in `lanes.md`, adapted
to the lane, never removed.
Expand Down
15 changes: 6 additions & 9 deletions plugins/plugin-ops/skills/install-marketplace/SKILL.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
---
name: install-marketplace
description: Install a Cursor plugin marketplace or plugin for the user's plan (Ultra/personal, Teams, Enterprise). Fetches official Cursor docs live, then guides /plugin marketplace add, Team Dashboard import, or local sync.
description: Install a Cursor plugin marketplace or plugin for the user's plan (Ultra/personal, Teams, Enterprise). Fetches official Cursor docs live, then guides /plugin marketplace add, Team Dashboard import, or local sync. Use when someone wants to add or install a plugin or marketplace, or asks which install route fits their plan.
---

# Install a Cursor marketplace / plugin (plan-aware)
Expand All @@ -16,11 +16,9 @@ Before any recommendation, fetch and skim:
Use `plugins/plugin-ops/reference/doc-sources.md`. **Docs win** over this skill.
Melodic policy: `docs/plugin-philosophy.md`.

**Verified 2026-08-30.** The literal string `/add-plugin` does not appear anywhere in
the current docs. A **user-scoped marketplace added by git URL** very much does — it
just has a different command. From
https://cursor.com/docs/cli/reference/slash-commands and
https://cursor.com/docs/cli/changelog:
**Observed 2026-08-30** on https://cursor.com/docs/cli/reference/slash-commands and
https://cursor.com/docs/cli/changelog (re-fetch both before advising), a
**user-scoped marketplace added by git URL** is documented:

- `/plugin marketplace add <git-url>` registers a marketplace; `/plugin` also browses
and manages marketplaces **by scope** and installs at user or project scope.
Expand All @@ -29,9 +27,8 @@ https://cursor.com/docs/cli/changelog:
the repository, and `remove` for a **user-scoped** marketplace.
- `--plugin-dir <path>` loads a local plugin directory.

So `/add-plugin` is a **renamed** command, not a removed capability. Do not tell a user
that personal, non-team marketplaces are undocumented — route them to
`/plugin marketplace add` instead. Re-fetch both pages before advising.
`/add-plugin` is the old name for `/plugin marketplace add`; a user who says it
means this route.

## Clarify

Expand Down
6 changes: 3 additions & 3 deletions plugins/plugin-ops/skills/sync-local/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -31,9 +31,9 @@ Ask only if missing:

## Resolve source — do not search the disk

The hang that made `/sync-local` look stuck was **not** the copy. It was
recursive `Get-ChildItem` / glob / `rg` under `$HOME`, OneDrive, Documents, or
AppData. Those walks take minutes on Windows and are forbidden here.
Do not search for a checkout with recursive `Get-ChildItem` / glob / `rg` under
`$HOME`, OneDrive, Documents, or AppData: those walks take minutes on Windows
and make the sync look hung.

Resolve source with `Test-Path` / `[ -d ]` on this list, then **stop**:

Expand Down
13 changes: 5 additions & 8 deletions plugins/plugin-ops/skills/update-plugins/SKILL.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
---
name: update-plugins
description: Update installed Cursor plugins/marketplaces for the user's plan. Fetches official docs live; covers Team Auto Refresh, /plugin marketplace update for personally-added marketplaces, and local sync-from-URL/path.
description: Update installed Cursor plugins/marketplaces for the user's plan. Fetches official docs live; covers Team Auto Refresh, /plugin marketplace update for personally-added marketplaces, and local sync-from-URL/path. Use when installed plugins look stale, a marketplace update appears to do nothing, or someone asks how to refresh plugins.
---

# Update Cursor plugins (plan-aware)
Expand All @@ -14,13 +14,10 @@ description: Update installed Cursor plugins/marketplaces for the user's plan. F
`plugins/plugin-ops/reference/doc-sources.md` lists URLs. **Docs win.**
Melodic policy: `docs/plugin-philosophy.md`.

**Verified 2026-08-30.** The string `/add-plugin` does not appear in the current docs,
but the capability was renamed, not removed: `/plugin marketplace add <git-url>`
registers a **user-scoped** marketplace, and `/plugin marketplace update` re-indexes
one from its repository (https://cursor.com/docs/cli/reference/slash-commands,
https://cursor.com/docs/cli/changelog). So there *is* a documented refresh story for
personally-added marketplaces. Read the row below as the current command, and treat
`/add-plugin` as the old name users may still say. See `install-marketplace`.
**Observed 2026-08-30** (https://cursor.com/docs/cli/reference/slash-commands,
https://cursor.com/docs/cli/changelog): `/plugin marketplace add <git-url>` registers a
**user-scoped** marketplace, and `/plugin marketplace update` re-indexes it from its
repository. `/add-plugin` is the old name users may still say. See `install-marketplace`.

## Clarify how they installed

Expand Down
2 changes: 1 addition & 1 deletion plugins/plugin-ops/skills/verify-plugin/SKILL.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
---
name: verify-plugin
description: Validate a Cursor plugin or marketplace checkout against live official Cursor plugin reference docs (manifests, discovery paths, frontmatter), then Melodic marketplace policy (skills-first; no new commands/).
description: Validate a Cursor plugin or marketplace checkout against live official Cursor plugin reference docs (manifests, discovery paths, frontmatter), then Melodic marketplace policy (skills-first; no new commands/). Use when checking a plugin or marketplace before publishing or after a port, or when a manifest fails to load or validate.
---

# Verify Cursor plugin / marketplace layout
Expand Down
Loading