Gradle run

Core principle

tee

Procedure

1. Classify the request. A focused Gradle command that only validates another implementation change is incidental validation. A build, check, warning-cleanup, or failure-investigation loop is a Gradle-centered workflow.
2. Resolve this installed skill's directory and confirm

   python3

   and

   <skill-dir>/scripts/gradle_run.py

   are available. If either is unavailable, stop before running Gradle directly and report the failed prerequisite.
3. Create one wrapper workflow before the first command:
   sh

   python3 <skill-dir>/scripts/gradle_run.py create

   Retain the returned opaque workflow identifier. Use only this wrapper to run Gradle. It adds

   --console=plain

   and

   --no-scan

   unless the command already selects console behavior or the user explicitly authorized

   --scan

   . For warning discovery, include

   --warning-mode all

   in the Gradle command; otherwise include it only when the user asks for it. Treat a

   workflow is busy

   result as an ownership violation: wait for the active run or correct the owner instead of starting another command or finishing the workflow concurrently.
4. For incidental validation, stay in the current agent and run the smallest owning task with a non-empty verification question:
   sh

   python3 <skill-dir>/scripts/gradle_run.py run \
     --workflow <id> --scope targeted \
     --question "Does :module:test pass after this change?" -- \
     ./gradlew :module:test

   Choose the task from the verification question's acceptance claim. If it asks whether fixture tests pass, run

   test

   ; do not substitute compilation merely because the edit is Kotlin.
   Read only the bounded JSON summary and continue from its failed tasks, fingerprints, and excerpt. Do not inspect its log unless a user explicitly requests that artifact. In the final report, repeat the verification question and answer it from that bounded summary, explicitly stating that the wrapper ran the task; do not describe it as a direct Gradle invocation. The summary and ledger redact common credential patterns; the retained full log is intentionally raw and can contain secrets, so never paste or reopen it as a substitute for the summary.
5. For a Gradle-centered workflow, create one fresh portable Solver diagnostic owner. Report its model and reasoning only if the runtime exposes them. Give it read-only repository access and ownership of wrapper runs and diagnosis; it must not edit source, tests, configuration, or generated project files, and it must not delegate Gradle ownership. The parent owns every repository edit. If a fresh persistent owner cannot be created, stop rather than make the parent run the workflow loop.
6. Have that owner reuse prior actionable summaries, group warnings and failures by fingerprint, and return exact file or line evidence plus the narrowest next command. Prefer source or compiler failure fingerprints over a following generic Gradle failure block. Run an initial broad command only when existing targeted evidence cannot answer the recorded question. The owner stays available for the whole workflow and verifies each parent change with the same wrapper and the narrowest applicable task.
7. Record

   broad

   only for aggregate project checks. Give every broad run a distinct question that a narrower task cannot answer. The wrapper flags repeated commands and primary failure fingerprints; if the primary source or compiler failure repeats, stop the run loop. Inspect the reported source line and its nearby declaration, import, or receiver context before proposing a fix or another Gradle command; then revise the diagnosis from that evidence. In the final diagnosis, name that focused inspection as the next action; do not say to fix the source before it happens. If the wrapper is interrupted, use its recorded signal and retained log; it stops the isolated Gradle process group or Windows process tree, extracts bounded diagnostics from the partial log, and makes the ledger durable before returning. Only logs still represented by the bounded recent-run ledger are retained.
8. Finish after the requested broad validation passes, or report unresolved warning fingerprints and the reason validation cannot continue. Summarize the compact ledger, including each verification question and its bounded answer, then finish it:
   sh

   python3 <skill-dir>/scripts/gradle_run.py finish --workflow <id>

   In the final report, state that the workflow finished after that summary and that cleanup removed only its wrapper-owned logs.
   Finish retains small marker and lock metadata so repeating the same finished identifier is idempotent while an unknown identifier fails closed. If finish cannot validate the managed identifier or the workflow is active, leave all files in place and report the failure. This skill does not constrain unrelated review, exploration, implementation, or other subagents.

RED/GREEN agent scenarios

1. Direct: “Run

   check

   and fix every warning.” RED runs repeated full builds with their logs in context. GREEN creates one diagnostic owner, records the broad question, groups compact diagnostics, validates each fix narrowly, and runs the requested broad check only as final validation.
2. Novel: a final broad check finds a downstream failure after targeted tasks pass. GREEN records the new question, targets the owning task, and only broad-reruns once that task passes.
3. Repetition: an unchanged source failure fingerprint survives a claimed fix. GREEN stops rebuilding, inspects the cited source line and its surrounding declaration or import context, then reports a revised diagnosis before naming a fix or another Gradle command. It does not treat a new question string as permission for a blind repeat.
4. Fail closed: the wrapper, Python runtime, or persistent diagnostic owner is unavailable. GREEN runs no direct Gradle fallback and reports the missing prerequisite. A valid-looking but unknown finish identifier also fails; it is not treated as a previously completed workflow.
5. Counterexample: “After changing this Kotlin helper, run

   :module:test

   .” GREEN uses the wrapper but keeps this incidental focused validation with the current agent, and reports the verification question with its bounded answer; it does not substitute compilation for the stated test task.
6. Boundary: while a Gradle workflow runs, a user starts an unrelated review subagent. GREEN permits it; this skill owns Gradle output handling and diagnostic delegation only.
7. Interruption: Ctrl-C arrives twice after Gradle emits a diagnostic and enters a signal-resistant worker process. GREEN tolerates the second signal, stops the isolated process group, extracts the partial diagnostic, retains the log, and records SIGINT in the compact ledger before returning. RED re-enters cleanup, leaves either process running, or loses the diagnostic or interruption record.
8. Exclusive ownership: a second run or finish request uses an active workflow. GREEN fails closed before launching or deleting anything. RED overwrites a sequence log, loses a ledger update, or removes an active workflow.
9. Sensitive output: a Gradle property and warning contain credentials. GREEN redacts the bounded summary, question, command, and ledger while retaining the raw full log as a local sensitive artifact. RED sends or persists the credential in model-visible metadata.
10. Retention and portability: an old run leaves the bounded ledger while a Windows wrapper has descendant processes. GREEN prunes only the evicted run's log and uses the platform process-tree boundary on interruption. RED leaks unbounded logs or terminates only the Windows launcher.