Imported from OriginalGary/vale-no-animal-violence (AGENTS.md). Install upstream with npx skills add OriginalGary/vale-no-animal-violence. Copyright stays with the author.

AGENTS.md — vale-no-animal-violence

Summary

vale-no-animal-violence distributes two Vale prose-linting style packages — NoAnimalViolence (primary, actively maintained) and Speciesism (legacy, kept for backwards compatibility) — that detect speciesist language in documentation, README files, and written prose. It is the prose layer of the Open Paws speciesist language detection suite, consuming patterns from the no-animal-violence canonical rule dictionary and translating them into Vale YAML substitution rules. The repository has no runtime code: it is a collection of static YAML rule files packaged as a GitHub Releases ZIP artifact and installed by end users via vale sync.

Status

Active Development — receiving rule updates and CI fixes as of April 2026. No named owner as of 2026-04-02. The feat/add-industry-euphemisms-rule remote branch may contain pending work worth evaluating.

Change implications:

• Rule changes take effect for consumers only after a new GitHub Release is published and users run vale sync.
• The .vale.ini in this repo points at Speciesism for local testing — it is a developer convenience config, not the canonical consumer config.
• Most rule files under NoAnimalViolence/ are auto-generated. Editing them directly will be overwritten on the next generation cycle.

Key Files

Install and Test Commands

# Install Vale
brew install vale   # macOS; see https://vale.sh/docs/install for other platforms

# Lint the repo's own README with the local developer config
vale --config .vale.ini README.md

# Lint any document
vale --config .vale.ini path/to/file.md

# Package for release (run from repo root)
zip -r NoAnimalViolence.zip NoAnimalViolence/
zip -r Speciesism.zip Speciesism/

# Validate YAML syntax
yamllint NoAnimalViolence/
yamllint Speciesism/

# Run pre-commit hooks locally
pre-commit run --all-files

There is no automated test suite. Rule validation is manual: lint a document containing both flagged and clean phrases and confirm that Vale reports only the expected findings.

Architecture

Vale rule format

Each rule file is a YAML document following the Vale substitution extension format:

extends: substitution
message: "Consider using '%s' instead of '%s'. <reason>"
level: warning | suggestion
ignorecase: true
swap:
  flagged phrase: suggested replacement

Vale loads rules by looking for a style directory (e.g., NoAnimalViolence/) on the StylesPath, then applying every .yml file in that directory to the target prose. Rules are identified in output as StyleName.RuleName (e.g., NoAnimalViolence.AnimalIdioms).

Two packages

Auto-generation pipeline

Files marked # AUTO-GENERATED from project-compassionate-code. Do not edit directly. are produced by project-compassionate-code, which consumes the no-animal-violence canonical dictionary and outputs Vale-formatted YAML. The generation cycle is not automated in this repo's CI — it is a manual sync step.

Distribution model

Consumers reference the package via a GitHub Releases ZIP URL in their .vale.ini:

Packages = https://github.com/Open-Paws/vale-no-animal-violence/releases/latest/download/NoAnimalViolence.zip

Running vale sync downloads and unpacks the ZIP into the consumer's StylesPath. There is no package registry (e.g., Vale Hub) involved — the release artifact is the distribution mechanism.

Integration Points

Safe vs. Risky Changes

Safe

• Adding a new swap entry to NoAnimalViolence/IndustryEuphemisms.yml (the only hand-maintained rule file in the primary package).
• Updating NoAnimalViolence/meta.json metadata fields (name, description, homepage).
• Editing CI workflow files (.github/workflows/).
• Updating .pre-commit-config.yaml dependency versions.

Requires upstream coordination

• Any change to auto-generated rule files (AnimalIdioms.yml, AnimalMetaphors.yml, TechTerminology.yml in either package) — these are owned by project-compassionate-code and no-animal-violence. Submit changes there first, then regenerate.

Risky

• Restructuring the NoAnimalViolence/ directory layout — any change to the directory name or file names breaks all consumers using the releases/latest ZIP URL until they re-sync.
• Modifying Speciesism/ rules — unknown downstream consumers may depend on the exact rule names and behavior. Check before changing.
• Publishing a release with malformed YAML — Vale will silently skip or error on bad rule files; consumers will lose coverage with no clear error message. Always run yamllint before releasing.

TODOs (from CLAUDE.md, as of 2026-04-11)

• Evaluate and potentially merge the feat/add-industry-euphemisms-rule remote branch.
• Integrate into context repo CI for document linting (issue §27a).
• Integrate into open-paws-platform documentation workflows.
• Add bootcamp setup instructions referencing this package.
• Establish a named owner/maintainer for the suite.
• Address the automated testing gap — currently all rule validation is manual.
• Automate the sync from no-animal-violence canonical dictionary to keep auto-generated files current.