OpenMetadata Development Workflow

This skill is loaded automatically at session start. It ensures you follow the right workflow for every task.

Before Starting Any Task

Check which skills apply to your task and use them. This is not optional — if a skill applies, you must follow it.

Skill Selection Guide

Task type	Required skill(s)
New feature (multi-file)	/planning then /tdd then /test-enforcement then /verification
Bug fix	/systematic-debugging then /tdd (write regression test) then /verification
New API endpoint	/planning then /tdd then /test-enforcement (must include integration test)
New connector	/connector-standards then /connector-building then /test-enforcement
UI component	Read openmetadata-ui/src/main/resources/ui/DEVELOPER_HANDBOOK.md first (folder structure + file naming for any new file), then /ui-core-components + /react-best-practices + /composition-patterns before writing, then /tdd, then /web-design-guidelines after, then /test-enforcement (must include Jest + Playwright if user-facing)
UI a11y / UX / design audit	/web-design-guidelines
React perf work (re-renders, waterfalls, bundle)	/react-best-practices
Code review / PR review	/code-review then /test-enforcement
Opening / finalizing a PR	/test-enforcement then /java-affected-tests (any Java, schema, migration or pom change) then /verification then /pr-checklist (includes /ui-pr-recording when creating a PR for a UI feature or feature task)
Connector review	/connector-review
E2E test creation	/playwright
Finishing implementation	/test-enforcement then /java-affected-tests (Java side) then /verification

Note: Connector skills (/connector-standards, /connector-building, /connector-review) and /playwright are part of the OpenMetadata Skills plugin and ship together with this workflow skill. They are defined in the skills/ directory alongside this file.

Why the UI row names skills explicitly: a skill only loads when it is invoked, and the model decides that from the skill's own description. /composition-patterns describes itself as being for refactoring prop proliferation and building component libraries, and /web-design-guidelines describes itself as being for "review my UI" / "check accessibility" — so neither reliably fires on "build me a component". Naming them here is what makes them part of the workflow instead of a coin flip. Invoke /web-design-guidelines after the component exists: it is an audit, and running it first works against its own trigger.

/react-best-practices, /composition-patterns and /web-design-guidelines are vendored from vercel-labs/agent-skills (MIT) under skills/vendor/. They are authoring aids, not gates — enforcement is ui-checkstyle, see docs/ui-code-quality-gate.md.

Workflow Rules

1. Plan before coding. For any non-trivial task, use /planning to design the approach before writing code.

2. Test-first when possible. Use /tdd to write failing tests before implementation. This applies to Java, Python, and TypeScript equally.

3. Always enforce test coverage. Before any PR, use /test-enforcement to verify:

   • 90% line coverage on changed Java classes
   • Integration tests for all changed/new API endpoints
   • Playwright E2E tests for new user-facing features
   • Jest unit tests for new React components

4. Verify with evidence. Use /verification before claiming completion. Show actual test output, not claims.

5. Review before merging. Use /code-review for two-stage review (spec compliance + code quality).

6. Fill the PR template completely. Use /pr-checklist before gh pr create to gather every required section: linked issue (a test fix needs none), high-level design (large PRs), tests + coverage, UI screen recording, and manual test steps. When creating a PR for a UI feature or feature task, use ui-pr-recording: run the PR build in Docker with sample data and upload the verified feature video into the description. Other changes may explain N/A; this requirement does not activate during implementation or standalone review.

OpenMetadata Cross-Layer Checklist

When your task touches multiple layers, ensure all are synchronized:

• JSON Schema in openmetadata-spec/ → run make generate
• Connection schema → run yarn parse-schema
• Java entity changes → Flyway migration in bootstrap/sql/migrations/
• Backend API changes → update frontend API client
• New UI strings → add to locale/languages/en-us.json then run yarn i18n
• Java files → run mvn spotless:apply
• Python files → run make py_format && make py_format_check
• TypeScript/React files → run yarn organize-imports:cli && yarn lint:fix && yarn pretty:base --write
• New source files → ensure Apache 2.0 license header (run yarn license-header-fix)
• Application changes → run yarn generate:app-docs

CLAUDE.md Takes Precedence

If CLAUDE.md instructions conflict with any skill, CLAUDE.md wins. Skills are supplementary workflows, not overrides.