Skip to content

Codify single-owner coordination, protocol-state, and durable-outbox ethos in CLAUDE.md #549

@FidoCanCode

Description

@FidoCanCode

Problem

#397 codified the repo's OO + constructor-DI rules, but it intentionally stayed broad. It did not define the more specific coordination ethos now emerging from the runtime pain:

  • one owner per mutable state bucket
  • explicit command/transition boundaries across webhook, worker, and recovery flows
  • durable outbox/store semantics for crash-safe intents
  • smaller coordination code with fewer timing branches as an explicit design goal

Without writing that down, the repo will keep half-remembering the lesson in local fixes:

  • one PR will remove a timing edge
  • the next PR will reintroduce a different ambient coordination seam because the deeper rule was never stated

This issue should make the new coordination ethos reviewable and teachable, not just intuitive to whoever most recently debugged a heisenbug.

Scope

  • CLAUDE.md
  • directly related architectural guidance for runtime coordination work
  • explicit language for ownership, commands, durable intent boundaries, and state-transition thinking

Required design constraints

  1. Build on #397 rather than replacing it.
  2. Define single-owner mutable state as the default coordination rule.
  3. Define command translation at webhook/entry boundaries.
  4. Define durable outbox/store boundaries as separate from in-memory coordination.
  5. State plainly that the goal is smaller code with fewer edge cases, not abstraction for its own sake.
  6. Give reviewers language to reject new ambient coordination globals, long-lived callable-slot seams, and cross-thread reach-through behavior.

Acceptance criteria

  • CLAUDE.md contains an explicit coordination ethos, not just the broad OO/DI rules
  • contributors can tell where coordination logic should live and what kinds of boundaries are preferred
  • reviewers can point to one written rule set when rejecting new shared-state or procedural coordination drift

Non-goals

  • This issue does not implement coordinators yet.
  • This issue does not choose a framework.
  • This issue does not require naming every future class up front.

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Projects

    No projects

    Milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions