name

omero-biomero-dev

description

Development runbook for the OMERO.biomero Django and React web plugin. Use when changing omero_biomero views, URLs, templates, settings, or tests; changing webapp React components, BlueprintJS/Tailwind UI, API calls, polling, state, or generated frontend assets; adding database-backed monitoring; updating configuration or deployment surfaces; or debugging OMERO.biomero integration with BIOMERO importer and converter services.

OMERO.biomero Development

Work from the repository root, the directory containing .agents. Inspect the current branch, git status, and the nearest related implementation and tests before editing. Match local conventions and make the smallest coherent change; do not reformat or rewrite unrelated code.

Preserve released behavior and deployment compatibility unless the user explicitly authorizes a breaking change. Treat generated frontend bundles as watcher-owned output. Change and verify source, but do not build or clear assets.

Workflow

Trace the behavior end to end: React caller, shared state/API service, Django URL/view, database or OMERO gateway access, tests, and deployment configuration.
Write a focused regression or behavior test and observe it fail when practical. If implementation and tests must be batched, temporarily disable the new behavior to prove the positive test goes red, then restore it.
Implement using the nearest established pattern. Extract shared code only when behavior genuinely repeats.
Run the narrowest useful checks, then the relevant backend/frontend suite.
Run Python installation and tests through the repository-local venv. Install the editable package and test requirements into that environment when imports are missing; never fall back to bare python or pip.
Never run build, clear-assets, or start another frontend watcher. Assume the developer-owned corepack yarn watch process updates assets. Inspect the source diff, preserve watcher output, and run git diff --check.

Reference Routing

Read only the references needed for the task:

references/frontend.md: React state and effects, BlueprintJS/Tailwind conventions, reusable UI, polling, accessibility, frontend tests, lint, and watcher-owned assets.
references/django-api-testing.md: Django and OMERO view patterns, authentication and authorization, safe APIs and SQL, backend tests, and CI verification.
references/config-and-deployment.md: configuration/admin UI consistency, templates, dependencies, generated assets, and sibling deployment repositories.
references/importer-converter-debug.md: Docker/Podman importer-converter debugging, logs, OMERO database checks, and physical-unit registration pitfalls.

Core Rules

Prefer BlueprintJS components, then existing Tailwind utilities. Add custom CSS only when neither expresses the required behavior.
Keep feature-local state local. Put data in AppContext only when multiple independent consumers require the same source of truth.
Treat effect dependencies, cleanup, request cancellation, stale responses, overlapping polling, inactive tabs, document visibility, stable keys, and loading/error/empty states as mandatory review points.
Require authentication on plugin APIs and derive user scope from the OMERO connection, never from client-supplied identity. Validate inputs, parameterize SQL, preserve CSRF handling, encode generated links, and keep secrets and raw infrastructure errors out of responses.
Reuse constants, API helpers, components, and derived state rather than duplicating values. Do not add global state merely to avoid passing a prop.
Preserve unrelated worktree changes. Do not use destructive Git commands.

OMERO.biomero Development

Workflow

Trace the behavior end to end: React caller, shared state/API service, Django URL/view, database or OMERO gateway access, tests, and deployment configuration.

Write a focused regression or behavior test and observe it fail when practical. If implementation and tests must be batched, temporarily disable the new behavior to prove the positive test goes red, then restore it.

Implement using the nearest established pattern. Extract shared code only when behavior genuinely repeats.

Run the narrowest useful checks, then the relevant backend/frontend suite.

Run Python installation and tests through the repository-local venv. Install the editable package and test requirements into that environment when imports are missing; never fall back to bare python or pip.

Never run build, clear-assets, or start another frontend watcher. Assume the developer-owned corepack yarn watch process updates assets. Inspect the source diff, preserve watcher output, and run git diff --check.

Reference Routing

Read only the references needed for the task:

references/frontend.md: React state and effects, BlueprintJS/Tailwind conventions, reusable UI, polling, accessibility, frontend tests, lint, and watcher-owned assets.

references/django-api-testing.md: Django and OMERO view patterns, authentication and authorization, safe APIs and SQL, backend tests, and CI verification.

references/config-and-deployment.md: configuration/admin UI consistency, templates, dependencies, generated assets, and sibling deployment repositories.

references/importer-converter-debug.md: Docker/Podman importer-converter debugging, logs, OMERO database checks, and physical-unit registration pitfalls.

Core Rules

Prefer BlueprintJS components, then existing Tailwind utilities. Add custom CSS only when neither expresses the required behavior.

Keep feature-local state local. Put data in AppContext only when multiple independent consumers require the same source of truth.

Treat effect dependencies, cleanup, request cancellation, stale responses, overlapping polling, inactive tabs, document visibility, stable keys, and loading/error/empty states as mandatory review points.

Require authentication on plugin APIs and derive user scope from the OMERO connection, never from client-supplied identity. Validate inputs, parameterize SQL, preserve CSRF handling, encode generated links, and keep secrets and raw infrastructure errors out of responses.

Reuse constants, API helpers, components, and derived state rather than duplicating values. Do not add global state merely to avoid passing a prop.

Preserve unrelated worktree changes. Do not use destructive Git commands.