jade-core-tooling-scout

Detects what can be auto-assisted by OpenRewrite, PMD, and Checkstyle before manual scanner work. Probes tool availability, runs each tool against the legacy workspace using a modern JDK, collects fin

SKILL.md

GitHub

JADE Tooling Scout

Objective

Discover what migration work can be auto-assisted by static analysis tooling (OpenRewrite, PMD, Checkstyle) before any manual scanner or code edits execute. Never rewrite code — only probe, run, and report.

Runtime decoupling

The tooling engine runs on a modern JDK (MODERN_JAVA_HOME, Java 11/17+) while the analysis target is the legacy JADE workspace (Java 1.5/1.6 source level). This decoupling means:

Layer JDK
Engine (OpenRewrite, PMD, Checkstyle) MODERN_JAVA_HOME (Java 11/17+)
Analysis target (source code) Legacy workspace (Java 1.5/1.6)

The modern JDK is only used to execute the tooling binaries; the tools themselves are configured to analyze Java 1.5/1.6 source level code. The legacy workspace is never compiled with the modern JDK — tools that require compilation must use the workspace's own JDK.

Required inputs

Artifact Source
artifacts/00-run-config.json Created by orchestrator in INIT phase
artifacts/01-breaking-changes-manifest.json Created during MANIFEST_READY phase

The run-config provides workspace_path and artifacts_path. The manifest provides the initial rule set that findings will be merged into.

Outputs

Artifact Description
artifacts/02-tooling-scout-report.json Summary of tools probed, available, and findings
artifacts/02-linter-findings.json Raw violations from each tool
artifacts/01-breaking-changes-manifest.json Updated in-place — new rules merged with provenance

Step-by-step

Step 1: Validate inputs

Run the bundled script with --validate to check that all inputs exist and the modern JDK is a valid Java 11+ installation:

python .claude/skills/jade-tooling-scout/scripts/tooling_scout.py --validate \
  --modern-jdk $MODERN_JAVA_HOME

Exit codes:

  • 0 — all inputs valid, tools ready for probing
  • 2 — missing or invalid input (configuration error)
  • 3 — modern JDK unusable (wrong version, missing javac)

Step 2: Probe tool availability

python .claude/skills/jade-tooling-scout/scripts/tooling_scout.py --probe \
  --modern-jdk $MODERN_JAVA_HOME

This checks for:

  • OpenRewrite — Maven plugin or Gradle plugin presence in workspace, or mvn/gradle wrapper availability. Also checks for existing rewrite configuration files (rewrite.yml, rewrite.yaml).
  • PMD — pmd binary on PATH, or bundled PMD zip, or Maven plugin.
  • Checkstyle — checkstyle jar or Maven/Gradle plugin configuration.

Unavailable tools are logged and skipped — the scout never fails because a tool is missing.

Step 3: Run tools and collect findings

python .claude/skills/jade-tooling-scout/scripts/tooling_scout.py --run \
  --modern-jdk $MODERN_JAVA_HOME

For each available tool:

OpenRewrite: Run --dry-run against the workspace to list applicable recipes. Do NOT apply any recipe. Capture the recipe list and categorize as:

  • applicable — recipe matches at least one source file
  • not_applicable — recipe registered but no matches found

PMD: Scan **/*.java with rulesets relevant to the migration jump (source_version → target_version). Capture violation: file, line, rule, priority.

Checkstyle: Scan with a minimal checkset targeting migration-relevant patterns (unused imports, deprecation markers, raw types, etc.). Capture violation: file, line, check, severity.

Step 4: Generate reports

The --run step produces:

  • artifacts/02-tooling-scout-report.json — structured summary
  • artifacts/02-linter-findings.json — raw, machine-readable findings

Schema for 02-tooling-scout-report.json:

{
  "run_id": "string",
  "modern_jdk": "string",
  "available_tools": ["openrewrite", "pmd", "checkstyle"],
  "unavailable_tools": ["..."],
  "findings_summary": {
    "openrewrite": {
      "recipes_total": 0,
      "recipes_applicable": 0,
      "recipes_not_applicable": 0
    },
    "pmd": {
      "violations_total": 0,
      "rulesets_used": ["category/java/bestpractices.xml"]
    },
    "checkstyle": {
      "violations_total": 0,
      "checks_triggered": ["UnusedImports"]
    }
  },
  "manifest_merge_count": 0,
  "updated_at": "ISO-8601"
}

Schema for 02-linter-findings.json:

{
  "run_id": "string",
  "source_version": "string",
  "target_version": "string",
  "workspace_path": "string",
  "openrewrite": {
    "available": true,
    "version": "string|null",
    "recipes": [
      {
        "name": "org.openrewrite.java.UpgradeToJava6",
        "status": "applicable|not_applicable",
        "description": "string"
      }
    ]
  },
  "pmd": {
    "available": true,
    "version": "string|null",
    "violations": [
      {
        "file": "path/relative/to/workspace",
        "line": 0,
        "rule": "string",
        "ruleset": "string",
        "priority": 0,
        "description": "string"
      }
    ]
  },
  "checkstyle": {
    "available": true,
    "version": "string|null",
    "violations": [
      {
        "file": "path/relative/to/workspace",
        "line": 0,
        "check": "string",
        "severity": "error|warning|info",
        "message": "string"
      }
    ]
  }
}

Step 5: Merge into manifest

python .claude/skills/jade-tooling-scout/scripts/tooling_scout.py --merge \
  --modern-jdk $MODERN_JAVA_HOME

Reads 01-breaking-changes-manifest.json, appends new rule entries derived from tool findings. Each new entry includes:

{
  "rule_id": "tooling:openrewrite:UpgradeToJava6",
  "source": "tooling-scout",
  "provenance": {
    "tool": "openrewrite",
    "tool_version": "x.y.z",
    "detected_at": "ISO-8601",
    "confidence": "high|medium|low"
  },
  "description": "Auto-detectable recipe: UpgradeToJava6 (1 match)",
  "auto_fixable": true
}

Merge rules:

  • Never remove existing manifest entries.
  • Entries with the same rule_id are deduplicated (last writer wins).
  • auto_fixable: true means a tool can apply the fix automatically.
  • auto_fixable: false means linter flagged it but no automatic rewrite exists.

Step 6: Report to orchestrator

The --all flag runs the full pipeline (validate → probe → run → merge) and returns the appropriate exit code:

python .claude/skills/jade-tooling-scout/scripts/tooling_scout.py --all \
  --modern-jdk $MODERN_JAVA_HOME

Exit code 0 means the orchestrator can transition to TOOLING_SCOUT_READY.

Graceful handling of missing tools

Situation Behavior
OpenRewrite not installed Skip, log reason, mark available: false
PMD binary not found Skip, log reason, mark available: false
Checkstyle jar not found Skip, log reason, mark available: false
Modern JDK not usable Exit code 3, do not modify any artifacts
Config file missing Exit code 2, print missing path
All tools unavailable Still produce reports (empty findings), exit 0

The scout never fails because a tool is absent. It fails only due to configuration errors or an unusable modern JDK.

Constraints

  1. Never rewrite or modify source code.
  2. Never compile the workspace with the modern JDK.
  3. Run tools in read-only / dry-run mode only.
  4. Append to manifest; never remove existing entries.
  5. All outputs include UTC timestamps and run provenance.
  6. Tool stdout/stderr is captured but not echoed (append to findings where useful).

Exit criteria

  • artifacts/02-tooling-scout-report.json exists and is valid JSON
  • artifacts/02-linter-findings.json exists and is valid JSON
  • artifacts/01-breaking-changes-manifest.json has new tooling-scout sourced entries (if tools found applicable results)
  • Exit code is 0 (even if no tools were available)