Troubleshooting

Problems met in real workspaces, grouped by the part of the guide they belong to: what you see, why, and the fix.

Claude Code

The /rness:* commands do not appear

A session opens with the rness line, rness <version> · <organization> · …, but typing /rness lists no command.

Claude Code loads the rness plugin, .claude/skills/rness/, only in a folder whose trust dialog you accepted. A folder inside one you already trust never shows that dialog: the hooks run, so the rness line appears, but the plugin stays off.

1. Quit Claude Code in that folder.

2. From the folder you open Claude Code in, the workspace root or a repository's root, mark it as trusted:

   node -e '
   const fs = require("fs")
   const file = require("os").homedir() + "/.claude.json"
   const config = JSON.parse(fs.readFileSync(file, "utf8"))
   config.projects ??= {}
   config.projects[process.cwd()] = { ...config.projects[process.cwd()], hasTrustDialogAccepted: true }
   fs.writeFileSync(file, JSON.stringify(config, null, 2) + "\n")
   '

3. Start claude there again and type /rness: adr, plan, spec and status are listed.

What the command changes

~/.claude.json keeps one entry per folder under projects. The command sets "hasTrustDialogAccepted": true in the current folder's entry, which is what accepting the dialog writes, and leaves the rest of the file as it is. You can make the same change in an editor. Trusting a folder lets Claude Code apply the .claude/ files it holds: do it for a workspace you know. Observed with Claude Code 2.1.287 (2026-10-02).

Node.js and updates

rness needs Node … or newer

Every rness command checks the Node.js it runs on before anything else, and stops with rness needs Node <version> or newer (running v…). Install Node.js 22.17 or later.

Inside a workspace, rness runs the version pinned in .rness/package.json, and an older pin may ask for a newer Node.js than that. upgrade is the exception: it runs the copy you start. To move such a workspace to the latest release without changing Node.js, from .rness/:

npx @rness/cli@latest upgrade

Then push .rness and commit the files it lists, as in Update Rness.