---
name: analyze-ansible-role-project
description: "Analyze a source application project (monorepo or single service, any runtime: .NET, Go, Python, Node) and produce a Role Design Spec: components, images/ports or install details, env config maps, infra dependencies, migration jobs, and deployment requirements. Use this before write-ansible-role when deploying a new product or service with Ansible."
license: MIT
handoffs:
  - label: "Write the Ansible role"
    agent: "write-ansible-role"
    prompt: "Run the write-ansible-role skill against the Role Design Spec at {spec_path} and generate the role."
  - label: "Analyze an infra component"
    agent: "analyze-ansible-component"
    prompt: "Run the analyze-ansible-component skill for each infrastructure dependency listed in the spec so the writer has exact image/port/healthcheck details."
---

# What I do

I analyze a source project (a monorepo or a single service) that needs to be
deployed on-prem / in a customer environment, and I produce a structured
**Role Design Spec** — the single source of truth that feeds
`write-ansible-role`. I extract everything a deployment role must know from
the project's own artifacts instead of guessing.

The project may be written in **any runtime** (.NET, Go, Python, Node, Java,
...), deployed as Docker Compose services (`app-deploy`) or as a standalone
service (`infra-service`).

# When to use me

- You need to write an Ansible role for a new application/infrastructure product.
- You have the source of the product (Dockerfiles, docker-compose, configs, CI).
- A `Role Design Spec` does not exist yet for the project.

If you already have a spec, skip me and go straight to `write-ansible-role`.

# User Input

> You **MUST** consider the user input before proceeding (if not empty).

`$ARGUMENTS` may contain any of:

- Path to the project root (monorepo root or service root). If not given, **ask**.
- Optional: the target deployment context (single host, air-gap, registry URL,
  nginx in-container vs host). If unknown, note assumptions in the spec.

# Operating Constraints

- Report only facts with real file references — no guessing.
- Do not invent image tags, ports, config keys, or install URLs; mark unknowns
  as **Open Questions** in the spec.
- The spec must be enough for the writer to generate a complete role **without**
  re-reading the project.
- Stay within the project; do not modify any source file.

# Execution Steps

## 1. Inventory the project

- `README.md` / `docs/` — product overview, services, ports, configuration.
- Root `docker-compose*.yml` — the dev stack: every service, image, ports,
  volumes, healthchecks, init containers. This reveals infra dependencies and
  the intended "shape" of the deployment.
- Dockerfiles — image build inputs, `EXPOSE` ports, `ENTRYPOINT`/`CMD`, extra
  packages (e.g. `libldap` → LDAP), and the runtime of each component.
- CI/CD: `.gitlab-ci.yml`, `.github/workflows/*`, `azure-pipelines.yml` — how
  images are named and tagged (base image path, `RELEASE_TAG` usage).
- Source layout: one component per deployable unit (backend, worker, web,
  rtc, cli, ...).

## 2. Map every deployable component

For each component produce:
- Component name and Docker build context path.
- Image name suffix (e.g. `.../web`, `.../backend`, `.../worker`) and tag source.
- Exposed ports (from `EXPOSE` and reverse-proxy rules).
- Healthcheck endpoint/path if any.
- Env/config inputs (see step 4).

## 3. Map infrastructure dependencies

Identify which backing services the product needs and whether they are
required or optional. Typical candidates:

- **Databases**: PostgreSQL, MongoDB, ClickHouse, MySQL, pgvector.
- **Queues / streaming**: Kafka, RabbitMQ, Redis / valkey / KeyDB.
- **Object storage**: MinIO / S3.
- **Logging**: VictoriaLogs + Vector, ELK.
- **Messaging**: Kafka, etc.
- **Auth**: Active Directory / LDAP, JWT, OIDC.
- **AI/ML**: OpenAI-compatible endpoints, embedding models.
- **Kubernetes**: k3s / kube clusters.

For each: default-enabled or feature-flag?, image:tag or version, port, whether
the product creates it itself (dev compose) or expects an external one.

## 4. Build the env config map

This is the most critical part — the role's env templates must match the app's
configuration keys exactly. Detect the runtime and read its config discovery:

- **.NET API/Worker**: read `appsettings*.json` in each component. List every
  config section and key. Note which are required vs optional and which are
  feature-flag gated. Env-file keys use the `{{ section }}__{{ key }}` form.
- **Go**: read `config*.yaml`/`.env`/`os.Getenv` usage. List keys as the app
  expects them (e.g. `DATABASE_URL`, `APP_PORT`).
- **Python**: read `settings.py`/`.env`/`config.py`/`django settings`. List
  keys (`SECRET_KEY`, `DATABASE_URL`, ...).
- **Node**: read `.env.sample`, `config/index.js`, `env.js`. List keys.
- **Client / frontend (Angular/etc.)**: read `src/assets/env.sample.js` /
  `env.js`. List the `${PLACEHOLDER}` variables consumed at runtime via
  `envsubst`.
- **Other runtimes**: their config files in the same spirit.

For each key record: name, config file/section it maps to, required vs
optional, feature-flag gating, example/default.

## 5. Identify deployment mechanics

- **Migration/one-shot jobs**: e.g. `dotnet App.dll --migrate`, `python
  manage.py migrate`, `./app migrate`. Note the exact CLI flags and which
  image/artifact they run on.
- **Init/bootstrap**: SQL init scripts, MinIO bucket creation, etc.
- **Nginx / reverse proxy**: does the web container embed nginx (ports
  80/443)? Is there a host-level nginx with certbot? Server name / TLS /
  self-signed?
- **License / keys**: any license keys, registration keys, admin bootstrap
  credentials the product requires.
- **Multi-instance**: does the product need a suffix mechanism to run several
  instances on one host?
- **Standalone service**: if the product IS a single native service (kafka,
  clickhouse, k3s, exporter), record its install model (binary tarball, OS
  package), version, user/group, dirs, systemd needs.

## 6. Write the Role Design Spec

Write the spec to `role-design-spec.md` in the project root (or the requested
target dir) using `templates/role-design-spec.md` in this skill folder, and
present a summary to the user. If anything is ambiguous, list it as an **Open
Question** in the spec instead of inventing values.

# Validation

- Every claim in the spec has a real file path reference.
- No invented image tags, ports, config keys, or install URLs — all unknowns
  are Open Questions.
- The spec covers: role metadata, components table, env config maps, infra
  deps, deployment mechanics, registry/image or install info, open questions.
- The spec is self-sufficient: a writer who reads only the spec (and
  conventions) can produce the full role.

# Output

A `role-design-spec.md` following the template in this folder, containing: role
metadata (name/prefix, runtime, role type), components table, env config maps,
infra deps table, deployment mechanics, registry/image or install info, open
questions. This is the input contract for `write-ansible-role`.

# Quality bar

- Every claim backed by a real file path.
- No invented image tags, ports, or config keys — mark unknowns as open questions.
- The spec must be enough for the writer to generate a complete role **without**
  re-reading the project.