0. Tool Prerequisites Check (RECOMMENDED for first-time validation)
   ├─> Run bash scripts/setup_tools.sh for diagnostics
   ├─> Verify required tools are available
   ├─> Get installation instructions if tools are missing
   └─> NOTE: Validation scripts auto-install tools in temp venv if missing,
       but running setup_tools.sh first helps identify system issues early

1. Identify Ansible files in scope
   ├─> Single playbook validation
   ├─> Role validation
   ├─> Collection validation
   └─> Multi-playbook/inventory validation

2. Syntax Validation
   ├─> Run ansible-playbook --syntax-check
   ├─> Run yamllint for YAML syntax
   └─> Report syntax errors

3. Lint and Best Practices
   ├─> Run ansible-lint (comprehensive linting)
   ├─> Check for deprecated modules (see references/module_alternatives.md)
   ├─> **DETECT NON-FQCN MODULE USAGE** (apt vs ansible.builtin.apt)
   │   └─> Run bash scripts/check_fqcn.sh to identify short module names
   │   └─> Recommend FQCN alternatives from references/module_alternatives.md
   ├─> Verify role structure
   └─> Report linting issues

4. Dry-Run Testing (check mode)
   ├─> Run ansible-playbook --check (if inventory available)
   ├─> Analyze what would change
   └─> Report potential issues

5. Molecule Testing (for roles) - AUTOMATIC
   ├─> Check if molecule/ directory exists in role
   ├─> If present, ALWAYS run molecule test automatically
   ├─> Test against multiple scenarios
   ├─> Report test results (pass/fail/blocked)
   └─> Report any environmental issues if tests cannot run

6. Custom Module/Collection Analysis (if detected)
   ├─> Extract module/collection information
   ├─> Identify versions
   ├─> Lookup documentation (WebSearch or Context7)
   └─> Provide version-specific guidance

7. Security and Best Practices Review - DUAL SCANNING REQUIRED
   ├─> Run bash scripts/validate_playbook_security.sh or validate_role_security.sh (Checkov)
   ├─> **ALSO run bash scripts/scan_secrets.sh** for hardcoded secret detection
   │   └─> This catches secrets Checkov may miss (passwords, API keys, tokens)
   ├─> Validate privilege escalation
   ├─> Review file permissions
   └─> Identify common anti-patterns

8. Reference Documentation - MANDATORY CONSULTATION
   ├─> **MUST READ** references/common_errors.md when ANY errors are detected
   │   └─> Extract specific remediation steps for the error type
   │   └─> Include relevant guidance in validation report
   ├─> **MUST READ** references/best_practices.md when warnings are detected
   │   └─> Cite specific best practice recommendations
   ├─> **MUST READ** references/module_alternatives.md when:
   │   └─> Deprecated modules are detected
   │   └─> Non-FQCN module names are used (apt, service, etc.)
   │   └─> Provide specific FQCN migration recommendations
   └─> **MUST READ** references/security_checklist.md when security issues found
       └─> Include specific remediation guidance from checklist

undefined

**Common Issues Detected:**
- Indentation errors
- Invalid YAML syntax
- Duplicate keys
- Trailing whitespace
- Line length violations
- Missing colons or quotes

**Best Practices:**
- Always run yamllint before ansible-lint
- Use 2-space indentation consistently
- Configure yamllint rules in `.yamllint`
- Fix YAML syntax errors first, then Ansible-specific issues

undefined

**Common Issues Detected:**
- Deprecated modules or syntax
- Missing task names
- Improper use of `command` vs `shell`
- Unquoted template expressions
- Hard-coded values that should be variables
- Missing `become` directives
- Inefficient task patterns
- Jinja2 template errors
- Incorrect variable usage
- Role dependencies issues

**Severity Levels:**
- **Error:** Must fix - will cause failures
- **Warning:** Should fix - potential issues
- **Info:** Consider fixing - best practice violations

**Auto-fix approach:**
- ansible-lint supports `--fix` for auto-fixable issues
- Always review changes before applying
- Some issues require manual intervention

undefined

**Common Security Issues Detected:**

**Certificate Validation:**
- **CKV_ANSIBLE_1:** URI module disabling certificate validation
- **CKV_ANSIBLE_2:** get_url disabling certificate validation
- **CKV_ANSIBLE_3:** yum disabling certificate validation
- **CKV_ANSIBLE_4:** yum disabling SSL verification

**HTTPS Enforcement:**
- **CKV2_ANSIBLE_1:** URI module using HTTP instead of HTTPS
- **CKV2_ANSIBLE_2:** get_url using HTTP instead of HTTPS

**Package Security:**
- **CKV_ANSIBLE_5:** apt installing packages without GPG signature
- **CKV_ANSIBLE_6:** apt using force parameter bypassing signatures
- *
- *CKV2_ANSIBLE_4:** dnf installing packages without GPG signature
- **CKV2_ANSIBLE_5:** dnf disabling SSL verification
- **CKV2_ANSIBLE_6:** dnf disabling certificate validation

**Error Handling:**
- **CKV2_ANSIBLE_3:** Block missing error handling

**Cloud Security (when managing cloud resources):**
- **CKV_AWS_88:** EC2 instances with public IPs
- **CKV_AWS_135:** EC2 instances without EBS optimization

**Example Violation:**

```yaml

**Integration with Validation Workflow:**

Checkov complements ansible-lint:
1. **ansible-lint** catches code quality issues, deprecated modules, best practices
2. **Checkov** catches security vulnerabilities, compliance violations, cryptographic issues

**Best Practice:** Run both tools for comprehensive validation:
```bash

**Output Format:**

Checkov provides clear security scan results:

**Remediation Resources:**
- Checkov Policy Index: https://www.checkov.io/5.Policy%20Index/ansible.html
- Ansible Security Checklist: `references/security_checklist.md`
- Ansible Best Practices: `references/best_practices.md`

**Installation:**

Checkov is automatically installed in a temporary environment if not available system-wide. For permanent installation:

```bash
pip3 install checkov

undefined

**Validation Checks:**
- YAML parsing
- Playbook structure
- Task definitions
- Variable references
- Module parameter syntax
- Jinja2 template syntax
- Include/import statements

**Error Handling:**
- Parse error messages for specific issues
- Check for typos in module names
- Verify variable definitions
- Ensure proper indentation
- Check file paths for includes/imports

undefined

**Check Mode Analysis:**

When reviewing check mode output, focus on:

1. **Task Changes:**
   - `ok`: No changes needed
   - `changed`: Would make changes
   - `failed`: Would fail (check for check_mode support)
   - `skipped`: Conditional skip

2. **Diff Output:**
   - Shows exact changes to files
   - Helps identify unintended modifications
   - Useful for reviewing template changes

3. **Handlers:**
   - Which handlers would be notified
   - Service restarts that would occur
   - Potential downtime

4. **Failed Tasks:**
   - Some modules don't support check mode
   - May need `check_mode: no` override
   - Identify tasks that would fail

**Limitations:**
- Not all modules support check mode
- Some tasks depend on previous changes
- May not accurately reflect all changes
- Stateful operations may show unexpected results

**Safety Considerations:**
- Always run check mode before real execution
- Review diff output carefully
- Test in non-production first
- Validate changes make sense
- Check for unintended side effects

undefined

**Test Sequence:**
1. `dependency` - Install role dependencies
2. `lint` - Run yamllint and ansible-lint
3. `cleanup` - Clean up before testing
4. `destroy` - Destroy existing instances
5. `syntax` - Run syntax check
6. `create` - Create test instances
7. `prepare` - Prepare instances (install requirements)
8. `converge` - Run the role
9. `idempotence` - Run again, verify no changes
10. `side_effect` - Optional side effect playbook
11. `verify` - Run verification tests (Testinfra, etc.)
12. `cleanup` - Final cleanup
13. `destroy` - Destroy test instances

**Molecule Configuration:**

Check `molecule/default/molecule.yml`:
```yaml
dependency:
  name: galaxy
driver:
  name: docker
platforms:
  - name: instance
    image: ubuntu:22.04
provisioner:
  name: ansible
verifier:
  name: ansible

---
- name: Verify
  hosts: all
  tasks:
    - name: Check service is running
      service:
        name: nginx
        state: started
      check_mode: true
      register: result
      failed_when: result.changed

undefined

Steps:
1. Use `mcp__context7__resolve-library-id` with collection name
2. Get documentation with `mcp__context7__get-library-docs`
3. Focus on specific modules or plugins as needed

For **Custom/Private Modules or Collections:**

```bash

Steps:
1. Construct search query with module/collection name + version
2. Use `WebSearch` tool with targeted queries
3. Prioritize official documentation sources
4. Extract relevant examples and usage patterns

**Search Query Templates:**

**Example Workflow:**

**Version Compatibility Checks:**

- Compare required collection versions with available versions
- Identify deprecated modules or parameters
- Suggest upgrade paths if using outdated versions
- Warn about breaking changes between versions
- Check Ansible core version compatibility

**Common Collection Sources:**
- **Ansible Galaxy**: Official community collections
- **Red Hat Automation Hub**: Certified collections
- **GitHub**: Custom/private collections
- **Internal repositories**: Company-specific collections

undefined

**Minimum Versions:**
- Ansible: >= 2.9 (recommend >= 2.12)
- ansible-lint: >= 6.0.0
- yamllint: >= 1.26.0
- molecule: >= 3.4.0 (if testing roles)

**Optional Tools:**
- `ansible-inventory` - Inventory validation and graphing
- `ansible-doc` - Module documentation lookup
- `jq` - JSON parsing for structured output

Solution: Install required collection with ansible-galaxy
Check collections/requirements.yml
Verify collection namespace and name

Solution: Define variable in vars, defaults, or group_vars
Check variable precedence
Use default() filter for optional variables
Verify variable file is included

Solution: Check Jinja2 template syntax
Verify variable types match filters
Ensure proper quote escaping
Test template rendering separately

Solution: Verify inventory host accessibility
Check SSH configuration and keys
Verify ansible_host and ansible_port
Test with ansible -m ping

Solution: Add become: yes for privilege escalation
Verify sudo/su configuration
Check file permissions
Verify user has necessary privileges

Solution: Check ansible-lint output for replacement
Consult module documentation for alternatives
Update to recommended module
Test functionality with new module

bash scripts/setup_tools.sh

bash scripts/extract_ansible_info_wrapper.sh <path-to-playbook-or-role>

bash scripts/validate_playbook.sh <playbook.yml>

bash scripts/validate_playbook_security.sh <playbook.yml>

**validate_role.sh** - Comprehensive role validation script that checks role structure, YAML syntax, Ansible syntax, linting, and molecule configuration.

Usage:
```bash
bash scripts/validate_role.sh <role-directory>

bash scripts/validate_role_security.sh <role-directory>

bash scripts/test_role.sh <role-directory> [scenario]

bash scripts/scan_secrets.sh <playbook.yml|role-directory|directory>

bash scripts/check_fqcn.sh <playbook.yml|role-directory|directory>

User: "Check if this playbook.yml file is valid"

Steps:
1. Read the file to understand contents
2. Run yamllint on the file
3. Run ansible-playbook --syntax-check
4. Run ansible-lint
5. Report any issues found
6. If custom modules detected, lookup documentation
7. Propose fixes if needed

User: "Validate my ansible role in ./roles/webserver/"

Steps:
1. Run bash scripts/validate_role.sh ./roles/webserver/
2. This automatically checks:
   - Role directory structure (tasks/, defaults/, handlers/, meta/, etc.)
   - Required main.yml files
   - YAML syntax with yamllint
   - Ansible syntax with ansible-playbook
   - Best practices with ansible-lint
   - Molecule configuration (if present)
3. Report any issues found (errors and warnings)
4. If custom modules detected, lookup documentation
5. Provide specific recommendations for fixes
6. **CRITICAL:** If molecule/ directory exists in the role, AUTOMATICALLY run molecule tests:
   - Run bash scripts/test_role.sh ./roles/webserver/
   - Do NOT ask user first - molecule testing is mandatory for roles that have it configured
   - Report test results (pass/fail with details)
   - If tests fail due to environmental issues (Docker, compatibility), document the blocker
   - If tests fail due to role issues, provide detailed debugging steps

User: "Run playbook in check mode for production servers"

Steps:
1. Verify inventory file exists
2. Run ansible-playbook --check --diff -i production
3. Analyze check mode output
4. Highlight tasks that would change
5. Review handler notifications
6. Flag any security concerns
7. Provide recommendation on safety of applying

User: "I'm using community.postgresql.postgresql_db version 2.3.0, what parameters are available?"

Steps:
1. Try Context7 MCP: resolve-library-id("ansible community.postgresql")
2. If found, use get-library-docs for postgresql_db module
3. If not found, use WebSearch: "ansible community.postgresql version 2.3.0 postgresql_db module documentation"
4. Extract module parameters (required vs optional)
5. Provide examples of common usage patterns
6. Note any version-specific considerations

User: "Test my nginx role with molecule"

Steps:
1. Check if molecule is configured in role
2. If not, ask if user wants to initialize molecule
3. Run molecule list to see scenarios
4. Run molecule test
5. If failures, run molecule converge for debugging
6. Analyze test results
7. Report on idempotency, syntax, and verification
8. Suggest improvements if needed