New Playbook

new-playbook

Create a new Ansible playbook following production conventions.

Required Inputs

Collect these parameters (one question at a time, using discovery context for defaults):

1. path — Directory where the playbook will be created (default: ./ or ./playbooks/ if that directory exists)
2. filename — Playbook filename (e.g., site.yml, deploy-nginx.yml)
3. target_hosts — Inventory group(s) or host pattern (e.g., webservers, all, databases:webservers)
4. roles — List of roles to include (suggest roles found in discovery; accept FQCN or short names)
5. playbook_type — Site playbook / Component playbook / AWX-ready playbook (suggest based on filename and roles)

If the user provides all of these inline, skip parameter collection.

Behavior

Step 1 — Discovery

Run discovery per references/discovery.md. Report:

• Roles found (in roles_path)
• Collections found (in collections_path)
• Existing playbooks
• Inventory location

Use discovered roles as suggestions during parameter collection.

Step 2 — Parameter Collection

Ask one question at a time. Suggest smart defaults:

• If site.yml is the filename → suggest site playbook type
• If single role → suggest component playbook type
• If AWX is mentioned or tower_job_id is referenced → suggest AWX-ready type
• Roles list: show numbered list of discovered roles, let user pick by number or type FQCN

Step 3 — Pre-Write Confirmation

Show a summary:

Will create: ./playbooks/deploy-nginx.yml

Play: "Deploy nginx web server"
  Hosts: webservers
  Roles: myorg.infra.nginx
  Type: Component playbook
  Tags: nginx, validate

Proceed? (yes/no)

Check if the file already exists. If it does, warn and require explicit confirmation.

Step 4 — Generate Playbook

Use references/playbook.md as the base template. Select the appropriate template:

• Site playbook → Template 1
• Component playbook → Template 2
• AWX-ready → Template 3

Apply these rules to the generated content:

• All modules use FQCN
• All tasks have tags (component + action category)
• no_log: true on any task handling secrets per references/security_vault.md
• pre_tasks includes OS version assertion using ansible.builtin.assert
• Include a post_tasks validation block using ansible.builtin.wait_for or ansible.builtin.uri
• Keep inventory and variable references aligned with references/inventory.md
• End with validation guidance aligned with references/testing.md
• Include block/rescue pattern for the main execution block if multiple steps
• Proper YAML comment header (author, version, description, usage)

Write using bash:

cat > /path/to/playbook.yml << 'EOF'
[playbook content]
EOF

Step 5 — Final Output

Show file tree:

find ./playbooks -type f | sort

Suggest next step:

Next step: Validate with `ansible-lint playbooks/deploy-nginx.yml`
           or use /ansible-designer:review-playbook to get a structured review.

Example Generated Output

---
# =============================================================================
# Playbook: deploy-nginx.yml
# Author:   Platform Team
# Version:  1.0.0
# Description: Deploy and configure nginx on webservers group.
# Usage:
#   ansible-playbook -i inventory/ deploy-nginx.yml
#   ansible-playbook -i inventory/ deploy-nginx.yml --check --diff
# =============================================================================

- name: Deploy nginx web server
  hosts: webservers
  become: true
  gather_facts: true
  vars:
    nginx_port: "{{ deploy_nginx_port | default(80) }}"
    nginx_enable_ssl: "{{ deploy_nginx_ssl | default(false) }}"

  pre_tasks:
    - name: Verify target OS is supported
      ansible.builtin.assert:
        that:
          - ansible_os_family in ['RedHat', 'Debian']
        fail_msg: "Unsupported OS family: {{ ansible_os_family }}"
      tags: [always]

  roles:
    - role: myorg.infra.nginx
      vars:
        nginx_port: "{{ nginx_port }}"
        nginx_enable_ssl: "{{ nginx_enable_ssl }}"

  post_tasks:
    - name: Confirm nginx is listening
      ansible.builtin.wait_for:
        host: "{{ ansible_host }}"
        port: "{{ nginx_port }}"
        timeout: 30
      delegate_to: localhost
      tags: [nginx, validate]

    - name: Print deployment summary
      ansible.builtin.debug:
        msg: "nginx deployed on {{ inventory_hostname }} — port {{ nginx_port }}"
      tags: [nginx, validate]