# 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](/guidelines.md) and the idioms in [/patterns.md](/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.