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
- Build on
#397 rather than replacing it.
- Define single-owner mutable state as the default coordination rule.
- Define command translation at webhook/entry boundaries.
- Define durable outbox/store boundaries as separate from in-memory coordination.
- State plainly that the goal is smaller code with fewer edge cases, not abstraction for its own sake.
- 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.
Problem
#397codified 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:Without writing that down, the repo will keep half-remembering the lesson in local fixes:
This issue should make the new coordination ethos reviewable and teachable, not just intuitive to whoever most recently debugged a heisenbug.
Scope
CLAUDE.mdRequired design constraints
#397rather than replacing it.Acceptance criteria
CLAUDE.mdcontains an explicit coordination ethos, not just the broad OO/DI rulesNon-goals