# Integrations An integration binds one OAS layer to a real framework. It can bind knowledge to OKF, messaging to aweb, tasks to Jira, or anything else your deployment uses. Integrations are intentionally small. The minimal integration is just: 1. **Skills** that teach agents how to use the framework. 2. **An injection** that tells agents those skills exist and when to load them. It may also provide lifecycle hooks and external requirements. ## What an integration contains A bundled or self-contained integration can have this shape: ```text team-chat/ oas.json skills/team-chat/SKILL.md injects/team-chat.md bin/team-chat-hook.mjs ``` The manifest tells OAS what the integration provides: ```json { "integration": "team-chat", "layer": "messaging", "description": "Messaging through the team chat system.", "requires": [ { "command": "team-chat", "why": "send and receive messages" } ], "skills": ["skills"], "inject": "injects/team-chat.md", "hooks": { "spawn": "bin/team-chat-hook.mjs spawn", "retire": "bin/team-chat-hook.mjs retire" } } ``` Not every integration needs a manifest. A hand-rolled integration can live entirely in `oas-config.yaml` by pointing at a skills directory and an injection file. ## Injections An injection is not runtime code. It is instructions written into each soul's `AGENTS.md`. An integration's injection should answer: - What framework is active? - Which skill should the agent load? - What is the scope? For example, messaging only, tasks only, knowledge only. - What must the agent avoid? For example, do not use chat for task state. Example injection: ```md ## Tasks: Linear This workspace tracks tasks in Linear. Use the **linear-tasks** skill before creating, updating, or closing work items. Coordination stays in Linear, not mail. ``` OAS writes the injection into the soul's `AGENTS.md` when the soul is created. It reconciles the block at spawn and through `oas sync`. Instances do not get per-instance injections. They read their soul's AGENTS.md. Per integration, configure injection with `agents-md-injection`: | Value | Meaning | |---|---| | absent or `default` | Use the integration's shipped injection file. | | path | Use your own file. Any path relative to the level root works. | | `none` | Do not inject instructions. Skills still attach. | A clean convention is `injects/.md` or `.agents/injections/.md`, but the path is yours. ## Hooks Hooks let an integration do lifecycle work. The kernel runs hooks for resolved layers only. | Event | Example use | |---|---| | `soul-scaffold` | Create a knowledge bundle. | | `spawn` | Create instance memory or mint a messaging identity. | | `post-commit` | Harvest notes after an instance commits. | | `retire` | Delete a messaging identity before the home is removed. | Hooks run with the instance home as cwd, except `soul-scaffold`, which runs from the soul dir. Environment includes `OAS_EVENT`, `OAS_INSTANCE`, `OAS_HOME`, `OAS_AGENT`, `OAS_SOUL`, `OAS_CONTEXT`, `OAS_WORKSPACE`, `OAS_ROOT`, `OAS_LEVEL`, `OAS_SETTINGS`, and `OAS_META` where relevant. A hook may print JSON: ```json { "meta": { "alias": "docs-expert-audit" }, "brief": "Comms ready." } ``` `meta` persists in `instance.json` and returns as `OAS_META` at retire. `brief` is added to `TASK.md`. `warning` is surfaced to the spawner. Hook failures warn and never block spawn. ## Requirements `requires` declares external commands an integration needs. OAS checks them when the layer resolves and warns at spawn or in `oas doctor`. Example: ```json "requires": [ { "command": "aw", "why": "identity minting and agent messaging", "install": "https://aweb.ai/docs" } ] ``` A missing command is loud but non-fatal. ## The bundled integrations ### oas-okf Binds the knowledge layer to OKF markdown bundles. It provides: - Soul knowledge bundles. - Instance `STATE.md`, `log.md`, and `notes/`. - The `okf` skill for bundle craft. - The `memory-harvest` skill for promotion judgment. - A `post-commit` hook that spawns a memory-harvest agent when notes are pending. ### oas-aweb Binds messaging to aweb. It provides: - A spawn hook that creates a team-scoped aweb identity for the instance. - A retire hook that self-deletes the identity. - Official aweb messaging and team membership skills from `@awebai/pi`. - An injection that tells agents to use `aw mail` and `aw chat` for messaging. Messaging is only messaging. Task state belongs in the task layer. ## Four ways to ship your own integration | Way | Location | Good for | |---|---|---| | Contribute it | `integrations//` in this repo | Broadly useful defaults. | | Install it | `oas install ` → `~/.oas/integrations//` | Reusing a published integration across a machine. | | Keep it local | `/.agents/integrations//` (or `oas install --here`) | One repo, workspace, or laptop. | | Use its own repo | `path:` in `oas-config.yaml` | Private or shared integrations outside OAS. | `oas install ` fetches (when remote), verifies the integration's declared `requires`, and binds it at the current level — for bundled integrations it is verify + bind in one step (`oas install okf`). A local integration with an `oas.json` is auto-discovered. You still select it under `layers:`. ```yaml layers: messaging: team-chat ``` A cloned integration uses `path:`: ```yaml integrations: team-chat: path: ../shared-integrations/team-chat layers: messaging: team-chat ``` When names collide, closer levels override outer levels. Bundled integrations are the floor. ## Minimal hand-rolled example A Linear task integration can be just a skill and an injection: ```text ~/agent-skills/linear/linear-tasks/SKILL.md ~/injects/linear.md ``` ```yaml # ~/oas-config.yaml layers: tasks: linear integrations: linear: skills: agent-skills/linear agents-md-injection: injects/linear.md ``` Every agent below `~` now gets the Linear skill and the Linear instructions, unless a closer config overrides `tasks`. Check it: ```bash oas doctor ~/some-oas-repo ``` Doctor shows where the layer resolved, which skills attached, which injection file was used, which hooks exist, and whether any `requires` are missing. ## Build one with an expert This repo includes an **integrations-expert** soul. It knows the five layers, manifest schema, hook contract, distribution paths, and reference integrations. Spawn it when you want help designing, building, or testing a new integration.