--- title: "Operating rules" description: "Standing instructions from the operator that every agent session on this repository follows, with the date each was given. Read before planning, dispatching, landing, or editing the roadmap." audience: "agents and maintainers" updated: "2026-09-27" --- # Operating rules These are the operator's standing instructions, recorded so a session does not have to be told twice. Each rule names the date it was given and where it is enforced. A rule that is retired is deleted, not kept beside its replacement. ## Roles and routes - **The planner does not write product code.** Claude plans, reviews, and lands. The default writer is the native Grok CLI (`grok-4.7`), a starting rotation rather than a sole writer. If Grok is logged out, use a relief route the tracker admits or stop and say what was hit. (`CLAUDE.md`, standing.) - **One writer per checkout.** Each unit of work runs in its own lane worktree (`kxm lane create `). Two writers in one tree clobber each other. (2026-09-25.) ## Landing - **Every PR is landed without asking.** Once a PR is open: monitor it, rebase onto `main` when it falls behind, resolve conflicts and blockers, merge, and follow through to the auto-release tag and the npm publish. Report the outcome; do not stop to ask for the merge. Enforced by `kxm land` (verify, docs, push, pr, rebase, unblock, merge, release, milestone); every stage ran green end to end on #338 with kxm 0.7.126, so hand landing is the exception, not the rule. (2026-09-26.) - **Documentation is regenerated after a green pipeline and before the merge.** The `docs` stage of `kxm land` runs the roadmap generator and commits the regenerated pages on the branch. (2026-09-26.) - **After every phase or milestone, the intense pass runs, not the refresh.** `/reanalyze-roadmap` (the `kxm-roadmap-review` skill with its read-only critic), triggered by the `milestone` stage reporting `deep_review_required`. (2026-09-26.) - **`npm run verify` stays the pre-push gate.** It is the first stage of landing and is never replaced by it. CI's validate leg runs the same script. (2026-09-26.) - **After every publish, the workflow runs on the improvements it just landed.** `kxm update --kxm`, then `kxm update --extensions`, then `kxm plugin install --all`, so the CLI and the kxm plugin in pi, omp, and Claude Code are current; the Claude Code session then needs `/reload-plugins`, which only the operator can run. The supervisor tick does this after any `PUBLISHED` line. (2026-09-26.) ## Entry points - **No new just recipes.** The repository is migrating off `just`. A needed entry point is a `kxm` command: a group under `plugins/kxm/src/cli/`, registered in `cli.ts`, owned by a bundled skill so `check:generated` passes, documented in the CLI reference. Existing recipes retire as their `kxm` verbs land; the transport recipes (`impl`, `plan`, `review-arch`, `review-cli`, `impl-bg`, `dispatch`) retired in #343, so units dispatch through `kxm lane run --brief --workflow implement-only` and the read-only critic workflows `review-arch-only` and `review-cli-only`. `just` keeps only the assignment-runner recipes (`assign`, `witness`, `accept`, `observe-cost`, `attribute`, `change-report`, `plan-current`), which are harness transport for the issue 127 runner. (2026-09-26.) ## Accounts - **Machine account names follow [ADR-0006](../adr/ADR-0006-machine-account-names.md).** Platform-wide accounts are `svc--`. Tenant-scoped accounts are `svc---`, where `` is the tenant slug. Test, witness, and proof accounts use those shapes with a `test-` prefix and are never members of production groups. Authentik-managed accounts (outposts and `ak-*`) are exempt. Recorded names such as `kxm-agent`, `kxm-witness-*`, `witness9`, and `kxmdproof` stay until an approved inventory. Do not invent a replacement for a specific account. (2026-09-27.) ## Decisions and debt - **Automated KXM work records every medium-or-higher decision it makes in `docs/contributing/decisions.md`** for its working project: the options evaluated, the weight each option scored and against what, and why the selected option won. Recorded the turn the decision is taken, not at session end. The doc keeps the last 50 entries; older ones rotate to `docs/contributing/decisions-archive.jsonl` as `kxm.decision-archive.v1` lines. (2026-09-27.) - **Every option comes with pros and cons and two recommendations**, the solid-product answer and the interim answer. (2026-09-26.) - **Every shortcut goes on the backlog the same turn it is taken**, as an item in `plans/backlog-shortcuts.md` with what was skipped and the proper fix. (2026-09-26.) ## Roadmap and plan content - **No stale data.** A fact that no longer holds is replaced, never kept beside its replacement. - **History is brief.** One short line per material change, capped by the generator; never a running narrative. - **No stale contacts.** A contact carries a role and a confirmation date; unconfirmed past 90 days is dropped. Empty is fine. - **Present and upcoming only.** Superseded material leaves the roadmap. - **Progressive detail.** A far-off phase or task is brief but complete (goal, scope, done criterion, evidence needed) and gains detail as it nears implementation. A task cannot be `ready` without a template and a source. - **Tasks use the artifact templates** under `docs/templates/`. All six enforced by the `kxm.roadmap.v1` schema, the generator's semantic refusals, and the two roadmap skills. (2026-09-26.) ## Monitoring - **Background monitors emit progress, not only results**, in this line form: `[{lane}/{agent}]: {phrase}. {No action|Review needed}. - {E}e|{D}d ({M}m{S}s)`. Routine lines are not echoed back in chat. (2026-09-26, formatter at `~/.claude/scripts/evt-monitor.sh`.) - **A supervisor tick runs every thirty minutes** while a session is open: sweep the lanes, act on "Review needed", cap concurrent verifies at two, regenerate the roadmap after a merge, and run the improvement loop every tick. Its prompt is checked in at `plans/kxm-roadmap/supervisor-prompt.md`; a tick that finds the schedule missing or expiring recreates it from that file in the same chat session, never a new one, so the loop continues under the same task. (2026-09-26.) ## Where the same rules live for agents The session memory under `~/.claude/projects/…/memory/` mirrors these as `pr-landing-autonomy`, `pipeline-docs-then-merge`, `no-just-prefer-kxm-cli`, `decisions-pros-cons-backlog`, `roadmap-editorial-rules`, and `monitor-progress-events`. This page is the checked-in copy; when the two disagree, this page is updated and the memory follows.