airi: Skill for Codex

Enforce AIRI TypeScript Rules

Apply these rules to every TypeScript and Vue source change in AIRI. The root AGENTS.md gives the core code rules. This skill gives the detailed rules.

Imports and Types

• Import types from the module or package that owns the contract. Do not redeclare an external or public contract locally to use a narrower subset.
• Do not route type imports through local runtime assembly modules when the original side-effect-free type source is available.
• If Node-only and browser-only types mix in one import chain, move the type declarations into a neutral type file. Keep the runtime modules environment-specific.
• Do not import values from a module that has side effects only to get its types.
• If a wrong or missing export causes an error, trace the full import chain and side-effect chain first. Fix the package exports or the owning boundary. Do not add a local workaround import at the leaf.
• Before you fix an import or type error, examine the compilation behavior and the type declarations. Also examine the exports field in package.json, and the browser and Node entry points of the dependency.
• Keep JSON Schemas compliant with providers. Give an explicit type: object and the required fields. Do not use unbounded records.

Naming

• Let module boundaries provide context. Do not repeat package, product, protocol, or transport names in symbols. The exception is a symbol that crosses a boundary where that context is otherwise lost.
• Name functions after domain operations, not implementation layers.
• Use nouns for resolved domain concepts. Use verbs for transformations and side effects.
• If a symbol needs several ownership qualifiers to be clear, reconsider the module boundary or introduce a clearer domain concept.

Comments

• Write a comment only for information that the code cannot express clearly: intent, constraints, ownership, invariants, precedence, lifecycle, ordering, side effects, protocol shape, or non-obvious fallbacks.
• Do not add comments that only restate names, types, or visible operations.
• Treat a contract comment as an explanation of the relationship between a producer and its consumers.
• Explain why a value exists in the system before you explain how the code represents it.
• Describe the decision, behavior, or invariant that a value controls.
• If different values select different control-flow or UI paths, describe each observable outcome.
• If a value crosses a module or component boundary, identify the consumer and how it applies the value.
• Put representation details after behavior: units, coordinate systems, thresholds, clamps, and source API fields.
• Put background evidence after the contract: browser behavior, issue links, investigation history, and removal conditions.
• If the name, type, and surrounding code express the full contract, omit the comment.
• Put an implementation comment next to the branch, calculation, transition, or side effect that it explains.
• In calculation-heavy code, explain non-obvious coordinate systems, units, conversions, clamps, rounding, aggregation, and precedence. Put each explanation next to the related intermediate value or branch.
• Prefer clearer names, types, and structured state over comments that compensate for hidden or encoded concepts.
• When you move code, keep the accurate comments. Remove the comments that no longer describe current behavior.
• Write an investigation-heavy comment as short paragraphs. When useful, give the context and the observed failure. Then give the reason that the obvious fix is not sufficient. Give the chosen fix and its removal condition or references.
• Use these markers:
  • // TODO: for follow-up work.
  • // REVIEW: for a concern that needs another opinion.
  • // NOTICE: for workarounds, magic values, external constraints, and other important non-obvious context. The root AGENTS.md gives the required format for a workaround.