chore: sync agent skills from team-devtools

Source: ansible/team-devtools@b588ea2

Author: ansibuddy

.agents/skills/architecture-diagram/SKILL.md

@@ -0,0 +1,287 @@
+---
+name: architecture-diagram
+description: >
+  Generate professional C4 architecture diagrams of the Ansible Dev Tools
+  ecosystem by cloning and introspecting actual repos. Produces PNG output
+  for the AAP Miro board. Use when the user says 'architecture diagram',
+  'C4 diagram', 'generate diagram', 'update architecture', or references
+  AAP-77196.
+argument-hint: "[level=context|container|component|all]"
+user-invocable: true
+type: workflow
+mandatory: false
+triggers:
+  - "architecture diagram"
+  - "C4 diagram"
+  - "generate diagram"
+  - "update architecture"
+  - "AAP-77196"
+metadata:
+  author: Ansible DevTools Team
+  version: 1.0.0
+---
+
+# Architecture Diagram Generator
+
+Generate professional C4 architecture diagrams of the Ansible Dev Tools
+ecosystem. Diagrams are built from **actual repo introspection** — not
+documentation — to ensure accuracy.
+
+## Prerequisites
+
+Before running, ensure these are available:
+
+```bash
+python3 --version   # >= 3.10
+java -version       # or: plantuml --version
+git --version
+pip show c4-diagrams  # >= 0.5.2, install with: pip install c4-diagrams
+```
+
+If `c4-diagrams` is not installed:
+
+```bash
+pip install c4-diagrams
+```
+
+PlantUML rendering requires Java. If Java is not present:
+
+```bash
+# Fedora / RHEL
+sudo dnf install java-17-openjdk
+# macOS
+brew install plantuml
+```
+
+## Workflow
+
+### Step 1: Clone and crawl repos
+
+Clone all ADT ecosystem repos fresh into `/tmp` and introspect their
+actual dependency files. This is the foundation — never skip it.
+
+```bash
+python3 scripts/crawl_repos.py --clone-dir /tmp/adt-c4-repos --output .architecture-diagrams/dependencies.json
+```
+
+This clones 19 repos (shallow, default branch) and reads:
+- `pyproject.toml` for Python inter-project dependencies
+- `package.json` for TypeScript/Node dependencies
+- `Containerfile` / `Dockerfile` for container image builds
+- `.github/workflows/*.yml` for container publishing and reusable workflows
+- Source code (vscode-ansible) for Python CLI tool spawns, language server, MCP server
+
+Output: `.architecture-diagrams/dependencies.json`
+
+### Step 2: Review crawl results
+
+Read `.architecture-diagrams/dependencies.json` and validate:
+
+1. Are all expected inter-project dependencies captured?
+2. Were container builds discovered in GitHub Actions workflows?
+3. Did the vscode-ansible crawl find the language server and MCP server?
+4. Did the abbenay crawl discover all sub-packages?
+5. Did the APME crawl find the Abbenay dependency?
+
+If the crawler missed a known relationship, the agent should note it for
+manual addition to the generated diagram code before rendering.
+
+### Step 3: Generate diagram code
+
+```bash
+python3 scripts/generate_diagram.py --input .architecture-diagrams/dependencies.json --output-dir .architecture-diagrams --level all
+```
+
+Levels:
+- `context` — L1 System Context (personas, systems, external deps)
+- `container` — L2 Container (individual projects with dependency arrows)
+- `component` — L3 Component (per-repo deep dive)
+- `all` — generate all levels
+
+For a single repo's component diagram:
+
+```bash
+python3 scripts/generate_diagram.py --level component --component-repo ansible/vscode-ansible
+```
+
+### Step 4: Review and refine diagram code
+
+Before rendering, the agent SHOULD review the generated `.py` files in
+`.architecture-diagrams/` and make refinements:
+
+- Adjust layout by changing `Rel` to `RelDown`, `RelRight`, etc.
+- Add missing relationships the crawler could not infer
+- Improve labels and descriptions
+- Ensure the provenance footer is present
+
+### Step 5: Render to PNG
+
+```bash
+python3 scripts/render.py --input-dir .architecture-diagrams --renderer plantuml
+```
+
+Output: PNG files in `.architecture-diagrams/`
+
+### Step 6: Present results
+
+Show the user the PNG file paths. The user can then paste them into the
+Miro board or include them in documentation.
+
+---
+
+## Repos Crawled
+
+### ADT Primary Projects (10 repos)
+
+| Repo | Language | Notes |
+|------|----------|-------|
+| `ansible/ansible-dev-tools` | Python | Meta-package + container image builds |
+| `ansible/ansible-lint` | Python | Linter |
+| `ansible/ansible-compat` | Python | Shared compatibility library |
+| `ansible/ansible-navigator` | Python | TUI for execution environments |
+| `ansible/ansible-dev-environment` | Python | Virtual env manager (ade) |
+| `ansible/ansible-creator` | Python | Scaffolding tool |
+| `ansible/ansible-sign` | Python | Content signing |
+| `ansible/molecule` | Python | Functional test runner |
+| `ansible/vscode-ansible` | TypeScript | VS Code extension (see special handling below) |
+| `ansible/team-devtools` | Mixed | Meta-repo (shared CI, skills, config) |
+
+### ADT Experimental / Testing / Community (5 repos)
+
+| Repo | Notes |
+|------|-------|
+| `ansible/pytest-ansible` | Pytest plugin |
+| `ansible/tox-ansible` | Tox plugin |
+| `ansible/actions` | Shared GitHub Actions |
+| `ansible/ansible-content-actions` | Marketplace actions |
+| `ansible/mkdocs-ansible` | MkDocs theme |
+
+### AAP Downstream Container Repos (2 repos)
+
+| Repo | Notes |
+|------|-------|
+| `ansible-automation-platform/ansible-devtools-container` | Downstream devtools container — packages ADT web server |
+| `ansible-automation-platform/ansible-devspaces-container` | Downstream devspaces container |
+
+### Abbenay — AI Daemon (1 repo)
+
+| Repo | Notes |
+|------|-------|
+| `redhat-developer/abbenay` | Unified AI daemon and library for LLM providers |
+
+Abbenay is a TypeScript monorepo producing:
+- `@abbenay/core` — LLM engine abstraction library
+- `@abbenay/daemon` — gRPC server, web dashboard, CLI, VS Code backchannel
+- VS Code extension (in `packages/vscode/`)
+- Python gRPC client (in `packages/python/`)
+- Containerized deployment (root `Containerfile`)
+
+**Key relationship:** APME depends on Abbenay for AI-assisted remediation.
+
+### AAP Portal — External Consumer (not crawled)
+
+The AAP Portal is a custom Backstage instance for AAP self-service. It is
+NOT a devtools-owned project and is not included in the repo manifest. It
+appears in diagrams as an external system (`SystemExt`/`ContainerExt`) with
+two key relationships:
+- Consumes the ADT web server packaged in the downstream devtools container
+- Consumes the ADT Python packages' REST API
+
+### APME — Adjacent Consumer (1 repo)
+
+| Repo | Notes |
+|------|-------|
+| `ansible/apme` | Multi-validator static analysis platform for Ansible content |
+
+APME is NOT owned by DevTools but is a significant consumer:
+- Depends on Abbenay for AI-assisted remediation (Tier 2 escalation)
+- Likely depends on ansible-lint (confirm from `pyproject.toml`)
+- Components: CLI, engine, validators, daemon, gateway, Galaxy Proxy, React frontend
+- Has own containers, Helm chart, bootc VM deployment
+
+---
+
+## Special Crawling Instructions
+
+### vscode-ansible
+
+The VS Code extension is the most architecturally complex single repo.
+The crawler MUST discover:
+
+1. **Python CLI tool dependencies** — the extension spawns: `ansible-lint`,
+   `ansible-navigator`, `ansible-creator`, `ansible-dev-environment`, and
+   potentially others. The crawler searches source code for process spawn
+   calls, command references, and configuration settings.
+
+2. **Language Server** — the extension contains an integrated Ansible Language
+   Server (previously `ansible/ansible-language-server`, now merged). Find
+   `LanguageClient`, `createConnection`, or `LanguageServer` references.
+
+3. **MCP Server** (`packages/ansible-mcp-server/`) — the extension ships
+   a bundled MCP server (`@ansible/ansible-mcp-server`) that wraps ADT CLI
+   tools for AI agent consumption. The crawler inspects its `src/tools/`
+   directory for spawned Python CLI tools (e.g., `ansible-lint`,
+   `ansible-navigator`, `ansible-creator`, `ade`, `ansible-builder`).
+
+4. **Package dependencies** — `package.json` deps that map to other ADT projects.
+
+### Abbenay
+
+Crawl `packages/` monorepo structure for sub-packages. Each directory
+under `packages/` with a `package.json` is a separate component. Also
+discover the root `Containerfile` and `proto/` gRPC definitions.
+
+Note: Abbenay does NOT consume the downstream devtools container. That
+relationship belongs to the AAP Portal (Backstage), which is a separate
+external system.
+
+### APME
+
+Crawl `pyproject.toml` for Python deps (especially abbenay, ansible-lint).
+Discover components from the project structure:
+- `src/apme_engine/` — CLI, engine, validators, daemon, remediation
+- `src/apme_gateway/` — FastAPI API gateway
+- `src/galaxy_proxy/` — Galaxy PEP 503 proxy
+- `frontend/` — React operator UI
+- `containers/` — container topology
+- `proto/` — gRPC service definitions
+
+---
+
+## Diagram Provenance
+
+Every generated diagram includes a footer/subtitle:
+
+> Generated by architecture-diagram skill —
+> https://github.com/ansible/team-devtools/tree/main/.agents/skills/architecture-diagram
+
+This tells anyone viewing the diagram on the Miro board where to find
+the source for updates or regeneration.
+
+---
+
+## Output Directory
+
+All output goes to `.architecture-diagrams/` in the workspace root:
+
+```text
+.architecture-diagrams/
+├── dependencies.json           # Crawl results (intermediate)
+├── l1_system_context.py        # L1 diagram source
+├── l1_system_context.png       # L1 rendered
+├── l2_container.py             # L2 diagram source
+├── l2_container.png            # L2 rendered
+├── l3_component_*.py           # L3 diagram sources (per-repo)
+└── l3_component_*.png          # L3 rendered
+```
+
+Add `.architecture-diagrams/` to `.gitignore` if not already present.
+
+## Scripts
+
+| File | Purpose |
+|------|---------|
+| `scripts/arch_models.py` | Data classes, repo manifest, package name mappings |
+| `scripts/crawl_repos.py` | Clone + introspect repos, output `dependencies.json` |
+| `scripts/generate_diagram.py` | Consume crawl data, produce C4 diagram `.py` files |
+| `scripts/render.py` | Render diagram `.py` files to PNG via `c4 export` |

.agents/skills/architecture-diagram/examples/l1_system_context.png

@@ -0,0 +1,97 @@
+# C4 Model Guide for ADT Architecture Diagrams
+
+## C4 Levels
+
+The C4 model defines four levels of abstraction for software architecture:
+
+### Level 1 — System Context
+
+Shows the system under consideration and its relationships with users
+and other systems. Use this to communicate with non-technical stakeholders.
+
+**For ADT:** The entire Ansible Dev Tools ecosystem as a single system,
+with the Content Author persona, Abbenay (AI daemon/library),
+APME (adjacent consumer), and external systems (PyPI, Galaxy, GitHub,
+LLM providers).
+
+### Level 2 — Container
+
+Zooms into the system boundary to show the individual deployable units
+(applications, services, data stores). Each "container" is separately
+deployable.
+
+**For ADT:** Each repo becomes a container. Group them into boundaries:
+
+| Boundary | Contents |
+|----------|----------|
+| ADT Core Tools | ansible-dev-tools, ansible-lint, ansible-compat, ansible-navigator, ansible-dev-environment, ansible-creator, ansible-sign, molecule |
+| ADT Testing & Automation | pytest-ansible, tox-ansible, actions, ansible-content-actions |
+| ADT Extensions | vscode-ansible (with language server + MCP sub-components) |
+| Community | mkdocs-ansible |
+| Downstream Containers | ansible-devtools-container, ansible-devspaces-container |
+| Abbenay (AI Daemon) | @abbenay/core, @abbenay/daemon, VS Code ext, Python client |
+| APME (Adjacent) | engine, validators, gateway, frontend, Galaxy Proxy |
+
+### Level 3 — Component
+
+Zooms into a single container to show its internal components. Use this
+for repos with rich internal architecture.
+
+**Best candidates for L3 in ADT:**
+
+- **vscode-ansible** — language server, MCP server, Python tool
+  integrations, extension host, webview panels
+- **abbenay** — core library, daemon layer, gRPC server, web dashboard,
+  VS Code extension, Python client, proto stubs
+- **APME** — engine (parse/annotate/fan-out), validators (native, OPA,
+  Ansible, Gitleaks, collection health, dep audit), daemon, remediation
+  engine, API gateway, Galaxy Proxy, React frontend
+
+### Level 4 — Code
+
+Class/function level detail. Rarely useful for architecture boards.
+Not generated by this skill.
+
+## Relationship Types
+
+| Type | Label Convention | Example |
+|------|-----------------|---------|
+| Direct dependency | "depends on {package}" | ansible-lint depends on ansible-compat |
+| CLI spawning | "spawns {tool}" | vscode-ansible spawns ansible-lint |
+| Container packaging | "packages into image" | ADT packaged into devtools-container |
+| API consumption | "consumes {API}" | AAP Portal consumes ADT web server |
+| Build artifact | "builds" | ansible-dev-tools builds community-ansible-dev-tools-image |
+| Test dependency | "tests with" | molecule tests with community.molecule |
+| Workflow reuse | "uses reusable workflow" | ansible-lint uses ansible/team-devtools workflows |
+| AI escalation | "AI remediation via" | APME escalates to Abbenay |
+
+## Technology Annotations
+
+Every container in the L2 diagram gets a technology annotation:
+
+| Technology | Used By |
+|-----------|---------|
+| Python | Most ADT tools |
+| TypeScript | vscode-ansible, abbenay |
+| TypeScript (LSP) | Ansible Language Server |
+| TypeScript (MCP) | MCP Server |
+| Python (gRPC) | APME engine, abbenay Python client |
+| Python (FastAPI) | APME Gateway |
+| TypeScript (React) | APME Frontend |
+| Container Image | Downstream containers |
+| Ansible Collection | community.molecule |
+
+## External Systems
+
+Shown as `SystemExt` (L1) or `ContainerExt` (L2) — visually distinct:
+
+- **ansible-builder** — not owned by DevTools, but ADT and ade depend on it
+- **ansible-runner** — Navigator dependency
+- **ansible-core** — underlying engine (ansible-playbook, ansible-galaxy, etc.)
+- **community.molecule** — molecule and compat test dependency
+- **vscode-yaml** — vscode-ansible extension dependency
+- **AAP Portal** — custom Backstage instance for AAP self-service; consumes ADT web server and REST API
+- **LLM Provider APIs** — abbenay talks to OpenAI, Anthropic, Gemini, Ollama, etc.
+- **PyPI** — where Python packages are published
+- **Ansible Galaxy** — where collections are published
+- **GitHub** — source code hosting and CI/CD