Imported from tylium/unit-enum (AGENTS.md). Install upstream with npx skills add tylium/unit-enum. Copyright stays with the author.

Agent Instructions

Project Overview

This repository contains the unit-enum Rust crate, a procedural macro (#[derive(UnitEnum)]) for enums that are primarily composed of unit variants. It generates utility methods such as name, ordinal, from_ordinal, discriminant, from_discriminant, len, and values, while respecting the enum's #[repr] and optionally supporting a single "other" catch‑all variant.

File Structure and Organization

• AGENTS.md: Root instruction file for AI agents (this file). Also used via symlinks by other tools.
• README.md: Human-facing crate documentation and quick-start examples.
• Cargo.toml: Crate metadata, dependencies, and configuration (proc-macro = true).
• src/lib.rs: Implementation of the UnitEnum derive macro and its validation / codegen logic.
• src/lib.md: Crate-level Rustdoc included into the library docs; keep examples and text in sync with README.md.
• examples/: Small runnable binaries (example.rs, example_other.rs) that demonstrate typical usage, including the optional "other" variant.
• .github/workflows/rust.yml: GitHub Actions workflow for CI (build/tests).
• CHANGELOG.md: Human-maintained change log; follow existing style when documenting externally visible changes.
• LICENSE-MIT, LICENSE-APACHE: Dual licensing information.
• agents/: Reserved for generic, reusable, and versioned instruction documents. Do not modify from within this project; treat contents (if any) as read-only.

Symbolic Links

This AGENTS.md file is symlinked for compatibility with different AI agents:

• CLAUDE.md → AGENTS.md
• .junie/guidelines.md → AGENTS.md
• GEMINI.md → AGENTS.md
• .cursorrules → AGENTS.md

Any changes you make here automatically apply to those entrypoints; keep instructions tool-agnostic.

Development Guidelines

Code Organization

• Maintain a clear separation between agent instructions (AGENTS.md) and human documentation (README.md, CHANGELOG.md, crate docs in src/lib.md).
• Keep instructions dense, unambiguous, and optimized for AI processing (short sections, explicit bullets, minimal prose).
• When modifying macro behavior in src/lib.rs, also:
  • Update or add examples in src/lib.md, README.md, and examples/ as appropriate.
  • Preserve the documented semantics of generated methods (name, ordinal, discriminant, etc.) unless the change is intentionally breaking and coordinated with versioning.
• Do not modify files under agents/ from this repository; treat them as shared, versioned guidance.

Rust & Testing

• Use cargo test (and, if relevant, cargo test --examples) to validate changes; this runs doctests in src/lib.md and README.md as well as any unit tests.
• Prefer adding or updating doctests and examples when fixing bugs or changing behavior in the derive macro.
• Avoid introducing public API changes without updating documentation and, when applicable, bumping versions and changelog entries in coordination with maintainers.

File Management

• Only modify AGENTS.md directly; its symbolic links (CLAUDE.md, .junie/guidelines.md, GEMINI.md, .cursorrules) should not be edited independently.
• After making non-trivial changes to the crate or its structure, update this AGENTS.md to reflect the current project state so future agents have accurate context.