Structuring with Nested Groups

How to use containers to organize diagrams into sub-state machines: systems within systems, agents within agents.

Containers are bpmn:subProcess elements that hold other elements. They are the core structural tool in a .dai diagram because nesting is how a diagram says this contains that: a system contains services, an agent contains its tools and rules, a release contains its features. Containers nest freely at any depth, so a diagram can be a tree of arbitrary shape.

Making a container

There is no separate “group” to place. Any element becomes a container when you drop other elements onto it:

• Drop elements onto a plain Task and it becomes an untyped group — pure structure.
• Drop elements onto a typed element — an Agent, a System, an Epic, a VPC — and it becomes a typed container whose type says what the region means.
• Drag the last child out and it turns back into an ordinary element. Its type and values never change either way.

Markdown notes are the one exception: they never take children.

Some types are placed as containers from the start because that’s how they’re almost always used: Agent, MCP Server, Session, Initiative, Release, Roadmap, Environment, System, and most cloud account, region, and network types.

Why nesting beats sprawling

A flat diagram forces every element into one visual and semantic plane. Nesting lets each region of the diagram carry its own meaning:

• A Rule inside a container governs that container. Scope rules and context by placement rather than by restating their reach in prose.
• A container is a named abstraction. “Payments” as a container of six elements keeps the top-level diagram legible; readers — humans and models — can stop at the boundary until they need to go in.
• Connections can cross container boundaries, so containment and flow are orthogonal: sub-state machines inside a sub-state machine, with connections between them, is the native shape of a real system.

Typed containers

A typed container is a statement about everything inside it:

Agents nested inside agents — a Pipeline Agent containing a Researcher and a Writer, connected by a sequence flow — is how .dai expresses sub-agent architectures. The multi-agent research pipeline example shows the full shape.

Working with containers

• A container keeps its size. Content that extends past its border is clipped, not used to grow the container. Resize it with its handles, or use the Space tool (S) to open up room — containers that straddle the line grow with it.
• Tidy with Clean up layout. Select a container and choose Clean up layout from its action menu or the Properties panel header: its children are lined up on an even grid and the container is resized to fit them.
• Move things in and out by dragging. Drop an element on a container to put it inside; drag it out onto the canvas to take it out.
• Use the Outline panel to navigate deep trees. Folders in the Outline mirror your nesting and can be collapsed; click a row to jump to any element without scrolling (see the Editor Tour).

Practical patterns

• One container per coherent thing. The “System” and “Content” containers in an app build — each with its own rules, tests, and dependencies — read cleaner than one giant diagram.
• Name containers like the subsystem they are. “Checkout”, “Grounding”, “v2 scope”: the name is what appears in the Outline tree and what the AI reads as the region’s intent.
• Prefer a typed container when one fits. A System or an Agent tells the AI more than an untyped group with the same name.
• Add a description. A container’s description (dai:notes) frames everything inside it — one sentence about what this region is for.

The XML form, container attributes, and how typed containers serialize are documented in Flow & Structure Elements.