Build on Oblive
Extend Oblive through its typed, durable, and reviewable application and package boundaries.
This guide is for contributors adding product behavior, integrations, skills, profiles, API contracts, runtime capabilities, storage mechanics, or local-stack configuration.
Start with Ownership
Before writing code, identify the canonical owner of the state you are changing. Do not select a queue, cache, process, or framework before answering that question.
| Concern | Canonical Owner |
|---|---|
| Organizations, chats, tasks, attempts, inbox, schedules, actions | PostgreSQL |
| Built-in templates, skills, managed integration presentation | Git agent-pack catalog |
| Published catalog revisions and large artifacts | S3-compatible object storage |
| Organization profile selections and pins | PostgreSQL profile records |
| Semantic organizational memory | Files and object storage |
| Live chat signals | Redis Pub/Sub as transport |
| Worker wakeups | Redis Streams as transport |
Redis, a browser, a harness session, process memory, and a local workspace are never the only durable owner.
Choose an Extension Path
Architecture
Understand the closed loop and non-negotiable invariants.
Agent Packs
Add skills, profile capabilities, and static MCP grants.
Integrations
Add managed MCP, STDIO, OAuth, or CLI providers.
Backend Endpoint
Follow the type-to-OpenAPI implementation path.
Runtime and Control Plane
Extend manifests, harness behavior, and oblivectl.
Change Checklist
Close code, tests, CLI, API docs, and knowledge-base impact together.
Engineering Style
- Prefer functions and small composable helpers.
- Keep factories thin and public exports intentional.
- Parse
unknownat integration boundaries; do not introduceany. - Use typed discriminated unions for persisted variants.
- Keep behavior in the layer that owns it.
- Reuse existing lifecycle records before adding tables or services.
- Prefer the smallest reversible change that closes the workflow end to end.
Required Documentation Impact Review
Every change under apps/ or packages/ must assess:
- Does agent-authored control-plane behavior require an
oblivectlor command-reference change? - Does an HTTP contract require backend OpenAPI documentation?
- Does setup, configuration, behavior, architecture, or an extension workflow require a page here?
- Does an accepted decision or cross-layer journey require its owning architecture reference?
Record deliberate not-applicable decisions. Documentation is part of the change, not follow-up work.