omni

name: omni description: "Wire a Genie agent to an Omni channel in one canonical flow — register the agent, bind to an instance, verify the round-trip. Replaces the 5+ command legacy chain." allowed-tools: Bash(omni ), Bash(genie )

/genie:omni — Canonical Genie ↔ Omni Wiring

Single-command wizard that takes an operator from "no agent yet" (or "an existing genie agent") to "agent answering messages on a channel". Wraps genie agent register + omni connect + verification into one conversational flow so operators don't have to remember two systems' command surfaces.

When to Use

Adding a new agent to a connected Omni channel.
Wiring an existing genie agent dir to a fresh Omni instance.
Verifying that an existing wire still works end-to-end.
Operator types /genie:omni and expects the assistant to drive.

If the legacy multi-command chain (omni providers create + omni agents create + omni instances update --agent + omni routes create) is what you reach for first — stop and use this skill instead. The legacy chain still works for power users / CI but emits stderr deprecation nudges pointing here.

Pre-conditions (verify before driving)

These checks are quick and tell you which Phase to start in. Always run them up front:

omni auth status      # Phase 1 needed if missing or invalid
genie serve status    # Phase 4 verification needs this green
omni instances list   # at least one connected instance needed for Phase 3

Flow

Phase 1 — Omni installed and authenticated?

Entry: Always (first thing to check).

Steps:

Run omni auth status. If it reports a valid connection, skip to Phase 2.
If not authenticated or omni is not installed:
- Tell the operator that omni needs a one-time bootstrap and instruct them to run omni install in a separate terminal (do NOT nest two interactive flows from inside this skill — the omni installer is itself a wizard).
- Wait for the operator to confirm omni install completed.
- Re-run omni auth status to verify, then continue to Phase 2.

Exit: omni auth status succeeds.

Phase 2 — Pick or scaffold the genie agent dir

Entry: Phase 1 passed.

Steps:

Ask the operator: "Which genie agent are we wiring? Existing one, or do we scaffold a new dir?"
If existing:
- Ask for the agent name.
- Run genie dir ls <name> to confirm it's already registered. If yes, skip to Phase 3.
- If not registered, ask for the agent's home directory — the path that contains a real AGENTS.md. Validate up front:
  - The path must exist.
  - <dir>/AGENTS.md must be a real file, not a symlink. If it's a symlink, ask whether the operator wants to register the dir the symlink points to instead (almost always the right answer), or pass --allow-symlink (only if intentional template-sharing layout).
- Run genie agent register <name> --dir <validated-path>. The default flow auto-registers the agent in Omni (creates the agent record). Do NOT pass --skip-omni here — Phase 3 uses omni connect which expects the agent record to exist.
If scaffolding new:
- Direct the operator to /genie:wizard (which scaffolds an agent identity and AGENTS.md), then come back to this Phase 2 with the freshly-scaffolded dir.

Exit: genie dir ls <name> returns a clean entry with the correct Dir: field.

Phase 3 — Bind to an Omni instance

Entry: Phase 2 passed.

Steps:

Run omni instances list and show the operator the connected instances (those with ACTIVE=yes). Highlight the channel and profile name so the operator picks the right one.
If there are no connected instances, point the operator at /omni:omni-setup (the omni plugin's connect-channel wizard) and pause this flow until an instance is connected.
Once the operator picks an instance:
- Run omni connect <instance-id> <agent-name> — this is the canonical command. It:
  - reads genie dir ls <name> --json (so the agent must have been registered in Phase 2),
  - creates (or reuses) a nats-genie provider,
  - creates (or reuses) the omni agent record bound to that provider,
  - updates the instance with agentId, agentProviderId, agentReplyFilter, and triggerMode.
- The operator can pass --mode turn-based (default, recommended for chat) or --mode fire-and-forget if they have a reason. Default --reply-filter all is fine for KHAL-V1-LAUNCH-style group bots.
Confirm the success summary printed by omni connect — note the agent ID, provider ID, and the NATS subjects (omni.message.<inst>.* inbound, omni.reply.<inst>.* outbound).

Exit: omni connect exits 0 with the configuration summary.

Phase 4 — Verify the round-trip

Entry: Phase 3 passed.

Steps:

Confirm the bridge daemon is running:
```
genie serve status
```
If not running, start it:
```
genie serve start --headless
```
Confirm the bridge is subscribed to the right NATS subjects:
```
nats --server localhost:4222 server report connections | grep genie-omni-bridge
```
Should show 7+ subscriptions with non-zero uptime.
Run a synthetic round-trip:
- Tell the operator to send a real test message in the chat that's now wired (e.g. a WhatsApp group).
- Watch the omni-api log: tail -f ~/.pm2/logs/omni-api-out.log | grep <chat-id> — expect Received → Dispatching → Published to NATS → Agent response within a few seconds.
- On the genie side: genie agent ls should show a new per-chat agent (e.g. <name>:<chat-id> in idle state).

Print the final topology:

📨  WhatsApp/Telegram
     │
     ▼
🌐  Omni instance      <instance-id>     channel=<channel>
     │
     ▼
🔌  nats-genie provider <provider-id>    agentName=<name>
     │
     ▼  NATS subject: omni.message.<inst>.*
     ▼
🤖  genie-omni-bridge → spawns claude in <agent.dir> with --resume <session>
     │
     ▼
📝  Claude (TUI)       responds via `omni say "..."`

Exit: A real test message gets a real reply in the chat. Done.

Recovery

If any Phase fails, point the operator at Runbooks/wire-new-omni-agent.md (lives in their genie-configure brain) for the fallback two-command path:

genie agent register <name> --dir <validated-path>
omni connect <instance-id> <name>

…plus the troubleshooting table for common symptoms (wrong cwd, bridge not subscribing, multiple agents with same role).

Rules

Never nest interactive flows. If omni install or /genie:wizard is needed, hand off to the operator and pause this skill.
Never use --skip-omni in this flow. It defeats Phase 3.
Always validate --dir is real (not a symlink). As of v4.260429.14+, genie agent register rejects symlinked AGENTS.md by default; this skill should not pass --allow-symlink unless the operator explicitly says so.
Always run omni connect, not the legacy chain. If the operator is mid-way through manually creating providers/agents/routes, ask them to stop and run omni connect instead — it's idempotent and reuses anything already created.
Never commit secrets. The omni_sk_… API key in ~/.omni/config.json is read by genie agent register automatically; never echo it back to the operator or include it in commit messages.

name: omni description: "Wire a Genie agent to an Omni channel in one canonical flow — register the agent, bind to an instance, verify the round-trip. Replaces the 5+ command legacy chain." allowed-tools: Bash(omni *), Bash(genie *)

/genie:omni — Canonical Genie ↔ Omni Wiring

When to Use

Pre-conditions (verify before driving)

Flow

Phase 1 — Omni installed and authenticated?

Phase 2 — Pick or scaffold the genie agent dir

Phase 3 — Bind to an Omni instance

Phase 4 — Verify the round-trip

Recovery

Rules

See also

name: omni description: "Wire a Genie agent to an Omni channel in one canonical flow — register the agent, bind to an instance, verify the round-trip. Replaces the 5+ command legacy chain." allowed-tools: Bash(omni ), Bash(genie )