ansible/docs/guides/custom-roles.md

# Custom roles guide

This repo is designed to be extended by adding new roles under `roles/`.

## Role structure

Follow the standard Ansible role layout:

```
roles/<role_name>/
├── defaults/main.yml
├── handlers/main.yml
├── tasks/main.yml
├── templates/
├── files/
└── README.md
```

## Where to wire a new role

- Add it to the relevant playbook under `playbooks/` (or create a new playbook if it’s a major concern).
- Prefer tagging the role at inclusion time so `make <feature>` targets can use `--tags`.

## Standards (canonical)

- `project-docs/standards.md`
- `project-docs/decisions.md` (add an ADR entry for significant changes)