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 · Kimi Code · opencode
• What you get — Always on · Skills · What the skills use
• Setup — credentials and environment variables
• Validate — what to run after a change
• Versioning and releases
• Contributing

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 KB 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:

• Global (install once, applies everywhere). Point opencode at the shipped config:

  export OPENCODE_CONFIG="$XWIKI_LLM_HOME/opencode.jsonc"

  Or merge the mcp and instructions entries from opencode.jsonc into your ~/.config/opencode/opencode.json.
• Per project. Copy opencode.jsonc to opencode.json in an XWiki repo (it needs no editing — it reads XWIKI_LLM_HOME). This scopes the config to that repo only.

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
ln -s "$XWIKI_LLM_HOME/xwiki/opencode/plugins/xwiki-commit-gates.js" ~/.config/opencode/plugins/xwiki-commit-gates.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; only the message (-m, -F file or stdin, --body/--body-file) is read, not the rest of a compound command; summary line exempt	—
Commit diff check (xwiki/scripts/check-diff.mjs) — refuses a commit whose diff breaks a rule it shows exactly: a malformed @since / @Deprecated(since), or one not naming the next release of the root pom (the release line just before it is only a warning: it was right before a version bump), a version in a javadoc @deprecated, new public API without @Unstable (xwiki org only), a .properties file turned UTF-8, a new file without a license header (Maven projects); heuristics (coverage threshold untouched, page change with no test, [Misc] on production code) come back as advice. It also refuses, once per skill, a commit touching files whose rules live in a skill the session has not loaded (xwiki/scripts/skill-gates.json: tests, -legacy code, translations, XAR pages; loads recorded by xwiki/scripts/skill-gate.mjs). Kimi gets the diff refusals only	Every git commit, in the same repos as the org conventions; reads the staged diff (the work tree too after -a or a git add in the same command)	Diff-Check: skip trailer for a wrong finding; XWIKI_LLM_COMMIT_GATES=off

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 KB, 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"
xwiki-review ⚠	A few senior-reviewer agents (correctness, design, tests, history and past reviews of the touched code, conventions) reading the code with general judgement plus the KB, each finding re-checked against the code before it is posted; asks for a quick or full security pass when the private xwiki-security plugin is installed	gh login	/xwiki-review PR 6453
xwiki-backport	Cherry-pick to an older branch and adapt it (poms, Java level, @since, API drift)	gh login	"backport this to stable-18.8.x"
xwiki-backport-testneeded	The testneeded sweep: backport one issue's test to every supported branch	gh login, JIRA_API_TOKEN	"backport the test of XWIKI-24710"
xwiki-review-help	A local HTML page to decide on the user-facing changes of several PRs or a release: one card per change (before/after, screenshots that enlarge, who is affected, admin action, release-notes line), the open decisions, and an export of your choices to paste back	a browser	"make me the review page for the open PRs"
xwiki-security-advisory	Draft a GitHub Security Advisory from a security-restricted issue	JIRA_API_TOKEN	"draft the advisory for XWIKI-25001"
xwiki-openproject	Work packages on op.xwiki.org (not the issue tracker)	OPENPROJECT_API_TOKEN	"what's on my OpenProject list?"

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 kb/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"
xwiki-xs-release	Drive an XWiki Standard release's Release Plan with the release manager: pre-build checks, release notes, JIRA dashboard, wiki pages, branch cleanup, announcement drafts	~/.xwiki-credentials, JIRA_API_TOKEN, gh, a logged-in browser for the JIRA dashboard and Jenkins	"help me release 18.10.0RC1"
xwiki-contrib-release-blog-post	The " Extension X.Y Released" blog post on xwiki.org	~/.xwiki-credentials	"announce the Jira extension 9.2 release"
xwiki-presentation	Build a .pptx deck in the XWiki look, then PDF/PNG/Keynote	LibreOffice, Python deps	"build a deck on XWiki 18.x for FOSDEM"

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

KB (xwiki/kb/)	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, KB 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. It also syncs the KB with the dev.xwiki.org pages it cites, in a separate PR.

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/ (KB, 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.