xwiki-dev-llm
Shared LLM configuration for XWiki developers, distributed as a
Claude Code plugin marketplace,
a Kimi Code plugin,
and an opencode config.
The goal is consistency across developers, sharing the work of others, and simple onboarding —
generic enough to work for every XWiki developer (no committed secrets, no personal paths). It
was designed in the forum thread
Organizing our LLM configs for all our repos.
The Claude marketplace manifest lives at the repo root (.claude-plugin/marketplace.json), the
Kimi plugin manifest lives at kimi.plugin.json, the opencode config lives at opencode.jsonc,
and the shared plugin content lives under xwiki/.
Install
Claude Code
/plugin marketplace add https://github.com/xwiki/xwiki-dev-llm
/plugin install xwiki@xwiki-dev-llm
For local development against a checkout:
/plugin marketplace add /path/to/xwiki-dev-llm
/plugin install xwiki@xwiki-dev-llm
Kimi Code
/plugins install https://github.com/xwiki/xwiki-dev-llm
/reload
For local development against a checkout:
/plugins install /path/to/xwiki-dev-llm
/reload
opencode
opencode has no plugin marketplace, so it reads this repo from a local checkout. Clone it once and
point XWIKI_LLM_HOME at it (the opencode.jsonc config resolves every path through that variable,
so the file stays portable — no personal paths):
git clone https://github.com/xwiki/xwiki-dev-llm ~/dev/xwiki/xwiki-dev-llm
# in your shell profile (~/.zshrc, ~/.bashrc, …):
export XWIKI_LLM_HOME="$HOME/dev/xwiki/xwiki-dev-llm"
Skills. opencode only discovers skills in fixed directories, so symlink this checkout's skills
into your opencode config once (a single link — the skills and their OKF stay in the checkout):
mkdir -p ~/.config/opencode
ln -s "$XWIKI_LLM_HOME/xwiki/skills" ~/.config/opencode/skills
Config (MCP servers + org conventions). Choose one:
Guard plugins (optional). Symlink them into an opencode plugin directory:
mkdir -p ~/.config/opencode/plugins
ln -s "$XWIKI_LLM_HOME/xwiki/opencode/plugins/xwiki-line-endings.js" ~/.config/opencode/plugins/xwiki-line-endings.js
ln -s "$XWIKI_LLM_HOME/xwiki/opencode/plugins/xwiki-commit-text.js" ~/.config/opencode/plugins/xwiki-commit-text.js
Note — no git-remote scoping in opencode. In Claude Code the org conventions are injected only
inside xwiki/* / xwiki-contrib/* repos — and any org listed in XWIKI_LLM_ORGS — via a
remote-scoped SessionStart hook. opencode has no
equivalent hook, so with the global config the conventions load in every repo. Use the
per-project config if you need them scoped to XWiki repos only.
What you get
Always on — no invocation
| What | When it fires | Tune with |
|---|
Org conventions (xwiki/instructions/xwiki-org.md) — the shared "CLAUDE.md for all repos": build commands, commit format, code conventions, @since rules | Every session, in xwiki/* and xwiki-contrib/* repos only (scoped by git remote) | XWIKI_LLM_ORGS to add your own orgs. No scoping in opencode — see the install note above |
Work directory — plans, handoffs, drafts and notes go to one root instead of the repo, /tmp and your home | The first time a task needs a file that must outlive the session | XWIKI_LLM_WORK (defaults) |
Line-ending guard (xwiki/scripts/check-line-endings.mjs) — blocks a write whose endings contradict the repo's .gitattributes, so no spurious whole-file diffs | Every Write/Edit; silent unless violated | — |
Commit/PR text guard (xwiki/scripts/check-commit-text.mjs) — blocks a message body holding a bare @name, or a #123 in a repo whose issues live in JIRA (read from its pom.xml or remote), which GitHub turns into a mention of a stranger or the wrong issue | Every git commit, gh pr create/edit; summary line exempt | — |
A pushed commit message cannot be fixed without rewriting a shared branch, and a CRLF diff hides the
real change — which is why those two are hooks and not conventions. Both are Node (no bash, no jq),
observation-only under Kimi Code, and available to opencode as plugins.
When you ask — skills
⚠ = explicit invocation only: named or nothing, because it is expensive or it writes.
Needs is what must be set for the skill to do its job — how to set it; a —
means it needs nothing.
Build & test
| Skill | What it does | Needs | Example |
|---|
xwiki-build | Maven commands: the right JDK, profiles, single module, single test | — | "run EditIT in xwiki-platform-flamingo-skin-test" |
xwiki-test-guidelines | The rules and frameworks for writing a test — loads itself before any test change, down to one @Test | — | "add a test for this" |
xwiki-convert-tests | Convert unit tests to JUnit 5 + Mockito | — | "convert this test class to JUnit 5" |
xwiki-convert-tests-docker | Convert functional ITs to the Docker @UITest framework | — | "convert these ITs to @UITest" |
xwiki-increase-test-coverage | Recompute a module's JaCoCo ratio and raise the pom's floor | — | "bump the coverage ratio for this module" |
xwiki-fix-flickering-docker-test | Investigate a flicker from its CI evidence, confirm a hypothesis by forcing the race, then fix it | Docker | "fix the NotificationsIT flicker" |
Code & APIs
| Skill | What it does | Needs | Example |
|---|
xwiki-knowledge | Answer "what is the rule here?" from the OKF, and extend it by PR | — | "what's our policy on comments in code?" |
xwiki-javadoc | Write Javadoc per the XWiki code style | — | "javadoc this class" |
xwiki-fix-deprecation | Move every caller of a deprecated API — Java, Velocity, wiki pages, JS — to its replacement, then retire the API to legacy; proposes easy candidates | — | "fix some easy deprecations" |
xwiki-legacy | Move a deprecated API with no caller left to its -legacy module: remove, re-add, Revapi | — | "retire XWikiRightService" |
xwiki-translations | Externalize and render i18n strings safely (escaping, word order) | — | "externalize these strings" |
xwiki-xar-pages | Edit extension wiki pages in a XAR (xar:format / xar:verify conventions) | — | "add a page to this XAR" |
Issues, PRs & review
| Skill | What it does | Needs | Example |
|---|
xwiki-jira | View, search, create, update and transition jira.xwiki.org issues | JIRA_API_TOKEN | "file a bug for this in XWIKI" |
xwiki-jira-bfd | Prepare a Bug Fixing Day: score the old backlog, propose closes and quick wins, apply only the approved closes (you run the apply) | JIRA_API_TOKEN; TYPESAFE_TOKEN, or the claude CLI as the judge | "prepare the BFD on the 5-year-old XWIKI bugs" |
xwiki-daily-close ⚠ | Your daily push on work you already have open: PRs, assigned issues and forum topics you started that are ready or one step from done, ranked, with stats and trend; offers each merge, close or forum conclusion for a yes | gh login; JIRA_API_TOKEN; DISCOURSE_API_* to write on the forum (read-only without) | /xwiki-daily-close |
xwiki-forum | Draft and post forum.xwiki.org topics and replies: category, brainstorming/proposal/vote tag instead of a title prefix, confirmation of every field before posting | DISCOURSE_API_* to post (draft to paste without) | "prepare a brainstorming post about X" |
xwiki-pull-request | Commit format, PR template, squash and backport conventions | gh login | "open a PR for this branch" |
| ⚠ |
CI & quality
| Skill | What it does | Needs | Example |
|---|
xwiki-release-test-triage | Reads CI and reports: known flicker, unknown flicker or real breakage — does it block the release? Never writes | — | "is master green?" |
xwiki-ci-check ⚠ | The daily sweep that acts: attributes each failure, comments on the culprit commit, opens fix PRs, files flicker issues, posts the digest | to analyse, nothing — but a red quality gate keeps its cause only with SONARQUBE_TOKEN, and a failing test its history only with a Develocity key; the bot tokens to write (GH_TOKEN_BOT, JIRA_TOKEN_BOT, MATRIX_*) | /xwiki-ci-check xwiki-platform, master only |
xwiki-fix-sonarqube-issue | Fix a SonarCloud finding correctly (per-rule traps live in okf/sonarqube/) and open the PR | SONARQUBE_TOKEN, SONARQUBE_PROJECT_KEY | "fix a Sonar issue in this repo" |
Documentation — the ones that write to xwiki.org read your credentials from ~/.xwiki-credentials.
| Skill | What it does | Needs | Example |
|---|
xwiki-doc-writing | Write, update or review an xwiki.org page per the Documentation Guide (Diataxis) | ~/.xwiki-credentials | "document this feature" |
xwiki-doc-convert | Migrate an old page into the new /documentation tree, as a resumable plan | ~/.xwiki-credentials | "convert the Skin Extensions page" |
xwiki-doc-export | Export a /documentation subtree to one PDF in navigation order, optionally translated (official UI terms), re-translating only what changed since the last export — as a resumable plan | Chrome/Chromium; pdftotext for page numbers; an xwiki-platform checkout to translate | "export the XS user documentation to a German PDF" |
xwiki-release-documentation ⚠ | Audit a release's fixed issues: what needs a page, what needs a release note, then write both and fill the JIRA fields | ~/.xwiki-credentials, JIRA_API_TOKEN | /xwiki-release-documentation 18.8.0 |
xwiki-contrib-release | Release a contrib extension: release:prepare/perform to Nexus, issue-tracker version, extensions.xwiki.org, hand-off to the blog post | Nexus xwiki-staging account + GPG in ~/.m2/settings.xml, JIRA_API_TOKEN or OPENPROJECT_API_TOKEN | "release v1.15 of the doc app" |
|
Running wiki
| Skill | What it does | Needs | Example |
|---|
xwiki-rest-api | Read and write a live instance over REST: pages, xobjects, Solr search | the instance's login (~/.xwiki-credentials for xwiki.org) | "what's in the sandbox page?" |
xwiki-deploy-extension | Install a built XAR/JAR into a running XWiki via the job REST API | the instance's login | "deploy this XAR to localhost:8080" |
xwiki-capture-ui-change | Capture the "before" screenshot of a UI fix that the branch can no longer produce, on the released version's Docker image or by deploying the pre-fix code locally. Runs only with your approval | the agent-browser skill; Docker, or a prebuilt jetty+hsqldb distribution | "show the before of this button fix" |
What the skills use
| |
|---|
OKF (xwiki/okf/) | XWiki's declarative knowledge — conventions, architecture, servers, testing, SonarQube rule correctness, processes. Durable facts inline; volatile ones (versions, build status) stored as "where to look and how to verify", never cached. Extended only through a reviewed PR. |
discourse MCP | forum.xwiki.org: search and read with no credential, post with one (setup) |
develocity MCP | community.develocity.cloud: build scans, test outcomes, flaky history, cache hit rates (setup) |
sonarqube MCP | SonarCloud issues and quality gates, per repo (setup) |
IT slot limiter (xwiki/scripts/xwiki-it-slot.mjs) | Caps concurrent Docker IT runs on one machine (2 by default). Several agents starting one at once starve the Docker daemon, and starvation surfaces as a beforeAll failure that reads like a product bug. Also runs testcontainers with a ryuk the daemon accepts, so runs on old XWiki parents stop leaking containers and networks |
Repeat-run oracle (xwiki/scripts/xwiki-it-repeat.mjs) | Runs one functional test N times on one configuration and reports the pass rate — a flicker is a probability, and "it passed" is not evidence that a fix worked. Keeps each failing repetition's report, screenshot and video |
Setup
Optional, all of it — see docs/setup.md for the environment variables and the
credentials for JIRA, the forum, Develocity, SonarCloud and xwiki.org.
Validate
claude plugin validate ./xwiki # manifest schema
node scripts/validate.mjs # repo consistency (skill inventory, version untouched + in sync, OKF map, size budgets, copied paragraphs)
scripts/validate.mjs also runs automatically in CI (GitHub Actions) on every push and pull request.
A weekly Claude routine (scripts/consolidation-routine.md)
then looks for what the validator cannot judge — near-duplicate rules, wordiness, files to split — and
opens at most one [Misc] Weekly consolidation: PR for a committer to review; it never merges.
Versioning and releases
Claude Code (and Kimi, and opencode) picks up a plugin change only when the version increases, and
that version is written in five places across the three host manifests. Pull requests never touch
it. They used to, and the result was that every open PR conflicted with every other one on those
same five lines — a conflict that was never about either change. scripts/validate.mjs now fails any
branch whose version differs from the base branch's.
The release is cut on master instead, by scripts/release.mjs, which
GitHub Actions runs automatically on every push to master that
touches xwiki/. It sets all five fields, commits [Misc] Release X.Y.Z and tags vX.Y.Z; the tag
is how the following run knows what has already shipped. To see what would happen without changing
anything:
node scripts/release.mjs --dry-run
Which segment moves is derived from the change, not asked for:
- minor — the capability inventory changed: a skill, an MCP server, a hook or an opencode
plugin was added or removed.
- patch — anything else under
xwiki/ (OKF, skill and instruction wording).
- major — never derived; it has to be asked for explicitly.
Two ways to override it. For a change whose significance the file list cannot show, add a trailer to
a commit message — unlike a version field, two branches can never conflict on one:
Release-Bump: minor
Or run the release workflow by hand from the Actions tab (workflow_dispatch) and choose the
segment. Note that automatic releases need master to accept a push from github-actions[bot]; if
master is protected, either allow the bot to bypass it or run node scripts/release.mjs --push
locally instead.
Contributing
Keep committed content minimal and generic — no personal paths, machine state, or secrets — and
review the conventions and skills periodically. Issues and changes are discussed on the
XWiki forum and tracked in JIRA.
