Plugins

A Dotfiles Pro plugin is any Ansible collection installed next to dotfilespro.roles in your requirements.yml, the company.roles pattern from the team setup, generalized to anyone.

Because the plugin interface is plain Ansible, much of the existing Galaxy ecosystem already works alongside the collection; a true Dotfiles Pro plugin goes further and delivers the same experience the built-in roles do.

The index below has two tiers accordingly: Plugins follow the requirements and earn the badge; works alongside lists reviewed install-grade roles that compose cleanly but skip the shell experience.

What a plugin requires

A collection qualifies as a Dotfiles Pro plugin when it meets all of these:

1. Installable collection: a valid galaxy.yml, installable from a git URL or Ansible Galaxy via requirements.yml.
2. Standard role layout: roles/<name>/tasks/main.yaml, defaults/main.yaml, with files/ and templates/ as needed.
3. Tagged tasks: every task tagged with the role name, so --tags <role> works for targeted runs.
4. Configuration via defaults: all user-facing values live in defaults/main.yaml and are overridable through inventory, group_vars, or host_vars; no hardcoded personal values.
5. Shell integration only via ~/.profile.d/: never edit .bashrc, .zshrc, or .profile directly; aliases follow the alias pattern.
6. Idempotent: a second run reports zero changes, and the role behaves under diff: true.
7. Local execution as the user: designed for connection: local, with become only where genuinely needed.
8. Graceful platform skips: guard platform-specific tasks with ansible_facts.os_family (or similar facts) so the role skips rather than fails on machines it does not support.
9. No secrets: never ship credentials, tokens, or .env files.

Strongly recommended, and required for a listing:

• A README per role documenting its variables.
• Role CI: apply plus idempotence proven in a clean container (required once the shared test harness ships; see the roadmap Testing section).

Recommended:

• Cleanup of stale artifacts: mark generated files and remove ones no longer declared in vars.
• Tagged semver releases (optionally published to Galaxy) so consumers can pin you, see the pinning gradient in the roadmap Releases section.
• Galaxy tags: tag your collection dotfiles and dotfilespro in galaxy.yml so plugins are discoverable via Galaxy search.
• Settings, not files: where software co-writes its own config, manage the relevant keys rather than templating the whole file, so upstream defaults and runtime writes survive; own whole files only as .d drop-ins or configs the software never writes itself.

Getting listed

Open a merge request adding a row to the index:

• Works alongside: we review the role's tasks for composition conflicts: no writes to user rc files, no ownership clashes over files the collection or other plugins manage. System-wide /etc/profile.d/ entries are fine.
• Plugins: the requirements above, a role README, and green CI. Listed plugins may carry the badge:

[![works with dotfilespro](https://img.shields.io/badge/works%20with-dotfilespro-1d76db?style=flat-square)](https://dotfiles.pro)

Index

Plugins

None yet, be the first.

Works alongside (reviewed)

Role	Stars	Provides	Review notes
geerlingguy.composer		PHP Composer + global packages	No shell writes. Interim until the native composer role ships
geerlingguy.nodejs		Node.js + npm globals	Writes /etc/profile.d/npm.sh (system-wide, coexists with ~/.profile.d/). Interim until the native node role (nvm) ships
gantsign.golang		Go SDK	Writes /etc/profile.d/golang.sh (system-wide, coexists)
gantsign.visual-studio-code		VS Code + extensions	Writes VS Code settings.json when configured, keep settings ownership in one place
hurricanehrndz.rustup		Rust toolchain via rustup	Role writes no shell config itself; the upstream rustup installer may append cargo's env line to rc files (append-only, coexists). Small project, slow release cadence
geerlingguy.mac		Homebrew, mas, dock (macOS)	macOS-only, no shell writes; overlaps the built-in macos role

Reviewed, not listed

• gantsign.oh-my-zsh templates the user's .zshrc wholesale (overwrite with backup). That is ownership of the exact seam file this collection's shell framework and zsh role manage, so it conflicts by design, not by accident; also dormant since 2023. A native oh-my-zsh story belongs in the zsh role (see the roadmap).