Conventions and Working Agreements

Hard rules for how to work on demarkus with Fritz. These are collaboration and repo/process conventions, distinct from the Go code-quality rules in /guidelines.md and the idioms in /patterns.md. Reference all three before writing code.

These were migrated from Claude Code's built-in auto-memory on 2026-06-06 when that feature was disabled in favor of demarkus-soul as the single memory store. They were reconstructed from index summaries; the original long-form rationale for each was lost in the migration, so the "why" below is brief.

Collaboration

No sycophancy

On code or ideas. Critically review before presenting: layering violations, missing edge cases, state desync, stale references, channel blocking, rune vs byte vs cell-width confusion, silent error paths, leaky abstractions, wrong architectural layer. Challenge ideas before agreeing: what's the downside? what breaks? what's the simpler alternative? is this the right problem? Disagreement backed by reasoning is expected.

No AI co-author trailer in commits

Never add Co-Authored-By: Claude ... or any AI co-author trailer to commits or PRs. Fritz is the sole author.

Never ship anything broken

Grow PR scope rather than ship a known-broken surface. "A follow-up will fix it" is not a valid mitigation. If a change leaves something broken, the fix belongs in the same PR.

Prefer OSS, non-cost-blocker tooling

When recommending infra or platform tools, default to genuinely open-source options. Flag BSL/SSPL/Elastic-licensed or paid-tier-gated tools explicitly and offer OSS alternatives.

Question opt-in knobs that come from plans

When a plan calls for an Enabled bool or an "opt-in deployment," ask whether a real "off" deployment actually exists. Default to baking the capability in rather than adding a flag nobody will turn off.

Architecture and layering

Core vs knowledge-system layering

The protocol core is permanent. Broker, universe, onboarding, gateway, MCP, and the plugins are disposable overlays. Default to layering above the core; only touch core if the feature survives throwing away every product built on top of it.

No core changes for plugin work

Plugins must reuse the existing server/client/protocol surface. Discuss before touching core for a plugin feature.

Repo conventions

Branch for every change: never commit directly to main

Every change starts on a feature branch. Never commit to main, never push to main directly. Land via PR so reviews and CI gates fire. This is true even for work that looks small or obviously correct; the value of the rule is that it is not negotiated per change. Push to main triggers auto-release (see /patterns.md §CI/CD), so a direct commit to main also skips the release sanity-check that a PR provides.

The first step of any code-touching task is git switch -c <branch> (or confirm we are already on one). When in doubt, ask before staging changes.

This rule was added 2026-06-08 after a broker change landed on main as a direct commit. See /journal/2026-06-08.md.

Utility binaries live in tools/

New sync, agent, or dev-ops binaries go in tools/, not client/cmd/.

Bump plugin pin versions on every update

plugins/claude-code/scripts/lib.sh SERVER / CLIENT / TOOLS_VERSION must move with every plugin change.

No external runtime deps in the plugin

The claude-code plugin is pure awk/bash. No jq, no python, no node at runtime; parse JSON in awk. (This governs the shipped hook/script runtime, not dev-only test helpers.)

No ${{ }} in GitHub Actions run: comments

GH Actions parses run: blocks for expressions before shell semantics. A stray ${{ inside a # comment fails the entire workflow.

No em dashes in user-facing strings

CLI flag help, error messages, prompts, and MCP tool descriptions never use em dashes. Use a semicolon, colon, or comma instead. Code comments follow the surrounding file's idiom. Added 2026-07-06 after em dashes landed in the agent's -publish-retention help text.

Code comments are terse

Added 2026-07-13 after a review pass found agent-written comments running to 10+ line essays.

A comment states only what the code cannot show: the why, an invariant, a platform caveat, a rejected alternative that will tempt the next reader. Target 1-3 lines. No narration of what the next line does, no restating the function signature, no design-document prose in doc comments; deep rationale belongs in the soul (debugging.md, plans) or the PR description, with the comment carrying the one-line conclusion.

Refactor-on-touch: when editing code whose existing comments are verbose, tighten them in the same edit. Scope this to the code being touched; no repo-wide comment churn commits.