michaelalber/cargo-package-scaffold

Cargo Package Scaffold

"A crate is a promise. Its Cargo.toml is the contract. Its tests are the proof. Semver is a social contract — publish nothing you would not stake your reputation on."

Core Philosophy

Publishing a Rust crate is a commitment. Once a version is on crates.io, it cannot be deleted — only yanked. This skill enforces the practices that make crates trustworthy: complete metadata, semver discipline, a CI gate that blocks broken publishes, and a test harness that covers the public API surface. The scaffold is opinionated by default and configurable by exception — every generated crate starts with deny(unsafe_code), #![warn(missing_docs)], and a CI pipeline that runs cargo test, cargo clippy, cargo fmt --check, and cargo publish --dry-run on every push.

Non-Negotiable Constraints:

1. SEMVER — breaking changes require a major version bump; verify with cargo semver-checks in CI.
2. DRY-RUN GATE — cargo publish --dry-run must pass in CI before any release.
3. DOCUMENTED — every public item has a doc comment; #![warn(missing_docs)] + cargo doc in CI.
4. SAFE BY DEFAULT — #![deny(unsafe_code)]; unsafe requires explicit justification and a // SAFETY: comment.
5. MINIMAL DEFAULTS — default = [] features and an explicit include list; users opt in, and the publish never ships .github/ or target/.

The full principle set, anti-patterns, discipline rules, and recovery steps live in references/conventions.md.

Workflow

DETECT      Read workspace Cargo.toml (inherit [workspace.package] if present), existing
            .github/workflows/, and deny.toml. Report findings. No files written.

SCAFFOLD    Create the crate skeleton:
              <crate-root>/
              ├── Cargo.toml          # complete metadata (see cargo-metadata-reference.md)
              ├── src/lib.rs          # deny(unsafe_code), warn(missing_docs), module structure
              ├── tests/integration.rs# integration stubs for the public API
              ├── examples/basic.rs   # minimal working example
              ├── CHANGELOG.md        # Keep a Changelog format
              └── README.md           # description, install, quick start
            Exit: cargo build / test / doc --no-deps all pass.

CI          Create .github/workflows/ci.yml with jobs: test (stable + MSRV matrix),
            lint (clippy -D warnings + fmt --check), docs, semver (PRs only), publish-dry-run.

RELEASE     Create release.yml triggered on v* tags: full CI gate, then publish to crates.io via
            CARGO_REGISTRY_TOKEN secret, then a GitHub Release with the CHANGELOG excerpt.
            (release.yml + secret documented in release-checklist.md.)

VERIFY      Run and require pass: cargo build · test · clippy -- -D warnings · fmt --check ·
            doc --no-deps · publish --dry-run. A captured command result, never a claim.

Exit criteria: crate builds, tests pass, lints clean, docs complete, publish --dry-run passes; CI and release workflows created; CARGO_REGISTRY_TOKEN documented for the user to add.

State Block

<cargo-package-scaffold-state>
phase: DETECT | SCAFFOLD | CI | RELEASE | VERIFY | COMPLETE
crate_name: [name]
crate_type: lib | bin | proc-macro
workspace: true | false
workspace_metadata_inherited: true | false
msrv: [version]
unsafe_allowed: true | false
features: [comma-separated]
ci_created: true | false
release_workflow_created: true | false
build_status: pass | fail | not-run
last_action: [description]
next_action: [description]
</cargo-package-scaffold-state>

Output Template

• Cargo.toml — references/cargo-metadata-reference.md (required + recommended fields, include/exclude).
• lib.rs, CI workflow, progress report — references/scaffold-templates.md.
• release.yml, CHANGELOG format, semver/yanking policy, pre-release checklist — references/release-checklist.md.

Integration with Other Skills

| Skill | Relationship | |-------|-------------| | rust-architecture-checklist | Run after scaffold to verify the crate's internal architecture. | | rust-security-review | Run before first publish to audit for security issues. | | rust-migration-analyzer | Use when migrating an existing crate to a new Rust edition. | | supply-chain-audit | Audit crate dependencies for CVEs and license compliance before publish. |