bobi-agent: Instructions file for Codex

Bobi Agent Instructions

Read ~/AGENTS.md first for general coding rules. This file only contains repo-specific guidance for Bobi.

Bobi is an event-driven AI agent framework.

Reference Docs

• README.md: product overview, installation path, architecture summary, and user-facing setup docs.
• skills/bobi.md: CLI command reference.
• skills/create-agent.md: agent team authoring guidance.
• skills/checklist-execution.md: the generic worker protocol for running a long job from a committed markdown checklist (read once, next item, verify, commit) - no engine, no framework code.
• skills/slack-setup.md: Slack integration setup.
• skills/whatsapp-setup.md: WhatsApp (Meta Cloud API) integration setup.
• skills/discord-setup.md: Discord bot integration setup (Gateway, local server).
• skills/linear-setup.md: Linear integration setup.
• docs/EVENT_SERVER.md: event-server architecture, topics, and security model.
• docs/SELF_HOSTED_EVENT_SERVER.md: running your own webhook ingress - tunnel, standalone Node event server, or the durable Cloudflare Worker.
• docs/ADMIN_PROTOCOL.md: the supervisor sidecar's wire contract (admin topics, the nine commands, heartbeat/lifecycle schemas, compatibility promise). Versioned by SUPERVISOR_VERSION; additive-only pre-1.0.
• docs/REFERENCE_IMAGE.md: the published container image (ghcr.io/moda-labs/bobi) - what it contains, the --init requirement, the runtime env contract, the TEAM_DEPS bake hook, and how it is published.
• docs/AGENT_STATE.md: the agent page's state tri-state (running / stopped / not_responding), the manager health probe behind it, and the status strip's best-effort telemetry segments.
• docs/AGENT_OVERVIEW.md: the agent page's read-only composition view (GET .../overview) and the script_cache savings block in the spend payload - how automations are counted and how savings are priced.
• docs/RUNS_VIEW.md: the unified runs read model behind the agent page's one table (GET .../runs) - the status vocabulary, the stalled threshold, and the rule that one piece of work produces one row.
• docs/RUN_DRILLDOWNS.md: opening a run - the debugging transcript view (timestamps + tool calls, distinct from /messages) and the Details payload for runs that have no transcript.
• docs/MONITORS.md: monitor scheduler and the script_cache token-saving runner.
• docs/WORKFLOW_ENGINE.md: workflow state machine, step types, suspend/resume.
• docs/RUN_RESUME.md: resuming a stalled workflow run from the agent page - why it spawns a process, and where the single-winner claim lives.
• docs/TOOL_LIBRARY.md: unified dependency model - declaring tools/skills/MCP deps (pinned install: vs guide-only), the catalog, and how they bake + verify.
• docs/OTEL.md: agent-authored OTLP telemetry (bobi agent <name> otel) - operator setup, the resource-attribute table, collector bring-up, and the write-only per-instance token requirement.
• docs/FINE_GRAINED_METRICS.md: implementation and operations guide for the session/turn/invocation/tool usage pipeline, schema, Admin/MCP queries, transcript recovery, list pricing, and JEV routing configuration.
• docs/JEV_ROUTER_DATA_FLOW.md: how a JEV routing decision flows from session start through the policy call, the sticky route, and telemetry into the metrics view.
• docs/SECURITY.md: overall security model (trust, credentials, prompt-injection).
• docs/TICKETING_POLICY.md: Linear/GitHub ticketing conventions.
• docs/RELEASE_RUNBOOK.md: release process and checklist.
• docs/FRONTEND_QA.md: local frontend QA guidance for Bobi's vanilla web UIs.
• docs/design-system/: the Bobi design system - source of truth for anything visual on any Bobi surface (palette, type, icon set, components).
• DESIGN.md: source of truth for bobi setup UX and its offline constraints; its visual tokens were superseded by the design system on 2026-07-31.