ansible-designer

AI-assisted Ansible authoring toolkit. Scaffolds, reviews, and updates Ansible projects with production-quality output following official ansible-core 2.15+ conventions.

Available Commands

All commands are top-level regardless of install path.

Playbook Commands

Role Commands

Collection Commands

ansible.cfg Commands

Global Rules

Every sub-command enforces these rules without exception:

1. Discovery first — At command start, read in order: CLAUDE.md → ansible.cfg → README.md → filesystem scan. Build internal context (roles, collections, paths, namespace). Skip if user already provided all required parameters inline. See references/discovery.md.

1. Never overwrite silently — Before writing any file, show a summary (new files) or unified diff (modifications). Wait for explicit user confirmation (yes / y). Only write after confirmation.

1. FQCN mandatory — Every module reference uses the Fully Qualified Collection Name. ansible.builtin.copy, never copy. ansible.builtin.service, never service. See references/best_practices.md.

1. no_log: true on secrets — Every task handling passwords, tokens, API keys, vault variables, or credentials must include no_log: true. See references/security_vault.md.

1. Tags on every task — Minimum: component name + action category (install, configure, service, validate, security, cleanup). No task may be untagged.

1. review never modifies — review-* commands produce a structured severity report (CRITICAL / WARNING / INFO) only. They never write, modify, or suggest sed commands. Report only.

1. update always diffs — update-* commands read the existing file, compute the change, show a unified diff, and wait for explicit confirmation before writing a single byte.

1. Show file tree after writes — After any write operation, list all created or modified files and display the resulting file tree.

1. Testing-aware output — New or updated examples must include a realistic validation path. See references/testing.md.

1. Suggest next step — End every command with a concrete suggestion: which command to run next, or what to validate.

Standard Operational Flow

Every command follows this exact sequence:

Step 1 — Discovery

Read: CLAUDE.md → ansible.cfg → README.md → filesystem scan
Build: internal context (roles_path, collections_path, existing roles, collections, inventory)
Report: "Discovery complete: [summary of what was found]"

Skip Step 1 only if the user provided all required parameters inline.

Step 2 — Parameter Collection

• If the user already provided all required parameters: proceed to Step 3.
• Otherwise: ask one question at a time, using discovery context for smart defaults.
• Never ask for something that can be inferred from discovery (e.g., don't ask for namespace if a collection already exists).

Step 3 — Pre-Write Confirmation

• For new files: show a summary of what will be created (paths + brief description).
• For update commands: show a unified diff (--- original, +++ proposed).
• Wait for explicit user confirmation (yes, y, or equivalent) before proceeding.
• If user says no: ask what to change and loop back to Step 2.

Step 4 — Execution

• Write or modify files using bash commands.
• Follow all global rules: FQCN, tags, no_log.
• Use templates from the appropriate references/ file as the base.

Step 5 — Final Output

Show file tree of all created/modified files.
Suggest: "Next step: [specific actionable suggestion]"

Reference Files

Installation

Install via the Claude Code marketplace from 3A2DEV/ansible-designer. This preserves the ansible-designer: namespace prefix for all sub-commands.

Requires Claude Code.