diff --git a/.github/workflows/pr-require-checks.yml b/.github/workflows/pr-require-checks.yml index 32df1bc..1a1f473 100644 --- a/.github/workflows/pr-require-checks.yml +++ b/.github/workflows/pr-require-checks.yml @@ -113,6 +113,12 @@ jobs: - name: sync-local regression suite run: bash scripts/test-sync-local.sh + - name: docs-naming regression suite + run: bash scripts/test-check-docs-naming.sh + + - name: docs/ filenames are lower-kebab-case + run: bash scripts/check-docs-naming.sh --check + psscriptanalyzer: name: PowerShell (PSScriptAnalyzer) # The contract-only predicate, verbatim (see the `on.pull_request` comment). diff --git a/AGENTS.md b/AGENTS.md index 75ca8d9..6d47d18 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -6,7 +6,7 @@ This repository is a **Cursor plugin marketplace** (not a compiled application). contains Markdown docs, JSON manifests (`.cursor-plugin/marketplace.json`, `plugins//.cursor-plugin/plugin.json`), plugin skills (`skills//SKILL.md`), and the `scripts/sync-local.*` sync tooling. See `README.md` and -`docs/PLUGIN-PHILOSOPHY.md` for the full model. +`docs/plugin-philosophy.md` for the full model. ### Environment / dependencies @@ -98,21 +98,25 @@ and the `scripts/sync-local.*` sync tooling. See `README.md` and automation lane and write a source-controlled record) and `plugins/capabilities` (inventory what a session can already do). Exercising them means running the skill in an agent session; there is nothing to execute from a shell. Each keeps its own live-doc - index at `plugins//reference/DOC-SOURCES.md`, tiered by authority and dated by - live fetch under the same "Verified means fetched" rule as `docs/OFFICIAL-DOCS.md`. + index at `plugins//reference/doc-sources.md`, tiered by authority and dated by + live fetch under the same "Verified means fetched" rule as `docs/official-docs.md`. ### Doc conventions - **How to cite a repo path in Markdown.** In human-facing files — `README.md`, `docs/*.md`, `plugins/*/README.md`, `plugins/*/reference/*.md` — cite a repo file as a **resolvable relative link** — from `plugins/plugin-ops/README.md` that is - `[docs/PLUGIN-PHILOSOPHY.md]` followed by `(../../docs/PLUGIN-PHILOSOPHY.md)` — so it + `[docs/plugin-philosophy.md]` followed by `(../../docs/plugin-philosophy.md)` — so it renders as a working link on GitHub. Inside a `SKILL.md` **body** the reader is an agent with the repo checked out, so a bare repo-root-relative code span — - `docs/PLUGIN-PHILOSOPHY.md` — is the convention, the same one this file uses. Pick the + `docs/plugin-philosophy.md` — is the convention, the same one this file uses. Pick the style from the file's kind and do not mix the two within one file. -- Doc dates (`Verified` columns in `docs/OFFICIAL-DOCS.md` and - `docs/PLUGIN-PHILOSOPHY.md`) mean "a live fetch of that URL still matched this row on +- **Name `docs/` and `plugins/*/reference/` files in lower-kebab-case.** The exceptions are the conventional names + `README`, `AGENTS`, `CLAUDE`, `CHANGELOG`, `LICENSE`, `SKILL`, `CONTRIBUTING`, + `SECURITY`, `REVIEW` and `CODE_OF_CONDUCT`. `bash scripts/check-docs-naming.sh --check` + enforces it in CI. +- Doc dates (`Verified` columns in `docs/official-docs.md` and + `docs/plugin-philosophy.md`) mean "a live fetch of that URL still matched this row on that date". Never bump one without fetching. A 403/429 is a blocked fetch, not a verification and not a dead link — record it as blocked and leave the old date. @@ -175,15 +179,15 @@ Each line names a rule CI does not enforce; the linked file states it in full. - Org-wide criteria: [`REVIEW.md`](https://github.com/melodic-software/standards/blob/main/REVIEW.md) in `melodic-software/standards`. - Plugin design boundary: no sibling-plugin imports and no runtime dependence on - org names, repos or machine paths: [rule](docs/PLUGIN-PHILOSOPHY.md#design-boundary). + org names, repos or machine paths: [rule](docs/plugin-philosophy.md#design-boundary). - No new `commands/` files; procedures ship as skills: - [component stances](docs/PLUGIN-PHILOSOPHY.md#component-stances). + [component stances](docs/plugin-philosophy.md#component-stances). - A `Verified` date moves only on a live fetch that matched; a blocked fetch keeps the old date: [doc conventions](#doc-conventions). - A port records one PR line per non-trivial reshape or drop decision: - [pre-port review](docs/MIGRATION-PLAYBOOK.md#mandatory-pre-port-review-keep--reshape--drop). + [pre-port review](docs/migration-playbook.md#mandatory-pre-port-review-keep--reshape--drop). - A port or version bump that adds MCP servers or hooks records its trust review (ACCEPT or - blockers) in the PR: [trust review](docs/MIGRATION-PLAYBOOK.md#trust-review-mcp--hooks). + 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). diff --git a/README.md b/README.md index 300e35b..3dd4b92 100644 --- a/README.md +++ b/README.md @@ -12,9 +12,9 @@ runtime behavior here are Cursor-only. | Doc | Purpose | | --- | --- | -| [docs/PLUGIN-PHILOSOPHY.md](docs/PLUGIN-PHILOSOPHY.md) | Component stances, skills-first policy, Claude vs Cursor | -| [docs/MIGRATION-PLAYBOOK.md](docs/MIGRATION-PLAYBOOK.md) | Port gates from Claude → Cursor | -| [docs/OFFICIAL-DOCS.md](docs/OFFICIAL-DOCS.md) | Official URL jump sheet (fetch live; not a procedure cache) | +| [docs/plugin-philosophy.md](docs/plugin-philosophy.md) | Component stances, skills-first policy, Claude vs Cursor | +| [docs/migration-playbook.md](docs/migration-playbook.md) | Port gates from Claude → Cursor | +| [docs/official-docs.md](docs/official-docs.md) | Official URL jump sheet (fetch live; not a procedure cache) | ## Layout @@ -25,9 +25,9 @@ plugins// skills/ # primary capability surface agents/ | rules/ | hooks/ | mcp.json # adopt on need scripts/sync-local.* # sync any path/URL into ~/.cursor/plugins/local -docs/PLUGIN-PHILOSOPHY.md -docs/MIGRATION-PLAYBOOK.md -docs/OFFICIAL-DOCS.md +docs/plugin-philosophy.md +docs/migration-playbook.md +docs/official-docs.md ``` Skills are the primary surface (they appear in Agent `/`). Do not add new @@ -84,8 +84,8 @@ Plan cheat-sheet (always re-check live docs): ## Contributing -1. Follow [docs/PLUGIN-PHILOSOPHY.md](docs/PLUGIN-PHILOSOPHY.md); fetch live docs via [docs/OFFICIAL-DOCS.md](docs/OFFICIAL-DOCS.md) / `plugin-ops`. -2. Port Claude ideas via [docs/MIGRATION-PLAYBOOK.md](docs/MIGRATION-PLAYBOOK.md). +1. Follow [docs/plugin-philosophy.md](docs/plugin-philosophy.md); fetch live docs via [docs/official-docs.md](docs/official-docs.md) / `plugin-ops`. +2. Port Claude ideas via [docs/migration-playbook.md](docs/migration-playbook.md). 3. Open a PR against `main`. ## Governance diff --git a/docs/MIGRATION-PLAYBOOK.md b/docs/migration-playbook.md similarity index 95% rename from docs/MIGRATION-PLAYBOOK.md rename to docs/migration-playbook.md index 842b520..1f75976 100644 --- a/docs/MIGRATION-PLAYBOOK.md +++ b/docs/migration-playbook.md @@ -4,8 +4,8 @@ This repo is the **Cursor-native** Melodic marketplace. It is intentionally separate from [`melodic-software/claude-code-plugins`](https://github.com/melodic-software/claude-code-plugins). -Design policy SSOT: [PLUGIN-PHILOSOPHY.md](PLUGIN-PHILOSOPHY.md). -Official URL pointers: [OFFICIAL-DOCS.md](OFFICIAL-DOCS.md) (fetch live). +Design policy SSOT: [plugin-philosophy.md](plugin-philosophy.md). +Official URL pointers: [official-docs.md](official-docs.md) (fetch live). Do **not** dual-read Claude manifests at runtime. Do **not** regenerate `.cursor-plugin/` from Claude plugins as a continuous export into the Claude @@ -32,7 +32,7 @@ repo. Migrate and adapt here. ## Mandatory pre-port review (keep / reshape / drop) For **every** Claude component before copying files, decide using live Cursor -docs + [PLUGIN-PHILOSOPHY.md](PLUGIN-PHILOSOPHY.md) stances: +docs + [plugin-philosophy.md](plugin-philosophy.md) stances: | Claude surface | Default decision | Notes | | --- | --- | --- | @@ -72,7 +72,7 @@ For each Claude plugin you choose to port: `minClientVersions` — narrower than the "Plugin entry fields" table in the plugins reference, so validate against `marketplace.schema.json`, not the prose table. 7. **Acceptance gates** (all required before merge): - - Component-stance check against [PLUGIN-PHILOSOPHY.md](PLUGIN-PHILOSOPHY.md) + - Component-stance check against [plugin-philosophy.md](plugin-philosophy.md) - Live verify via `verify-plugin` skill (Cursor checklist + Melodic policy) - Local sync into `~/.cursor/plugins/local//` (real copy) and **Developer: Reload Window** diff --git a/docs/OFFICIAL-DOCS.md b/docs/official-docs.md similarity index 89% rename from docs/OFFICIAL-DOCS.md rename to docs/official-docs.md index 0bbb0db..5277807 100644 --- a/docs/OFFICIAL-DOCS.md +++ b/docs/official-docs.md @@ -8,10 +8,10 @@ Skills under `plugins/plugin-ops/` **fetch these pages live** before advising. > content as procedures. When docs and this repo disagree, **docs win**. A fetch > that no longer matches a row is that row’s recheck trigger: update the row and > its verified date. Skill-facing copy of the URL list: -> [`plugins/plugin-ops/reference/DOC-SOURCES.md`](../plugins/plugin-ops/reference/DOC-SOURCES.md). +> [`plugins/plugin-ops/reference/doc-sources.md`](../plugins/plugin-ops/reference/doc-sources.md). -Policy: [PLUGIN-PHILOSOPHY.md](PLUGIN-PHILOSOPHY.md). -Ports: [MIGRATION-PLAYBOOK.md](MIGRATION-PLAYBOOK.md). +Policy: [plugin-philosophy.md](plugin-philosophy.md). +Ports: [migration-playbook.md](migration-playbook.md). ## Plugin components → doc page @@ -56,15 +56,15 @@ Those concerns have their own tiered source indexes, owned by the plugin that re | Concern | Index | | --- | --- | -| Automations, cloud agent runtime, trigger sources, managed agents, programmatic lanes | [`plugins/automations/reference/DOC-SOURCES.md`](../plugins/automations/reference/DOC-SOURCES.md) | -| Built-in skills, agent tools, plugins, MCP, integrations, plan gates | [`plugins/capabilities/reference/DOC-SOURCES.md`](../plugins/capabilities/reference/DOC-SOURCES.md) | +| Automations, cloud agent runtime, trigger sources, managed agents, programmatic lanes | [`plugins/automations/reference/doc-sources.md`](../plugins/automations/reference/doc-sources.md) | +| Built-in skills, agent tools, plugins, MCP, integrations, plan gates | [`plugins/capabilities/reference/doc-sources.md`](../plugins/capabilities/reference/doc-sources.md) | Both start from the live page index https://cursor.com/docs/llms.txt (verified 2026-09-02), which is the self-healing root for every URL in this repository. Optional community index (not official): https://cursor.directory — **blocked**, HTTP 429 via proxy on 2026-08-30 (rate limit, not a dead link; see -[DOC-SOURCES fetch status](../plugins/plugin-ops/reference/DOC-SOURCES.md#fetch-status-2026-09-02)). +[doc-sources fetch status](../plugins/plugin-ops/reference/doc-sources.md#fetch-status-2026-09-02)). Rows dated **2026-09-02** were re-fetched this session and still matched. `https://cursor.com/help/customization/skills` timed out on 2026-09-02: leave @@ -77,7 +77,7 @@ edited that day". Ideas may come from [`melodic-software/claude-code-plugins`](https://github.com/melodic-software/claude-code-plugins). Manifests and runtime here are Cursor-only. Do not treat Claude “commands merged / -prohibited” as Cursor platform law — see [PLUGIN-PHILOSOPHY.md](PLUGIN-PHILOSOPHY.md). +prohibited” as Cursor platform law — see [plugin-philosophy.md](plugin-philosophy.md). | Topic | Official Claude doc | | --- | --- | diff --git a/docs/PLUGIN-PHILOSOPHY.md b/docs/plugin-philosophy.md similarity index 95% rename from docs/PLUGIN-PHILOSOPHY.md rename to docs/plugin-philosophy.md index f9e090c..8464f34 100644 --- a/docs/PLUGIN-PHILOSOPHY.md +++ b/docs/plugin-philosophy.md @@ -1,9 +1,9 @@ # Plugin philosophy (Cursor) Durable design policy for plugins in this marketplace. The -[migration playbook](MIGRATION-PLAYBOOK.md) applies it when porting from +[migration playbook](migration-playbook.md) applies it when porting from [`claude-code-plugins`](https://github.com/melodic-software/claude-code-plugins). -Official URL pointers live in [OFFICIAL-DOCS.md](OFFICIAL-DOCS.md) — **fetch live; +Official URL pointers live in [official-docs.md](official-docs.md) — **fetch live; never treat this file as a procedure cache.** ## Design boundary @@ -31,8 +31,8 @@ runtime. Do not auto-export Cursor artifacts into `claude-code-plugins`. Before advising on install, update, marketplace layout, component format, or changing a stance row below: -1. Fetch the relevant pages from [OFFICIAL-DOCS.md](OFFICIAL-DOCS.md) / - [`plugins/plugin-ops/reference/DOC-SOURCES.md`](../plugins/plugin-ops/reference/DOC-SOURCES.md). +1. Fetch the relevant pages from [official-docs.md](official-docs.md) / + [`plugins/plugin-ops/reference/doc-sources.md`](../plugins/plugin-ops/reference/doc-sources.md). 2. Prefer the fetched page over this file, training data, or prior chat memory. 3. If a fetch diverges from a stance row, update the row and its verified date. @@ -128,6 +128,6 @@ native one matures. ## Related -- [MIGRATION-PLAYBOOK.md](MIGRATION-PLAYBOOK.md) — port gates and acceptance -- [OFFICIAL-DOCS.md](OFFICIAL-DOCS.md) — URL jump sheet +- [migration-playbook.md](migration-playbook.md) — port gates and acceptance +- [official-docs.md](official-docs.md) — URL jump sheet - [`plugin-ops`](../plugins/plugin-ops/README.md) — install / update / sync / verify skills diff --git a/plugins/automations/.cursor-plugin/plugin.json b/plugins/automations/.cursor-plugin/plugin.json index ec7b2a4..52059d0 100644 --- a/plugins/automations/.cursor-plugin/plugin.json +++ b/plugins/automations/.cursor-plugin/plugin.json @@ -1,6 +1,6 @@ { "name": "automations", - "version": "0.1.0", + "version": "0.1.1", "description": "Design Cursor Automations lane by lane — trigger source, runtime, tools, identity, config seams, guardrails — and record the prompt in source control. Every platform fact is read from live official docs, never from a cached copy.", "author": { "name": "Melodic Software", diff --git a/plugins/automations/README.md b/plugins/automations/README.md index db6656e..72543e7 100644 --- a/plugins/automations/README.md +++ b/plugins/automations/README.md @@ -5,12 +5,12 @@ keep the prompt in source control while the platform has no config-as-code. Skills **fetch official Cursor docs live** before stating any platform fact; the plugin holds pointers and procedure, never copied documentation. Sources and their read order: -[`reference/DOC-SOURCES.md`](reference/DOC-SOURCES.md). Lane model, selection order, and +[`reference/doc-sources.md`](reference/doc-sources.md). Lane model, selection order, and the cross-cutting seams (plan gates, repository scope, identity, config binding, -concurrency, guardrails): [`reference/LANES.md`](reference/LANES.md). +concurrency, guardrails): [`reference/lanes.md`](reference/lanes.md). Melodic policy (skills primary; no `commands/`): -[`docs/PLUGIN-PHILOSOPHY.md`](../../docs/PLUGIN-PHILOSOPHY.md). +[`docs/plugin-philosophy.md`](../../docs/plugin-philosophy.md). ## Skills diff --git a/plugins/automations/reference/DOC-SOURCES.md b/plugins/automations/reference/doc-sources.md similarity index 98% rename from plugins/automations/reference/DOC-SOURCES.md rename to plugins/automations/reference/doc-sources.md index c0d6adc..1e6efa5 100644 --- a/plugins/automations/reference/DOC-SOURCES.md +++ b/plugins/automations/reference/doc-sources.md @@ -6,8 +6,8 @@ a trigger, tool, setting, or plan limit behaves — that text lives upstream and without notice. When a fetched page and anything in this repo disagree, **the page wins**, and the disagreement is the trigger to update this index. -Repo policy: [`docs/PLUGIN-PHILOSOPHY.md`](../../../docs/PLUGIN-PHILOSOPHY.md). -Lane model this index serves: [`LANES.md`](LANES.md). +Repo policy: [`docs/plugin-philosophy.md`](../../../docs/plugin-philosophy.md). +Lane model this index serves: [`lanes.md`](lanes.md). ## Read order diff --git a/plugins/automations/reference/LANES.md b/plugins/automations/reference/lanes.md similarity index 98% rename from plugins/automations/reference/LANES.md rename to plugins/automations/reference/lanes.md index c01948f..372735d 100644 --- a/plugins/automations/reference/LANES.md +++ b/plugins/automations/reference/lanes.md @@ -2,7 +2,7 @@ A **lane** is one trigger source, one responsibility, one kind of output. It is the unit this plugin designs, stores, and reviews. Lanes are chosen from what the platform offers -**today**, read from the pages in [`DOC-SOURCES.md`](DOC-SOURCES.md); this file only +**today**, read from the pages in [`doc-sources.md`](doc-sources.md); this file only names the lanes, says which pages decide each one, and fixes the selection order. Every statement below that names a concrete trigger, tool, setting, or limit is an @@ -112,7 +112,7 @@ their plan offers. Channels, in preference order, with the page that documents e ### Concurrency and idempotency -Staff statements (Tier 3, see `DOC-SOURCES.md`): scheduled fires are skipped while a run +Staff statements (Tier 3, see `doc-sources.md`): scheduled fires are skipped while a run of the same automation is active; manual runs have no guard; event triggers are not described. Team-wide concurrent-agent and on-demand spend limits block runs. Therefore every prompt states its idempotency rule explicitly: **inspect current state before diff --git a/plugins/automations/skills/design-automation/SKILL.md b/plugins/automations/skills/design-automation/SKILL.md index fe97541..0ecd404 100644 --- a/plugins/automations/skills/design-automation/SKILL.md +++ b/plugins/automations/skills/design-automation/SKILL.md @@ -15,14 +15,14 @@ gap with an assumption, and never state a platform fact you did not read this se page this skill names, because pages move. 2. Fetch https://cursor.com/docs/automations and read *Triggers*, *Tools*, *Automation settings* (Repositories, Permissions, Identity), *Billing*, and *Writing prompts*. -3. Open `plugins/automations/reference/LANES.md`, pick the candidate lanes, and fetch the +3. Open `plugins/automations/reference/lanes.md`, pick the candidate lanes, and fetch the pages its catalog names for them (managed agents, integrations, API, CLI). 4. Fetch the plan gate on the **feature page** for anything gated (Jira, Team Rules, Team Owned scope, marketplaces, managed agents). 5. State the fetch date in your reply. If a page times out or returns 403/429, say it is unverified; do not fall back to memory. -Source policy and tiers: `plugins/automations/reference/DOC-SOURCES.md`. Docs win over +Source policy and tiers: `plugins/automations/reference/doc-sources.md`. Docs win over this skill, over training data, and over any blog. ## Discover before you ask @@ -61,7 +61,7 @@ lands in the decision record. Minimum set, skipping anything discovery already a section as fetched. Default to the fewest. 7. **Config keys.** Every consumer-specific value the prompt needs (field ids, state names, rosters, prefixes) as a **named key**, and which binding channel the consumer - will use (see *Config binding* in `LANES.md`). + will use (see *Config binding* in `lanes.md`). 8. **Quality bar.** When to open a PR, when to comment, when to do nothing. 9. **Output.** What artifact the world should see, in what format, where. 10. **Failure and idempotency.** What to do on partial state, on a re-fire, on missing @@ -71,7 +71,7 @@ lands in the decision record. Minimum set, skipping anything discovery already a ## Choose the lane -Apply *Selection order* from `plugins/automations/reference/LANES.md` top-down and stop +Apply *Selection order* from `plugins/automations/reference/lanes.md` top-down and stop at the first fit. Hard requirements come first: a consumer who *requires* deterministic surrounding steps, a `.github/workflows` definition, or orchestration from their own system gets `api-and-cli` before any trigger is considered. Next, a managed agent @@ -104,7 +104,7 @@ order: bound (env var name, rule name, MCP lookup). 3. Procedure as numbered steps, each verifiable. 4. Decision rules: the do-nothing conditions first, then act conditions. -5. Guardrails from *Guardrails baked into every generated prompt* in `LANES.md`, adapted +5. Guardrails from *Guardrails baked into every generated prompt* in `lanes.md`, adapted to the lane, never removed. 6. Idempotency rule: inspect current state first; update or stop if the outcome already exists. diff --git a/plugins/capabilities/.cursor-plugin/plugin.json b/plugins/capabilities/.cursor-plugin/plugin.json index b383614..04f3a89 100644 --- a/plugins/capabilities/.cursor-plugin/plugin.json +++ b/plugins/capabilities/.cursor-plugin/plugin.json @@ -1,6 +1,6 @@ { "name": "capabilities", - "version": "0.1.0", + "version": "0.1.1", "description": "Discover what this Cursor session can already do — built-in skills, managed agents, installed plugins and skills, MCP servers, integrations — on the current plan and surface, and prefer composing native capabilities over writing new prompts. Read from live official docs and the local machine, never from a cached list.", "author": { "name": "Melodic Software", diff --git a/plugins/capabilities/README.md b/plugins/capabilities/README.md index f44e600..3be2971 100644 --- a/plugins/capabilities/README.md +++ b/plugins/capabilities/README.md @@ -6,8 +6,8 @@ Cursor-managed agents, integrations, installed plugins and skills, MCP servers surface (IDE, CLI, cloud agent, automation) and plan in use. The plugin holds pointers and procedure, never a copied list. Sources and read order: -[`reference/DOC-SOURCES.md`](reference/DOC-SOURCES.md). Melodic policy (skills primary; -no `commands/`): [`docs/PLUGIN-PHILOSOPHY.md`](../../docs/PLUGIN-PHILOSOPHY.md). +[`reference/doc-sources.md`](reference/doc-sources.md). Melodic policy (skills primary; +no `commands/`): [`docs/plugin-philosophy.md`](../../docs/plugin-philosophy.md). ## Skills diff --git a/plugins/capabilities/reference/DOC-SOURCES.md b/plugins/capabilities/reference/doc-sources.md similarity index 98% rename from plugins/capabilities/reference/DOC-SOURCES.md rename to plugins/capabilities/reference/doc-sources.md index 0d1182b..5854a20 100644 --- a/plugins/capabilities/reference/DOC-SOURCES.md +++ b/plugins/capabilities/reference/doc-sources.md @@ -5,7 +5,7 @@ ships; it fetches these pages and inspects the machine it is running on, then re what exists **today**. A built-in skill, tool, integration, or plan limit named anywhere in this repository is an observation with a date, never a fact to reuse. -Repo policy: [`docs/PLUGIN-PHILOSOPHY.md`](../../../docs/PLUGIN-PHILOSOPHY.md). +Repo policy: [`docs/plugin-philosophy.md`](../../../docs/plugin-philosophy.md). ## Read order diff --git a/plugins/capabilities/skills/discover-capabilities/SKILL.md b/plugins/capabilities/skills/discover-capabilities/SKILL.md index e6b1241..2fb1e4c 100644 --- a/plugins/capabilities/skills/discover-capabilities/SKILL.md +++ b/plugins/capabilities/skills/discover-capabilities/SKILL.md @@ -26,7 +26,7 @@ last. 7. Skim https://cursor.com/changelog for capabilities newer than the docs. 8. State the fetch date. Anything that timed out or returned 403/429 is unverified; say so. -Index, tiers, and expansion rule: `plugins/capabilities/reference/DOC-SOURCES.md`. +Index, tiers, and expansion rule: `plugins/capabilities/reference/doc-sources.md`. ## Establish surface and plan diff --git a/plugins/plugin-ops/.cursor-plugin/plugin.json b/plugins/plugin-ops/.cursor-plugin/plugin.json index 0047524..a8838d1 100644 --- a/plugins/plugin-ops/.cursor-plugin/plugin.json +++ b/plugins/plugin-ops/.cursor-plugin/plugin.json @@ -1,6 +1,6 @@ { "name": "plugin-ops", - "version": "0.2.0", + "version": "0.2.1", "description": "Plan-aware Cursor plugin/marketplace install, update, local sync, and verify — always fetch official Cursor docs live.", "author": { "name": "Melodic Software", diff --git a/plugins/plugin-ops/README.md b/plugins/plugin-ops/README.md index c3f4130..d1855e7 100644 --- a/plugins/plugin-ops/README.md +++ b/plugins/plugin-ops/README.md @@ -3,10 +3,10 @@ Plan-aware operators for Cursor plugins and marketplaces (Ultra / Teams / Enterprise). Skills **fetch official Cursor docs live** before advising — see -[`reference/DOC-SOURCES.md`](reference/DOC-SOURCES.md). +[`reference/doc-sources.md`](reference/doc-sources.md). Melodic policy (skills primary; no new `commands/`): -[`docs/PLUGIN-PHILOSOPHY.md`](../../docs/PLUGIN-PHILOSOPHY.md). +[`docs/plugin-philosophy.md`](../../docs/plugin-philosophy.md). ## Skills diff --git a/plugins/plugin-ops/reference/DOC-SOURCES.md b/plugins/plugin-ops/reference/doc-sources.md similarity index 95% rename from plugins/plugin-ops/reference/DOC-SOURCES.md rename to plugins/plugin-ops/reference/doc-sources.md index b380fee..3f27e3c 100644 --- a/plugins/plugin-ops/reference/DOC-SOURCES.md +++ b/plugins/plugin-ops/reference/doc-sources.md @@ -4,8 +4,8 @@ Skills in this plugin **must not** invent install/update UI steps from memory. Before advising, fetch the current pages. Repo jump sheet (same URLs + Melodic stance notes): -[`docs/OFFICIAL-DOCS.md`](../../../docs/OFFICIAL-DOCS.md). -Policy: [`docs/PLUGIN-PHILOSOPHY.md`](../../../docs/PLUGIN-PHILOSOPHY.md). +[`docs/official-docs.md`](../../../docs/official-docs.md). +Policy: [`docs/plugin-philosophy.md`](../../../docs/plugin-philosophy.md). | Topic | URL | | --- | --- | diff --git a/plugins/plugin-ops/skills/install-marketplace/SKILL.md b/plugins/plugin-ops/skills/install-marketplace/SKILL.md index 0083995..8252d83 100644 --- a/plugins/plugin-ops/skills/install-marketplace/SKILL.md +++ b/plugins/plugin-ops/skills/install-marketplace/SKILL.md @@ -13,8 +13,8 @@ Before any recommendation, fetch and skim: 2. https://cursor.com/docs/reference/plugins — multi-plugin `marketplace.json` shape 3. https://cursor.com/docs/integrations/github — only if Team Auto Refresh / GitHub App comes up -Use `plugins/plugin-ops/reference/DOC-SOURCES.md`. **Docs win** over this skill. -Melodic policy: `docs/PLUGIN-PHILOSOPHY.md`. +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 diff --git a/plugins/plugin-ops/skills/sync-local/SKILL.md b/plugins/plugin-ops/skills/sync-local/SKILL.md index 120cc90..1cfd3ab 100644 --- a/plugins/plugin-ops/skills/sync-local/SKILL.md +++ b/plugins/plugin-ops/skills/sync-local/SKILL.md @@ -9,9 +9,9 @@ description: Sync any Cursor plugin or marketplace (local path or git URL) into 1. Fetch https://cursor.com/docs/plugins — especially **Test plugins locally**. 2. Fetch https://cursor.com/docs/reference/plugins — marketplace vs single-plugin layout. -3. Follow `plugins/plugin-ops/reference/DOC-SOURCES.md` for the full URL list. +3. Follow `plugins/plugin-ops/reference/doc-sources.md` for the full URL list. 4. Prefer live docs over this skill if they disagree. -5. Melodic policy: `docs/PLUGIN-PHILOSOPHY.md` (skills primary; no `commands/` layer for this workflow). +5. Melodic policy: `docs/plugin-philosophy.md` (skills primary; no `commands/` layer for this workflow). ## When to use diff --git a/plugins/plugin-ops/skills/update-plugins/SKILL.md b/plugins/plugin-ops/skills/update-plugins/SKILL.md index b574913..58f1564 100644 --- a/plugins/plugin-ops/skills/update-plugins/SKILL.md +++ b/plugins/plugin-ops/skills/update-plugins/SKILL.md @@ -11,8 +11,8 @@ description: Update installed Cursor plugins/marketplaces for the user's plan. F 2. https://cursor.com/docs/integrations/github — GitHub App requirement for Auto Refresh 3. https://cursor.com/docs/reference/plugins — only if validating marketplace layout after a pull -`plugins/plugin-ops/reference/DOC-SOURCES.md` lists URLs. **Docs win.** -Melodic policy: `docs/PLUGIN-PHILOSOPHY.md`. +`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 ` diff --git a/plugins/plugin-ops/skills/verify-plugin/SKILL.md b/plugins/plugin-ops/skills/verify-plugin/SKILL.md index 2d173ec..a3d8b8a 100644 --- a/plugins/plugin-ops/skills/verify-plugin/SKILL.md +++ b/plugins/plugin-ops/skills/verify-plugin/SKILL.md @@ -12,10 +12,10 @@ description: Validate a Cursor plugin or marketplace checkout against live offic 3. The published JSON Schemas — machine-checkable, and stricter than the prose tables. Validate the actual files against them (ajv or equivalent), do not just eyeball the docs: - https://raw.githubusercontent.com/cursor/plugins/main/schemas/marketplace.schema.json - https://raw.githubusercontent.com/cursor/plugins/main/schemas/plugin.schema.json -4. Related pages from `plugins/plugin-ops/reference/DOC-SOURCES.md` if hooks/MCP/rules/skills are present +4. Related pages from `plugins/plugin-ops/reference/doc-sources.md` if hooks/MCP/rules/skills are present 5. Melodic policy pointers (not Cursor requirements): - - `docs/PLUGIN-PHILOSOPHY.md` - - `docs/MIGRATION-PLAYBOOK.md` + - `docs/plugin-philosophy.md` + - `docs/migration-playbook.md` Build the Cursor checklist from **fetched** docs, not from memory. diff --git a/scripts/check-docs-naming.sh b/scripts/check-docs-naming.sh new file mode 100755 index 0000000..743f493 --- /dev/null +++ b/scripts/check-docs-naming.sh @@ -0,0 +1,57 @@ +#!/usr/bin/env bash +# Check that every tracked file under docs/ and plugins/*/reference/ has a lower-kebab-case basename. +# +# Rule: the basename matches ^[a-z0-9]+([.-][a-z0-9]+)*\.[a-z0-9]+$. +# Exempt: README, AGENTS, CLAUDE, CHANGELOG, LICENSE, SKILL, CONTRIBUTING, SECURITY, REVIEW +# and CODE_OF_CONDUCT (each .md), the conventional names forges and tooling look for +# by exact spelling. +# Independently, no two tracked paths under those paths may differ only by case: a +# case-insensitive checkout (Windows, macOS) writes the second over the first. +# +# Usage: bash scripts/check-docs-naming.sh [--check] +# Exit: 0 clean, 1 any offender, 2 usage or environment. +set -euo pipefail + +case "${1:-}" in +'' | --check) ;; +*) + printf 'usage: %s [--check]\n' "${0##*/}" >&2 + exit 2 + ;; +esac + +src_dir="${BASH_SOURCE[0]%/*}" +[[ "$src_dir" == "${BASH_SOURCE[0]}" ]] && src_dir=. +cd "$src_dir/.." || exit 2 +git rev-parse --show-toplevel >/dev/null 2>&1 || { + printf 'check-docs-naming: not inside a git repository\n' >&2 + exit 2 +} + +name_re='^[a-z0-9]+([.-][a-z0-9]+)*\.[a-z0-9]+$' +exempt_re='^(README|AGENTS|CLAUDE|CHANGELOG|LICENSE|SKILL|CONTRIBUTING|SECURITY|REVIEW|CODE_OF_CONDUCT)\.md$' +scope=(docs/ ':(glob)plugins/*/reference/**') +offenders=() + +while IFS= read -r -d '' path; do + base="${path##*/}" + [[ "$base" =~ $exempt_re || "$base" =~ $name_re ]] || + offenders+=("$path: basename is not lower-kebab-case") +done < <(git ls-files -z -- "${scope[@]}") + +while IFS= read -r folded; do + [[ -n "$folded" ]] || continue + while IFS= read -r path; do + if [[ "$(printf '%s' "$path" | tr '[:upper:]' '[:lower:]')" == "$folded" ]]; then + offenders+=("$path: differs only by case from another tracked path") + fi + done < <(git ls-files -- "${scope[@]}") +done < <(git ls-files -- "${scope[@]}" | tr '[:upper:]' '[:lower:]' | sort | uniq -d) + +if ((${#offenders[@]} == 0)); then + printf 'check-docs-naming: every tracked file under docs/ and plugins/*/reference/ is lower-kebab-case.\n' + exit 0 +fi +printf '%s\n' "${offenders[@]}" | sort -u >&2 +printf 'check-docs-naming: %d offender(s); rename to lower-kebab-case.\n' "${#offenders[@]}" >&2 +exit 1 diff --git a/scripts/test-check-docs-naming.sh b/scripts/test-check-docs-naming.sh new file mode 100755 index 0000000..b467945 --- /dev/null +++ b/scripts/test-check-docs-naming.sh @@ -0,0 +1,46 @@ +#!/usr/bin/env bash +# Regression suite for check-docs-naming.sh: runs it against throwaway git repos. +# Usage: bash scripts/test-check-docs-naming.sh +# Exit: 0 all cases passed, 1 otherwise. +set -euo pipefail + +src_dir="${BASH_SOURCE[0]%/*}" +[[ "$src_dir" == "${BASH_SOURCE[0]}" ]] && src_dir=. +sut="$(cd "$src_dir" && pwd)/check-docs-naming.sh" +work="$(mktemp -d "${TMPDIR:-/tmp}/docs-naming-tests.XXXXXX")" +trap 'rm -rf "$work"' EXIT +fail=0 + +# run_case NAME WANT_EXIT FILE... (files are created under docs/ and staged) +run_case() { + local name="$1" want="$2" repo rc=0 f + shift 2 + repo="$work/$name" + mkdir -p "$repo/scripts" + cp "$sut" "$repo/scripts/" + git -C "$repo" init -q + for f in "$@"; do + mkdir -p "$repo/docs/$(dirname "$f")" + : >"$repo/docs/$f" + done + git -C "$repo" add -A + bash "$repo/scripts/check-docs-naming.sh" --check >/dev/null 2>&1 || rc=$? + if [[ "$rc" == "$want" ]]; then + printf ' ok %s\n' "$name" + else + printf ' FAIL %s (exit %s, want %s)\n' "$name" "$rc" "$want" + fail=1 + fi +} + +run_case clean 0 plugin-philosophy.md README.md CHANGELOG.md v1.2.schema.json +run_case upper-kebab 1 UPPER-KEBAB.md +run_case mixed-case 1 Mixed.md +run_case snake-case 1 snake_case.md +run_case empty-segment 1 foo..md +run_case nested-offender 1 sub/Bad-Name.md +run_case nested-exempt 0 sub/README.md sub/SKILL.md +run_case dir-case-collision 1 Guides/a.md guides/a.md +run_case reference-offender 1 ../plugins/p/reference/DOC-SOURCES.md + +exit "$fail"