flowstate-obs-server Package Skill

Package: @epicdm/flowstate-obs-server Repository: epic-flowstate-community Path: packages/obs-server Version: 0.1.0

Use this published Dojo skill as the package-level entrypoint. For detailed workflows, use the package-local skills listed below.

Primary Package Workflow

FlowState Obs Server Consumer Compatibility

Status: Active Purpose: Prevent obs-server changes from silently breaking downstream packages and services. Scope: Cross-package compatibility for packages/obs-server. Trigger: A route, auth, payload, port, stream, WebSocket, RPC, schema, or Docker/service change may affect consumers. Input: Proposed obs-server change and affected API/stream/runtime surface. Output: Compatibility-aware implementation with downstream checks recorded.

Consumer Map

Contract Surfaces

Check downstream consumers before changing:

• Route paths or HTTP methods.
• X-API-Key auth.
• ?apiKey= EventSource auth.
• Authorization: Bearer WebSocket auth.
• Event, log, error, session, or breadcrumb schema fields.
• SSE event names or payload shape.
• WebSocket message type envelopes.
• RPC request/response envelopes and status mappings.
• Default port, service name, Docker image, or gateway route.

Compatibility Workflow

1. Name the exact contract being changed.
2. Search for route/path/schema/auth usage across the repo:

rg "api/stream|/api/errors|/api/logs|/api/sessions|/api/rpc|OBS_SERVER_URL|OBS_API_KEY|obs-server|Authorization: Bearer|X-API-Key" packages

3. Update server tests for the contract.
4. Update consumer tests or types where the contract is public.
5. Record intentional breaking changes in package docs and feature matrix.

Example: Change SSE Event Shape

1. Update src/routes/stream.ts and route tests.
2. Update packages/obs-client SSE parsing/tests.
3. Update packages/obs-browser stream client if browser-facing.
4. Search generated docs/Dojo for stale examples.
5. Re-run obs-server and affected client tests.

Verification

At minimum:

yarn workspace @epicdm/flowstate-obs-server test --runInBand --no-cache
yarn workspace @epicdm/flowstate-obs-server typecheck

For cross-package changes, add affected package gates, commonly:

yarn workspace @epicdm/flowstate-obs-client test --runInBand --no-cache
yarn workspace @epicdm/flowstate-obs-browser test --runInBand --no-cache
yarn workspace @epicdm/flowstate-obs-middleware test --runInBand --no-cache

Use exact package names/scripts from each package's package.json.

Composition Notes

• Use this skill after flowstate-obs-server-rest-api, flowstate-obs-server-streaming, or flowstate-obs-server-rpc when a public contract changes.
• Pair with gateway and CLI package skills for service routing or Docker changes.

Created: 2026-06-29

Package Skill Inventory

@epicdm/flowstate-obs-server Skill Inventory

Repository: epic-flowstate-community Package path: packages/obs-server Package: @epicdm/flowstate-obs-server Inventory date: 2026-06-29

Skill Map

Composition

Start with flowstate-obs-server for package orientation. Use focused skills based on the task:

• Runtime boot or Docker work: flowstate-obs-server-operations
• REST route behavior: flowstate-obs-server-rest-api
• Schema, validation, or persistence work: flowstate-obs-server-storage-events
• EventSource or WebSocket work: flowstate-obs-server-streaming
• Browser command dispatch: flowstate-obs-server-rpc
• Downstream compatibility checks: flowstate-obs-server-consumer-compatibility
• Documentation, feature inventory, or Dojo repair: flowstate-obs-server-maintenance

Not Created

• No one-skill-per-endpoint set was created. Routes share auth, validation, storage, and test patterns, so endpoint work is better handled by the REST API skill.
• No generic "observability concepts" skill was created. This package needs executable service instructions, not a conceptual lesson.
• No Dojo publication skill was created in this package. Publication should use the repo-level Dojo lifecycle skills after these local skills pass review.

Review Gate

@epicdm/flowstate-obs-server Skills Review

Review date: 2026-06-29 Verdict: Pass for local package-skill coverage; package source has one pre-existing timing-sensitive test failure; Dojo publication deferred until generated Dojo files are rebuilt from these reviewed skills.

Coverage Check

• Package purpose is covered in flowstate-obs-server.
• Runtime boot, config, health, memory storage, Docker and Nx verification are covered in flowstate-obs-server-operations.
• REST routes, auth, query validation, status codes, and route ordering are covered in flowstate-obs-server-rest-api.
• RxDB/Zod schemas, event processing, rate limiting, and database test isolation are covered in flowstate-obs-server-storage-events.
• SSE EventSource behavior and WebSocket ingestion/session lifecycle are covered in flowstate-obs-server-streaming.
• Browser RPC dispatch and response handling are covered in flowstate-obs-server-rpc.
• Cross-package compatibility checks are covered in flowstate-obs-server-consumer-compatibility.
• Docs, feature matrix, generated Dojo drift, and verification hygiene are covered in flowstate-obs-server-maintenance.

Quality Notes

• Skills avoid the stale "WebSocket-only observability server" framing from README and describe the actual REST/SSE/RPC service.
• Skills call out that storage is memory-only in the community package even when OBS_DATA_PATH is set.
• Skills identify hardcoded MVP API keys as local/dev service configuration rather than a production auth model.
• Skills direct agents to preserve client compatibility before route, schema, streaming, or RPC changes.
• Skills are hand-authored from source review, not generated from the feature matrix.

Deferred Work

• Rebuild packages/obs-server/.flowstate/dojo from reviewed local skills before publishing.
• Modernize .flowstate/docs into feature-matrix, workflows, troubleshooting, and maintenance indexes.
• Decide whether package.json should expose stable types or exports if source-level reuse becomes intentional.
• Align query validation enums with event schemas, or document why broader query values are intentionally tolerated.

Verification

Skill-file checks run:

find packages/obs-server/.flowstate/skills -name 'SKILL.md' -print
rg '^---$|^name:|^description: Use when' packages/obs-server/.flowstate/skills
LC_ALL=C rg -n '[^\x00-\x7F]' packages/obs-server/.flowstate/skills

Results:

• Eight SKILL.md files found.
• Frontmatter pattern present for all skills.
• ASCII scan passed.

Package verification run:

yarn workspace @epicdm/flowstate-obs-server test --runInBand --no-cache
yarn workspace @epicdm/flowstate-obs-server typecheck
yarn workspace @epicdm/flowstate-obs-server build
yarn workspace @epicdm/flowstate-obs-server lint
yarn nx build @epicdm/flowstate-obs-server

Results:

• typecheck passed.
• build passed.
• lint passed with 59 existing warnings.
• nx build passed and built/cached @epicdm/flowstate-obs-browser; Nx Cloud reported the existing unconnected-workspace 401.
• test --runInBand --no-cache failed one existing assertion in src/__tests__/routes/projects.test.ts: updatedAt equaled createdAt for a same-millisecond project update. The other 15 suites passed, 155 of 156 tests passed. SSE tests emitted expected connection reset logs during client abort cleanup.

Start with this skill to understand the package purpose, then use the package-local focused skills for specific workflows. Keep this Dojo version aligned with packages/obs-server/package.json. Do not treat generated feature lists as lessons; use workflow evidence from CODE-REVIEW.md, SKILL-INVENTORY.md, and REVIEW.md.