---
name: cargo-anvil-adoption
description: Complete cargo-anvil adoption in an existing Rust repository after the first cargo anvil run. Use when generated Anvil files coexist with legacy CI, recipes, scripts, tool configuration, or validation failures.
license: MIT
---

<!-- GENERATED BY cargo-anvil. DO NOT EDIT DIRECTLY. -->

# Complete cargo-anvil adoption

Use this skill after the first `cargo anvil` run in a repository that already
contained Rust build and CI infrastructure. The goal is a clean, reviewable
Anvil installation that adopts the Anvil catalog as its default build and
validation contract, removes duplicate capabilities, and passes the generated
checks.

Do the work in the repository. Do not stop at an audit or plan unless a
decision genuinely requires the user.

## Invariants

- Read the repository's instructions and design documentation before editing.
- Preserve unrelated working-tree changes. Never discard or rewrite user work.
- Treat existing CI, scripts, configuration, and branch policies as evidence of
  prior behavior to evaluate, not as behavior that must be preserved.
- Compare legacy and Anvil behavior across command arguments, operating systems,
  feature sets, toolchains, failure policy, outputs, schedules, permissions,
  and downstream consumers. Call out meaningful differences, then prefer the
  Anvil behavior unless a concrete repository requirement justifies divergence.
- Migrate justified repository requirements to Anvil-supported configuration
  before deleting their old implementation. Do not preserve historical
  customization solely to maintain exact legacy behavior.
- Keep release, deployment, packaging, compliance, code-signing, and
  other capabilities outside Anvil's scope. Keep repository-specific test
  automation only when it covers a documented requirement that the Anvil
  catalog does not satisfy.
- Change cargo-anvil templates rather than generated copies when working in the
  cargo-anvil source repository, then regenerate.

## 1. Establish the adoption state

1. Inspect the current branch, working tree, repository root, and remotes.
2. Read `AGENTS.md`, nested instruction files, design docs, and contributor
   documentation.
3. Inspect `.anvil.lock`, generated files, and any `.anvil-proposed` siblings.
4. Run `cargo anvil --dry-run`. Classify every proposed update, refusal,
   customized file, disabled item, and stale manifest entry.
5. If Anvil prerequisites are missing, run `just anvil-setup` and retry.

Do not use `--force` merely to make the run succeed. Use it only when the
repository is intentionally switching from a different tool recorded in
`.anvil.lock`.

## 2. Inventory the existing build system

Search for all local and cloud build surfaces:

- GitHub Actions, Azure DevOps pipelines, reusable templates, composite actions,
  and scheduled jobs;
- root and imported Justfiles, Makefiles, task runners, and developer scripts;
- Rust toolchain files and independent tool-version lists;
- `rustfmt.toml`, `clippy.toml`, Cargo lint tables, `deny.toml`, audit config,
  spelling dictionaries, coverage configuration, and impact configuration;
- mutation, Miri, Loom, fuzzing, examples, documentation, semver, external-type,
  license, and dependency checks;
- badges, contributor docs, agent instructions, branch protection, rulesets,
  required contexts, and merge queues.

Build a capability map from each legacy entry point to its Anvil counterpart.
Record meaningful differences and unmatched behavior. For every retained
repository-specific capability, document the requirement that prevents using
the Anvil behavior.

## 3. Align the repository to Anvil

Resolve differences at the policy source:

- Merge formatting and lint policy into the repository's normal Rust,
  rustfmt, and Clippy configuration outside Anvil-managed regions.
- Preserve license, source, advisory, ban, and duplicate-dependency policy in
  `deny.toml` or the relevant tool configuration.
- Move spelling exceptions into `.spelling`.
- Express coverage thresholds and opt-outs through cargo-coverage-gate metadata
  or narrowly scoped source attributes. Do not preserve a second coverage
  exclusion list when the Anvil gate cannot read it.
- Record intentional external public types in the package metadata understood
  by cargo-check-external-types.
- Ensure the root MSRV and stable toolchain selection are intentional and
  compatible with Anvil's deterministic selection rules.
- Represent Miri exclusions next to the affected tests, using profile-specific
  cfgs when only one scheduled profile needs an exception.
- Represent Loom support structurally with a feature, a required-feature test
  target, and a cfg-gated dependency.
- Mark interactive, credentialed, destructive, or long-running examples in
  `[package.metadata.anvil.examples].no-run`.

Prefer changing repository configuration or code to weakening a generated
check. Never convert discovery errors or unsupported states into silent skips.
When the legacy and Anvil behaviors differ, explain the resulting behavior
change and recommend the Anvil standard. Preserve the legacy behavior only when
the repository has a current, explicit requirement that Anvil cannot represent.

## 4. Resolve generated-content conflicts

For every Anvil-owned file or managed region:

1. Determine whether the repository edit encodes real policy or is an obsolete
   implementation detail.
2. Prefer the catalog behavior. Move only justified repository policy to the
   supported configuration surface where possible.
3. Revert the generated content to the catalog form by running `cargo anvil`.
4. Take ownership of generated content only when the repository has a durable
   requirement the catalog cannot represent. Document why it must diverge.
5. Re-run `cargo anvil --dry-run` until there are no unexplained proposals,
   refusals, or manifest changes.

Do not hand-edit emitted files when their source template is available.

## 5. Evaluate differences before deleting duplicates

Run the narrow Anvil recipe corresponding to each legacy capability and resolve
its failures first. Examples:

- `just anvil-fmt`
- `just anvil-clippy`
- `just anvil-doc-build`
- `just anvil-pr-test`
- `just anvil-pr-msrv`
- `just anvil-pr-runtime-analysis`
- `just anvil-pr-mutants`

When a check fails, fix the root cause and rerun that specific recipe instead of
repeating the entire tier. Install missing prerequisites with the matching
`*-setup` recipe or `just anvil-setup`.

Compare results with the legacy command where behavior is not obviously
identical. Treat disagreements as migration decisions, not automatic Anvil
defects: describe the impact and adopt Anvil's behavior unless the legacy
behavior serves a current requirement outside the catalog. Account for impact
scoping by using `ANVIL_IMPACT=off` when a deliberate full-workspace comparison
is required.

## 6. Remove duplicate infrastructure

After equivalence is established:

- delete legacy workflows, scheduled jobs, setup actions, recipes, and scripts
  whose complete behavior is now owned by Anvil;
- remove duplicate tool-version files and updaters when
  `justfiles/anvil/versions.just` is the authoritative list;
- update badges, contributor documentation, and agent instructions to name the
  Anvil workflows and recipes;
- retain scripts and pipelines only for requirements outside Anvil's scope, and
  document the unmet requirement and why the catalog behavior is insufficient;
- identify required status contexts or external rulesets that must change
  before the cleanup can merge.

Do not change hosted branch protection or organization policy without the
required authorization. Report the exact old and new contexts for the
maintainer when an atomic external update is necessary.

## 7. Final verification

1. Run `cargo anvil` and then `cargo anvil --dry-run`; the second run must be
   clean.
2. Run `just anvil-pr-fast`.
3. Run `just anvil-pr` for the complete local PR tier. If that is impractical,
   and a generated CI backend will validate the current change, ask whether to
   stop after the fast tier and rely on PR checks for the remaining groups. A
   local-only installation must run the remaining groups locally. Never
   describe partial validation as complete.
4. Confirm generated README files and documentation are current.
5. Search again for deleted workflow names, stale badges, old recipe names,
   duplicate version lists, and orphaned scripts.
6. Review the final diff for unrelated changes and accidental policy loss.

Finish with:

- what Anvil now owns;
- what legacy infrastructure was removed;
- what repository-specific infrastructure remains, which requirement it serves,
  and why the Anvil behavior is insufficient;
- any intentional behavioral differences;
- any branch-policy or ruleset action required before merge;
- the exact validation completed and anything left to cloud CI.