0003-collaboration-working-agreements

ADR-0003: Collaboration & git working agreements

• Status: Accepted
• Date: 2026-05-30
• Scope: core (all repos, every project)

Context

Development is AI-assisted across several independent repos. That makes it easy
to (a) start editing on the wrong branch, (b) land changes the human hasn’t
reviewed, or (c) lose the thread on a multi-phase initiative. These are the
working agreements that keep the human in control, the history clean, and the
shared knowledge current. They complement the branching mechanics in
0001-three-step-git-flow.

Decision

• Branch before editing. Create the feature/* branch off develop before
  editing any file — never start work on develop/main.
• Approval-gated writes. Never commit, merge, or release without the user
  explicitly saying so. Proposing a diff is fine; landing it needs a yes.
• Branch both repos for cross-repo work. A cd into one repo does not leave
  you on a feature branch in the other — branch each repo explicitly at the start
  of a cross-repo phase.
• Recap before each phase. Before starting a new phase of a multi-phase
  initiative, restate purpose + current state + this phase’s scope, and wait for
  confirmation before writing code.
• Batch small related fixes. Don’t spin a fresh branch for every one-line
  change; bundle related follow-ups into one branch.
• Consult the handbook before implementing. Before non-trivial work — and
  before authoring a new ADR — check docs/core/ and the relevant project’s
  folder for an existing convention that governs it. The handbook is the durable
  shared memory; don’t rely on recall.
• Document decisions proactively, then ask. When a choice will bind future
  work, propose an ADR (or an update to one) rather than leaving it in chat or a
  private memory — and ask before landing it. Memories point at ADRs, they
  don’t restate them.
• One decision, one home — keep the set compact. Generic rules live in
  docs/core/; project-scoped ones in that project’s folder (see
  0009-one-knowledge-monorepo). When the same rule appears in two ADRs, merge
  or cross-link it; don’t let it drift in two places.

Consequences

• The human always knows what is about to land and where.
• A little more upfront ceremony (branch + recap) in exchange for predictable,
  reviewable changes and no surprise commits.
• These are behavioral rules for the assistant; they are not currently enforced
  by tooling (a future Stop/pre-merge hook could check branch + approval state).

Related

• 0001-three-step-git-flow — the branching/release mechanics themselves