cargo-anvil-adoption

<!-- 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-fuzzing
• 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.