skeleton

README.md

@@ -0,0 +1,103 @@
+# Tribes Plugin Template
+
+Template for creating [Tribes](https://github.com/your-org/tribes) plugins.
+
+## Getting Started
+
+1. Click **"Use this template"** on GitHub to create your own repo
+2. Clone and rename:
+
+```bash
+git clone https://github.com/you/your-plugin.git
+cd your-plugin
+./scripts/rename.sh your_plugin YourPlugin
+```
+
+3. Edit `manifest.json` — set description, capabilities, requirements
+4. Implement your plugin in `lib/your_plugin/plugin.ex`
+5. Run tests:
+
+```bash
+mix deps.get
+mix test
+```
+
+## Development
+
+For local development alongside a Tribes checkout:
+
+```bash
+# Symlink into the host plugins directory
+cd /path/to/tribes
+ln -s /path/to/your-plugin plugins/your_plugin
+
+# Start Tribes dev server — your plugin loads automatically
+iex --sname dev -S mix phx.server
+```
+
+Edit your plugin source. Phoenix code reloader picks up changes.
+
+## Project Structure
+
+```
+your_plugin/
+├── manifest.json           # Plugin metadata (Nix build + runtime)
+├── mix.exs                 # Dependencies
+├── lib/
+│   ├── your_plugin/
+│   │   ├── plugin.ex       # Tribes.Plugin entry point
+│   │   └── application.ex  # OTP supervision tree (optional)
+│   └── your_plugin_web/
+│       └── live/            # LiveView pages
+├── assets/                 # JS/CSS (one bundle per plugin)
+├── priv/
+│   ├── static/             # Built assets for release
+│   └── repo/migrations/    # Ecto migrations
+└── test/
+```
+
+## Manifest
+
+`manifest.json` declares your plugin's identity and capabilities:
+
+```json
+{
+  "name": "your_plugin",
+  "provides": ["some_capability@1"],
+  "requires": ["ecto@1"],
+  "enhances_with": ["inference@1"]
+}
+```
+
+- **provides** — capabilities this plugin makes available
+- **requires** — hard dependencies (build fails without them)
+- **enhances_with** — optional dependencies (plugin degrades gracefully)
+
+See the [Plugin System docs](https://github.com/your-org/tribes/blob/master/docs/PLUGINS.md) for the full specification.
+
+## Testing
+
+Three test levels:
+
+- **Unit tests** (`test/your_plugin/`) — plugin logic in isolation
+- **Manifest tests** (`test/your_plugin/manifest_test.exs`) — manifest schema validation
+- **Contract tests** (`test/contract_test.exs`) — runtime spec matches manifest
+
+Run all: `mix test`
+
+## Building for Release
+
+```bash
+MIX_ENV=prod mix compile
+
+mkdir -p dist/your_plugin
+cp -r _build/prod/lib/your_plugin/ebin dist/your_plugin/
+cp -r priv dist/your_plugin/
+cp manifest.json dist/your_plugin/
+```
+
+For Nix-based deployment, add your plugin to the host's `plugins.json`.
+
+## Licence
+
+TODO: Choose a licence.