compose-doctor: Instructions file for Codex

AGENTS.md — compose-doctor

Cross-tool agent instructions, read automatically by Codex, OpenCode, Google Antigravity, Cursor, and other agents that honor AGENTS.md. This is the neutral mirror of the Claude Code skill at skills/compose-doctor/SKILL.md — that file is the source of truth; read it for the full detail.

What compose-doctor is

A deterministic health check for Android Jetpack Compose. It runs detekt + the io.nlopez.compose.rules ruleset and scores the result 0–100. The tool only diagnoses — it never edits code. You are the actuator: read the diagnosis, make one targeted fix, re-run.

Use it whenever you write, review, or fix Compose code (@Composable functions, Modifier usage, state/remember, ViewModels).

The fix loop

1. Find or bootstrap the task. Check whether the composeDoctor task exists:

   ./gradlew tasks --all 2>/dev/null | grep -q composeDoctor && echo applied || echo missing
   

   • applied → run it (step 1).
   • missing → bootstrap it without editing any build file, using the bundled init script:

     ./gradlew --init-script ./init/compose-doctor.init.gradle.kts composeDoctor
     

     This resolves the plugin (dev.composedoctor) from the Gradle Plugin Portal. If resolution fails, fall back to applying plugins { id("dev.composedoctor") version "0.1.0" } to the target module's build.gradle.kts (or a composite includeBuild of a compose-doctor checkout — see the README) and re-run.

2. Run it.

   ./gradlew composeDoctor                  # whole project
   ./gradlew :feature:home:composeDoctor    # a single module, if applied there
   

3. Read the machine-readable report, not the console:

   • build/reports/compose-doctor/score.json — score, status (ok/below_gate), per-dimension sub-scores, a byRule remediation plan (pre-sorted by score-per-fix), a delta vs the previous run, and the findings array (each with a stable id).
   • build/reports/detekt/detekt.sarif — same findings with precise locations.

4. Take byRule[0] (highest score-per-fix). The score counts unique rule IDs, not instances (score = 100 − uniqueErrorRules×1.5 − uniqueWarningRules×0.75), so fix every instance of that one rule — partial fixes score nothing.

5. Re-run and verify: delta.fixedRules contains the rule you targeted, the score went up, and delta.newRules is empty. Then also run :module:compileKotlin / tests — a Compose fix that changes a signature can break call sites; a higher score with a broken build is a regression, so revert if so.

6. Repeat until the score is satisfactory (75+ is "Great") or the remaining rules need human judgement.