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.