# Example: Oh My OpenAgents

**Example crew plugin** · 3 lifecycle events · 1 middleware · 5 commands · 3 skills · `host.agents` + `host.models`
· multi-file TypeScript

Inspired by the open-source *oh-my-openagent* project, this package turns an AgentParley account into a conducted
team: a lead that decomposes work by category and delegates it in parallel to six specialists, each on the model
that suits its job. It shows every crew technique at once.

| Agent | Role | Model preference (first match among the account's models) |
| --- | --- | --- |
| Sisyphus · Orchestrator | the lead; decomposes, delegates, integrates, finishes on evidence | flagship reasoning (Opus, GPT-5, …) |
| Prometheus · Planner | plans with acceptance criteria before building | strong reasoning |
| Hephaestus · Deep Worker | scoped implementation end to end | GPT-class coding models first, then Claude |
| Oracle · Architect | architecture review and root-cause debugging | the highest-reasoning models |
| Librarian · Researcher | grounded research with exact citations | fast, cheap models able to synthesize |
| Explore · Navigator | fast "where does X live" navigation | the cheapest, fastest models |
| Argus · Visual Analyst | screenshots, diagrams, image analysis | strong multimodal models |

It needs room for seven agents (plus the account's default agent) — an Entrepreneur plan.

## Package layout

```
oh-my-openagents/
  readme.md
  index.ts                 registrations only
  src/
    crew.ts                the seven members: key, name, soul, instructions, model preferences
    reconcile.ts           the self-healing provisioner
    models.ts              picks each member's model from the account's models
    providers.ts           per-model-family prompt corrections
    doctrine.ts            the lead's doctrine and the specialists' report contract
    types.ts
  tsconfig.json            authoring only, left out of the upload
  commands/
    orchestrate.md  plan.md  deep.md  debug.md  research.md
  skills/
    parallel-orchestration/skill.md
    parallel-orchestration/references/routing.md
    parallel-orchestration/references/verification.md
    root-cause-analysis/skill.md
    evidence-first-delivery/skill.md
```

Multiple source files, so `index.ts` is the entry; the `src/` modules are pulled in by relative imports.

## `index.ts` — everything the platform needs to see

```ts
// infrastructure/plugins/oh-my-openagents/index.ts
import { reconcileCrew } from "./src/reconcile";
import { ORCHESTRATION_DOCTRINE } from "./src/doctrine";
import { CREW } from "./src/crew";

globalThis.manifest = {
  agents: CREW.map((member) => ({ key: member.key, name: member.name })),
};

globalThis.events.pluginInstalled = async () => {
  await reconcileCrew();
};
globalThis.events.sessionStarted = async () => {
  await reconcileCrew();
};
globalThis.events.pluginUpdated = async () => {
  await reconcileCrew();
};

globalThis.middleware.systemPrompt = async (context) => {
  const { agents } = await host.agents!.list();
  const isOwnedCrewMember = agents.some((agent) => agent.id === context.agentId);
  return isOwnedCrewMember ? context.systemPrompt : context.systemPrompt + ORCHESTRATION_DOCTRINE;
};
```

At publish the platform discovers: 3 lifecycle-hook capabilities, 1 middleware, 5 commands, 3 skills. From the
`host.agents.list/create/update/delete` and `host.models.list` calls (in `src/reconcile.ts`) it derives
`agentApi:agents.read`, `agentApi:agents.write` and `agentApi:models.read`. The manifest's `agents` lets the install
page say **Adds 7 agents** and check plan room first. No egress, no settings.

## 1. Declare each member once — `src/crew.ts`

```ts
// infrastructure/plugins/oh-my-openagents/src/crew.ts (one member, abridged)
{
  key: "sisyphus",
  category: "orchestration",
  name: "Sisyphus · Orchestrator",
  description: "The lead. Reads true intent, decomposes by category, delegates in parallel, integrates, and drives to a verified finish.",
  preferredModels: [/opus/i, /gpt-?5(?!.*(mini|nano))/i, /kimi|k2|k3/i, /glm/i, /sonnet/i],
  replyMode: "auto",
  soul: "You are Sisyphus, the tireless conductor. …",
  baseInstructions: "You CONDUCT. You almost never do the deep work yourself. The loop for every non-trivial request: …",
},
```

`key` is the stable identity used everywhere: in `manifest.agents`, in `host.agents.create`, and when reconciling.
Names are for people and can change.

## 2. Pick a model per member — `src/models.ts`

Each member lists model-name patterns in preference order. The first pattern matching one of **the account's**
enabled models (`host.models.list()`) wins; no match falls back to the account default. The resolved model's family
(Claude, GPT, Gemini, Kimi, GLM) then selects a short corrective overlay appended to the member's instructions —
so the same protocol reads right on each vendor.

## 3. Heal the crew — `src/reconcile.ts`

On install, on every update, and at the start of every interactive chat, `reconcileCrew()`:

1. lists the installation's own agents and the account's models;
2. provisions the lead first (as a **main** agent), so its id exists;
3. provisions each specialist as a **subagent** whose parent is the lead — `create` if its key is missing,
   otherwise `update` to re-assert name, persona, instructions, model, reply mode, parent, and `enabled: true`;
4. deletes any agent it owns whose key is no longer in `CREW`.

Delete a specialist in the console and it's back on the next new chat. Upgrade the plugin with a new member and
it appears after the update. See the full code in [Agent crews](plugin-agent-crews.md#self-healing-crews).

Two details worth copying:

- `create` sends a flat `parentAgentId`; `update` sends `parent: { parentAgentId }` so "no parent" (`null`) and "leave
  it" (omitted) are distinct.
- Every call is written `host.agents!.x(…)` — never through a variable — so the permission scan sees it.

And one to decide deliberately: because `update` re-asserts the whole definition, a user's edits to a crew member
are reset on the next chat start.

## 4. Make the lead a conductor — doctrine, contract, skills, commands

- **Doctrine (middleware).** Every turn, agents that are *not* crew members get a short orchestration doctrine: a
  routing table by category (planning → Prometheus, deep → Hephaestus, architecture → Oracle, research → Librarian,
  navigation → Explore, visual → Argus) and a five-step loop — read true intent, decompose by category, spawn
  independent units in parallel, integrate, finish on evidence. Crew members are skipped so a specialist never
  starts orchestrating.
- **Report contract (instructions).** Every specialist's instructions end with: do one scoped thing fully, then
  report the result *with evidence* **by calling `report_to_caller`**.
- **Skills (on demand).** The doctrine ends by pointing at `parallel-orchestration`, a multi-file skill with the
  full method, the routing table (`references/routing.md`) and a done-checklist (`references/verification.md`),
  loaded with `use_skill` only when the lead actually conducts. `root-cause-analysis` and `evidence-first-delivery`
  are for specialists.
- **Commands.** `/orchestrate <goal>` runs the whole loop; `/plan`, `/deep`, `/debug` and `/research` send a goal
  straight to one specialist:

```markdown
---
description: Run the full crew orchestration loop on a goal — decompose, delegate in parallel, integrate, and finish on evidence.
argument-hint: <goal>
---

Run the full Oh My OpenAgents orchestration loop on the goal below. You are the conductor — decompose and delegate; do not try to carry every stone yourself.
…
Goal: $ARGUMENTS
```

## What the user experiences

They install it, see seven new agents under Sisyphus, and type `/orchestrate migrate the docs site to the new
template` to Sisyphus. Sisyphus asks Prometheus for a plan, then starts Hephaestus and Librarian in parallel with
`start_subagent`; the chat shows a live card per specialist. The platform holds Sisyphus's answer until both have
called `report_to_caller`, then Sisyphus integrates the results and replies once.

## Ideas to build on it

- Add `middleware.interAgentMessage` to enforce the report contract (e.g. flag reports that claim "done" without
  evidence) — see [Agent crews](plugin-agent-crews.md#watching-and-shaping-crew-traffic).
- Mark specialists `isGroupOnlyCallable: true` so only Sisyphus and siblings can reach them.
- Use `thinkingLevel: "high"` for Oracle and Prometheus.