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:

• 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.

Line-ending guard (optional). Symlink the plugin 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

Note — no git-remote scoping in opencode. In Claude Code the org conventions are injected only inside xwiki/* / xwiki-contrib/* repos (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 the xwiki plugin provides

• Org-wide conventions (xwiki/instructions/xwiki-org.md) — the shared "CLAUDE.md for all repos". In Claude Code and Kimi Code it is injected into every session by a SessionStart hook (xwiki/scripts/inject-org-instructions.mjs), scoped by git remote so it only applies inside xwiki/* and xwiki-contrib/* repos (never in personal projects). The hook is written in Node (which ships with Claude Code), so it works on Windows, macOS and Linux without a bash or jq dependency. In opencode it is loaded via the instructions config entry (not remote-scoped — see the opencode install note above).
• Line-ending guard (xwiki/scripts/check-line-endings.mjs) — a PostToolUse hook on Write/Edit that checks every file written against the explicit eol declared by the repo's .gitattributes (via git check-attr). On a CRLF/LF mismatch it fails with a clear message so Claude Code rewrites the file with the right endings, preventing spurious whole-file diffs. It enforces this deterministically and at near-zero token cost — it only emits output on an actual violation, and stays silent when no eol is declared (so it never mis-fires on Windows core.autocrlf working trees). Also Node-based for cross-platform support. In Kimi Code the same warning is emitted, but because PostToolUse hooks are observation-only there, the model must act on the warning itself. In opencode the same check runs as a plugin (xwiki/opencode/plugins/xwiki-line-endings.js, a tool.execute.after hook reusing the same logic).
• MCP servers (xwiki/.mcp.json for Claude; mirrored in kimi.plugin.json and opencode.jsonc):
  • discourse — forum.xwiki.org search/read (no auth).
  • sonarqube — SonarCloud code-quality analysis (Docker). Reads SONARQUBE_TOKEN and the repo-specific SONARQUBE_PROJECT_KEY from the environment; no secrets are committed. SONARQUBE_PROJECT_KEY is optional (it defaults to empty), so repos that have no SonarCloud project do not fail to load the server.
• OKF — knowledge base (xwiki/okf/) — a curated, LLM-oriented corpus of XWiki declarative knowledge: conventions (conventions/), architecture (architecture/), the dev-server ecosystem (servers/), testing strategy (testing/), SonarQube rule-fix correctness (sonarqube/ — split per rule family so a fix loads only the one it needs) and release process (processes/). It complements the skills (which hold task procedures): the OKF holds facts. A slimmed map of it is injected via xwiki-org.md; okf/index.md is the full map. Durable facts are stored inline; volatile facts (versions, build/issue status, role holders) are stored as a "where to look + how to verify" pointer, never as a cached value, so the corpus does not go stale silently. New knowledge is added only through a reviewed PR — the xwiki-knowledge skill governs reading and extending it.
• Skills (xwiki/skills/):
  • xwiki-knowledge — read and extend the OKF knowledge base (declarative XWiki knowledge).
  • xwiki-build — canonical Maven build/test commands.
  • xwiki-pull-request — conventions for creating a PR (template, commit format, squash/backport).
  • xwiki-jira — view/search/create/update/transition issues on jira.xwiki.org (jira-cli or REST).
  • xwiki-test-guidelines — testing best practices and the XWiki test frameworks.
  • xwiki-javadoc — write clear, useful Javadoc following the XWiki Java Code Style and Oracle conventions.
  • xwiki-convert-tests — convert unit tests to JUnit5/Mockito.
  • xwiki-convert-tests-docker — convert functional IT tests to the Docker @UITest framework.
  • xwiki-increase-test-coverage — raise and lock in a module's unit-test coverage (JaCoCo instruction ratio).
  • xwiki-legacy — move a deprecated public API out of a main module into its -legacy companion (migrate callers, remove, re-add via a plain class or an AspectJ aspect, Revapi ignore).
  • xwiki-fix-flickering-docker-test — fix a flickering Docker-based functional test.
  • xwiki-deploy-extension — deploy a XAR/JAR extension to a running XWiki instance.
  • xwiki-rest-api — read/write a running XWiki over REST: get page content & xobjects, update pages & object properties, create pages (with xobjects), Solr search.
  • xwiki-xar-pages — edit extension wiki pages (XAR XML): the xar:format / xar:verify conventions.
  • xwiki-translations — externalize and render i18n strings safely.
  • xwiki-doc-writing — write, update or review a page of xwiki.org documentation per the XWiki Documentation Guide (Diataxis).
  • xwiki-doc-convert — convert old documentation (the Documentation space or the Extensions wiki) into the new /documentation tree.
  • xwiki-contrib-release-blog-post — create the " Extension Released" announcement on the xwiki.org Blog for an xwiki-contrib extension.
  • xwiki-fix-sonarqube-issue — find and fix SonarCloud issues, open a PR, mark them Accepted; the per-rule fix correctness and drop conditions it applies live in xwiki/okf/sonarqube/.
  • xwiki-backport — backport any change to an older branch: cherry-pick -x, adapt to the branch (module pom versions, Java level, style/API), verify, open the PR.
  • xwiki-backport-testneeded — backport testneeded-labelled tests to supported stable branches, adjust @since across branches, open the PRs (builds on xwiki-backport).

Required environment variables

Variable	Used by	Notes
XWIKI_LLM_HOME	opencode	Absolute path to your xwiki-dev-llm checkout. opencode only (Claude Code and Kimi Code resolve paths themselves).
SONARQUBE_TOKEN	sonarqube	Your personal SonarCloud token (same for all repos).
SONARQUBE_PROJECT_KEY	sonarqube	The SonarCloud project key — differs per repo. Optional: leave it unset in repos that have no SonarCloud project.
JIRA_API_TOKEN	xwiki-jira (jira-cli / REST)	Your jira.xwiki.org personal access token. Optional — only needed to act on JIRA issues. See "JIRA access" below.
JIRA_AUTH_TYPE	jira-cli	Set to bearer (PAT auth) for the self-hosted XWiki JIRA.

Setting SONARQUBE_PROJECT_KEY per repo

The project key is specific to each repository, so set it per checkout. The recommended way is direnv: drop an .envrc in each repo (it loads automatically when you cd in, and unloads when you leave). Add .envrc to your global gitignore so it's never committed:

# ~/dev/xwiki/xwiki-platform/.envrc
export SONARQUBE_TOKEN="<your-sonarcloud-token>"   # or set once in your shell profile
export SONARQUBE_PROJECT_KEY="org.xwiki.platform:xwiki-platform"

# ~/dev/xwiki/xwiki-commons/.envrc
export SONARQUBE_PROJECT_KEY="org.xwiki.commons:xwiki-commons"

Then run direnv allow in each repo once. Without direnv, just export the vars in your shell before launching Claude Code from that repo.

Find a repo's exact key on its SonarCloud project page (Project Information → Project Key) at https://sonarcloud.io/organizations/xwiki/projects.

JIRA access (for the xwiki-jira skill)

The xwiki-jira skill lets Claude view, search, create, update and transition issues on jira.xwiki.org. This is optional — set it up only if you want Claude to operate on JIRA. Two backends; the skill auto-detects which is available.

Recommended: install jira-cli

jira-cli gives the richest experience. XWiki's JIRA is a self-hosted (Server/Data Center) instance authenticated with a personal access token (PAT):

1. Install it — e.g. brew install ankitpokhrel/jira-cli/jira-cli (see the installation guide for Nix, Docker, etc.).
2. Create a PAT in your JIRA profile (Profile → Personal Access Tokens) and export it, plus the bearer auth type, in your shell profile (or a git-ignored .envrc as above):

   export JIRA_API_TOKEN="<your-jira-personal-access-token>"
   export JIRA_AUTH_TYPE="bearer"

3. Run jira init and choose:
   • installation type Local (on-premise, not Cloud),
   • server https://jira.xwiki.org,
   • authentication type bearer (PAT),
   • your login (JIRA username / email) and a default project (e.g. XWIKI).

Fallback: REST API only

If you don't install jira-cli, the skill falls back to the JIRA REST API using the same JIRA_API_TOKEN as a bearer token — just export it:

export JIRA_API_TOKEN="<your-jira-personal-access-token>"

The token is read from the environment and never committed. Issue-field conventions (Component, Affects/Fix Version) are documented once in xwiki/okf/servers/jira.md.

xwiki.org credentials (for the documentation skills)

Optional. The documentation skills write to xwiki.org over REST; put your xwiki.org credentials in ~/.xwiki-credentials (chmod 600) and they are found instead of asked for. Two lines, no quotes and no export — the file is sourced:

XWIKI_USER=MyUserName
XWIKI_PASSWORD=<your-xwiki.org-password>

Validate

claude plugin validate ./xwiki   # manifest schema
node scripts/validate.mjs        # repo consistency (skill inventory, version sync, OKF map)

scripts/validate.mjs also runs automatically in CI (GitHub Actions) on every push and pull request.

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.