---
name: scode-modernize
description: Scan a repository for known deprecated or outdated patterns and propose or apply the modern equivalent. Use when the user explicitly invokes /scode-modernize or $scode-modernize to audit and modernize project conventions incrementally.
---

# Scode Modernize

Scan the current project for known deprecated or outdated patterns. For each pattern found, replace it with the modern
equivalent. Report what was changed and what was already clean.

## Workflow

1. Detect project type (Rust, etc.) from the repository root.
2. Walk the checklist below. For each item, check whether the pattern exists. Collect all findings.
3. Present the full list of findings to the user and ask which ones to address.
4. Apply replacements only for the items the user approves. By default, treat each approved item as its own `$jjstack`
   PR. If the user gives an explicit order, apply the items in that order; otherwise use the checklist order.
5. After all approved items are processed, summarize: which items were fixed, which were skipped, which were already
   clean.

## Checklist

### 1. Add formatting, clippy, and test CI jobs (Rust projects)

**Detect:** The project has a `Cargo.toml` at the repository root (or is a Cargo workspace). Check
`.github/workflows/*.yml` for existing CI jobs that run `cargo fmt` / `rustfmt`, `cargo clippy`, and `cargo test`. A job
counts as present only if it runs the check as a dedicated job (not a step buried inside another job).

**Skip if:** Dedicated formatting, clippy, and test jobs all already exist as separate jobs.

**Why:** Formatting, lint, and test checks catch issues early. Running them as separate jobs means they report failures
in parallel, making CI feedback faster and easier to triage. Bundling them into a single job delays feedback and
obscures which check failed.

**Replace with:**

- If no CI workflow exists at all, create `.github/workflows/ci.yml`.
- Add a `fmt` job that checks formatting. Use `actions-rust-lang/setup-rust-toolchain@v1` to install the `rustfmt`
  component, then run `cargo fmt --all -- --check`:

```yaml
fmt:
  runs-on: ubuntu-latest
  steps:
    - uses: actions/checkout@v4
    - uses: actions-rust-lang/setup-rust-toolchain@v1
      with:
        components: rustfmt
    - run: cargo fmt --all -- --check
```

- Add a `clippy` job that runs clippy. Use `actions-rust-lang/setup-rust-toolchain@v1` to install the `clippy`
  component, then run `cargo clippy`:

```yaml
clippy:
  runs-on: ubuntu-latest
  steps:
    - uses: actions/checkout@v4
    - uses: actions/cache@v4
      with:
        path: |
          ~/.cargo/registry
          ~/.cargo/git
          target
        key: ${{ runner.os }}-cargo-${{ hashFiles('**/Cargo.lock') }}
        restore-keys: |
          ${{ runner.os }}-cargo-
    - uses: actions-rust-lang/setup-rust-toolchain@v1
      with:
        components: clippy
    - run: cargo clippy
```

- Add a `test` job that runs the test suite:

```yaml
test:
  runs-on: ubuntu-latest
  steps:
    - uses: actions/checkout@v4
    - uses: actions/cache@v4
      with:
        path: |
          ~/.cargo/registry
          ~/.cargo/git
          target
        key: ${{ runner.os }}-cargo-${{ hashFiles('**/Cargo.lock') }}
        restore-keys: |
          ${{ runner.os }}-cargo-
    - run: cargo test
```

- If `Cargo.lock` is not committed (library crates), use `hashFiles('**/Cargo.toml')` for the cache key instead.
- If existing CI already has formatting, clippy, or tests as steps within another job, extract them into their own jobs
  and remove the steps from the original job.
- Only use official actions: `actions/checkout`, `actions/cache`, and `actions-rust-lang/setup-rust-toolchain`. Do not
  use `actions-rs/*` or third-party community actions.
- Every Rust CI job that compiles code (clippy, test, build — but not fmt, which only runs rustfmt) must include cargo
  caching with `actions/cache@v4`. Use the same cache configuration shown in the clippy example above, placed
  immediately after checkout.
- When auditing an existing workflow, check that every job which runs `cargo build`, `cargo test`, or `cargo clippy` has
  a cache step. Add one if missing.

**Verify:** The workflow file has separate `fmt`, `clippy`, and `test` jobs. Every job that compiles Rust code has cargo
caching. `act` or a manual read confirms each job runs the expected command.

### 2. Switch GitHub Actions workflows to Ubicloud runners

**Detect:** The project has GitHub Actions workflows under `.github/workflows/` and at least one job uses a GitHub
hosted Ubuntu runner such as `ubuntu-latest`, `ubuntu-24.04`, or `ubuntu-22.04` instead of an Ubicloud runner.

**Skip if:** There are no GitHub Actions workflows, every job already uses an Ubicloud runner, or the workflow clearly
needs a GitHub-hosted runner for a documented reason.

**Why:** Ubicloud runners are a standard part of the baseline CI setup. They are compatible with GitHub runner images
for ordinary Linux CI, and the short label keeps the workflow independent of a specific CPU size until the project has a
reason to care.

**Replace with:**

- By default, do the same migration as <https://github.com/scode/ferricode/pull/6>: replace each GitHub-hosted Ubuntu
  runner with `runs-on: ubicloud` and leave the rest of the workflow alone.
- Preserve intentional non-Linux jobs. Do not rewrite macOS, Windows, self-hosted, or container-only jobs unless the
  user explicitly asks for that.
- If the user asks to use Ubicloud with a custom runner, present the full available runner list below and ask which
  label to use before editing. The list was pulled from Ubicloud's runner type documentation and linked
  `github_runner_labels.yml` on 2026-06-27; do not browse during the normal modernization run just to refresh it.
- Do not offer deprecated arm label aliases unless the user specifically asks about backwards compatibility.

Available Ubicloud runner labels:

- `ubicloud` (alias for `ubicloud-standard-2-ubuntu-2404`)
- `ubicloud-arm` (alias for `ubicloud-standard-2-arm-ubuntu-2404`)
- `ubicloud-standard-2`, `ubicloud-standard-4`, `ubicloud-standard-8`, `ubicloud-standard-16`, `ubicloud-standard-30`,
  `ubicloud-standard-60`
- `ubicloud-standard-2-ubuntu-2204`, `ubicloud-standard-4-ubuntu-2204`, `ubicloud-standard-8-ubuntu-2204`,
  `ubicloud-standard-16-ubuntu-2204`, `ubicloud-standard-30-ubuntu-2204`, `ubicloud-standard-60-ubuntu-2204`
- `ubicloud-standard-2-ubuntu-2404`, `ubicloud-standard-4-ubuntu-2404`, `ubicloud-standard-8-ubuntu-2404`,
  `ubicloud-standard-16-ubuntu-2404`, `ubicloud-standard-30-ubuntu-2404`, `ubicloud-standard-60-ubuntu-2404`
- `ubicloud-standard-2-ubuntu-2604`, `ubicloud-standard-4-ubuntu-2604`, `ubicloud-standard-8-ubuntu-2604`,
  `ubicloud-standard-16-ubuntu-2604`, `ubicloud-standard-30-ubuntu-2604`, `ubicloud-standard-60-ubuntu-2604`
- `ubicloud-premium-2`, `ubicloud-premium-4`, `ubicloud-premium-8`, `ubicloud-premium-16`, `ubicloud-premium-30`
- `ubicloud-premium-2-ubuntu-2204`, `ubicloud-premium-4-ubuntu-2204`, `ubicloud-premium-8-ubuntu-2204`,
  `ubicloud-premium-16-ubuntu-2204`, `ubicloud-premium-30-ubuntu-2204`
- `ubicloud-premium-2-ubuntu-2404`, `ubicloud-premium-4-ubuntu-2404`, `ubicloud-premium-8-ubuntu-2404`,
  `ubicloud-premium-16-ubuntu-2404`, `ubicloud-premium-30-ubuntu-2404`
- `ubicloud-premium-2-ubuntu-2604`, `ubicloud-premium-4-ubuntu-2604`, `ubicloud-premium-8-ubuntu-2604`,
  `ubicloud-premium-16-ubuntu-2604`, `ubicloud-premium-30-ubuntu-2604`
- `ubicloud-standard-2-arm`, `ubicloud-standard-4-arm`, `ubicloud-standard-8-arm`, `ubicloud-standard-16-arm`,
  `ubicloud-standard-30-arm`, `ubicloud-standard-60-arm`
- `ubicloud-standard-2-arm-ubuntu-2204`, `ubicloud-standard-4-arm-ubuntu-2204`, `ubicloud-standard-8-arm-ubuntu-2204`,
  `ubicloud-standard-16-arm-ubuntu-2204`, `ubicloud-standard-30-arm-ubuntu-2204`, `ubicloud-standard-60-arm-ubuntu-2204`
- `ubicloud-standard-2-arm-ubuntu-2404`, `ubicloud-standard-4-arm-ubuntu-2404`, `ubicloud-standard-8-arm-ubuntu-2404`,
  `ubicloud-standard-16-arm-ubuntu-2404`, `ubicloud-standard-30-arm-ubuntu-2404`, `ubicloud-standard-60-arm-ubuntu-2404`
- `ubicloud-standard-2-arm-ubuntu-2604`, `ubicloud-standard-4-arm-ubuntu-2604`, `ubicloud-standard-8-arm-ubuntu-2604`,
  `ubicloud-standard-16-arm-ubuntu-2604`, `ubicloud-standard-30-arm-ubuntu-2604`, `ubicloud-standard-60-arm-ubuntu-2604`

**Verify:** Workflow jobs that previously used GitHub-hosted Ubuntu runners now use `runs-on: ubicloud`, or the
user-selected Ubicloud label when they explicitly requested a custom runner. Non-Linux jobs are unchanged.

### 3. Keep agent finish-work commands in sync with CI

**Detect:** The repository has `AGENTS.md` and/or `CLAUDE.md` instructions that tell the agent what to run before
finishing work, creating a PR, or claiming the work is done. Compare those commands against the commands actually run by
required CI workflows in `.github/workflows/*.yml`. Treat this as a finding when the command sets differ, when the same
tool is run with different arguments (for example `cargo clippy` vs. `cargo clippy --all-targets --all-features`), or
when the instructions omit a required CI signal entirely.

**Skip if:** There are no agent instruction files, no CI workflow files, or no finish-work/checks section in the agent
instructions. Also skip if the instructions already match the CI commands exactly.

**Why:** The agent should run the same checks locally that GitHub will run after a PR is opened. Near-matches are not
good enough: a missing flag can hide exactly the failure CI is about to report.

**Replace with:**

- Identify the CI jobs that gate PR health. For Rust projects, include every workflow command that runs `cargo fmt`,
  `cargo clippy`, `cargo test`, `cargo check`, `cargo build`, `dprint`, or another explicit formatter/linter/test
  command.
- Normalize only shell trivia. Compare the actual tool invocation and arguments exactly after removing harmless YAML
  wrapping, step names, and surrounding shell boilerplate. Do not treat `cargo clippy` and `cargo clippy --all-targets
  --all-features` as equivalent.
- Update the finish-work section in `AGENTS.md` (preferred) or `CLAUDE.md` so the required commands match CI exactly,
  including flags, `--` argument separators, feature flags, workspace flags, package selectors, and check-only flags.
- If both `AGENTS.md` and `CLAUDE.md` are regular files, keep them consistent with each other. If they conflict and
  there is no clear canonical file, report the conflict and ask which file should be authoritative before editing.
- If CI uses a matrix, environment variable, setup step, or script wrapper that materially changes what command runs,
  capture that faithfully in the agent instructions. Prefer the literal command the agent can run locally; if the CI
  behavior cannot be expressed as a single local command, say so explicitly in the instructions instead of inventing an
  approximation.
- If a CI command is intentionally not useful locally, do not silently drop it. Either document the reason in the
  finish-work section or report it as an unresolved modernization finding.

**Verify:** Read the final `AGENTS.md` / `CLAUDE.md` instructions and the workflow files side by side. Every local
finish-work command matches a required CI command exactly, every required CI signal is represented, and no extra local
command is described as required unless it is intentionally stricter than CI and the instructions say that.

### 4. Replace `actions-rs/*` GitHub Actions (Rust projects)

**Detect:** Any `.github/workflows/*.yml` file that references `actions-rs/` in a `uses:` field (e.g.
`actions-rs/toolchain`, `actions-rs/cargo`, `actions-rs/clippy-check`, `actions-rs/audit-check`).

**Why:** The `actions-rs` organization is unmaintained and deprecated. Ubuntu runners already ship with a recent stable
Rust toolchain, so a dedicated toolchain action is unnecessary for stable builds. Removing the dependency simplifies CI
and eliminates a supply-chain risk.

**Replace with:**

- Remove all `uses: actions-rs/*` steps.
- Replace `actions-rs/cargo` steps with direct `cargo` invocations (`run: cargo build`, `run: cargo test`, etc.).
- Replace `actions-rs/toolchain` steps — if the workflow only needs stable Rust, simply remove the step (ubuntu has it).
  If a specific toolchain or component is needed (e.g. nightly, rustfmt, clippy), use
  `actions-rust-lang/setup-rust-toolchain@v1` with appropriate `toolchain:` and `components:` inputs.
- Replace `actions-rs/clippy-check` with a plain `run: cargo clippy` step.
- Replace `actions-rs/audit-check` with `run: cargo install cargo-audit && cargo audit` or equivalent.
- Add cargo caching using `actions/cache@v4`:

```yaml
- uses: actions/cache@v4
  with:
    path: |
      ~/.cargo/registry
      ~/.cargo/git
      target
    key: ${{ runner.os }}-cargo-${{ hashFiles('**/Cargo.lock') }}
    restore-keys: |
      ${{ runner.os }}-cargo-
```

- Place the cache step immediately after `actions/checkout`.
- If `Cargo.lock` is not committed (e.g. library crates), use `hashFiles('**/Cargo.toml')` instead.

**Verify:** `rg 'actions-rs/' .github/` returns no matches after replacement.

### 5. Canonicalize agent instructions as `AGENTS.md`

**Detect:** Find every `CLAUDE.md` in the repository, at the root and in subdirectories. For each one, note whether it
is a symlink resolving to the sibling `AGENTS.md` (compare by canonicalized path, so `AGENTS.md`, `./AGENTS.md`, and
equivalent forms all count), a dangling symlink, a symlink pointing elsewhere, or a regular file, and whether a sibling
`AGENTS.md` exists in the same directory.

**Skip if:** No `CLAUDE.md` exists anywhere in the repository. There is nothing to canonicalize.

**Why:** Claude now reads `AGENTS.md` directly, so the old `CLAUDE.md -> AGENTS.md` compatibility symlink serves no
purpose. One canonical instruction file per directory, named `AGENTS.md`, with no symlinks to maintain.

**Replace with:**

Apply these branches in order for each directory containing a `CLAUDE.md`:

- Never create a `CLAUDE.md` symlink. This item only removes or renames; it does not set up new symlinks.
- First, if the sibling `AGENTS.md` is itself a symlink: if its target is readable, replace it with a regular file
  containing the target's current content. If it is dangling, report it as blocked and do nothing with that pair until
  the user decides. This runs before any content comparison below, so a reverse `AGENTS.md -> CLAUDE.md` symlink is
  materialized first and its content is never deleted.
- For each `CLAUDE.md` that is a symlink resolving to the sibling `AGENTS.md`: include its full path in the findings
  list, and after the user approves, delete the symlink. Present the complete list of paths to be removed before
  deleting anything.
- For each `CLAUDE.md` that is a dangling symlink (including one whose target string names `AGENTS.md` when no sibling
  exists): include its full path in the findings list, and after the user approves, delete it. A dangling link points at
  nothing, so deleting it loses no content.
- For each `CLAUDE.md` that is a regular file:
  - If no sibling `AGENTS.md` exists in the same directory, rename `CLAUDE.md` to `AGENTS.md` (use `git mv` when the
    file is tracked).
  - If a sibling `AGENTS.md` exists with byte-identical content (compare with `cmp`, no normalization), delete
    `CLAUDE.md`.
  - If a sibling `AGENTS.md` exists with different content, do not guess which one is authoritative. Report the conflict
    with both paths and ask the user what to do before changing either file.
- If `CLAUDE.md` is a symlink pointing somewhere other than the sibling `AGENTS.md`, report that explicitly: the target
  may be intentional project-specific wiring. Delete it only after explicit per-path approval, like the branches above.

Note: this item covers all directories, while items 6, 9, and 12 only cover root-level instruction files.

**Verify:** No `CLAUDE.md` remains anywhere in the repository, except cases the user explicitly asked to keep. Every
remaining `AGENTS.md` is a regular file (`test ! -L` succeeds).

### 6. Remove architecture-overview bloat from `CLAUDE.md` / `AGENTS.md`

**Detect:** A `CLAUDE.md` or `AGENTS.md` at the repository root (or `.claude/` directory) whose content is predominantly
architecture overview — descriptions of what each directory contains, how modules relate to each other, summaries of the
tech stack, or restating what is already obvious from reading the code and repo structure.

**Why:** These files should contain _intent and preferences_ that an agent cannot infer from the project itself: coding
conventions, workflow rules, things to avoid, non-obvious constraints, and domain-specific decisions. Architecture
overviews are redundant — an agent can read the code — and they rot as the code evolves, becoming actively misleading.

**Replace with:**

- Remove sections that merely describe the project structure, list directories and their purposes, summarize the tech
  stack, or restate what `README.md` already covers.
- Keep any sections that express preferences, constraints, workflow instructions, or non-obvious conventions.
- Keep required checks and commands (e.g. "run `cargo fmt`", "run `cargo test`", "run `cargo clippy`"). These are
  intentional guardrails, not architecture descriptions, even if they appear alongside structural overviews.
- If the entire file is architecture overview with no preference/intent content, delete it.
- If only some sections are bloat, remove those sections and keep the rest.

**Verify:** Read the resulting file (if it still exists) and confirm every remaining section expresses an intent,
preference, or constraint that cannot be trivially inferred from the repository contents.

### 7. Migrate from `log` crate to `tracing` (Rust projects)

**Detect:** `Cargo.toml` (including workspace and member `Cargo.toml` files) lists `log` as a dependency, or the source
code uses `log::info!`, `log::debug!`, `log::warn!`, `log::error!`, `log::trace!`, or the corresponding unqualified
macros imported from `log`. Also detect `env_logger`, `simple_logger`, `pretty_env_logger`, `fern`, or `simplelog` as
dependencies — these are `log`-ecosystem logger implementations that should be replaced.

**Skip if:** No logging dependency (`log`, `tracing`, or any logger implementation) exists in any `Cargo.toml` and no
logging macros are used in the source code. The project simply doesn't do logging — leave it alone.

**Why:** The `tracing` crate is the modern Rust logging/diagnostics standard. It is a superset of `log` — all `log`
macros (`info!`, `debug!`, etc.) have direct `tracing` equivalents with the same syntax. `tracing` additionally supports
structured fields, spans for contextual diagnostics, and `async`-aware instrumentation. The ecosystem has converged on
`tracing`; most major libraries and frameworks (tokio, axum, etc.) emit `tracing` events natively.

**Replace with:**

- In `Cargo.toml`: replace `log` with `tracing`. Remove `env_logger` / `simple_logger` / `pretty_env_logger` / `fern` /
  `simplelog` and add `tracing-subscriber` instead.
- In source files: replace `use log::{...}` with `use tracing::{...}`. The macro names (`info!`, `debug!`, `warn!`,
  `error!`, `trace!`) are identical — most call sites need only the import change.
- For logger initialization (e.g. `env_logger::init()`), replace with a `tracing-subscriber` setup. A minimal
  equivalent:
  ```rust
  tracing_subscriber::fmt::init();
  ```
  If the project was using `env_logger` with `RUST_LOG` filtering, `tracing-subscriber`'s `EnvFilter` provides the same
  behavior:
  ```rust
  use tracing_subscriber::EnvFilter;
  tracing_subscriber::fmt()
      .with_env_filter(EnvFilter::from_default_env())
      .init();
  ```
- If the project has library crates that use `log` but no logger initialization, just swap the dependency and imports —
  library crates should not initialize a subscriber.
- If any dependency emits `log` events and the project wants to capture them, add the `tracing-log` bridge or enable
  `tracing`'s `log` feature (`tracing = { version = "...", features = ["log"] }`).

**Verify:** `rg 'use log' src/` and `rg '\blog\b' Cargo.toml` return no matches. `cargo check` succeeds.

### 8. Add `dprint` formatting with checksum-pinned plugins (projects with JSON, TOML, or Markdown files)

**Detect:** The project has any `.json`, `.toml`, or `.md` files. Check whether `dprint.json` already exists at the
repository root, but do not treat an existing config as "already done". In an existing config, inspect every entry in
`plugins`: a remote plugin — an `https://` URL or an `npm:` specifier — that does not end in `@<64 hex characters>` is a
finding, however precisely its filename or specifier names a version. `https://plugins.dprint.dev/json-0.23.0.wasm` is
unpinned; `https://plugins.dprint.dev/json-0.23.0.wasm@3e1f…443c` and `npm:@dprint/json@0.23.0@1bf6…1bc3` are pinned.

**Skip if:** `dprint.json` exists, every remote plugin entry carries a checksum, the core plugins for the file types
present are all configured, and CI runs `dprint check`.

**Why:** `dprint` enforces consistent formatting for JSON, TOML, and Markdown files. Without it, formatting drift
accumulates across contributors and tools. It is fast, pluggable, and easy to add to CI.

The checksum matters because a version in a URL pins a name, not bytes. Nothing stops a later download from the same URL
returning different content — a replaced release asset, a compromised host, a cache problem — and without a checksum the
formatter CI trusts can change with no diff to review. These are Wasm plugins, so the sandbox limits what a bad one can
do to the host, but it still reads every file it formats and decides what comes back. With a checksum, `dprint` refuses
a download whose bytes do not match (exit code 12, "The checksum did not match the expected checksum"). That
verification happens at download time only: a plugin already in the local cache is not re-hashed, so the pin is what
protects fresh environments — CI above all — rather than a developer's warm cache.

**Replace with:**

- Check the installed `dprint` first. `dprint add --checksum` exists from dprint 0.55.0 onwards; older binaries accept
  `dprint add` but reject `--checksum` as an unknown argument, and have no other way to pin. Feature-detect rather than
  trusting the version string: `dprint add --help | grep -q -- --checksum`. If the flag is missing, do not fall back to
  unpinned URLs: either upgrade `dprint` (the install script at `https://dprint.dev/install.sh` puts a current binary
  wherever `DPRINT_INSTALL` points, so this needs no system change) or pin the entries by hand as described below, which
  works on any version because the checksum is just part of the plugin string.

- If `dprint.json` does not exist yet, create it at the repository root with the desired formatter settings and an empty
  plugin list, then let `dprint` fill the list with pinned, current plugins. Do not hand-write plugin entries from this
  skill; they would be stale.

```json
{
  "json": {
  },
  "markdown": {
    "lineWidth": 120,
    "newLineKind": "lf",
    "textWrap": "always"
  },
  "toml": {
  },
  "excludes": [
    "**/*-lock.json"
  ],
  "plugins": []
}
```

```sh
dprint add --checksum json markdown toml
```

- If `dprint.json` already exists, keep the project's formatter settings and plugin order. Add any missing core plugin
  with `dprint add --checksum <name>`. For each existing remote entry without a checksum, pin it in place at its current
  version — do not upgrade it as a side effect of pinning; an upgrade is a separate decision for the user:
  - For an `https://…wasm` entry, the checksum is the SHA-256 of the file: `curl -fsSL <url> | sha256sum`, then edit the
    entry to `<url>@<sha256>`.
  - For an `npm:` entry, the checksum is not the hash of the Wasm file, so compute it with `dprint` itself: in a scratch
    directory, `dprint add --checksum npm:@dprint/json@0.23.0` (the same version the project has) writes the pinned form
    to a throwaway config; copy the checksum into the project's entry.
  - Edit in place rather than running `dprint add --checksum <url>` against the project config: when the unpinned entry
    is already present, `add` appends a pinned duplicate instead of replacing it, which changes plugin order and leaves
    the unpinned entry behind.

- Offer `dprint config update` as a separate, user-approved step, not as part of pinning. It upgrades every plugin to
  the latest version and, for entries that already carry a checksum, writes the new version's checksum (a pinned
  `https://` URL comes back as a pinned `npm:` specifier on current versions). It does not add checksums to entries that
  lack them: an unpinned URL is upgraded to an unpinned specifier. So pin first, then update if the user wants the
  upgrade, and re-check the pins afterwards either way.

- If the project has a `.github/workflows/ci.yml` (or similar CI workflow), add a `dprint` job:

```yaml
dprint:
  runs-on: ubuntu-latest
  steps:
    - uses: actions/checkout@v4
    - name: Check formatting with dprint
      uses: dprint/check@v2.3
```

- Run `dprint fmt` to fix any existing formatting issues.

**Verify:** Every remote plugin entry in `dprint.json` ends in `@<64 hex characters>`; for example `grep -E
'"(https?://|npm:)[^"]*"' dprint.json | grep -v -E '@[0-9a-f]{64}"'` prints nothing. Then `dprint clear-cache && dprint
check` passes — clearing the cache is what makes `check` actually download and verify against the pins instead of
reusing already-cached plugins. If `dprint config update` was run, confirm afterwards that no entry lost its checksum.
If CI was updated, confirm the `dprint` job exists in the workflow file.

### 9. Add conventional commit instructions to agent config (projects with `CLAUDE.md` or `AGENTS.md`)

**Detect:** The project has a `CLAUDE.md` or `AGENTS.md` (at the repo root or in `.claude/`) that does not already
contain conventional commit guidance (search for "conventional commit" case-insensitively).

**Why:** Conventional Commits give commit messages and PR titles a machine-parseable, human-scannable structure. Tools
like `git-cliff`, `release-please`, and `semantic-release` rely on the prefix to generate changelogs and pick version
bumps automatically. Even without automation, a consistent prefix makes `git log --oneline` trivially scannable.

**Replace with:**

- If item 5 is also approved, apply it first, then edit the surviving canonical file. Editing before canonicalization
  can turn identical twins into a conflict.
- Add the following section to the project's `AGENTS.md` (preferred) or `CLAUDE.md`. Place it near any existing commit
  message or PR guidance. If the file already has a commit-message section, merge the conventional commit rules into it
  rather than creating a duplicate section.

```markdown
# Conventional Commits

All commit messages and PR titles must use Conventional Commit format: `<type>: <short summary>`

Allowed types: `feat`, `fix`, `docs`, `perf`, `refactor`, `style`, `test`, `chore`, `ci`, `revert`.

Append `!` after the type for breaking changes (e.g. `feat!: remove legacy endpoint`). Scope is optional.

Rules:

- Type reflects the user-visible effect, not the implementation activity. A bug fix that requires heavy refactoring is
  `fix`, not `refactor`. A new CLI flag is `feat`, not `chore`.
- The summary after the colon is lowercase, imperative mood, no trailing period.
- Keep the first line under 72 characters.
```

**Verify:** The target file contains a conventional commit section. Read it back and confirm the types list and rules
are present.

### 10. Remove the `require-main-base` PR guard (GitHub Actions projects)

**Detect:** A workflow under `.github/workflows/` has a `require-main-base` job, or an equivalent job whose only purpose
is to fail pull requests when `github.base_ref` is not the repository's main integration branch. Also inspect GitHub
branch protection and repository rulesets for a required status check tied to that job.

**Skip if:** No workflow enforces this restriction and no matching required status check remains in GitHub settings.

**Why:** A stacked PR is intentionally based on the PR below it until the stack lands. Requiring every PR to target the
integration branch makes those valid child PRs stay red, then adds retargeting and event-ordering work before their CI
state becomes useful. The guard is not worth that routine noise and hassle.

**Replace with:**

- Remove the base-guard job from the workflow. If it was the workflow's only job, delete the workflow file; otherwise
  preserve the unrelated triggers, permissions, and jobs.
- Match by behavior as well as by the `require-main-base` name. Remove a differently named job only when its sole
  purpose is the same base-branch restriction. Do not remove unrelated PR policy or validation jobs.
- Remove the guard's status check from branch protection and repository rulesets before the workflow stops producing it.
  A deleted workflow with a still-required check can leave pull requests permanently blocked.
- Change only the matching required-check entry. Preserve every other branch-protection and ruleset setting.
- If GitHub settings cannot be inspected or changed with the available access, remove the workflow job and report the
  exact required-check cleanup as unfinished rather than claiming the modernization is complete.

**Verify:** No workflow job rejects pull requests solely because their base is another branch in the stack. GitHub
branch protection and repository rulesets no longer require the removed status check, and all unrelated jobs and
protection settings remain intact.

### 11. Fix `changelog: include` parser ordering in `cliff.toml` (git-cliff projects)

**Detect:** The project has a `cliff.toml` with a `commit_parsers` list in which a rule matching `changelog: include`
(in message, body, or footer) appears _before_ the type-based grouping rules (`^feat`, `^fix`, `^perf`, `^revert`). Also
treat it as a finding when the ordering is correct but the rationale comment above the type-grouping rules is the older
scode-dist-rust-setup wording — a claim that PR bodies or commits "always" contain a changelog tag, without scoping the
claim to commits merged under the convention.

**Skip if:** There is no `cliff.toml`, there are no `changelog: include` parser rules at all, or the include rules
already come after the type-based grouping rules and the rationale comment already matches the current template wording.

**Why:** git-cliff applies the first matching parser. In repos where CI requires every PR body to carry a `changelog:
include` / `changelog: skip` tag, squash merges copy that tag into the commit body — so for commits merged under the
convention, an early include rule matches first and forces every entry into its group (typically "Changed"). Fix commits
never reach the "Fixed" group and the generated changelog misclassifies everything. This bit saltybox: every release
section came out as "### Changed" until the parsers were reordered. The stale comment wording matters too: the comment
is the only documentation of this load-bearing ordering constraint, and the old wording overstates the invariant
(pre-convention commits in migrated repos carry no tag at all).

**Replace with:**

- Reorder `commit_parsers` to: `changelog: skip` overrides first (skip must win over everything), then the type-based
  grouping rules (`feat` → Added, `fix` → Fixed, `perf` → Performance, `revert` → Reverted), then the `changelog:
  include` rules (which now only rescue commit types that would otherwise be skipped), then the type-based skip rule for
  non-user-visible types.
- The corrected block, with rationale comments, is in
  `agent-skills/scode-dist-rust-setup/references/git-cliff-and-changelog-flow.md` — keep the two in sync.
- If the ordering is already correct and only the comment wording is stale, replace the rationale comment with the
  current block from the reference file and leave the parser rules untouched. No changelog regeneration is needed in
  that case — the output does not change.
- After reordering, regenerate the changelog (`git-cliff --tag <current-tag> -o CHANGELOG.md`) and review the diff:
  entries for past releases may legitimately move between groups (that is the fix working). Watch for hand-written
  sections that regeneration drops; restore them manually.

**Verify:** In `cliff.toml`, the first `changelog\s*:\s*include` rule appears on a later line than the `^fix` grouping
rule, and the rationale comment matches the current template in the reference file. When the ordering changed,
regenerating the changelog puts `fix:` commits under "### Fixed", not "### Changed".

### 12. Declare whether the project is public or private in `AGENTS.md`

**Detect:** The repository has an `AGENTS.md` and/or `CLAUDE.md` at the root. Check whether it contains a visibility
declaration: a statement that the project is (or may become) public and must not contain personal information, or a
statement that the project is intentionally private and local/personal assumptions are fine. Match on intent, not exact
wording — an existing paragraph that clearly makes either declaration counts.

**Skip if:** Either declaration is already present. Also skip if neither `AGENTS.md` nor `CLAUDE.md` exists; do not
create an instruction file only to hold this statement.

**Why:** Whether usernames, hostnames, local paths, and similar environment details are allowed in a repo depends
entirely on whether the repo will ever be public, and an agent cannot infer that from the code. Without an explicit
statement the agent either leaks personal details into something that later gets published, or wastes effort scrubbing a
repo that was never going to leave the machine. The declaration has to be made by the user; there is no safe default to
guess.

**Replace with:**

- If item 5 is also approved, apply it first, then add the statement to the surviving canonical file. Editing before
  canonicalization can turn identical twins into a conflict.
- Ask the user which of the two applies. Do not pick one on their behalf, and do not infer it from the presence of a
  GitHub remote or a license file — a public remote today does not mean personal details were intended to be there, and
  a private remote does not mean it will stay private.
- Add the chosen statement, verbatim, to `AGENTS.md` (preferred) or `CLAUDE.md`, near the top or alongside other
  project-wide constraints:

  For public or possibly-public projects:

  ```markdown
  This project is either public now, or may become public in the future. No content in this project should contain
  personal information such as personal usernames, hostnames, details about the local environments, etc.
  ```

  For intentionally private projects:

  ```markdown
  This project is intentionally and definitely private. It's ok to have local/personal assumptions in the content of this
  repo.
  ```

- If the user picks the public statement, that is only the declaration. Scanning the repo for existing personal details
  is out of scope for this item; mention it as a possible follow-up rather than doing it unasked.

**Verify:** The instruction file contains exactly one of the two declarations. Read it back and confirm it matches the
user's answer.

### 13. Set up or normalize repository lore

**Detect:** Load `skillette`, read its `lore/SKILLETTE.md` and `lore/setup.md`, and use that convention to inspect the
repository's lore setup without changing anything. Missing `lore/`, noncanonical instruction files, entry naming or
directory-entry README gaps, and missing Markdown-tool exclusions are findings. Inspect historical contents only as
needed for this setup audit; do not turn it into a review of old entries.

**Skip if:** The setup already conforms to `skillette-lore` and there are no unresolved setup findings.

**Why:** Historical notes need a predictable home that normal maintenance leaves alone. The lore skillette owns that
convention; delegating setup to it avoids maintaining a second, drifting copy here.

**Replace with:**

- Include setup or normalization in the full findings list and wait for the user's approval for this repository, like
  every other checklist item. Detecting missing lore is not permission to create it.
- Once approved, follow `skillette-lore setup` using the loaded setup procedure. It covers fresh installation and
  normalization, including instruction files, naming, and tool exclusions. Do not invent a separate setup procedure.
- Keep its safeguards: an unrelated directory named `lore` needs clarification, existing entries stay frozen, unknown
  dates are not guessed, and collisions or dependencies on lore are reported rather than silently repaired.
- If the dependency cannot be loaded, report this item as blocked rather than approximating its canonical texts.
- This item establishes the storage convention only; it does not enable automatic logging or start reading lore during
  ordinary work.

**Verify:** Recheck against the loaded setup procedure. Report changed paths, already-conforming parts, and every
unresolved deviation; do not claim a clean setup when the procedure left findings for the user to decide.

### 14. Offer an always-on agent work log in lore

**Detect:** Read the repository's agent instructions for a standing work-log policy. Compare its behavior with
`work-log.md` beside this skill, not just its heading. Missing daily append-only logging, decision/reasoning capture,
startup or compaction reads, or committing the log with the work are findings. Read instructions, not historical log
contents, to detect this item.

**Skip if:** An equivalent policy is already present. If the repository explicitly declines automatic logging, report
that choice as skipped rather than offering to override it.

**Why:** Decisions, rejected approaches, and unfinished work otherwise disappear with the conversation. An append-only
record kept as work happens lets later sessions recover the reasoning without treating historical notes as live specs.

**Replace with:**

- Present this as a separate choice in the findings list. Explain that approval makes logging always on for future
  sessions in this repository, including small tasks; approval of lore setup alone does not approve logging.
- Require the lore convention from item 13 first. If it is absent or needs normalization and that item was not approved,
  ask for approval of the prerequisite or leave logging blocked. Do not silently bundle in lore setup.
- After approval, install the policy from `work-log.md` as a standalone `Work log` section in the repository's agent
  instructions, outside its `Lore` section so later normalization preserves it. Install in `AGENTS.md` when it exists,
  or when neither file exists; if item 5 has not been applied and only `CLAUDE.md` exists, install there instead so this
  item does not manufacture a both-files state. If both exist as separate regular files, keep both consistent. Ask
  before resolving conflicting policies rather than replacing a deliberate repository choice.
- Preserve unrelated instructions and existing log entries. Do not backfill old sessions or create empty daily files as
  setup artifacts. Keep all Markdown-tool exclusions for `lore/`; current-day logs are not a formatting exception.

**Verify:** Read the installed policy and lore instructions together: only the specified work-log reads and current-day
appends are automatic, old logs and other entries stay frozen, and normalization preserves the standalone policy.
Confirm the policy is equivalent to the template and there is no duplicate or contradictory work-log section. Report
whether logging was enabled, already present, declined, or blocked on lore setup.
