ax-conventions

What problem does it solve?

Standardizes how to write and modify AX plugins and hooks so they remain transport/storage agnostic, avoid unsafe coupling, and stay fully wired and correct across the system.

Core Features & Use Cases

• The five invariants: enforce transport- and storage-agnostic hook payloads, prohibit cross-plugin imports, prevent half-wired plugins, ensure one source of truth per concept, and require explicit/minimized capabilities with untrusted content handling.
• Plugin manifest format: document and implement manifest.registers, manifest.calls, manifest.optionalCalls, and manifest.subscribes so boot-time validation and dependency cycles behave predictably.
• Hook bus mechanics: choose between service hooks (hooks.call) and subscriber hooks (hooks.fire), including timeout behavior, return-shape validation, and isolation of subscriber failures.
• Boundary review checklist: guide signature changes and payload evolution with checks for alternative implementations, payload leak risks, subscriber risk around “opaque” tokens, and correct wire surface ownership.
• Common patterns: apply opaque version tokens, lazy content fetchers in deltas, optimistic concurrency via parent, two-phase validation (pre-apply/applied), construction-time config, boot-time cycle detection, and tenant-scoped query helpers.

Quick Start

Use the ax-conventions skill when you are about to add a new hook signature or modify an existing AX plugin so you can validate your payload shape, dependencies, and security boundaries before merging.