Authoring Workspace Manifests

A workspace manifest is a YAML file with the header below. Add the schema comment for IDE completion:

yaml

1# yaml-language-server: $schema=https://xema.dev/schemas/workspace/v1/WorkspaceManifest.json
2apiVersion: xema.dev/workspace/v1
3kind: WorkspaceManifest
4metadata:
5  slug: my-manifest
6  version: 1.0.0
7  description: Optional one-line description
8spec:
9  inputs: { ... }
10  mounts: { ... }
11  agent: { ... }
12  seedFiles: [ ... ]
13  env: [ ... ]

`spec.inputs`

Declares the variables callers must (or may) supply at bind time. All ${input.x} references in the rest of the manifest must be declared here.

yaml

1spec:
2  inputs:
3    repoRef:
4      type: string
5      required: true
6      description: SCM repo the agent operates on (e.g. owner/repo).
7    theme:
8      type: string
9      required: false
10      default: light
11      enum: [light, dark]
12    kbSpaceIds:
13      type: string[]
14      required: false
15      default: []

Field	Type	Description
`type`	`string`, `number`, `boolean`, `string[]`	Value type
`required`	boolean	Whether the caller must supply a value
`default`	any	Value used when the caller omits the input
`enum`	array	Closed set of allowed string values
`description`	string	Human label shown in the platform UI

`spec.mounts`

Controls which workspace slots are active and their access mode.

yaml

1spec:
2  mounts:
3    repos:
4      mode: read-write          # agent can commit and push
5    references:
6      mode: read-only           # KB spaces, external repos
7    deliverable-specs:
8      mode: read-only
9    deliverables:
10      mode: read-write          # agent writes output here; harvested at end
11    uploads:
12      mode: read-only           # files the user attached to the session
13    inputs:
14      mode: read-only           # inputs.json is written here automatically

Omit a slot to leave it unmounted. The agent field (below) is always mounted automatically — you do not declare it under mounts.

You can also use true as a shorthand to enable a slot with platform defaults:

yaml

1spec:
2  mounts:
3    repos: true              # equivalent to { mode: read-write }
4    deliverables: true

`references` with KB space IDs

To bind specific knowledge-base spaces at dispatch time, add kbSpaces alongside mode:

yaml

1spec:
2  mounts:
3    references:
4      mode: read-only
5      kbSpaces: ${input.kbSpaceIds}   # resolved from inputs at bind time

Similarly, externalProjects pins specific external SCM repos under references/external-projects/:

yaml

1    references:
2      mode: read-only
3      externalProjects: ${input.repoRef}

`spec.agent`

Declares the agent identity. The platform resolves the agent definition, its skills, and its instruction sections from the LLM Registry before the workspace is handed to the agent runtime.

yaml

1spec:
2  agent:
3    slug: engineer              # agent slug registered in the LLM Registry
4    stage: engineering          # stage key — a structural label, not a config-resolution dimension
5    role: engineer              # see Role values below
6    deliverableSpecRef: ${input.deliverableSpecRef}   # optional

Field	Required	Description
`slug`	Yes	Agent identifier in the LLM Registry
`phase`	Yes	Phase key used for agent config resolution
`role`	Yes	One of the canonical role values — see below
`deliverableSpecRef`	No	Spec slug passed to AGENTS.md rendering

Role values

Role	When to use
`unit-worker`	Pipeline executor producing files under a builder template
`coordinator`	Pipeline coordinator merging unit outputs / authoring system-wide pages
`engineer`	Code-producing pipeline executor (writes commits, runs builds)
`auditor`	Read-only repo scanner
`generic-agent`	User-defined pipeline agent that doesn't fit the closed catalogue
`gate-reviewer`	Read-only verdict over upstream deliverables; emits `review.json`
`clarification-coordinator`	Pre-pipeline clarification phase that emits the typed handoff package
`scope-validator`	Validates whether an upstream output stays inside an envelope; read-only
`agent-session`	Free-chat session bound to a primary agent
`brainstorming`	Brainstorming session — design canvas, no pipeline retry/manifest concepts

Manifests that name a role outside this list fail at compile time — in the editor via the schema hint, and again when the biome shipping the manifest is installed — with a typed error pointing at $.spec.agent.role.

`spec.seedFiles`

Files written into the workspace before the agent starts. Each entry renders content from a named Handlebars template or inline content string.

yaml

1spec:
2  seedFiles:
3    # From a named template
4    - path: preview/index.html
5      slot: deliverables          # which workspace slot the path is relative to
6      template: brainstorming-preview-app
7      vars:
8        theme: ${input.theme}
9
10    # From inline content
11    - path: pinned-notes.md
12      slot: deliverables
13      content: |
14        # Session Notes
15        Use this file to capture key decisions.

Field	Required	Description
`path`	Yes	File path relative to the slot root
`slot`	Yes	Target slot (`deliverables`, `repos`, etc.)
`template`	Either	Named template registered in the platform
`content`	Either	Inline Handlebars or literal string
`vars`	No	Variables passed to the Handlebars template

Template names are skill-bundle resources served by the Skill Registry — each biome ships its templates under templates/*.hbs (declared in the biome manifest's workspaceManifestTemplates field) and the platform resolves them at seed-render time through the same five-tier scope ladder as every other Skills-First primitive (user → project → org → biome → system).

`spec.env`

Environment variables injected into the agent's container. Names must be UPPER_SNAKE_CASE (validated at compile time).

yaml

1spec:
2  env:
3    - name: BRAINSTORM_THEME
4      value: ${input.theme}
5    - name: REVIEW_MODE
6      value: strict

Complete Examples

Seeded canvas (demo biome)

This demo-seeded-canvas manifest from the demo biome showcases seedFiles end-to-end: three theme-aware files (preview/index.html, preview/styles.css, preview/app.js) are materialised into the deliverables slot from named Handlebars templates BEFORE the agent runs. The agent inherits a working scaffold and the live-preview launcher picks it up as a static_http app on first scan.

yaml

1# yaml-language-server: $schema=https://xema.dev/schemas/workspace/v1/WorkspaceManifest.json
2apiVersion: xema.dev/workspace/v1
3kind: WorkspaceManifest
4extends: xema://manifest/agent-session-[email protected]
5metadata:
6  slug: demo-seeded-canvas
7  version: 1.0.0
8  description: >-
9    Demo workspace manifest showcasing the spec.seedFiles feature.
10spec:
11  inputs:
12    theme:
13      type: string
14      required: false
15      default: light
16      enum: [light, dark]
17    title:
18      type: string
19      required: false
20      default: My Xema Canvas
21  agent:
22    slug: demo-runner
23    stage: interactive
24    role: agent-session
25  seedFiles:
26    - path: preview/index.html
27      slot: deliverables
28      template: demo-seeded-canvas-index.html
29      vars:
30        theme: ${input.theme}
31        title: ${input.title}
32    - path: preview/styles.css
33      slot: deliverables
34      template: demo-seeded-canvas-styles.css
35      vars:
36        theme: ${input.theme}
37    - path: preview/app.js
38      slot: deliverables
39      template: demo-seeded-canvas-app.js
40      vars:
41        title: ${input.title}
42  env:
43    - name: DEMO_CANVAS_THEME
44      value: ${input.theme}

Once compiled into a published Agent revision, a workflow selects this environment through that Agent's agentRef. The Agent can then extend the scaffold without rewriting it—a canonical “first paint correct, Agent contributes the delta” pattern.

Brainstorming session

This is the brainstorming-default manifest shipped by the brainstorming biome verbatim:

yaml

1# yaml-language-server: $schema=https://xema.dev/schemas/workspace/v1/WorkspaceManifest.json
2apiVersion: xema.dev/workspace/v1
3kind: WorkspaceManifest
4metadata:
5  slug: brainstorming-default
6  version: 1.0.0
7  description: >
8    Brainstorming session workspace — open canvas, uploads slot for
9    user-uploaded references, deliverables for harvest.
10spec:
11  inputs:
12    theme:
13      type: string
14      required: false
15      default: light
16      enum: [light, dark]
17    kbSpaceIds:
18      type: string[]
19      required: false
20      default: []
21  mounts:
22    references:
23      mode: read-only
24    uploads:
25      mode: read-only
26    deliverables:
27      mode: read-write
28    inputs:
29      mode: read-only
30  agent:
31    slug: brainstorming
32    stage: interactive
33    role: coordinator
34  seedFiles:
35    - path: preview/index.html
36      slot: deliverables
37      template: brainstorming-preview-app
38      vars:
39        theme: ${input.theme}
40    - path: preview/styles.css
41      slot: deliverables
42      template: brainstorming-styles
43      vars:
44        theme: ${input.theme}
45  env:
46    - name: BRAINSTORM_THEME
47      value: ${input.theme}

Engineering executor (repo + KB + deliverables)

This is the engineering-standard manifest shipped by the software-dev biome:

yaml

1# yaml-language-server: $schema=https://xema.dev/schemas/workspace/v1/WorkspaceManifest.json
2apiVersion: xema.dev/workspace/v1
3kind: WorkspaceManifest
4metadata:
5  slug: engineering-standard
6  version: 1.0.0
7  description: >
8    Standard engineering executor workspace — read-write repo, KB references
9    for engineering docs/runbooks, deliverables slot writeable for the agent's output.
10spec:
11  inputs:
12    repoRef:
13      type: string
14      required: true
15      description: SCM repo identifier the agent operates on (e.g. owner/repo).
16    kbSpaceIds:
17      type: string[]
18      required: false
19      default: ['engineering-docs', 'runbooks']
20      description: Knowledge-base spaces to mount under references/kb/.
21    deliverableSpecRef:
22      type: string
23      required: true
24      description: Deliverable-spec slug+version the agent must conform to.
25  mounts:
26    repos:
27      mode: read-write
28    references:
29      mode: read-only
30    deliverable-specs:
31      mode: read-only
32    deliverables:
33      mode: read-write
34    inputs:
35      mode: read-only
36  agent:
37    slug: engineer
38    stage: engineering
39    role: engineer
40    deliverableSpecRef: ${input.deliverableSpecRef}

Validating Before Shipping

Workspace manifests are validated at build time by the @xemahq/contracts workspace manifest compiler — the same schema enforced when the biome that ships the manifest is installed. Annotate every manifest YAML with the schema hint so your editor's YAML language server flags structural errors as you type:

yaml

1# yaml-language-server: $schema=https://xema.dev/schemas/workspace/v1/WorkspaceManifest.json
2apiVersion: xema.dev/workspace/v1
3kind: WorkspaceManifest

When a biome is installed, each manifests/*.workspace.yaml file is compiled and projected into a published agent composition. A manifest that fails validation — an empty agent.slug, a missing required input, or a seed file referencing an unknown template — fails the install fast with a typed error so the bad manifest never reaches a session.

See DSL Reference for the full error taxonomy.

Previous: ← Concepts Next: DSL Reference →

Authoring Workspace Manifests

spec.inputs

spec.mounts

references with KB space IDs

spec.agent

Role values

spec.seedFiles

spec.env

Complete Examples

Seeded canvas (demo biome)

Brainstorming session

Engineering executor (repo + KB + deliverables)

Validating Before Shipping

`spec.inputs`

`spec.mounts`

`references` with KB space IDs

`spec.agent`

`spec.seedFiles`

`spec.env`