# 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

### 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](/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.