Skip to content

README.md

Latest commit

 

History

History
213 lines (158 loc) · 10.1 KB

README.md

File metadata and controls

213 lines (158 loc) · 10.1 KB

OpenMetadata Skills Plugin (v2.0.0)

Complete AI development workflow for OpenMetadata. Provides structured planning, test-driven development, 90% test coverage enforcement, code review, systematic debugging, and connector development skills.

Inspired by obra/superpowers and everything-claude-code, tailored for OpenMetadata's multi-language, schema-first architecture.

Installation

Claude Code (Plugin)

# From the OpenMetadata repo root
claude plugin install skills/

This installs all skills, agents, hooks, and commands. The plugin auto-loads the OpenMetadata workflow on session start.

Claude Code (In-Repo, Zero Setup)

If you're working in the OpenMetadata repo, .claude/settings.json provides project-level hooks automatically — no plugin install needed. The .claude/skills/ directory also provides skills directly.

Other Tools

Tool Method
Cursor Settings -> Rules -> Add Rule -> select skills/ directory
Codex Add skills/ to workspace context
GitHub Copilot Reference skills/ in workspace instructions
Windsurf Add skills/ to rules configuration
Any Skills follow the Agent Skills open standard

Workflow Overview

The plugin enforces a structured development workflow:

1. /planning          — Design before code (brainstorm, propose, get approval)
2. /tdd               — Write failing test, implement, refactor
3. /test-enforcement   — Verify 90% coverage, integration tests, Playwright E2E
4. /verification       — Show evidence of passing tests before claiming done
5. /code-review        — Two-stage review (spec compliance + code quality)

The openmetadata-workflow meta-skill is loaded at session start and directs Claude to use the appropriate skills for each task type.

Skills

Development Workflow Skills

Skill Command Purpose
OpenMetadata Workflow (auto-loaded) Meta-skill: routes tasks to the right workflow
Planning /planning Brainstorm approaches, get approval, create step-by-step plan
TDD /tdd RED-GREEN-REFACTOR for Java, Python, and TypeScript
Test Enforcement /test-enforcement Enforce 90% line coverage, integration tests, Playwright E2E
Systematic Debugging /systematic-debugging 4-phase root cause analysis
Code Review /code-review Two-stage review: spec compliance then code quality
Verification /verification Evidence-based completion — show test output, not claims

Connector Skills

Skill Command Purpose
Connector Building /scaffold-connector Scaffold a new connector with JSON Schema, Python boilerplate, and AI context
Connector Review /connector-review Review connector code against golden standards with multi-agent analysis
Connector Standards /connector-standards Load connector development standards into agent context
Test Locally /test-locally Build and deploy a full local Docker stack to test your connector

Agents

Language-Specific Reviewers

Agent Purpose
java-reviewer Review Java code — Dropwizard, Flyway, JUnit 5, spotless, 90% coverage
python-reviewer Review Python code — Pydantic 2.x, pytest, connector architecture, 90% coverage
frontend-reviewer Review TypeScript/React — core components, tw: prefix, i18n, no MUI, Jest/Playwright

Connector Agents

Agent Purpose
connector-researcher Research source system APIs, SDKs, auth, and data models
connector-validator Validate connector implementation against standards
comment-resolution-checker Verify PR review comments were substantively addressed

Hooks

The plugin includes hooks (hooks/hooks.json) that fire automatically:

Hook Event What it does
OpenMetadata Workflow SessionStart Loads the meta-skill to route tasks to the right workflow
Block --no-verify PreToolUse Prevents skipping pre-commit hooks
Java format reminder PostToolUse Reminds to run mvn spotless:apply after .java edits
Schema regeneration PostToolUse Reminds to run make generate after JSON schema edits

Additional hooks in .claude/settings.json (in-repo, no plugin needed):

  • Block MUI imports
  • Remind yarn parse-schema after connection schema edits
  • Warn about any type in TypeScript

Test Coverage Targets

The /test-enforcement skill enforces these targets:

Layer Target Tool
Java service (openmetadata-service) 90% line coverage JaCoCo
API endpoints 100% of changed endpoints have integration tests openmetadata-integration-tests
React components 90% line coverage Jest
UI features Playwright E2E for all user-facing changes Playwright
Python ingestion 90% line coverage pytest --cov

Standards

12 core standards + 11 source-type standards in standards/:

Core Standards

Standard Content
main.md Architecture overview, schema-first approach, service types
patterns.md Error handling, logging, pagination, auth, filters
testing.md Unit tests, integration tests, pytest patterns
code_style.md Python and JSON Schema conventions
schema.md Connection schema structure, $ref patterns
connection.md BaseConnection vs function patterns
service_spec.md DefaultDatabaseSpec vs BaseSpec
registration.md Service enum, UI utils, i18n steps
performance.md Pagination, batching, rate limiting
memory.md Memory management, streaming, OOM prevention
lineage.md Lineage extraction methods, dialect mapping, query logs
sql.md SQLAlchemy patterns, URL building, auth, multi-DB

Source-Type Standards

Standard Covers
database.md General database patterns
sql_databases.md MySQL, PostgreSQL, Oracle, MSSQL
data_warehouses.md BigQuery, Snowflake, Redshift, Databricks
nosql_databases.md MongoDB, DynamoDB, Couchbase, Cassandra
dashboard.md Dashboard connectors
pipeline.md Pipeline connectors
messaging.md Messaging connectors
mlmodel.md ML model connectors
storage.md Storage connectors
search.md Search connectors
api.md API connectors

References

Architecture guides and decision trees in connector-building/references/:

Reference Content
architecture-decision-tree.md Service type, connection type, and base class selection
connection-type-guide.md SQLAlchemy vs REST API vs SDK client comparison
capability-mapping.md Capabilities by service type, schema flags, generated files

Review Templates

Template Purpose
full-review-report.md New connector or major refactor review
incremental-review-report.md PR with changes to existing connector
specialized-review-report.md Focused review on one area
pr-review-comment.md Condensed format for GitHub PR comments

Scripts

Script Purpose
gather-connector-context.sh Shell script to collect connector file inventory
analyze_connector.py Python script for structured connector analysis

Architecture

OpenMetadata uses schema-first architecture. One JSON Schema definition cascades through 6 layers:

JSON Schema (single source of truth)
    ├── Python Pydantic models     (make generate)
    ├── Java models                (mvn install)
    ├── TypeScript types           (yarn parse-schema)
    ├── UI config forms            (RJSF auto-renders)
    ├── API request validation     (server uses Java models)
    └── Test fixtures              (tests import Pydantic models)

Quick Start

# 1. Install the plugin
claude plugin install skills/

# 2. Start a new feature
# Just describe what you want — the workflow skill will guide you to /planning

# 3. Implement with TDD
# /tdd "Add new endpoint for data quality scores"

# 4. Verify coverage before PR
# /test-enforcement

# 5. Review your changes
# /code-review

CI

The .github/workflows/lint-standards.yml workflow lints all standards markdown, validates JSON files, and checks symlink integrity on PRs that modify skills/.