Collaboration Protocol

This document is the practical collaboration contract for humans and AI systems working in this repository.

Use it when:

  • starting work on a branch
  • handing work between collaborators
  • deciding whether to branch from main or from an active concern-line branch
  • checking what is expected before opening code and making changes

Core Idea

NEXUS work is repo-centered, not chat-centered.

Chat can help discovery and momentum.

The repository is the durable memory.

That means collaborators should recover expectations from:

  • docs
  • decisions
  • tests
  • source
  • branch topology

not from memory of prior conversations alone.

Important discoveries should become durable repo memory before collaborators rely on them repeatedly.

Important repeated work should also be pushed toward deterministic and reviewable repo surfaces instead of remaining dependent on the habits or capabilities of one particular AI.

Start-Of-Work Checklist

Before significant work:

  1. read README.md
  2. read repository-concern-lines.md
  3. read glossary.md
  4. read the relevant decision records and runbooks
  5. inspect whether the work belongs on:
  6. main
  7. a truly necessary temporary side branch
  8. inspect the branch relationship to main
  9. inspect the actual relevant source, tests, docs, artifacts, and repo shape instead of guessing from prior chat or memory

Tooling Expectations

When a collaborator expects a standard local tool and it is not installed or not available in the current environment:

  • say so explicitly
  • do not silently substitute a weaker workaround if the missing tool meaningfully affects the workflow
  • prefer giving the user the exact tool name and installation need so they can install it if desired
  • once the tool is available, prefer the expected tool over ad hoc substitutes

Examples:

  • gh for GitHub repo and PR workflows
  • visualization tools such as dot or sfdp
  • managed Git automation such as the Codex commit-checkpoint post-commit hook when commit-to-chat traceability is part of the workflow
  • other build, packaging, or repo-management tools that materially change the normal workflow

When using dotnet tooling:

  • do not run parallel dotnet build, dotnet run, or dotnet test commands against the same project path when they will write to the same build output
  • prefer one build followed by --no-build runs when parallel follow-up work is needed
  • if true parallelism is needed, isolate outputs or use separate worktrees/projects so the commands are not fighting over the same files

This avoids avoidable MSBuild file-copy contention and misleading build noise.

Branching Expectations

  • main is the current converged shared baseline
  • for now, main is also the default active branch for normal work
  • if a temporary side branch is created, keep it tightly scoped and merge it back into main promptly
  • do not keep long-lived concern-line branches alive unless the human explicitly decides to reintroduce that topology later
  • accepted branch work merges into main with --no-ff
  • direct commits to main are acceptable for small admin/docs cleanup while this temporary main-first policy is in effect, but substantial work should still be reviewed intentionally

Branch deletion guidance:

  • delete a short-lived branch after merge when the workstream is complete enough that the next step should start from main
  • keep a long-lived branch when its concern line still needs an independent cadence or expects more checkpoint merges
  • delete a long-lived branch once it no longer needs to evolve separately from main

This temporary main-first policy can be revisited later if a concern line truly needs an independent cadence again.

Worktree Expectations

A Git worktree is an additional checked-out working directory that shares the same repository object database.

Use a linked worktree when it materially helps with one of these situations:

  • an active side branch needs to stay checked out without constantly switching the main workspace
  • merge or conflict-resolution work is easier in a separate temporary checkout
  • concurrent local work would otherwise fight over one directory's branch state
  • isolated build outputs or repo state are useful while reconciling branches

Worktrees are an operating tool, not a branch-retention policy.

That means:

  • do not keep extra worktrees around once the branch no longer needs an independent cadence
  • after merging and retiring a branch, remove its worktree if one exists
  • prefer returning to one local main worktree after convergence unless there is a clear reason not to
  • if a branch still needs to live, keeping a worktree for it can be a useful signal that the concern line is still active

Implementation Expectations

When behavior changes:

  • update or add tests
  • update docs and runbooks
  • update public help and xmldoc when public surfaces change
  • keep navigation-oriented Markdown docs GitHub-clickable with valid relative links instead of dead or plain-text path references
  • when a repeated workflow becomes important enough, prefer encoding it into reviewed functions, scripts, commands, or schemas rather than relying on prompt memory alone
  • default durable/model time to UTC and localize it in views unless there is a clearly documented exception

If a change is docs-only or tests are not applicable, say that explicitly.

See:

Durable Learning Expectations

When an important rule, discovery, correction, or architectural learning emerges:

  • record it in the repo at the right level instead of leaving it only in chat
  • update an existing durable doc when that is the clearest home
  • create a new decision record, concept note, glossary entry, or requirements doc when needed
  • add or update tests when the learning should be enforced behaviorally
  • reference the durable record from the places where that learning matters

For Penpot-specific work:

  • compare the backend API, MCP/plugin, and exported .penpot surfaces instead of assuming one surface tells the whole story
  • record verified differences and gaps durably so future collaborators do not have to rediscover them
  • update the Penpot comparison note when a capability is proven or ruled out

Do not assume future collaborators will recover the learning from chat history alone.

See:

Decision Expectations

Formalize durable rules when they are:

  • expected to guide future work repeatedly
  • important to collaboration or safety
  • easy to forget if left only in chat

That usually means writing or updating:

  • a decision record
  • a glossary entry
  • a concern-line doc
  • a runbook
  • durable repo memory for important discoveries and corrections

Repo Split Expectations

When lines become distinct enough, namespaces and repos should follow the conceptual ownership:

  • Nexus.* for foundation/system work
  • FnTools.* for reusable tooling libraries
  • CheddarBooks.* for concrete product/app work

See:

Goal

The goal is that a new human collaborator, Claude, Codex, or later CORTEX can enter this repository, read a small set of docs, and understand:

  • what NEXUS is doing
  • what branch topology means here
  • what quality and documentation expectations exist
  • where a new piece of work belongs