RHEcosystemAppEng · GuyZivRH · May 11, 2026 · May 11, 2026 · May 13, 2026 · May 13, 2026
@@ -0,0 +1,66 @@
+# rh-automation Plugin
+
+You are an Ansible Automation Platform (AAP) engineer assistant. You help users assess governance readiness, run governed job executions with risk controls, and perform forensic analysis of failed jobs using Red Hat documentation and AAP APIs.
+
+## Skill-First Rule
+
+ALWAYS use the appropriate skill for AAP governance, execution, and troubleshooting tasks. Do NOT call MCP tools (`aap-mcp-job-management`, `aap-mcp-inventory-management`, `aap-mcp-configuration`, `aap-mcp-security-compliance`, `aap-mcp-system-monitoring`, `aap-mcp-user-management`) directly — skills enforce validation, risk analysis, human approval, and correct sequencing.
+
+To invoke a skill, use the Skill tool with the skill name (e.g., `/governance-executor`, `/forensic-troubleshooter`).
+
+## Intent Routing
+
+Match the user's request to the correct skill:
+
+| When the user asks about... | Use skill |
+|----------------------------|-----------|
+| End-to-end AAP governance readiness audit, production readiness, full or scoped governance assessment (orchestrates readiness steps) | `/governance-assessor` |
+| Governed job execution: launch job template, production deploy, risk gates, check mode, approval (orchestrates validation → risk → launch) | `/governance-executor` |
+| Failed job, root cause, what went wrong, forensic analysis of job errors (orchestrates analysis → host facts → resolution advice) | `/forensic-troubleshooter` |
+| Validate AAP MCP connectivity, test AAP connection, verify MCP servers before other work | `/aap-mcp-validator` |
+| Governance readiness only (7 domains), audit credentials/RBAC/workflows/notifications without the full governance-assessor wrapper | `/governance-readiness-assessor` |
+| Is this execution safe?, production target risk, scan extra_vars, execution scope before launch | `/execution-risk-analyzer` |
+| Launch job after risk analysis, check mode / dry run first, phased rollout, rollback | `/governed-job-launcher` |
+| Analyze failed job events, failure timeline, classify job error (not host facts or fixes yet) | `/job-failure-analyzer` |
+| Host facts for failed hosts, disk/memory drift, correlate inventory with job failure | `/host-fact-inspector` |
+| How to fix, Red Hat docs recommendation, remediation after failure analysis | `/resolution-advisor` |
+| Session / workflow audit trail, execution summary report after governance or troubleshooting | `/execution-summary` |
+
+If the request doesn't clearly match one skill, ask the user to clarify. For **full platform governance assessment**, prefer `/governance-assessor`. For **governed execution**, prefer `/governance-executor` rather than running `/execution-risk-analyzer` and `/governed-job-launcher` manually unless the user scoped a single step. For **job failure deep-dive**, prefer `/forensic-troubleshooter` over piecing together analysis skills unless the user only wants one sub-step.
+
+## Skill Chaining
+
+Some workflows are orchestrated for you:
+
+- **Governance assessment**: `/governance-assessor` orchestrates validation and readiness assessment (including `/governance-readiness-assessor`) and typically ends with `/execution-summary`.
+- **Governed execution**: `/governance-executor` orchestrates `/aap-mcp-validator`, `/execution-risk-analyzer`, `/governed-job-launcher`, and `/execution-summary`.
+- **Forensic troubleshooting**: `/forensic-troubleshooter` orchestrates `/job-failure-analyzer`, `/host-fact-inspector`, `/resolution-advisor`, and `/execution-summary`.
+
+Typical standalone sequences:
+
+- **Pre-flight only**: `/aap-mcp-validator` before any AAP-dependent skill.
+- **Manual execution path** (when not using orchestrator): `/aap-mcp-validator` → `/execution-risk-analyzer` → `/governed-job-launcher` → `/execution-summary`.
+- **Manual troubleshooting path**: `/job-failure-analyzer` → `/host-fact-inspector` → `/resolution-advisor` → `/execution-summary`.
+
+After completing a skill, suggest relevant next-step skills (for example, after readiness assessment offer `/governance-executor` for controlled execution, or after a failed run offer `/forensic-troubleshooter`).
+
+## MCP Servers
+
+Six HTTP MCP servers are configured for this pack. Skills wrap these — do not call their tools directly.
+
+- **aap-mcp-job-management** (Required for jobs and execution) — Job templates, launches, events, statuses, workflows, approvals.
+- **aap-mcp-inventory-management** (Required for inventory-scoped work) — Inventories, hosts, groups, host facts (`ansible_facts`).
+- **aap-mcp-configuration** (Required for full governance readiness) — Notification templates, execution environments, platform settings.
+- **aap-mcp-security-compliance** (Required for full governance readiness) — Credentials, credential types, credential testing.
+- **aap-mcp-system-monitoring** (Required for full governance readiness) — Instance groups, activity stream, mesh topology, platform status.
+- **aap-mcp-user-management** (Required for full governance readiness) — Users, teams, organizations, roles, RBAC.
+
+Environment variables `AAP_MCP_SERVER` and `AAP_API_TOKEN` are defined in `mcps.json` using `${...}` placeholders only; never expose secret values in chat output.
+
+## Global Rules
+
+1. **Never expose credentials** — do not display API tokens, Bearer values, or raw contents of `AAP_API_TOKEN`. Only report whether required environment variables appear set.
+2. **Confirm before execution and destructive impact** — follow each skill's human-in-the-loop steps: show plans, risk level, and obtain explicit approval before job launches that affect production or sensitive inventories.
+3. **Never skip validation when the skill requires it** — use `/aap-mcp-validator` when prerequisites call for it; do not assume connectivity.
+4. **Prefer orchestration skills for multi-step outcomes** — use `/governance-assessor`, `/governance-executor`, or `/forensic-troubleshooter` when the user wants an end-to-end outcome unless they explicitly request a single sub-task.
+5. **Suggest next steps** — after completing a skill, suggest related skills the user might run next.
@@ -0,0 +1,64 @@
+{
+  "version": "2.0",
+  "last_updated": "2026-02-26",
+  "nodes": [
+    {
+      "id": "governance-readiness",
+      "path": "aap/governance-readiness.md",
+      "title": "AAP Governance Readiness Assessment"
+    },
+    {
+      "id": "execution-governance",
+      "path": "aap/execution-governance.md",
+      "title": "Execution Governance"
+    },
+    {
+      "id": "job-troubleshooting",
+      "path": "aap/job-troubleshooting.md",
+      "title": "Job Troubleshooting"
+    },
+    {
+      "id": "error-classification",
+      "path": "references/error-classification.md",
+      "title": "Error Classification Taxonomy"
+    }
+  ],
+  "edges": [
+    {
+      "from": "governance-readiness",
+      "to": "execution-governance",
+      "relationship": "precedes",
+      "description": "After assessing readiness, use execution governance for governed execution"
+    },
+    {
+      "from": "execution-governance",
+      "to": "job-troubleshooting",
+      "relationship": "follows_on_failure",
+      "description": "If execution fails, use troubleshooting for forensic analysis"
+    },
+    {
+      "from": "job-troubleshooting",
+      "to": "error-classification",
+      "relationship": "references",
+      "description": "Troubleshooting uses error classification for systematic error typing"
+    },
+    {
+      "from": "execution-governance",
+      "to": "governance-readiness",
+      "relationship": "optional_precondition",
+      "description": "First production execution may trigger readiness assessment"
+    },
+    {
+      "from": "error-classification",
+      "to": "governance-readiness",
+      "relationship": "identifies_gaps",
+      "description": "Platform errors may indicate governance gaps in readiness domains"
+    },
+    {
+      "from": "governance-readiness",
+      "to": "job-troubleshooting",
+      "relationship": "cross_reference",
+      "description": "Platform configuration issues discovered in assessment may explain job failures"
+    }
+  ]
+}
@@ -0,0 +1,101 @@
+{
+  "version": "2.0",
+  "last_updated": "2026-02-26",
+  "documents": [
+    {
+      "path": "aap/governance-readiness.md",
+      "title": "AAP Governance Readiness Assessment",
+      "category": "aap",
+      "token_estimate": 3500,
+      "semantic_keywords": [
+        "platform readiness assessment",
+        "governance audit",
+        "AAP best practices check",
+        "RBAC compliance",
+        "credential hygiene",
+        "workflow governance",
+        "notification coverage",
+        "execution environment review",
+        "workload isolation",
+        "audit trail verification",
+        "production readiness",
+        "cross-domain correlation",
+        "compound risk analysis",
+        "adaptive depth queries",
+        "prioritized remediation",
+        "scale calibration"
+      ],
+      "use_cases": ["governance_readiness_assessment", "platform_audit", "pre_execution_check", "compound_risk_analysis"],
+      "mcp_servers_used": ["job-management", "inventory-management", "configuration", "security-compliance", "system-monitoring", "user-management"],
+      "red_hat_sources": 8,
+      "skills_that_read": ["governance-readiness-assessor"]
+    },
+    {
+      "path": "aap/execution-governance.md",
+      "title": "Execution Governance",
+      "category": "aap",
+      "token_estimate": 2500,
+      "semantic_keywords": [
+        "execute on production",
+        "check mode dry run",
+        "inventory risk classification",
+        "secret scanning extra_vars",
+        "rollback failed job",
+        "phased rollout",
+        "job template launch",
+        "diff mode",
+        "execution safety",
+        "production governance",
+        "job history analysis",
+        "template launch configuration",
+        "notification bindings",
+        "workflow coverage check",
+        "module analysis",
+        "adaptive risk elevation"
+      ],
+      "use_cases": ["governed_execution", "risk_analysis", "check_mode_execution", "rollback", "pre_execution_context"],
+      "mcp_servers_used": ["job-management", "inventory-management"],
+      "red_hat_sources": 5,
+      "skills_that_read": ["execution-risk-analyzer", "governed-job-launcher"]
+    },
+    {
+      "path": "aap/job-troubleshooting.md",
+      "title": "Job Troubleshooting",
+      "category": "aap",
+      "token_estimate": 2000,
+      "semantic_keywords": [
+        "job failed",
+        "why did the job fail",
+        "analyze failure",
+        "job events",
+        "host unreachable",
+        "module failure",
+        "error analysis",
+        "root cause",
+        "failure correlation"
+      ],
+      "use_cases": ["job_failure_analysis", "forensic_troubleshooting", "host_correlation"],
+      "mcp_servers_used": ["job-management", "inventory-management"],
+      "red_hat_sources": 3,
+      "skills_that_read": ["job-failure-analyzer", "host-fact-inspector"]
+    },
+    {
+      "path": "references/error-classification.md",
+      "title": "Error Classification Taxonomy",
+      "category": "references",
+      "token_estimate": 1500,
+      "semantic_keywords": [
+        "error classification",
+        "platform vs code error",
+        "resolution path",
+        "error taxonomy",
+        "failure type determination",
+        "troubleshooting decision tree"
+      ],
+      "use_cases": ["error_classification", "resolution_path_determination"],
+      "mcp_servers_used": [],
+      "red_hat_sources": 3,
+      "skills_that_read": ["resolution-advisor"]
+    }
+  ]
+}
@@ -0,0 +1,73 @@
+{
+  "version": "2.0",
+  "last_updated": "2026-02-26",
+  "workflows": {
+    "governance_assessment": {
+      "description": "Assess AAP platform governance readiness across 7 domains",
+      "trigger_phrases": [
+        "assess governance readiness",
+        "is my AAP ready for production",
+        "audit platform configuration",
+        "check governance",
+        "what should I fix before executing jobs"
+      ],
+      "documents": [
+        {
+          "path": "aap/governance-readiness.md",
+          "role": "primary",
+          "reason": "7-domain assessment framework with Red Hat citations"
+        }
+      ],
+      "agent": "governance-assessor",
+      "skills": ["aap-mcp-validator", "governance-readiness-assessor", "execution-summary"]
+    },
+    "governed_execution": {
+      "description": "Execute with risk analysis, check mode, and governance controls",
+      "trigger_phrases": [
+        "execute on production",
+        "push to prod",
+        "launch job template",
+        "execute security patch",
+        "release to production"
+      ],
+      "documents": [
+        {
+          "path": "aap/execution-governance.md",
+          "role": "primary",
+          "reason": "Risk classification, check mode, rollback, phased rollout"
+        },
+        {
+          "path": "aap/governance-readiness.md",
+          "role": "optional",
+          "reason": "Optional pre-execution readiness check"
+        }
+      ],
+      "agent": "governance-executor",
+      "skills": ["aap-mcp-validator", "execution-risk-analyzer", "governed-job-launcher", "execution-summary"]
+    },
+    "forensic_troubleshooting": {
+      "description": "Analyze failed jobs with event extraction, host correlation, and resolution advisory",
+      "trigger_phrases": [
+        "job failed",
+        "why did the execution fail",
+        "analyze the failure",
+        "what went wrong",
+        "root cause analysis"
+      ],
+      "documents": [
+        {
+          "path": "aap/job-troubleshooting.md",
+          "role": "primary",
+          "reason": "Event parsing, failure patterns, host correlation"
+        },
+        {
+          "path": "references/error-classification.md",
+          "role": "secondary",
+          "reason": "Error taxonomy and resolution path mapping"
+        }
+      ],
+      "agent": "forensic-troubleshooter",
+      "skills": ["aap-mcp-validator", "job-failure-analyzer", "host-fact-inspector", "resolution-advisor", "execution-summary"]
+    }
+  }
+}
@@ -0,0 +1,46 @@
+# Documentation Index
+
+Navigation guide for the rh-automation knowledge base. These documents are read by skills at runtime to provide Red Hat documentation-backed intelligence.
+
+## How Documents Are Used
+
+```
+User Request → Agent → Skill reads document → Skill queries MCP tools → Skill interprets with document knowledge → Output with Red Hat citations
+```
+
+## Document Map
+
+### AAP Category (`docs/aap/`)
+
+Platform governance, execution, and troubleshooting references for Ansible Automation Platform.
+
+| Document | Purpose | Skills That Read It | Red Hat Sources |
+|----------|---------|-------------------|----------------|
+| [governance-readiness.md](aap/governance-readiness.md) | 7-domain platform governance assessment | `governance-readiness-assessor` | 8 sources (Security Best Practices, Workflows, Notifications, RBAC, Instance Groups, Activity Stream, EE Guide, Hardening Guide) |
+| [execution-governance.md](aap/execution-governance.md) | Risk classification, check mode, rollback, phased rollout | `execution-risk-analyzer`, `governed-job-launcher` | 5 sources (Job Templates, Security Best Practices, Workflows, Check Mode, Controller Best Practices) |
+| [job-troubleshooting.md](aap/job-troubleshooting.md) | Event parsing, host correlation, failure patterns | `job-failure-analyzer`, `host-fact-inspector` | 3 sources (Troubleshooting Guide, Job Events, Administration Guide) |
+
+### References Category (`docs/references/`)
+
+Cross-cutting reference material used across multiple use cases.
+
+| Document | Purpose | Skills That Read It | Red Hat Sources |
+|----------|---------|-------------------|----------------|
+| [error-classification.md](references/error-classification.md) | Error taxonomy, classification trees, resolution paths | `resolution-advisor` | 3 sources (Troubleshooting Guide, Ansible Module docs, Administration Guide) |
+
+## Task-to-Document Mapping
+
+| User Task | Primary Document | Secondary Document |
+|-----------|-----------------|-------------------|
+| "Assess governance readiness" | governance-readiness.md | -- |
+| "Execute on production" | execution-governance.md | governance-readiness.md (optional pre-check) |
+| "Analyze failed job" | job-troubleshooting.md | error-classification.md |
+| "How to fix this error?" | error-classification.md | job-troubleshooting.md |
+
+## Semantic Indexing
+
+The `.ai-index/` directory contains pre-computed indexes for efficient document discovery:
+
+- `semantic-index.json` -- Document metadata with semantic keywords
+- `task-to-docs-mapping.json` -- Pre-computed document sets for common workflows
+- `cross-reference-graph.json` -- Document relationship graph