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.claude/skills/jade-core-tooling-scout/SKILL.md
GitHubJADE 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 probing2— 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/gradlewrapper availability. Also checks for existing rewrite configuration files (rewrite.yml,rewrite.yaml). - PMD —
pmdbinary on PATH, or bundled PMD zip, or Maven plugin. - Checkstyle —
checkstylejar 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 filenot_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 summaryartifacts/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_idare deduplicated (last writer wins). auto_fixable: truemeans a tool can apply the fix automatically.auto_fixable: falsemeans 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
- Never rewrite or modify source code.
- Never compile the workspace with the modern JDK.
- Run tools in read-only / dry-run mode only.
- Append to manifest; never remove existing entries.
- All outputs include UTC timestamps and run provenance.
- Tool stdout/stderr is captured but not echoed (append to findings where useful).
Exit criteria
artifacts/02-tooling-scout-report.jsonexists and is valid JSONartifacts/02-linter-findings.jsonexists and is valid JSONartifacts/01-breaking-changes-manifest.jsonhas newtooling-scoutsourced entries (if tools found applicable results)- Exit code is 0 (even if no tools were available)