Workspace YAML
A workspace is a git directory of YAML and markdown, outside the vocion-core checkout. You edit files, check them, apply them.
The loop
npm run workspace:scaffold -- northwind # ../workspace/northwind, never overwrites
npm run workspace:check -- ../workspace/northwind # validate only; needs no database
npm run workspace:apply -- ../workspace/northwind --project northwind
workspace:apply flags: --project <id|slug>, --org <id>, --applied-by <name>, --dry-run. Without --project or --org it uses the only project if there is exactly one, else the manifest's orgId. Exit codes: 0 applied, 1 applied with errors, 2 validation failed and nothing was applied. Applies are idempotent.
Unknown keys are dropped silently, not reported. If a setting seems ignored, check its spelling against this page.
Files
| File | Path | Required |
|---|---|---|
| Manifest | workspace.yaml | version: 1, orgId, name |
| Agent | agents/<slug>.yaml + <slug>.system-prompt.md | slug, name, systemPromptFile or systemPrompt |
| Team | teams/<slug>.yaml | name |
| Skill | skills/<slug>/SKILL.md | frontmatter slug, name, description |
| Playbook | playbooks/<slug>/SKILL.md | same as a skill |
| Mission | missions/<slug>.yaml | slug, name, goal, agent |
| Workflow | workflows/<slug>/workflow.yaml | slug, name, trigger, steps |
| Automation | automations/<slug>.yaml | slug, when, do |
| Object type | objects/<slug>/type.yaml | slug, label |
| Source | sources/<slug>.yaml | slug, name, kind |
| Trust rules | trust.yaml | rules[] |
| Voice | voice.yaml | — |
| Operating intent | operating-intent.yaml | — |
| Learning step | learnings/<name>.yaml | name, title, description |
| Eval dataset | evals/<slug>.yaml | slug, name, agentSlug, items |
| Wiki page | wiki/<slug>.md | title (with the wiki plugin) |
| Page | pages/<slug>.yaml | file-only; served at /dashboard/p/<slug>, not validated by check/apply |
A workflow must be workflows/<slug>/workflow.yaml; a flat workflows/<slug>.yaml is ignored. An operations/ folder fails the load: convert each operation to a skill.
workspace.yaml
version: 1
orgId: proj_northwind
name: northwind
lead: northwind-lead # the agent that answers by default
accountableUser: ops@northwind.example
extends: core@2.1.0 # the base pack
use: { agents: [revenue-director] }
plugins: [wiki, proposals] # turns on apps; see Apps
surfaces: [discovery]
defaults:
model: claude-sonnet-5-5
timezone: America/Chicago
embeddingProvider: openai # or bedrock
learningEagerness: 7 # 0–10
agentBudget: { dailyCents: 500 }
Other keys: description, goal, mailbox, disable, pluginSettings, notifications, and under defaults: temperature, embeddingModel, agentProposals, gates.
Base pack
Core ships core@2.1.0 (nine agents, thirteen skills, one playbook) at packages/core/templates/base/. Pin it with extends: core@<version> and activate what you want with use: (all, or lists of agents, skills, playbooks). With extends set and no use, nothing is activated. Override a pack file with a same-slug file marked extends: core.
Environment tokens
{{env.NAME}} in a file is replaced at apply time, only for names listed in WORKSPACE_TEMPLATE_VARS. An unlisted or empty token fails the apply with exit code 2.
Minimal examples
# sources/handbook.yaml
slug: handbook
name: Northwind handbook
kind: web
config: { url: https://northwind.example/handbook }
schedule: '0 6 * * *'
# teams/revenue.yaml
name: Revenue
lead: northwind-lead
goal: Every Contoso and Acme deal has a next step.
# learnings/global.yaml
name: global
title: House rules
description: Standing rules every agent follows.
rules:
- { id: r1, text: Quote prices in USD. }
Agents, missions, workflows, automations, object types and evals have their own pages in this section.
From the app and MCP
Admins can apply from the drift banner. Editing a mission, playbook or skill in the app writes the file and applies it, without committing. Over local MCP, workspace_write_skill|playbook|mission|agent|object_type, workspace_diff and workspace_apply do the same from an IDE.