Favour code a future human can follow over abstractions that merely look enterprise-ready. Keep names concrete, files focused, and dependency direction obvious.
- Keep Core independent of frameworks and persistence.
- Put implementation details behind Core-owned interfaces only when a real alternate implementation, external concern, or test seam justifies it.
- Keep ASP.NET endpoint code thin: validate HTTP input, call an application boundary, and return a response.
- Do not put SQL, database types, Razor components, or
HttpClientin Core. - Do not add a generic service, repository, event bus, mediator, or base class until duplicated real code proves the shared abstraction.
- Give extension contributions stable, namespaced IDs. Reject duplicate IDs; never silently overwrite a contribution.
- Add an extension API only after an in-tree feature has exercised it.
- Prefer ordinary HTTP request/response behavior for user operations. Do not require persistent browser connections unless the feature truly needs them.
- Keep mutable Universe state separate from reusable templates.
- Before adding a durable design decision, update
docs/in the same change. - Prefer one set of shared visual primitives (
world-shell,panel,item-list, form controls) over page-specific component styling. Use the platform's built-in HTML elements until a repeated interaction justifies a component. - Never edit an applied SQLite migration. Append a new migration and test upgrading an existing database shape.
- Features own canonical state and Driver contracts. Drivers return typed proposals; Providers expose external capabilities. Neither may bypass Core validation or write canonical feature data directly.
Before considering code complete:
- build the solution;
- run Core, Infrastructure, and API integration tests when their behavior changes;
- smoke-test a changed HTTP or UI path when applicable;
- update relevant documentation;
- avoid leaving generated test databases or running local servers behind.
Documents should record decisions and their reasons, not narrate every edit. When a decision changes, revise the old statement rather than accumulating contradictory historical instructions. Use version control for history.