Catalog Documentation CreatorSAFE

An Aspire reference architecture for cloud-native microservices and agentic AI with MCP, A2A & AG-UI

The instruction file, verbatim from the audited commit — this is the text the model reads, and the surface the audit's instruction layer examines. Quoted here so you can judge it without cloning anything.

---
name: catalog-documentation-creator
description: Generates EventCatalog documentation files (systems, services, agents, events, commands, queries, domains, flows, channels, containers, ADRs, data products, entities, diagrams) with correct frontmatter, folder structure, and best practices. Use when user asks to "document a system", "document a service", "document an agent", "document an AI agent", "create EventCatalog files", "add an event to the catalog", "document my architecture", "generate catalog documentation", "create documentation for my microservice", "document a database", "create an ADR", "document a data product", or "document an entity".
license: MIT
metadata:
  author: eventcatalog
  version: "1.0.0"
---

# EventCatalog Documentation Creator

Generate properly formatted EventCatalog documentation files following project conventions and best practices.

## Instructions

### Step 1: Locate or Create the User's Catalog

Before generating any files, ask the user: **"Do you already have an EventCatalog project, or would you like to create a new one?"**

**If they already have a catalog:**

- Ask: **"Where is your EventCatalog project?"** — It could be:
  - A repo they've cloned locally (e.g., `~/projects/my-catalog/`)
  - A folder on their machine
  - A monorepo with the catalog in a subdirectory
- Verify it looks like an EventCatalog project by checking for an `eventcatalog.config.js` file or known directories (`systems/`, `services/`, `agents/`, `events/`, `domains/`, `adrs/`, `data-products/`, `entities/`, etc.)
- Read the existing structure to understand whether they use **nested** (domains/services/agents/events) or **flat** (top-level services/, agents/, events/) organization

**If they don't have a catalog yet:**

- Ask where they'd like to create it (default: current directory)
- Run the following command to scaffold a new empty catalog:
  ```bash
  npx @eventcatalog/create-eventcatalog@latest my-catalog --empty
  ```
  (Replace `my-catalog` with the user's preferred name)
- This creates a ready-to-use EventCatalog project with the correct structure
- All generated documentation files go inside this new catalog directory

CRITICAL: All generated files must be written to the user's catalog directory, not just displayed. Always ask where they want resources documented — never assume.

### Step 2: Understand What the User Wants to Document

Ask the user what they want to document. Common scenarios:

- A single service or agent and its messages
- A system that groups services, containers, flows, entities, actors, and related systems
- An event, command, or query
- A full domain with nested services
- A business flow across services and agents
- A channel (Kafka topic, RabbitMQ queue, etc.)
- A container (database, cache, queue)
- An architecture decision record (ADR)
- A data product for analytics, reporting, ML features, or operational data outputs
- A domain entity or aggregate
- A reusable diagram resource

Gather this information before generating:

- Resource name and purpose
- Version (default to `0.0.1` for new resources)
- System boundary, scope (`internal` or `external`), actors, relationships, and contained resources when documenting systems
- Message relationships (what it sends/receives)
- Channel routing (what channels messages flow through)
- Containers (what databases/caches the service reads from or writes to)
- ADR links (what resources a decision applies to, and whether it supersedes/amends another ADR)
- Data product lineage (inputs, outputs, contracts, freshness/SLA expectations)
- Entities and relationships (identifier, properties, references, aggregate root)
- Diagram notation (Mermaid, PlantUML, or other supported fenced diagram formats)
- Agent model/provider and tools when documenting agents
- Schema format if applicable (JSON Schema, Avro, Protobuf)

If the user points you at a codebase (not the catalog), analyze it to extract services, agents, messages, schemas, and relationships — then generate the corresponding catalog documentation.

### Step 3: Check the Existing Catalog

If the catalog directory already has resources, read the existing files to understand:

- Naming conventions (PascalCase IDs? kebab-case?)
- Folder structure (nested under domains or flat?)
- Which owners/teams are already defined
- Badge styles and patterns used
- Schema formats in use (JSON Schema, Avro, etc.)

Match new documentation to these existing conventions.

If the user has the EventCatalog MCP server connected:

1. Use `getResources` to see what already exists in the catalog
2. Use `getResource` to check conventions used in existing entries (naming patterns, owner formats, badge styles)
3. Use `findResourcesByOwner` to suggest consistent ownership
4. Use `getSchemaForResource` to match existing schema formats

This ensures new documentation is consistent with what's already in the catalog.

### Step 4: Generate the Documentation

Generate files following the resource-specific references. Consult the appropriate reference file for the resource type:

- `references/services.md` — Services with sends/receives, channel routing, containers
- `references/systems.md` — Systems with scope, services, containers, flows, entities, actors, and system relationships
- `references/agents.md` — Agents with model metadata, tools, sends/receives, containers, and flows
- `references/events.md` — Events with schemas, payload examples, producer/consumer code
- `references/commands.md` — Commands with REST operations and schemas
- `references/queries.md` — Queries with REST operations and response schemas
- `references/domains.md` — Domains with subdomains, services, and business context
- `references/flows.md` — Business flows with steps, branching, and external systems
- `references/channels.md` — Channels with routing, protocols, and parameters
- `references/containers.md` — Containers (databases, caches, queues) with data classification
- `references/adrs.md` — Architecture decisi

SAFEgrade B · trust 89/100 Nothing in the source contradicts what it says it does. Grade A is reserved for packages that have also passed the behavioural sandbox.

What the source does

Filesystem

none-observed

Network

none-observed

Shell

none-observed

Dependencies

pinned

Secrets in source

none-found

Findings (0)

No findings outside the package's declared scope.

Gates applied: no_behavioural_pass.