catalog-documentation-creator

这段内容是审核时保存的快照。外部来源才是完整且最新的版本。

---
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