---

name: observal description: "Route repository work for Observal, an AI agent registry and observability platform with Python CLI, FastAPI server, harness telemetry, and Vite web UI." metadata: disco-role: operating disable-model-invocation: true license: Apache 2.0

Observal Repo Skill

Use this skill when working in or reasoning about the Observal repository: the observal CLI, registry/agent component workflows, FastAPI backend, harness adapters and telemetry, session traces, web UI, self-hosting/developer operations, tests, or contribution policy.

Observal is a monorepo for an agent-centric registry and observability platform. Its primary product surfaces are:

• Python CLI (observal) for auth, scan, doctor, registry components, agents, teams, ops/admin, server lifecycle, reconciliation, and support bundles.
• FastAPI server for registry APIs, auth/SSO/SCIM, telemetry ingest, ClickHouse/Postgres storage, insights, admin/review, teams, inbox, and GraphQL.
• Vite/React/TanStack Router web UI for registry browsing, traces, admin dashboards, settings, insights, teams, and account flows.
• Shared harness registry/adapters for Claude Code, Kiro, Cursor, Pi, Codex, Copilot, OpenCode, Antigravity, and Goose.

First read

• For repo freshness and evidence baseline, read repo provenance.
• For a compact architecture map, read overview.
• For install/test commands and optional heavy checks, read quick commands.
• For cross-cutting failure triage, read troubleshooting.

Route by task

User task	Use
Add, rename, test, or operate a Typer command; keep JSON/table/error contracts and bundled skills in sync	cli
Change REST/GraphQL routes, schemas, models, services, auth, insights, jobs, migrations, dynamic settings, or backend tests	server
Add/promote/debug a harness, scan/doctor/layer behavior, hook specs, session push/reconcile, session parsers, telemetry ingest, or model catalog coverage	harness-telemetry
Modify Vite/React routes, pages, components, query hooks, auth storage, UI types, theme tokens, Playwright specs, or screenshots	web
Choose setup/lint/test/release/compliance scripts, docs/changelog obligations, SPDX/pre-commit policy, AI contribution disclosure, or PR readiness checks	repo-development

When a task crosses layers, start with the implementation owner, then return to repo-development for broad tests, docs, changelog, screenshots, and contributor-policy checks.

Minimal setup and smoke checks

For CLI users, install the released tool with one of:

uv tool install observal-cli
pipx install observal-cli

For source work inside a checkout, the repo documents Python 3.11+, uv, Node/pnpm, and Docker for the optional stack. A fast local source smoke is:

uv tool install --editable .
observal --version
observal --help

For server-aware unit tests, the native pattern runs from the server directory while pointing pytest at root tests. The default Make target wraps this:

make test
make lint

Do not run Docker Compose or Playwright E2E by default. Use them only for live stack, browser, or Kiro-specific coverage and state that requirement in the handoff.

Bundled helper checks

These helpers are copied into the skill so future agents can check contracts without reopening the source docs:

python scripts/check_observal_skill_tree.py --skill-root skills/disco/observal --pretty
python sub-skills/cli/scripts/check_cli_contract.py --repo-root . --pretty
python sub-skills/server/scripts/check_server_routes.py --server-path . --pretty
python sub-skills/harness-telemetry/scripts/check_harness_registry.py --repo-root . --pretty
python sub-skills/web/scripts/check_web_contract.py --repo-root .
python sub-skills/repo-development/scripts/inspect_observal_repo.py --repo-root . --pretty

Expected signals: valid skill frontmatter, known CLI groups, server route registry import, ten registered harnesses with parser coverage, frontend contract markers, and repository markers/test counts.

Operating invariants

• No telemetry wrappers or OTLP environment variables: harness telemetry flows through session push hooks and reconciliation.
• Harness-specific behavior belongs in adapters and shared registry entries, not orchestrator if/elif chains.
• CLI command changes must update CLI docs and bundled skills; run the sync command before handoff.
• ClickHouse schema changes live in ClickHouse SQL migrations; Alembic is for Postgres only.
• Frontend harness data comes from the server; do not hardcode harness lists in React.
• Log with Loguru positional placeholders and never log secrets, tokens, JWT payloads, keys, or credential values.
• Tests mock external services by default; E2E specs are the exception and require a running stack.
• Keep AI-assisted contribution claims explainable and human-reviewed; autonomous PR submission is out of scope.