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

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.