cloverdx-dev — Claude Skill for CloverDX Development

A Claude skill that acts as a CloverDX development co-pilot. It activates when working inside a CloverDX sandbox or when any CloverDX development task is mentioned.

What It Does

• Reads, writes, and modifies graph XML (.grf), jobflows (.jbf), subgraphs (.sgrf), and data services (.rjob)
• Writes correct CTL2 transformations that compile — not pseudocode
• Understands metadata, connections, parameters, and project conventions
• Validates every generated file via validate_graph (MCP) before presenting it — built-in feedback loop catches errors automatically
• Plans graph designs via plan_graph (MCP) before writing XML — catches edge refs, CTL entry points, and sort requirement issues upfront
• Executes jobs on demand via execute_graph (MCP) when the user asks
• When connected to a CloverDX Server via MCP: pulls live execution logs, edge debug data, and execution tracking

MCP Architecture — Single Server

All operations go through one MCP server: cloverdx-mcp-server. Required MCP implementation: dpavlis/mcpclover

Area	Tools
Discovery & navigation	list_sandboxes, list_files, find_file, grep_files, list_linked_assets, get_sandbox_parameters
File operations	read_file, write_file, patch_file, copy_file, rename_file, delete_file
Graph structure editing	graph_edit_structure, graph_edit_properties
Graph design & planning	plan_graph, get_workflow_guide
Component introspection	list_components, get_component_info, get_component_details
Graph lifecycle	validate_graph, execute_graph, await_graph_completion, abort_graph_execution
Execution history	list_graph_runs, get_graph_run_status, get_graph_tracking, get_graph_execution_log
Edge data inspection	get_edge_debug_data (requires debug=true run)
Reasoning	think — mandatory before complex design decisions

Knowledge Base

Area	Coverage
CTL2	Language reference, all built-in functions (string, date, math, conversion, container)
Components	All major component types with real configuration examples
Graph XML	.grf / .jbf / .sgrf / .rjob structure from real annotated examples
Metadata	Record types, field types, .fmt files, inline metadata, PostgreSQL type mapping, line-ending inspection
Patterns	Common ETL patterns derived from real example graphs
Debugging	Symptom triage table, MCP diagnostic call chains, log + edge data analysis
MCP Tools	Full tool reference for cloverdx-mcp-server (mcp-tools.md)
MCP Workflows	Step-by-step call sequences with parameters and key fields (mcp-workflows.md)
Architecture	Dual JVM model, memory sizing, AWS/Kubernetes deployment

Changelog

v3.0.0 — Single MCP Server

Migration from dual-server to single cloverdx-mcp-server architecture.

Removed (infra MCP server no longer available):

• deployment_current — server version, heap, cluster topology
• list_performance_logs — heap/GC/CPU metrics
• list_server_logs — server-level log search
• execute_database_query / retrieve_database_schema — historical trend analysis
• report_support_issue
• get_edge_debug_info / get_edge_debug_metadata — superseded by enhanced get_edge_debug_data

Added (new tools in cloverdx-mcp-server):

• plan_graph — validate design consistency before writing XML (edges, metadata refs, CTL entry points, sort requirements)
• graph_edit_structure — add/delete/move graph elements via XML DOM (replaces set_graph_element_attribute)
• graph_edit_properties — set attribute values, CTL code, metadata records on existing elements
• await_graph_completion — block until a run finishes instead of manual polling
• abort_graph_execution — cancel a running graph
• think — mandatory explicit reasoning step before complex decisions
• get_workflow_guide — gained create_edit_jobflow task type
• get_edge_debug_data — simplified: sandbox/graph_path now optional (include to get field names/types alongside values)

Updated across all files:

• SKILL.md — MCP architecture section, all workflow sequences, edit strategy, debugging chain
• mcp-tools.md — removed [infra-mcp] section, added new tools, stripped all server labels
• mcp-workflows.md — rewritten diagnostic chain (4 steps vs 7), session patterns updated
• sandbox-discovery.md — removed deployment_current from Step 1
• debugging.md — updated symptom triage table, stripped all server labels

v2.1.0 — Reference Documentation Audit (155-Task Training Build)

Comprehensive documentation fixes based on building all 155 CloverDX training tasks (31 task groups x 5 variants). 505 lines added across 7 reference files.

New component documentation (components.md):

• EXT_FILTER — port behavior, filterExpression syntax, silent data loss warning for unconnected port 1
• FAIL / SUCCESS — terminal nodes with context-dependent behavior (jobflow errorMessage vs graph mapping)
• HTTP_CONNECTOR — full attribute table, $in.0.* vs $in.1.* output mapping, response record fields
• SPREADSHEET_READER — key attributes, auto-mapping behavior
• SPREADSHEET_WRITER — writeMode values, existingSheetsActions, multi-sheet two-phase pattern, mapping XML
• STRUCTURE_WRITER — header/mask/footer template syntax, $fieldName substitution
• COMPLEX_DATA_READER — state machine overview, key attributes
• DATA_INTERSECTION — SCD Type-2 ports (insert/update/delete), joinKey, transform semantics
• FLAT_FILE_WRITER — terminal node warning (no output port)
• DEDUP — sorted vs unsorted behavior, memory implications, which duplicate is kept
• dataPolicy — full value table (strict/controlled/lenient) for reader error handling

LOOP component (comp-jobflow.md):

• Complete new section with port mapping (confirmed via get_component_info)
• whileCondition syntax (bare boolean, no function wrapper)
• Loop-back edge guiRouter="Manual" requirement
• Retry loop pattern
• Inline Metadata requirement for loop state

Expanded Fail section (comp-jobflow.md):

• Graph vs jobflow behavior table with code examples

Port reference table expansion (graph-xml.md):

• Expanded from 8 rows to 25+ rows covering all component categories
• Added: HTTP_CONNECTOR, Spreadsheet, StructureWriter, Normalizer, Denormalizer, Aggregate, Dedup, SimpleCopy, ExecuteGraph, Loop, ListFiles, terminal nodes

Other graph-xml.md fixes:

• enabled attribute: expanded from one-liner to behavior table (pass_through, wait_for_all explained)
• Common gotchas: FlatFileWriter terminal warning, dataPolicy values, most common unconnected port offenders

Type casting (ctlref.md):

• New section: function forms vs cast forms vs invalid forms
• Conversion function quick-reference table (12 common conversions)

Data service fixes (dataservice-xml.md):

• RequestParameter table: added "Accessed via" column
• Critical distinction: getParamValue() vs getRequestHeader() vs RESTJOB_INPUT for different location types

New patterns (patterns.md):

• Pattern 21: Data Service GET with query parameter (EndpointSettings, getParamValue, nature="restJob")
• Pattern 22: HTTP API call with error handling (standardOutputMapping, JSON_EXTRACT from response, nested mapping)

Metadata (metadata.md):

• Escalated timezone warning to CRITICAL with DST corruption explanation

v2.0.0 — Native MCP Integration

• SKILL.md — v2.0.0: two-server MCP architecture documented; get_workflow_guide added as mandatory Step Zero before any graph task; sandbox discovery rewritten to use MCP tools instead of bash find; validation and execution updated to use validate_graph and execute_graph
• mcp-tools.md — new: full tool reference for both MCP servers with parameters and usage guidance
• mcp-workflows.md — major rewrite: canonical call sequences for discovery, build, debug, execution
• debugging.md — symptom triage table (10 symptoms → cause → first MCP tool); per-tool guidance with regex patterns, cluster failure patterns, edge data extraction
• sandbox-discovery.md — rewritten to use MCP tools throughout
• checkconfig.sh — marked deprecated; prefer validate_graph from cloverdx-mcp-server
• run-job.sh — marked deprecated; prefer execute_graph from cloverdx-mcp-server; simplified to use correct /clover/rest/executor/run endpoint

v1.x — Real-World Bug Fixes

• Scripts: X-Requested-By: CloverDX header, macOS-compatible sed '$d', CheckConfigError JSON unwrap
• Subgraph: write-only pattern, lowercase <inputPorts>/<singlePort> casing documented
• Metadata: PostgreSQL type mapping (bigint → long), delimiter requirement for DB-only metadata
• Data services: publishing steps, URL format (no sandbox in path), SQL parameter injection
• Graph XML: phase ordering rule for FK-dependent components
• Jobflow: TRASH multi-port assignment, jobURL vs graphURL
• DataGenerator: generate attribute (not transform)
• Aggregate: boolean key fields become strings, CDATA leading newline rule

Installation

1. Download the latest .skill file from Releases
2. In Claude → Settings → Customize → Skills → Import
3. Select the .skill file

Repository Layout

skill/
  SKILL.md          — Skill definition, triggers, and workflow instructions
  scripts/
    checkconfig.sh  — Legacy fallback: validates via checkConfig API (prefer validate_graph MCP)
    run-job.sh      — Legacy fallback: executes via REST API (prefer execute_graph MCP)
  references/       — 29 focused reference files loaded on demand
    ctlref.md
    ctl-*.md        — CTL2 function reference (6 files)
    components.md
    comp-*.md       — Component reference by category (9 files)
    metadata.md
    graph-xml.md
    jobflow-xml.md
    subgraph-xml.md
    dataservice-xml.md
    patterns.md
    debugging.md
    architecture.md
    sandbox-discovery.md
    mcp-tools.md
    mcp-workflows.md