arxdsilva/agent-office / .claude/skills/add-event-source
add-event-source
VerifiedAdd a new agent source/provider to agent-office (e.g. LangGraph, OpenAI Agents SDK, OpenTelemetry GenAI spans, Claude Code hooks). Use when asked to support or ingest agents from another framework or data source.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 2.3 KB |
SKILL.md
View on GitHub---
name: add-event-source
description: Add a new agent source/provider to agent-office (e.g. LangGraph, OpenAI Agents SDK, OpenTelemetry GenAI spans, Claude Code hooks). Use when asked to support or ingest agents from another framework or data source.
---
# Add an event source
Rules that apply: `TESTING.md` (TDD, ≥70%), `ARCHITECTURE.md`, `PRIVACY_SECURITY.md`.
First ask: can the producer just `POST /api/events`? If yes, document it in the README instead of adding code.
1. **Red** — `packages/adapters/src/sources/<name>/*.test.ts`: fixtures shaped like the real data with **invented** content. Test a pure mapper `toEvent(raw, ctx): AgentEvent | null`:
- identity (`agentId` stable and namespaced, e.g. `lg:<id>`), `parentId` for sub-agents
- `provider` (the zone) and `topic` (the row) — what would a user call this conversation?
- status mapping onto `idle | thinking | tool | waiting | error | done`
- malformed input → `null`
2. **Green** — `packages/adapters/src/sources/<name>/`: a pure mapper plus a driving adapter with `start()` / `stop()` / a testable `tick()`. It depends only on core ports (`ReportActivity`, optionally `AgentInbox`, `Clock`, `Scheduler`); put file/network access behind an adapter-local interface (like `TranscriptFiles`) so it can be tested in memory. Never throw out of `tick()`.
3. **Config** — a setting in `shared/src/desktop-api.ts` `SettingsSchema` (additive, with a default, and a restart field in `core/src/domain/settings.ts`), plus an env override in `adapters/src/config.ts` and `.env.example`. Start or stop it in `startBackend` in `desktop/src/main/composition.ts`.
4. **E2E** — `packages/adapters/test/e2e.<name>.test.ts`: real source → real core → `observe(office)` sees the agent in the right zone and row.
5. **Docs** — README "Sources" section: what is read, what is ignored, privacy notes.
6. **Privacy check** — only status, tool, title, model and ≤80-char snippets leave the source; nothing is logged raw.
7. `make check` (including `make arch`), then `/run-office` to see the new zone.
**Runtime-based providers** (a CLI agent-office can also start and manage, such as Codex or an ACP agent): this skill is not enough. Follow the checklist in `docs/provider-integrations.md` §8 (declaration, profile or runner, probe, optional observation hooks, composition, contract suites).
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis. | Stars: 472k | Updated | Claude CodeCodex | Verified | Install |
| diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness. | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependencies | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is available | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |