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
6 changes: 6 additions & 0 deletions .github/workflows/pr-require-checks.yml
Original file line number Diff line number Diff line change
Expand Up @@ -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).
Expand Down
26 changes: 15 additions & 11 deletions AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -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/<name>/.cursor-plugin/plugin.json`), plugin skills (`skills/<name>/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

Expand Down Expand Up @@ -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/<name>/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/<name>/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.

Expand Down Expand Up @@ -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).
16 changes: 8 additions & 8 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand All @@ -25,9 +25,9 @@ plugins/<name>/
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
Expand Down Expand Up @@ -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
Expand Down
8 changes: 4 additions & 4 deletions docs/MIGRATION-PLAYBOOK.md → docs/migration-playbook.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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 |
| --- | --- | --- |
Expand Down Expand Up @@ -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/<name>/` (real copy) and
**Developer: Reload Window**
Expand Down
14 changes: 7 additions & 7 deletions docs/OFFICIAL-DOCS.md → docs/official-docs.md
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down Expand Up @@ -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
Expand All @@ -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 |
| --- | --- |
Expand Down
12 changes: 6 additions & 6 deletions docs/PLUGIN-PHILOSOPHY.md → docs/plugin-philosophy.md
Original file line number Diff line number Diff line change
@@ -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
Expand Down Expand Up @@ -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.

Expand Down Expand Up @@ -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
2 changes: 1 addition & 1 deletion plugins/automations/.cursor-plugin/plugin.json
Original file line number Diff line number Diff line change
@@ -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",
Expand Down
6 changes: 3 additions & 3 deletions plugins/automations/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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
Expand Down
10 changes: 5 additions & 5 deletions plugins/automations/skills/design-automation/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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
Expand All @@ -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
Expand Down Expand Up @@ -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.
Expand Down
2 changes: 1 addition & 1 deletion plugins/capabilities/.cursor-plugin/plugin.json
Original file line number Diff line number Diff line change
@@ -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",
Expand Down
4 changes: 2 additions & 2 deletions plugins/capabilities/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down
Loading
Loading