tribes-plugin-kobold/AGENTS.md

Tribes Plugin Agent Guide

This repository is a Tribes plugin. Preserve generated names unless a task explicitly asks to rename the plugin.

Required Workflow

• Use plugin for plugin-aware commands in the devenv shell: plugin validate, plugin test, plugin precommit, and plugin smoke. Outside the devenv shell, use the local scripts/plugin wrapper.
• Use devenv shell -- <command> when installing or building Node assets from outside the devenv shell. Do not run raw npm install directly.
• Do not use raw mix test for host-backed plugin suites unless you are deliberately recreating the plugin test host environment by hand; use mix raw_test only for that low-level debugging path.
• For AshPostgres resource changes, generate migrations with plugin ash.codegen <name>. Use plugin ecto.migration <name> only for rare manual schema migrations that are not derived from Ash resources.
• Do not edit an existing migration after it may have run; add a new migration instead.
• Run scripts/plugin smoke after changing mix.exs, manifest.json, entry modules, or host-facing dependency setup.
• Keep commits semantic, for example feat: add plugin smoke checks, and include a body except for minimal patches.

Plugin Contract

• manifest.json entry_module must point at the plugin entry module.
• The dev :tribes dependency is compile-only so host plugin loading can build _build/dev beams without starting a nested host app.
• The test :tribes dependency is runtime-enabled so host-backed tests can start Tribes.Repo and related services.
• If the plugin adds cluster-synced Ash resources, use AshNostrSync deliberately and document replication semantics in docs/plugin-contract.md.

Frontend

• Default pages should render inside host chrome with Tribes.Plugin.Layouts.app; keep org.tribe-one.caps.ui@1 in manifest.json requires for host chrome or direct Tribes.UI usage.
• Prefer TypeScript in assets/ts for browser code. The default build emits browser-ready files to priv/static.
• Register plugin LiveView hooks from manifest.json assets.global_js bundles via window.TribesPluginHooks. The host does not auto-import external plugin phoenix-colocated/<otp_app> modules into its app.js bundle.
• Keep CSS selectors plugin-scoped to avoid collisions with the host or other plugins.
• Use the package scripts in assets/package.json; do not bypass them with ad-hoc asset commands.