From 72fbf0ebba2bc8c1b0d60a5d0d9bc0530ec9da0c Mon Sep 17 00:00:00 2001 From: Kyle Sexton <153232337+kyle-sexton@users.noreply.github.com> Date: Sat, 14 Nov 2026 12:53:47 -0500 Subject: [PATCH] docs: align agent instructions with CI and drop incident history AGENTS.md named a shell-lint file list narrower than CI's, a bash -n fallback that parsed only its first file, and a push trigger wider than the workflow's. Three plugin-ops skills and the test notes stated rules as past incidents. The design boundary now records the sync-local fallback as an exception. Co-Authored-By: Claude Fable 5.2 Claude-Session: https://claude.ai/code/session_015XWwmdRVNmhT8VQkrZ53Fw --- .claude/ecosystems/bash.yaml | 4 +-- AGENTS.md | 29 +++++++++++-------- docs/plugin-philosophy.md | 6 ++++ .../skills/design-automation/SKILL.md | 6 ++-- .../skills/install-marketplace/SKILL.md | 15 ++++------ plugins/plugin-ops/skills/sync-local/SKILL.md | 6 ++-- .../plugin-ops/skills/update-plugins/SKILL.md | 13 ++++----- .../plugin-ops/skills/verify-plugin/SKILL.md | 2 +- 8 files changed, 43 insertions(+), 38 deletions(-) diff --git a/.claude/ecosystems/bash.yaml b/.claude/ecosystems/bash.yaml index c77520d..cf787ee 100644 --- a/.claude/ecosystems/bash.yaml +++ b/.claude/ecosystems/bash.yaml @@ -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 : 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 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 : 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 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)." diff --git a/AGENTS.md b/AGENTS.md index dbc6f2c..3bf3012 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -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 @@ -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 @@ -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 @@ -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). diff --git a/docs/plugin-philosophy.md b/docs/plugin-philosophy.md index 8464f34..828d3ee 100644 --- a/docs/plugin-philosophy.md +++ b/docs/plugin-philosophy.md @@ -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. diff --git a/plugins/automations/skills/design-automation/SKILL.md b/plugins/automations/skills/design-automation/SKILL.md index 0ecd404..7305c7d 100644 --- a/plugins/automations/skills/design-automation/SKILL.md +++ b/plugins/automations/skills/design-automation/SKILL.md @@ -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. diff --git a/plugins/plugin-ops/skills/install-marketplace/SKILL.md b/plugins/plugin-ops/skills/install-marketplace/SKILL.md index 8252d83..a20d87f 100644 --- a/plugins/plugin-ops/skills/install-marketplace/SKILL.md +++ b/plugins/plugin-ops/skills/install-marketplace/SKILL.md @@ -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) @@ -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 ` registers a marketplace; `/plugin` also browses and manages marketplaces **by scope** and installs at user or project scope. @@ -29,9 +27,8 @@ https://cursor.com/docs/cli/changelog: the repository, and `remove` for a **user-scoped** marketplace. - `--plugin-dir ` 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 diff --git a/plugins/plugin-ops/skills/sync-local/SKILL.md b/plugins/plugin-ops/skills/sync-local/SKILL.md index 1cfd3ab..c874c9e 100644 --- a/plugins/plugin-ops/skills/sync-local/SKILL.md +++ b/plugins/plugin-ops/skills/sync-local/SKILL.md @@ -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**: diff --git a/plugins/plugin-ops/skills/update-plugins/SKILL.md b/plugins/plugin-ops/skills/update-plugins/SKILL.md index 58f1564..c4b36df 100644 --- a/plugins/plugin-ops/skills/update-plugins/SKILL.md +++ b/plugins/plugin-ops/skills/update-plugins/SKILL.md @@ -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) @@ -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 ` -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 ` 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 diff --git a/plugins/plugin-ops/skills/verify-plugin/SKILL.md b/plugins/plugin-ops/skills/verify-plugin/SKILL.md index a3d8b8a..179e94e 100644 --- a/plugins/plugin-ops/skills/verify-plugin/SKILL.md +++ b/plugins/plugin-ops/skills/verify-plugin/SKILL.md @@ -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