Skip to content

bruce48x/Lakona / skills/lakona-organize-server

lakona-organize-server

Verified

Audit, explain, or reorganize a Lakona game server without imposing one universal folder tree. Use when reviewing Server directory smells, deciding where Shared, Server.App, or Server.Hotfix code belongs, replacing technical-layer junk drawers with clearer domain locality, aligning namespaces after moves, or validating a proposed server layout while preserving the user's own architectural choices.

FileKindSize
SKILL.mdskill md4.5 KB
agents/openai.yamlconfig302 B
references/layout-heuristics.mdmarkdown4.6 KB

references/layout-heuristics.md

View on GitHub
# Lakona Server Layout Heuristics

## Hard Lakona Boundaries

These constraints follow runtime ownership rather than directory taste:

- Shared contracts own wire DTOs, RPC service and notification contracts, and
  stable numeric IDs. Keep server runtime dependencies out of Shared.
- `Server.App` owns stable resource types/dependencies, optional ComponentState,
  stable actor state shells, and types that must survive a generation change.
- `Server.Hotfix` owns reloadable product behavior: RPC handlers, complete HTTP
  service declarations and handlers, actor behavior, timer callbacks,
  lifecycle policy, and HotfixComponent tools, registration, and resource hooks.
- A component may inject a custom App dependency only as its concrete marked
  ComponentState. App interfaces, resource wrappers and object injection cannot
  hide business state. Keep State data-only, with basic initialization and actual
  IDisposable/IAsyncDisposable implementations; move ordinary methods and computed
  properties to the Hotfix owner. Framework services, generated ActorAccess and
  external stable resource interfaces remain valid dependencies.
- Business exceptions deriving directly or indirectly from `System.Exception`
  may stay beside Hotfix business logic. They are created with `new` from runtime
  data, require no role or DI registration, and must not use `[HotfixComponent]`.
  Remove a mistaken marker (`LAKONA20060`); do not move exceptions to stable App
  merely to satisfy old `LAKONA20037` guidance. Upgrade affected framework
  versions and validate compilation and Hotfix loading before removing temporary
  suppressions. Ordinary helpers still require their appropriate framework role.
- Generated code remains generator-owned. Change its source contract or
  generator rather than editing generated output.
- Project references must keep the stable-to-reloadable dependency direction;
  stable assemblies cannot depend on Hotfix implementation types.
- HotfixComponent identity is `Type.FullName`. Its effective set (including
  stateless helpers) and State binding freeze until restart. Renaming a type or
  namespace, adding/removing a component, or rebinding State requires restart;
  moving a file while preserving these contracts can remain reloadable.

A different folder name is valid when these ownership and dependency rules
still hold.

## Soft Heuristics

Evaluate these as signals, not laws:

- Prefer folders named for a business capability when one change routinely
  touches contracts, state, handlers, persistence, and tests for that
  capability.
- Keep a technical folder when its contents share one lifecycle, abstraction,
  or maintenance reason.
- Align namespaces with paths when the repository already uses that convention,
  after assessing type identity and restart requirements. A path convention does
  not justify silently changing a running component's identity.
- Keep sibling concepts at comparable granularity. A single tiny type does not
  need a new folder merely to make the tree symmetric.
- Optimize for the next likely change, not for a complete taxonomy.

An optional feature-first arrangement can look like:

```text
Server/
├── App/
│   ├── Users/
│   ├── Rooms/
│   └── Operations/
└── Hotfix/
    ├── Users/
    ├── Rooms/
    └── Operations/
```

This is an example of cross-assembly domain locality, not a required tree.
Layer-first, hybrid, or project-specific structures remain sound when they
communicate ownership and keep changes coherent.

## Smell Catalogue

Investigate rather than automatically rewrite:

- A generic folder accumulates unrelated reasons to change.
- One feature edit requires navigating many orthogonal folders with no useful
  ownership boundary.
- A path implies stable state while the type is reloadable behavior, or the
  reverse.
- Namespaces and paths diverge enough to make discovery or source scans
  unreliable.
- A source file combines contract, orchestration, persistence, and unrelated
  policy.
- Tests, configuration, reflection, or documentation depend on obsolete fully
  qualified names or literal paths.
- Empty folders, forwarding shells, or one-type abstractions remain after a
  move without serving compatibility.

## Choosing Among Valid Layouts

When more than one layout is sound, compare:

1. Which option matches the project's domain vocabulary?
2. Which option makes the most frequent changes local?
3. Which option makes stable versus reloadable ownership obvious?
4. Which option minimizes namespace churn and compatibility risk?
5. Which option does the user prefer after seeing the tradeoff?

Use the answer as a recommendation, not as a universal Lakona convention.
rea-analysis-optimizationmorluto/reaOptimize REA providers and shared analysis workflows for agent context, latency, CPU, and memory while preserving correctness and Evidence. Use for analysis bottlenecks and cache or query design; CI/test-suite optimization belongs to rea-ci-tests-audit.Stars: 472kUpdated Claude CodeCodexVerifiedInstall
rea-ci-tests-auditmorluto/reaAudit REA CI and test suites for correctness, fixture drift, false passes, and measured performance; use for suite or workflow investigations and efficiency changes, rather than ordinary feature testing or a single test failure.Stars: 472kUpdated Claude CodeCodexVerifiedInstall
rea-tool-designmorluto/reaAudit, investigate, design, or change REA investigation tools, CLI/MCP contracts, provider capabilities, and Evidence semantics.Stars: 472kUpdated Claude CodeCodexVerifiedInstall
ponytail-auditDietrichGebert/ponytailQuality audit of the whole repo: bugs, security, real load, missing tests, speed, and what to delete. Most important first.Stars: 194kUpdated Claude CodeCodexVerifiedInstall