# DAI Studio
> DAI Studio is a workflow authoring tool that produces `.dai` files — BPMN 2.0 XML extended with a custom `dai:` namespace. A `.dai` file is an abstract tree describing a process, system, or domain using semantically typed nodes. Author a workflow in DAI Studio, click **Copy to LLM**, then paste the XML into any LLM or AI agent. The AI reads the structured tree, understands the intent of every element, and executes or reasons over the workflow with full context. The format applies equally to AI workflows, software architecture, business strategy, product development, and any other domain that benefits from structured decomposition.
---
## DAI Studio
DAI Studio is a native desktop application for authoring `.dai` workflow diagrams. It runs on macOS, Windows, and Linux. Download at **https://dai.studio/#download**.
The authoring loop: open DAI Studio, draw a diagram by placing and connecting elements on the canvas, fill in the name and fields for each element using the properties panel, then click **Copy to LLM** in the toolbar. This copies the complete `.dai` XML to the clipboard. Paste it directly into any LLM or AI agent.
`.dai` files carry the `.dai` extension and are registered as a native file type. Double-clicking a `.dai` file opens it directly in DAI Studio. The format is also valid BPMN 2.0 XML, readable by any standard BPMN tooling.
---
## The .dai Format
A `.dai` file is a BPMN 2.0 XML document with a `dai:` namespace extension layered on top. The file is an **abstract tree**: `bpmn:SubProcess` elements nest freely and at any depth to express containment, scope, and hierarchy. There is no constraint on nesting depth — a group can contain other groups, which can contain steps, which can contain further groups.
### Namespaces
Every `.dai` file declares these six namespaces on the root `bpmn:definitions` element:
| Prefix | URI | Purpose |
|--------|-----|---------|
| `bpmn:` | `http://www.omg.org/spec/BPMN/20100524/MODEL` | BPMN 2.0 model |
| `bpmndi:` | `http://www.omg.org/spec/BPMN/20100524/DI` | BPMN diagram interchange (visual layout) |
| `dc:` | `http://www.omg.org/spec/DD/20100524/DC` | Diagram common |
| `di:` | `http://www.omg.org/spec/DD/20100524/DI` | Diagram interchange |
| `dai:` | `https://diagram.app/schema/dai/1.0` | DAI Studio extensions |
| `xsi:` | `http://www.w3.org/2001/XMLSchema-instance` | XML schema instance |
### Minimal skeleton
```xml
```
---
## Diagram Metadata
The `dai:workflowMeta` extension element sits inside `bpmn:extensionElements` on the root `bpmn:process`. It frames the entire diagram for the AI.
| Attribute | Purpose |
|-----------|---------|
| `description` | Plain-language explanation of what this diagram achieves. The AI reads this to orient its overall execution strategy. |
| `defaultModel` | The AI model to use by default (e.g. `gpt-4o`, `claude-3-5-sonnet-20241022`). |
| `targetLanguage` | Target programming language, if applicable (e.g. `TypeScript`, `Python`). |
| `targetFramework` | Target framework, if applicable (e.g. `React`, `FastAPI`). |
| `version` | Version string for the diagram (e.g. `1.0`). |
---
## Element Types
All typed elements are `bpmn:Task` nodes. The `dai:` namespace extends `bpmn:Task` with structured attributes placed directly on the element.
### Universal attributes
| Attribute | Purpose |
|-----------|---------|
| `stepType` | The semantic type of this task (see tables below). Omit or leave empty for a generic task. |
| `notes` | Primary content — instructions, descriptions, constraints, or any text the AI should process for this node. |
| `code` | Implementation code. Used by `tool`; included verbatim when the workflow is executed. |
---
### AI types
These types shape how the AI thinks and acts. They are the core primitives for building AI workflows.
| `stepType` | Name | Key attributes | Meaning |
|------------|------|----------------|---------|
| `context` | Context | `source`, `format`, `scope`, `content` | Background knowledge or grounding data that informs downstream steps. Does not produce output itself. `source` is where it comes from (manual/file/url/database/api/previous-step). `scope` is global (all steps) or local (connected steps only). `content` holds the actual grounding data. |
| `rule` | Rule | `scope`, `rulePriority`, `enforcement` | A constraint, policy, or business rule the AI must enforce. `enforcement` is hard (never violate), soft (prefer to follow), or best-effort. `rulePriority` is critical/high/medium/low. `scope` is global or local. |
| `skill` | Skill | `trigger`, `examples` | An autonomous capability the AI can invoke when it judges the context appropriate. Describes behaviour rather than implementation. `trigger` describes when to apply it; `examples` shows input/output pairs. |
| `tool` | Tool | `language`, `returns`, `code` | A callable function with a concrete implementation in the `code` attribute. `language` is python/javascript/typescript/shell/sql. `returns` describes the return value. Uses `dai:properties` for typed parameters (see below). |
| `prompt` | Prompt | `systemPrompt`, `userPrompt`, `outputFormat`, `temperature`, `defaultModel` | A reusable prompt template. `systemPrompt` sets the AI's role; `userPrompt` is the user turn (use `{{variable}}` for template variables). `outputFormat` is text/json/markdown/code/list/table. `temperature` is 0–1. |
---
### Business types
These types document strategy, governance, and analysis artefacts.
| `stepType` | Name | Key attributes | Meaning |
|------------|------|----------------|---------|
| `risk` | Risk | `probability`, `impact`, `mitigation`, `owner` | A potential threat with probability/impact ratings (low/medium/high/critical) and a mitigation strategy. |
| `decision-record` | Decision | `status`, `context`, `decision`, `consequences` | An Architecture Decision Record. `status` is proposed/accepted/deprecated/superseded. Documents the context, choice made, and trade-offs. |
| `kpi` | KPI | `target`, `unit`, `formula`, `frequency`, `owner` | A Key Performance Indicator with a numeric target, unit of measurement, and reporting frequency (daily/weekly/monthly/quarterly/annually). |
| `objective` | Objective | `status`, `timeframe`, `keyResults`, `owner` | A strategic goal or OKR. `keyResults` lists measurable outcomes; `timeframe` is q1/q2/q3/q4/annual. `status` is draft/active/achieved/missed. |
| `stakeholder` | Stakeholder | `interest`, `influence`, `engagementStrategy` | A person or organisation with interest/influence in the outcome. `interest` and `influence` are low/medium/high. |
| `requirement` | Requirement | `priority`, `status`, `source`, `acceptanceCriteria` | A business or functional requirement. `priority` uses MoSCoW (must/should/could/wont). `acceptanceCriteria` lists testable conditions. `status` is draft/agreed/implemented/verified/rejected. |
| `assumption` | Assumption | `status`, `basis`, `ifWrong`, `owner` | A documented assumption the project depends on. `status` is unvalidated/validated/invalidated. `ifWrong` captures the impact if incorrect. |
---
### Product types
These types document user needs, product structure, and discovery artefacts.
| `stepType` | Name | Key attributes | Meaning |
|------------|------|----------------|---------|
| `persona` | Persona | `role`, `age`, `goals`, `frustrations`, `behaviours`, `quote` | A research-based user archetype. Connect Persona elements to Stories, Features, and Journeys via sequence flows to link them. |
| `story` | Story | `persona`, `priority`, `status`, `acceptanceCriteria`, `storyPoints` | A user story. `persona` names the target user. `notes` holds the "As a… I want… so that…" narrative. `priority` is MoSCoW. `status` is backlog/ready/in-progress/done/rejected. |
| `epic` | Epic | `status`, `theme`, `goal`, `owner` | A large body of work under a strategic theme. Groups multiple features or stories. `status` is draft/active/complete/cancelled. |
| `feature` | Feature | `status`, `valueStatement`, `acceptanceCriteria`, `owner` | A discrete product capability. `status` is idea/planned/in-progress/shipped/deprecated. `valueStatement` is "This feature enables users to…" |
| `journey` | Journey | `persona`, `goal`, `steps`, `painPoints`, `opportunities` | A user journey map. `persona` names the archetype (connect to a Persona element). `steps` is the numbered touchpoint sequence. |
| `experiment` | Experiment | `status`, `hypothesis`, `audience`, `successMetric`, `result` | A product experiment or A/B test. `hypothesis` follows "We believe that… will result in… because…". `status` is draft/running/complete/abandoned. |
---
### Software types
These types document technical architecture, implementation, and quality artefacts.
| `stepType` | Name | Key attributes | Meaning |
|------------|------|----------------|---------|
| `dependency` | Dependency | `package`, `version`, `dependencyType`, `license`, `purpose` | An external library or package. `dependencyType` is runtime/dev/peer/optional. `license` is important for compliance reviews. |
| `model` | Model | `modelFormat` | A data schema or structured type. `modelFormat` is typescript/json-schema/sql/protobuf/avro/plain. Uses `dai:properties` for typed fields (see below). |
| `test` | Test | `testType`, `testStatus`, `testSteps`, `expectedResult`, `actualResult` | A test case. `testType` is unit/integration/e2e/acceptance/performance/security. `testStatus` is not-run/passing/failing/skipped. |
| `issue` | Issue | `issueType`, `severity`, `status`, `stepsToReproduce`, `expectedResult`, `actualResult`, `assignee` | A bug or blocker. `issueType` is bug/enhancement/blocker/question. `severity` is critical/high/medium/low. |
| `api-endpoint` | API Endpoint | `method`, `path`, `authType`, `requestBody`, `responseBody`, `statusCode`, `service` | A REST or GraphQL endpoint. `service` names the owning service (connect to a Service element). `authType` is none/bearer/api-key/oauth2/basic. |
| `service` | Service | `baseUrl`, `version`, `authType` | An external or internal service. Provides context for API Endpoint elements that belong to it. Connect API Endpoint elements to this service with sequence flows. |
| `component` | Component | `componentType`, `propsInterface` | A UI or software component. `componentType` is ui/layout/page/hook/utility/service/library. `propsInterface` holds the TypeScript interface or prop types. |
| `database` | Database | `engine`, `host`, `schema`, `accessPattern` | A database or data store. `engine` is postgresql/mysql/sqlite/mongodb/redis/dynamodb/firestore/other. |
| `event` | Event | `producer`, `consumers`, `broker`, `payloadSchema` | A domain event in an event-driven system. `broker` is kafka/rabbitmq/aws-sns/aws-sqs/gcp-pubsub/redis-pubsub/custom/none. `payloadSchema` is the event payload structure. |
---
### Model and Tool properties
The `model` step type supports typed field definitions via `dai:properties` and `dai:property` child elements inside `bpmn:extensionElements`:
```xml
```
Supported property types: `str`, `int`, `float`, `bool`, `date`, `datetime`, `list`, `dict`.
The `tool` step type also uses `dai:properties` to define typed parameters:
```xml
```
---
## Flow and Structure Elements
### Group (SubProcess) — the nesting primitive
`bpmn:SubProcess` is the primary structural tool. Use it freely at any depth to express containment, scope, domain boundaries, or logical clustering. Groups can contain other groups, any step type, events, and gateways.
```xml
```
### Start Events
| Type | XML | When to use |
|------|-----|-------------|
| Plain start | `` | Workflow starts immediately or by direct invocation. |
| Message start | `` | Triggered by a specific incoming message from an external system. |
| Timer start | `R/PT24H` | Triggered on a schedule or after a delay. ISO 8601 duration or datetime. |
| Conditional start | `queue.length > 0` | Triggered when a boolean expression becomes true. |
| Signal start | `` | Triggered by a named broadcast signal. |
### End Event
```xml
```
Marks where a workflow path terminates.
### Intermediate Events
| Type | XML pattern |
|------|-------------|
| Plain intermediate | `` |
| Message catch | `` |
| Message throw | `` |
| Timer | `...` |
| Signal catch | `` |
| Signal throw | `` |
### Gateways
**Exclusive Gateway (Decision)** — routes execution down exactly one outgoing path based on conditions.
```xml
```
**Parallel Gateway (Fork/Join)** — splits execution into simultaneous branches (fork) or waits for all incoming branches (join). All outgoing paths are taken; no conditions evaluated.
```xml
```
### Connections
`bpmn:SequenceFlow` connects elements and controls execution order.
```xml
```
### Annotations and Data
**Text Annotation** — a free-text note for human readers. Not processed during execution.
```xml
Human-readable note here.
```
**Data Store Reference** — documents where data is read from or written to.
```xml
```
---
## Creating a .dai File
A `.dai` file can be created from anything: a software system, a business process, a product roadmap, an AI workflow, a research pipeline — any subject with structure can be expressed as a `.dai` tree.
Use the element types as a **vocabulary**. There is no prescribed mapping. Choose types that are semantically meaningful for the domain.
**AI workflows:** background knowledge is `context`; constraints and policies are `rule`; callable functions are `tool`; prompt templates are `prompt`; autonomous behaviours are `skill`.
**Business analysis:** threats are `risk`; strategic goals are `objective`; performance measures are `kpi`; architectural choices are `decision-record`; things assumed to be true are `assumption`; people with a stake in the outcome are `stakeholder`; things that must be built are `requirement`.
**Product development:** user archetypes are `persona`; user needs are `story`; large delivery chunks are `epic`; individual capabilities are `feature`; how users move through the product is `journey`; hypotheses being tested are `experiment`.
**Software architecture:** external packages are `dependency`; data shapes are `model`; callable APIs are `api-endpoint`; the services that own them are `service`; UI building blocks are `component`; databases are `database`; async contracts are `event`; verification conditions are `test`; known defects are `issue`.
**Generic steps** — tasks that don't fit a more specific type — are plain `bpmn:Task` elements with no `stepType`.
Use **nested `bpmn:SubProcess` groups** as the primary structural tool. Nest them to reflect how the subject is actually organised — a module inside a service inside a system, a story inside an epic inside a product area, a step inside a phase inside a process. There is no depth limit.
Visual hierarchy communicates meaning. A `rule` nested inside a `persona` group signals the rule applies within that persona's scope. A `context` node nested inside a `model` group describes that model's domain. A `dependency` nested inside a feature group scopes it to that feature. The more deliberately the nesting reflects the actual structure, the richer the AI's understanding of the relationships between elements.
Set `dai:workflowMeta` on the root process with a clear description of what the workflow achieves. Customise the `dai:taskTypeEntry` dictionary to give each type domain-specific meaning for that diagram.
---
## Keeping Your .dai File Current
A `.dai` file is living documentation. As a project evolves — features added, services changed, rules revised, risks identified, assumptions invalidated — the diagram should be updated to match. An outdated `.dai` file gives the AI a stale picture and reduces the quality of its output.
Add a new `dependency` when a library is introduced. Add an `issue` when a defect is found. Revise a `rule` when a policy changes. Add a `risk` when a threat is identified. Mark an `assumption` as invalidated when it proves false. Remove elements that no longer exist.
This discipline benefits humans and AI equally. For humans, the diagram is always an accurate visual map of the system's current structure and intent. For AI, an up-to-date `.dai` file means the context it receives reflects reality — which directly improves the precision and relevance of its output.
---
## Examples
### Example 1 — AI Workflow (data validation)
A complete `.dai` file modelling a data validation workflow with context, rule, model, decision branch, and parallel steps.
```xml
```
---
### Example 2 — Product and Software (feature delivery)
A `.dai` file modelling a feature delivery workflow using product and software types: persona, story, requirement, api-endpoint, test, and issue.
```xml
```