Repository Guide
Locate behavior in the owning app or package and run the correct development checks.
Workspace Map
| Location | Responsibility |
|---|---|
apps/backend | API, validation, persistence, orchestration, jobs, OpenAPI, integrations |
apps/frontend | Product routes, data loading, forms, Context, tasks, inbox, integrations |
apps/agents | Chat/worker runtime, harness adapter, workspace lifecycle, trusted MCP/CLI registries |
packages/types | Shared typed contracts and trusted integration runtime definitions |
packages/agent-packs | Git catalog, profile instructions, skills, validation, revision hashing |
packages/oblivectl | Authenticated agent control-plane CLI |
packages/organization-context | Local read-only contextctl verify |
packages/objectstore | Provider-neutral object storage and safe workspace operations |
packages/redis | Connection-injected cache, Pub/Sub, and Stream primitives |
packages/chat-commands | Shared chat command parsing/contracts |
sites/docs | Operator/developer knowledge base and generated API reference |
scripts | Stack configuration, portable generation, release CLI, and Bun tests |
.github/scripts | CI checks, release builders, smoke tests, and their fixtures |
The root Bun workspace contains apps/* and packages/*. sites/ is a separate Bun workspace
with its own manifest, lockfile, isolated dependency layout, and release lifecycle.
Backend Placement
Use the owning layer:
- validators parse params, queries, bodies, environment, and persisted untrusted input;
- repositories own organization-scoped CRUDL and transactions;
- services/helpers compose lifecycle behavior;
- controllers own one request-facing operation per named function;
- routes bind middleware and handlers;
- application modules assemble startup and shutdown; and
- documentation modules own OpenAPI paths and examples.
Do not put request behavior in routes or domain behavior in server assembly.
Runtime Preferences
Prefer Bun and Web APIs. Use Bun-supported compatibility modules only when needed. Do not add
node: specifiers or NodeJS namespace types. Validate environment once and inject dependencies in
tests.
Baseline Commands
bun install --frozen-lockfile
bun install --cwd sites --frozen-lockfile
bun run check:all
bun testbun run check is product-only. Use bun run check:all to check both dependency roots. Run the
affected app or package typecheck during implementation, then the complete relevant suite before
committing.
Continuous Integration
CI keeps expensive environment checks out of pull requests while preserving one required result:
| Trigger | Checks |
|---|---|
Pull request into main | Formatting, linting, type checks, tests, release tooling, and production frontend assets |
Push to main | The pull-request checks plus a complete disposable source-stack smoke |
The final CI job is the stable branch-protection check. Release and site workflows require a
successful CI run for their exact main commit. Releases do not repeat general repository checks;
they retain the semantic-image and packaged-stack smoke test because those artifacts do not exist
until publication begins.
Keep general validation in CI, release-only assembly in .github/scripts/release, executable smoke
tests in .github/scripts/tests, and test fixtures below .github/scripts/tests/fixtures.
Worktree Discipline
- Preserve unrelated user changes.
- Stage exact files for each semantic commit.
- Review
git diff --cached --name-statusbefore committing. - Keep commits aligned to one completed extension or documentation checkpoint.