butler-sos

Imported from ptarmiganlabs/butler-sos (AGENTS.md). Install upstream with npx skills add ptarmiganlabs/butler-sos. Copyright stays with the author.

GitNexus — Code Intelligence

This project is indexed by GitNexus as butler-sos (2919 symbols, 5442 relationships, 247 execution flows). Use the GitNexus MCP tools to understand code, assess impact, and navigate safely.

If any GitNexus tool warns the index is stale, run npx gitnexus analyze in terminal first.

Always Do

• MUST run impact analysis before editing any symbol. Before modifying a function, class, or method, run gitnexus_impact({target: "symbolName", direction: "upstream"}) and report the blast radius (direct callers, affected processes, risk level) to the user.
• MUST run gitnexus_detect_changes() before committing to verify your changes only affect expected symbols and execution flows.
• MUST warn the user if impact analysis returns HIGH or CRITICAL risk before proceeding with edits.
• When exploring unfamiliar code, use gitnexus_query({query: "concept"}) to find execution flows instead of grepping. It returns process-grouped results ranked by relevance.
• When you need full context on a specific symbol — callers, callees, which execution flows it participates in — use gitnexus_context({name: "symbolName"}).

Never Do

• NEVER edit a function, class, or method without first running gitnexus_impact on it.
• NEVER ignore HIGH or CRITICAL risk warnings from impact analysis.
• NEVER rename symbols with find-and-replace — use gitnexus_rename which understands the call graph.
• NEVER commit changes without running gitnexus_detect_changes() to check affected scope.

Resources

CLI

Butler SOS — Agent Guide

GitNexus index freshness — handled by git hooks, not by you

The index is re-generated automatically by git hooks; you should not normally need to re-index by hand. One-time setup per clone: npm run gitnexus:install.

Never run a bare npx gitnexus analyze, including where the generated GitNexus block in CLAUDE.md / AGENTS.md suggests it. It rewrites that managed block and, without --skills, deletes the generated-skills table from both files. Re-index only through the npm run gitnexus:* scripts, which reach GitNexus through scripts/gitnexus.js and pass --skip-agents-md. Other subcommands (impact, context, query, detect-changes) are read-only and safe to run directly.

See docs/README.gitnexus.md for the hooks, the full command table and version pinning.

Ask before building when the goal is unclear

Ask up to four clarifying questions before starting whenever anything about the intended goal, the requirements, which files to touch, or the existing conventions is ambiguous. Ask them up front, together, not one at a time mid-task.

Ambiguous means two readings would lead to materially different work. It does not mean every judgement call — if the repo, the code or an obvious default settles it, settle it and say which way you went. The test is whether being wrong would waste the work.

Ask especially about what the change is meant to prevent or achieve, not just what to build. A task framed only as an implementation invites verification that confirms the code does what it says, rather than that it solves the problem — which is how a change can pass every check and still miss the point.

Git workflow

• STOP when the solution is done. Do not commit, push, open a PR, or merge until Göran says so. Finish the work, leave it in the working tree, and report what changed and what you verified. This is not a gate you can decide you have satisfied. Only an explicit instruction releases it, and it releases only the step named — "commit this" is not permission to push, and "push" is not permission to merge.
• Branch names MUST be prefixed with claude/. When creating a branch for ongoing work, name it claude/<short-description> — e.g. claude/fix-udp-source-validation. This keeps agent-created branches clearly namespaced and easy to filter or bulk-clean.
• Never commit directly to master — branch first, then open a PR
• One topic per commit. Group changes by the subject they address, not by the order you happened to make them. Work that touches three unrelated things is three commits, and often three branches. A commit message that needs the word "and" to describe itself is usually two commits. An unrelated fix noticed in passing does not belong in the current commit.
• Conventional Commits required; release-please derives the changelog and version bump from the commit type, so the type is load-bearing, not decoration. Format the subject as <type>: <imperative summary>. Sections defined in release-please-config.json: feat, fix, chore, refactor, docs, build, test

Finish by recommending what is worth doing next

Every time you hand work back, close with what remains and what it is worth. Rank the remaining items by value against cost — not by the order you happened to find them — and say which one you would do next, and why. State explicitly anything you chose not to do, and what it would take.

Be willing to recommend against work. "Not worth doing" is a useful answer; an exhaustive list of everything technically possible is not. If the most valuable next step is outside the current task — a different file, a different branch, or a decision only Göran can make — say so rather than filling the space with what happens to be nearby.

Doc site staging — docs/to-doc-site

User-visible changes must be documented in docs/to-doc-site, in the same PR as the code change — otherwise the change ships and the doc site never learns about it. That covers new or changed features, config settings, bug fixes an administrator would notice, and new log messages or status codes an operator might search for.

Skip it for changes with no admin-visible effect: internal refactors, test-only changes, CI/tooling, and dependency bumps.

Read docs/to-doc-site/README.md before writing. It is the single source of truth for when a file is required, who the audience is, and how the file must be named and structured.

Commands

• npm ci — install deps
• npm run lint:fix then npm run test:unit — required quality gates before commit
• npm run test:unit — Jest with ESM (uses node --experimental-vm-modules)
• Single test: node --experimental-vm-modules node_modules/jest/bin/jest.js src/path/to/file.test.js
• npm run format — Prettier (100 printWidth, 4 tabWidth, single quotes)

Architecture

• Runtime entrypoint: src/butler-sos.js — requires YAML config via -c/--configfile
• Global singleton: src/globals.js (Settings class) — many modules depend on it; prefer existing patterns
• Config: YAML file loaded via config package; template at src/config/production_template.yaml
• Plugins: Fastify plugins in src/plugins/; use fastify-plugin patterns
• Tests: __tests__/ folders next to code, *.test.js naming, ESM imports from @jest/globals

Conventions

• ESM only ("type": "module") — use import/export, avoid require
• JSDoc enforced — ESLint with eslint-plugin-jsdoc; document all params, returns, and Promise types
• Logging — use globals.logger (winston-based), never console.log; use src/lib/log-error.js helpers for SEA compatibility
• Config-driven — prefer YAML config + config package over env vars or hard-coded values
• Dependencies — Docker/SEA builds use --omit=dev; runtime deps must be in dependencies, not devDependencies

SEA (Single Executable App)

• src/lib/sea-wrapper.js provides isSea() and path helpers
• In SEA binaries, __dirname/__filename are unavailable; use the sea wrapper
• Suppression of DEP0169 warnings from @influxdata/influxdb3-client is in src/butler-sos.js:34-48

Security

• No real secrets/keys/certs in repo — config templates/examples only
• systeminformation package may execute privileged OS commands on Windows — respect Butler-SOS.systemInfo.enable config option

OpenWiki

This repository has documentation located in the /openwiki directory.

Start here:

• OpenWiki quickstart

OpenWiki includes repository overview, architecture notes, workflows, domain concepts, operations, integrations, testing guidance, and source maps.

When working in this repository, read the OpenWiki quickstart first, then follow its links to the relevant architecture, workflow, domain, operation, and testing notes.