assistant-plugins CLAUDE.md

orq-skills — Maintainer Notes

Versioning

This repo follows Semantic Versioning. Version is tracked in 4 plugin manifests that must stay in sync:

• plugin.json — portable Agent Plugins 1.0.0 manifest
• .claude-plugin/plugin.json
• .codex-plugin/plugin.json
• .cursor-plugin/plugin.json

When to bump

Change	Bump
Bug fix, typo, small doc tweak	PATCH (0.0.x)
New skill, new command, backward-compatible capability	MINOR (0.x.0)
Skill removed/renamed, breaking frontmatter change, MCP server URL change	MAJOR (x.0.0)

Exception: removing shipped content that was never the canonical surface (e.g. stale duplicates tracked outside skills/) is a PATCH, not MAJOR — cleanup is not a breaking change.

How to bump

1. Update version in all 4 plugin.json files (same value).
2. Add an entry to CHANGELOG.md under a new ## [X.Y.Z] - YYYY-MM-DD heading. Use ### Added / Changed / Fixed / Removed sections.
3. Run tests/scripts/validate-plugin-manifests.sh — passes.
4. Commit with message: chore: bump version to X.Y.Z.

Plugin manifest rules

• All 4 plugin.json version fields must match — validate-skills.mjs enforces this in CI.
• Root plugin.json is a closed Agent Plugins 1.0.0 manifest: only $schema, name, version, description, author, homepage, repository, license, keywords, extensions are permitted. Never add skills/mcpServers to it — the spec fixes those locations (skills/, mcp.json). CI validates it with ajv against tests/schemas/agent-plugins-1.0.0.plugin.schema.json, a vendored copy of the published schema; re-vendor it if the spec revs.
• The per-harness manifests cannot be removed yet, and this is not just a scheduling matter. The Codex interface blob (displayName, logo, brandColor, category, privacy/ToS URLs) and Cursor's displayName have nowhere to go in the portable manifest: they belong under extensions["<reverse.domain>"], and no client has published a namespace — the spec defines no registry. Until one does, dropping .codex-plugin/ or .cursor-plugin/ loses store-listing metadata. Do not "finish the migration" without checking that first.
• Only the repo root may be an Agent Plugins root. A nested plugin.json carrying the 1.0.0 $schema is rejected by CI — it would re-create the plugins/orq escape (symlinks that stayed inside the repo but left their own plugin root). Client-specific manifests (.claude-plugin/, .codex-plugin/, .cursor-plugin/, plugins/trace-hooks/) are unaffected; they are matched by $schema, not filename.
• mcp.json, .claude-plugin/.mcp.json, .claude-plugin/skills are symlinks. Do not replace with copies; every tracked symlink must resolve inside the repo root (CI enforces).
• New skill = add to: skills/<name>/SKILL.md, agents/AGENTS.md (path list + <available_skills> block), README.md skills table, tests/skills.md (smoke tests + Critical Files), and skills-lock.json (see below). All five are enforced by validate-skills.mjs: each surface is diffed against skills/ in both directions, each must list a skill exactly once, and where the surface carries a target path (the AGENTS.md path list, the README.md table's [SKILL.md](…) link) the label and the target must agree — a registration pointing at another skill's file passes a name diff while every harness loads the wrong file. A missing surface file, or a README.md that has lost its table markers, is an error rather than a skipped check. One half is deliberately not covered: tests/skills.md is checked for a ## \`` smoke-test section per skill, but its "Critical Files" list is free prose and nothing verifies a skill appears there — add it by hand.