lean-contribute

# Contribute to LeanCode AI plugins The guided contributor path for `leancodepl/ai-plugins`. The repo's `CONTRIBUTING.md` carries the same steps for contributors working without it. Read top-to-bottom for the full picture, or jump to the relevant path. ## How to respond 1. Ask what kind of change the user wants: - **Tweak** an existing plugin (improve a skill or reference, fix a typo, sharpen wording). - **Add a new plugin** (a new focused capability). - **Add a skill or reference** to an existing plugin. 2. Walk through the matching path below. Print exact commands. Do not run `git`, `gh`, or any state-changing command on the contributor's behalf unless they explicitly ask. 3. After the PR is pushed, point the user at `gh pr checks <pr-number>` to follow CI verdicts. CI is the source of truth. ## Reading the current state Before answering questions about what plugins or clients exist, read the source of truth: - Plugins: `.claude-plugin/marketplace.json` at the repo root. - Supported clients: the "Supported clients" section of the root `README.md`. Do not enumerate plugins or clients from memory. ## Where to work All contribution work happens **inside a local clone of `leancodepl/ai-plugins`**, not in a consumer project. If the contributor does not have the clone yet: ``` gh repo clone leancodepl/ai-plugins cd ai-plugins ``` If `gh` is not installed, point them at https://cli.github.com/ or, for a fully GUI flow, https://desktop.github.com/. ## Plugin shape This repo ships Claude Code plugins. Every plugin lives under `plugins/<plugin-name>/`: ``` plugins/<plugin-name>/ skills/ <plugin-name>-usage/ SKILL.md # routing entry point, always present references/ # optional reference material the skill loads on demand <topic>.md <other-skill>/ SKILL.md .claude-plugin/plugin.json README.md CHANGELOG.md .mcp.json # only if the plugin drives an MCP server ``` Notes: - **`.claude-plugin/plugin.json` is the manifest.** It carries `name`, `displayName`, `description`, `version`, and points `skills` at `./skills/`. It has no `rules` key — Claude Code does not recognize one. - **Every plugin ships `skills/<plugin-name>-usage/SKILL.md`** as its routing entry point. The skill `name:` in frontmatter must exactly match the folder name. - **Skill names are unique across the whole marketplace.** If your slug could collide, prefix it with the plugin name. - **Everything ships as a skill.** Use a workflow skill for a step-by-step action, and `references/*.md` alongside a `SKILL.md` for convention-style guidance the model should apply. Mark skills that should never auto-fire on inferred intent with `disable-model-invocation: true`. - **Reference files are edited directly** — `SKILL.md` lists them under a "Reach for these references" section so Claude knows when to load each. They load only when referenced, so detailed material costs nothing until needed. - **Setup and configuration docs have one canonical home: the plugin `README.md`.** Anything a user has to do to make the plugin work (env vars, dependencies, post-install steps, sample directories, MCP servers, etc.) lives there in full. Other surfaces — `<plugin>-usage/SKILL.md`, other skills, top-level README bullets — reference the plugin README rather than restating the setup. The single exception is a skill that needs to print setup inline at runtime (because the user is not on GitHub at that moment); when you keep an inline copy for that reason, say so in the skill so the next contributor does not assume the duplication is accidental. This rule prevents drift between `README.md`, the usage SKILL, and any workhorse SKILL that all happen to mention the same env var. ## Skill conventions - Each skill is a folder `skills/<slug>/` containing a single `SKILL.md`. - Frontmatter `name:` must equal the folder name. - `description` should include "Use when …" with concrete trigger terms. - Add `argument-hint: "<args>"` when the skill takes arguments. - Add `disable-model-invocation: true` when the skill should never auto-fire on inferred intent. - Skill names must be unique across the whole marketplace. ## Reference-material conventions - Convention-style guidance lives in `skills/<plugin-name>-usage/references/*.md` as plain markdown (no frontmatter). - List each reference file in the owning `SKILL.md` under a "Reach for these references" section, with a one-line note on what it covers, so Claude knows when to load it. - A workhorse skill in the same plugin can cite a usage skill's reference with a relative path (e.g. `../<plugin-name>-usage/references/<topic>.md`). ## Path 1 — tweak an existing plugin 1. Open `plugins/<plugin-name>/` and find the file to change. 2. Edit it. Keep the change focused — one PR per concern. 3. Bump the plugin's `version` in `.claude-plugin/plugin.json`. PATCH for wording / docs, MINOR for new behavior, MAJOR for renames or removals. See "Versioning" below for what Claude Code does with the bump. 4. Add a bullet to `plugins/<plugin-name>/CHANGELOG.md` under a new top entry matching the new version. 5. Update `plugins/<plugin-name>/README.md` if the change affects what the plugin lists. 6. Branch, commit, push, open a PR — see "Open the PR" below. ## Path 2 — add a skill or reference to an existing plugin Same as Path 1, plus: - New skill → `plugins/<plugin-name>/skills/<skill-slug>/SKILL.md` with frontmatter `name: <skill-slug>` and a `description` that includes "Use when …" with concrete trigger terms. Add `disable-model-invocation: true` if it should not auto-fire. Also append the skill's plugin-relative path (e.g. `"./skills/<skill-slug>"`) to the plugin's `skills` array in `.claude-plugin/marketplace.json`. - New reference → `plugins/<plugin-name>/skills/<plugin-name>-usage/references/<topic>.md` (plain markdown), and list it under "Reach for these references" in that `SKILL.md`. - Mention the new asset in `plugins/<plugin-name>/README.md`. ## Path 3 — add a new plugin 1. Pick a kebab-case name with a prefix that reflects scope: - `flutter-<scope>` for a Flutter capability (the bulk of this marketplace). - `lean-<scope>` for a meta or repo-wide plugin with no natural domain (matches `lean-core`). Do not ship a bare slug. The prefix is what makes the marketplace listing predictable — users remember prefixes plus autocomplete, not full slugs. 2. Create `plugins/<plugin-name>/` with at minimum: - `skills/<plugin-name>-usage/SKILL.md` - `.claude-plugin/plugin.json` - `README.md` - `CHANGELOG.md` with a `0.1.0` entry 3. Copy manifest shape from a sibling plugin. Set `version: "0.1.0"`. 4. Register the plugin in `.claude-plugin/marketplace.json` — append to `plugins[]` with `name`, `source`, `description`, and a `skills` array listing every skill's plugin-relative path (e.g. `"./skills/<plugin-name>-usage"`). 5. Add the plugin to the human-readable overview in the root `README.md` under the matching group. 6. Branch, commit, push, open a PR. ## Versioning Per-plugin semver in `.claude-plugin/plugin.json`. - **PATCH** — wording, doc only. - **MINOR** — new skill, new reference, new behavior; expanded scope; additive change. - **MAJOR** — rename, removal, or reversal of existing guidance. Keep `plugin.json` to fields in the official Claude Code plugin manifest schema — CI runs `claude plugin validate . --strict`, which fails on unrecognized fields. ### What Claude Code does with the version `plugin.json.version` is the cache key for `/plugin update`. **Bumping it is load-bearing.** If you ship changes without bumping, users running `/plugin update` see "already at the latest version" and never get your change. Bump it on every release. (See https://code.claude.com/docs/en/plugins-reference.md, "Version management".) `marketplace.json.metadata.version` is **decorative** — no documented refresh or update behavior. Bump by convention when plugins are added/removed/renamed if you want, but nothing depends on it. Users get updates by running `/plugin update` (or auto-update if enabled) — no reinstall needed on a normal version bump. ## Open the PR ``` git checkout -b <short-slug> git add -A git commit -m "<plugin-name>: <what changed>" git push -u origin HEAD gh pr create --repo leancodepl/ai-plugins \ --title "<plugin-name>: <what changed>" \ --body "<one paragraph: what and why; mention any breaking changes>" ``` If `gh` is not installed, push the branch and open the PR via the GitHub web UI. The PR description should answer: what changed, why, and which plugins it touches. ## CI is the safety net Every PR runs on GitHub Actions: - **Structure** — manifest fields, marketplace registration, file shape and skill names (`go run ./cmd/validate-plugins`), plus the validator's own tests (`go test ./...`). - **Spec** — the official Claude Code plugin-spec check (`claude plugin validate . --strict`, warnings fail the build). - **Lint** — Go formatters/linters for repo tooling. Contributors do not need to install Go locally — CI runs it. Watch the verdicts with: ``` gh pr checks <pr-number> ``` A green PR means the shape is correct. Review focuses on guidance quality, not boilerplate. ## What NOT to do - Do not bundle changes across multiple plugins in a single PR. One plugin per PR keeps review tight. - Do not ship a Claude Code-visible change without bumping `plugin.json.version` — see "Versioning" above. - Do not invent guidance that is not grounded in real usage. If you cannot point at a concrete reason for a skill or reference claim, leave it out. - Do not enumerate plugins or clients from memory — read the source of truth.