Authoring Guide
This guide is the hands-on companion to the architecture chapters and the language reference. Where the architecture explains why Aggrega is shaped the way it is and the reference specifies what each field means, this guide teaches how to sit down and author — which entity you reach for, in which order, and how the CLI and an AI assistant help you get a correct file with the least friction.
The guide is written for two audiences at once: a person authoring by hand in an editor, and an AI assistant authoring on a person’s behalf through the Model Context Protocol server. Both follow the same loop and read the same reference surfaces, so the pages below serve both.
Read in this order
- Authoring Aggrega files — the end-to-end authoring loop: pick your role, learn the shape, scaffold, fill, validate, build. Start here.
- Personas — the four collaborating authoring roles (developer, architect, operations, operator) and the guidance-not-enforcement framing behind them.
- Entities by Role — every entity kind mapped to the role that typically owns it, so you know which file each concern belongs in.
- Install — install the
aggregabinary, with the commands first; its connect section points to Connect the MCP server. - Use Aggrega in Visual Studio Code — the Aggrega extension for Visual Studio Code: what it needs, the welcome page, its panels and the topology graph, and every setting and command.
Import starts from a project you already have in another format and drafts these files from it, for you to review and build.
Learn Aggrega places this guide in a path through the whole documentation.
Working with an AI assistant
- Set up Aggrega with your AI assistant — one prompt to paste into an assistant that can run commands, so it installs Aggrega, adds the Aggrega skill and connects itself to the server.
- Connect the MCP server — the server entry client by client, where each client keeps it, a server reached over HTTPS, and how to check the connection.
- The Aggrega skill — the instructions an assistant loads for Aggrega: installing them and keeping them current.
- What your assistant can do with Aggrega — what the connected server lets an assistant read, check, build and publish.
How the assistant surfaces relate to this guide
The aggrega mcp server exposes this guide, the language reference, and the JSON Schemas as resources an assistant reads before it writes YAML, plus tools that scaffold and validate entities. The assistant’s built-in authoring prompts point back at these pages rather than restating them, so this guide is the single prose home for the authoring method. See Authoring Aggrega files for the loop and Connect the MCP server for the connection.