nim-code-organization

Files (3)

• SKILL.md
• orchestration_pattern.md · references/
• parser_state_pattern.md · references/

SKILL.md (first lines)

# Nim Code Organization

Choose the smallest structure that exposes the real workflow.

# Rules

## State ownership

- Use ordinary locals when a workflow fits clearly in one proc.
- When independently meaningful operations must preserve one invariant, collect that state in
  a named object and pass it explicitly.
- Start with a plain `object` passed by `var`.
- Choose `ref object` when identity, aliasing, or shared lifetime is part of the design.
- Make shared mutation visible in proc parameters and field updates.

## Helper placement

- Extract a helper when it names a meaningful step, is reused, isolates a contract, or makes
  an invariant easier to state.
- To share an implementation across compile-time variants, parameterize one helper with 
  `static[bool]` or a static enum and branch with `when`.
- Keep a short, one-use sequence in its driver when extraction would only move lines elsewhere.
- Put helpers at module scope when several phases use them or they stand on their own.
- Use a nested proc for logic local to one caller or for an intentional closure.
- A nested proc captures outer locals by default. Mark it `{.nimcall.}` when its non-capturing
  calling convention is required.

## Module boundaries

- Give each module one cohesive responsibility and public contract. A module may own several
  related types or pieces of state.
- Split a module when a part has an independent responsibility, dependency set, lifecycle,
  or reuse boundary.
- Export only the types and entry points callers need.
- Keep orchestration state and helpers private unless another module is meant to use them.
- Do not use `{.define.}`/`{.undef.}` to scope behavior across modules; use a runtime parameter.

## Control flow

- Keep the normal path structured so its invariants remain visible.
- For a closed set of behaviors, represent the kind as data and branch with `case`.
- Use `method` when runtime subtype dispatch is part of the design, rather than as the default
  way to divide orchestration steps.

## Incremental APIs

- When the caller drives consumption piecewise, keep the cursor and lifecycle state in
  the object's fields so it survives between calls.
- Expose one proc per transition, with `open`/`close`-style lifecycle procs only when a
  resource or ordering constraint spans calls; keep a one-shot operation a single proc.
- Enforce that ordering with an assert on the lifecycle field (for example
  `assert s.opened`) at the start of each `next`-style proc.

# Workflow

1. Trace the data flow.
   Identify which values evolve, which steps share them, and which invariants must hold
   between steps.
2. Choose the smallest state scope.
   Use locals for one clear proc, a plain object for operations preserving one invariant,
   and a reference only for intentional identity or shared lifetime.
3. Shape the helpers.
   Extract meaningful operations. Keep local incidental logic near its caller.
4. Choose module boundaries.
   Group code by responsibility and contract, then split only at a real dependency,
   lifecycle, or reuse boundary.
5. Define the public surface.
   Export the minimum caller-facing types and operations.
6. Choose dispatch.
   Use direct calls and `case` for closed behavior. Introduce runtime dispatch for an open
   subtype-based design.

## State Scope

| Situation | Default shape |
| --- | --- |
| One linear operation | Local values in one proc |
| Several operations share an invariant | Plain state object passed by `var` |
| One caller owns a short captured operation | Nested proc |
| Several phases share a named operation | Module-level proc |
| Identity or shared lifetime is required | `ref object` |

# Common Mistakes

| Mistake | Why it is wrong |
| --- | --- |
| Hiding state shared by several phases in nested captures | The mutation and cross-phase invariants disappear from proc signatures |
| Creating a state type for a short linear calculation | The extra type adds ceremony without clarifying ownership or invariants |
| Extracting every small block into a top-level helper | The reader must jump between names that do not represent meaningful operations |
| Splitting modules by file size alone | File length does not identify a responsibility, dependency, lifecycle, or reuse boundary |
| Using a `method` hierarchy for a closed set of kinds | Static data plus `case` keeps the possible behaviors visible to the compiler and reader |
| Exporting orchestration helpers or state by default | It turns implementation details into a public compatibility obligation |
| Starting with `ref object` for locally owned state | It introduces aliasing and identity that the workflow does not require |

## References

- `references/orchestration_pattern.md` — Inventory reservations across independent operations
  that share a stock invariant, contrasted with a local calculation.
- `references/parser_state_pattern.md` — A scanner object for incremental cursor and lifecycle state.

From Vyrnexis/nim-agent-template, MIT.

More from Vyrnexis/nim-agent-template