AIP-34: WORKSPACE (workspace/v2): workspace tree node manifest
A markdown + frontmatter format for declaring a workspace node's identity AND its place in a tree of workspace nodes — globally addressable id, owner, storage choice, node type, visibility wall, two-sided includes/exports/apps doors, never-inherited secrets, and budget aggregation. Supersedes the original workspace/v1 identity-only draft outright (no parallel v1 support, no mixed-schema tree); see "Migrating from workspace/v1".
| Field | Value |
|---|---|
| AIP | 34 |
| Title | WORKSPACE (workspace/v2): workspace tree node manifest |
| Status | Review |
| Type | Schema |
| Domain | workspace.sh |
| Requires | AIP-7 (GOVERNANCE), AIP-19 (SECRETS), AIP-20 (WORK), AIP-25 (PERSONA), AIP-35 (STORAGE), AIP-36 (SANDBOX) |
Abstract
WORKSPACE.md is a markdown-with-frontmatter file format that
packages a workspace node's identity — its globally addressable
id, owner, name, description, storage choice, defaults, publish
posture — and its place in a tree of workspace nodes: a node
type, a visibility wall, two-sided includes/exports/apps
doors, never-inherited secrets, and budget aggregation. It is the
manifest every AIP-organized workspace node carries, and the entry
point hosts read first when materializing one.
This is workspace/v2 — the current and only normative schema of
this AIP. An earlier workspace/v1 draft (identity only, no tree
composition) is superseded outright: there is no parallel v1
support, no mixed v1/v2 tree, and no compatibility schema. A tree is
homogeneously workspace/v2. See "Migrating from workspace/v1" for
the field-by-field note.
The format pairs with two sibling blocks that mirror Mastra's
Workspace = filesystem + sandbox shape:
- STORAGE.md (AIP-35) — where the bytes live (filesystem). Required.
- SANDBOX.md (AIP-36) — where shell commands run (compute). Optional — workspaces MAY be storage-only.
Both fields accept inline or ref form.
The file is human-authored, version-controlled, machine-parseable, and grep-able — same posture as SKILL.md, TOOL.md, WORKFLOW.md, CODE.md.
Motivation
Workspaces today exist implicitly: a row in some app's database
points at a folder somewhere, and conventions emerge — .tools/,
.workflows/, .skills/, .runs/. The folder is real, the
conventions are real, but the workspace itself has no manifest.
That implicit shape blocks five real workflows:
-
No portable identity. "What is this workspace? Whose is it? Where do its bytes live?" answers require querying the host's database. There's no manifest a reviewer can read.
-
Storage choice is hidden. Whether a workspace is on Supabase, S3, GitHub, or local disk is a host config detail. The user can't override it without app-side changes.
-
No publishability. Workspaces can't be templates, exports, or registry citizens because they have no addressable id and no manifest to publish.
-
Hosts can't enumerate workspaces uniformly. A multi-tenant host with N workspaces per owner has to special-case its app schema to list, switch, or migrate them. With a root manifest,
find . -name "WORKSPACE.md" -maxdepth 2enumerates the substrate. -
No tree composition. Even once a single workspace has a manifest, nothing describes how MANY workspaces relate — which one is whose parent, who may read across a boundary, how budgets or secrets propagate. Hosts invent ad hoc parent-child conventions per product, each with its own leak surface.
WORKSPACE.md makes the workspace — and the tree it sits in — a
first-class declared entity.
Design principles
-
One file per node. A workspace NODE is a folder containing exactly one
WORKSPACE.mdat its root. A TREE is composed of many such nodes — the folder hierarchy IS the parent/child relationship (a node's implicit parent is its folder's nearest ancestor that also has aWORKSPACE.md), never a separateparent:field that could drift from the filesystem. -
Identity is globally addressable and flat.
idfollows the form@<owner-slug>/<workspace-slug>. Same posture as designkit / canvakit / agentproto manifests. The address is resolvable across hosts that share an owner namespace, and is immutable even if the node moves to a different folder. -
Storage policy is its own block. WORKSPACE.md does NOT redefine storage configuration. It either inlines a STORAGE.md block (AIP-35) for one-off cases, or refs a STORAGE.md file / registry slug for reusable policies.
-
Optional for backward compatibility. A workspace without a WORKSPACE.md is still a workspace — hosts fall back to defaults inferred from their database row. WORKSPACE.md is the upgrade path to declared identity, not a hard gate.
-
Manifest wins on conflict. When both a WORKSPACE.md and a host-side row exist, the manifest body is the source of truth. The row caches hot fields (id, current provider) for routing efficiency only.
-
Owner is descriptive, not load-bearing for FKs. The
owner.{type, id, slug}block describes who owns this workspace for human and registry consumption. The DB shape on any host that persists workspaces uses typed FK tables per owner kind (e.g.guild_workspaces,user_workspaces,org_workspaces) — not polymorphicowner_typecolumns. -
Publish posture is opt-in. A workspace declares
publish.template: trueif it intends to be cloneable. The declaration is the input to a downstream registry; this AIP does not specify the registry itself. -
Visibility defaults closed, every crossing is two-sided. A node's
walldefaults toisolated: nothing crosses a node boundary — files (includes/exports), secrets (uses_secrets), or app surfaces (apps[].attach) — without an EXPLICIT grant declared on BOTH the consumer and the provider side. A looser level (shared) or a stricter one (sealed,hard) is opt-in in both directions; there is no single-sided override anywhere in this AIP.
Specification
File location
<tree-root>/
WORKSPACE.md ← this AIP, exactly one per node — the tree ROOT
TYPES.md ← node-type registry (root only)
agentproto.lock ← tree-wide app/pack lockfile (root only)
.secrets/SECRETS.md ← AIP-19, this node's own secrets
.tools/<id>/TOOL.md ← AIP-14
.drivers/<id>/DRIVER.md ← AIP-30
.workflows/<id>/WORKFLOW.md ← AIP-15
.code/<id>/CODE.md ← AIP-26
.skills/<id>/SKILL.md ← AIP-3
storage/<slug>.STORAGE.md ← AIP-35 (if separated)
EXPORT.md ← AIP-34, only if wall is sealed/hard
<child-dir>/
WORKSPACE.md ← a NESTED node — its own id, own frontmatter,
implicit parent = this directory
... (same shape, recursively) ...A folder with no WORKSPACE.md is simply part of its nearest
ancestor's node — same "nearest manifest wins" rule a single
workspace already uses to find its own root, applied recursively
across a tree of them.
Frontmatter
YAML frontmatter, delimited by --- lines. All fields are
case-sensitive. schema is always "workspace/v2" — the sole
discriminator value this AIP defines.
On version vs. schema — two independent axes, do not conflate
them: version is the revision of THIS PARTICULAR manifest instance
(bump it when you meaningfully change this file's own content — an
owner reassignment, a storage swap, a policy change). schema: "workspace/v2" is the FORMAT version — which shape the file follows,
defined by this AIP. Editing your WORKSPACE.md's version never
implies the format changed; a format change is a new AIP revision
with (if ever needed again) a new schema literal, not a version
bump.
Required fields
| Field | Type | Description |
|---|---|---|
schema | string | Always workspace/v2. |
id | string | Globally addressable, FLAT id: @<owner-slug>/<workspace-slug>. Lowercase, digits, dashes. Immutable — survives the node moving to a different folder. |
version | semver string | Revision of THIS manifest instance. See "On version vs. schema" above. |
name | string | Human-readable display name. 1–80 chars. |
type | string | Node kind. MUST be a key in the nearest ancestor TYPES.md (walking up through plain folders with no WORKSPACE.md). Day-1 vocabulary: root, perso, company, project, initiative. The schema accepts any kebab string; the registry, not this schema, is the extension point — a tree MAY declare a client type that extends: project. |
owner | object | { type: "guild" | "user" | "org", id: string, slug: string }. The slug participates in the addressable id above and MUST match its slug suffix. |
storage | object | Filesystem policy: { inline: <STORAGE.md frontmatter body> } or { ref: "<path or registry slug>" } or { file: "<path>" }. See AIP-35. |
Optional fields
| Field | Type | Default | Description |
|---|---|---|---|
description | string | "" | One-paragraph purpose. ≤2000 chars. |
status | enum | "active" | "active" | "paused" | "archived". See "Node status: active / paused / archived" below. |
sandbox | object | (none) | Sandbox policy: inline / ref / file. See AIP-36. Optional — when absent, command-execution tools MUST be unavailable. |
code | object | (none) | Code policy: inline / ref / file. See AIP-26. Optional — when present, the workspace IS a code-workspace / repo (see "Workspace as repo" below). |
work | object | (none) | { inline: <WORK.md frontmatter body> } | { ref: <path or registry slug> } | { file: <path> } — AIP-20 WORK.md, same inline/ref/file union as code. A project node's status/board lives here, NOT in a flat status file: items are AIP-18 ITEM.md records under the collection(s) work declares. See "Node status: work:" below. |
presence | object | (none) | { inline: <PRESENCE.md frontmatter body> } | { ref: <path or registry slug> } | { file: <path> }. A workspace.presence/v1 document: how this node speaks in public (audience, topics, forbidden words, channels, cadence, approval, gates). Same inline/ref/file union as work. The voice itself stays in the AIP-25 PERSONA.md the document names. See "Presence block: presence:" below. |
identity | object | array | (none) | AIP-23 identity-ref block — default identity for all sub-blocks of this workspace. Sub-blocks (storage, sandbox, code) override. See AIP-23 identity-ref. |
wall | enum | "isolated" | Visibility level: "shared" | "isolated" | "sealed" | "hard". See "The four wall levels" below. |
includes | array | [] | { ref: "ws://workspaces/<id>[#<subpath>]", mode: "read" | "write" | "append" }. Consumer-side half of a door. Honoured only if the target ALSO exports to this id — see "Includes and exports". |
exports | array | [] | { path, to, mode: "read" | "write" }. Provider-side half of a door. to is a workspace id, an array of ids, or the sentinel "children" — see "Includes and exports". |
agents | array | [] | { file, share?: string[] } — AIP-42 AGENT.md manifests this node hosts. share lists other workspace ids the agent is also declared transverse to (runs scoped to whichever of these ids is the live caller, never a union). |
routines | array | [] | { file } — AIP-41 ROUTINE.md manifests this node hosts. |
secrets | object | (none) | { file } — ref to this node's OWN .secrets/SECRETS.md (AIP-19). Omitted = no secrets of its own. Never inherited; see "Secrets never descend". |
uses_secrets | array | [] | { from: <id>, slug, mode?: "bind" | "reveal" }. Consumer-side half of a secret grant — effective only if from's SECRETS.md carries a matching access.{bind,reveal}[].workspace grant for THIS node's id (AIP-19 extension — see "Secrets never descend"). |
apps | array | [] | { id, version, expose?: ("agents"|"tools"|"ui"|"data")[], attach?: "self" | <id> }. version is a semver or semver-range; the exact resolved version is recorded in agentproto.lock, never in WORKSPACE.md. attach crossing to another node needs that node's consent — see "Apps and consent". |
accepted_apps | array | [] | { from: <id>, app?: <id> }. Provider-side consent for an apps[].attach pointed at THIS node by another node. See "Apps and consent". |
policy | object | array | (none) | AIP-38 POLICY block — access grants, defaults, limits, requirements scoped to this workspace. Composable: inline / ref / file, OR an array (most-restrictive wins). limits[].kind additionally allows budget-usd-per-month | budget-usd-per-day (value = USD) — see "Budgets aggregate". |
defaults | object | {} | { read_only: bool } and other workspace-wide defaults. |
publish | object | { template: false, visibility: "private" } | Publish posture: { template: bool, registry?: string, visibility: "private" | "unlisted" | "public" }. |
tags | string[] | [] | Free-form discovery tags. |
created_at | string (ISO 8601) | none | Creation timestamp. |
lock | string | "agentproto.lock" | Tree-relative path to this node's apps/packs lockfile. Only meaningful on a node that attaches apps/packs directly. |
metadata | object | {} | Free-form. Authors MAY stash adapter-specific hints under namespaced keys. |
Body
Markdown body following the frontmatter. Recommended sections:
## Description— long-form purpose, what's in this workspace, who maintains it.## Layout— non-default folder conventions (e.g. "this workspace also uses.briefs/for content drafts").## Maintainers— humans + agents responsible.
The body is informational. Hosts MUST function reading only the frontmatter.
The defineWorkspace standard signature
defineWorkspace(definition: WorkspaceDefinition): WorkspaceHandle
interface WorkspaceDefinition {
schema: "workspace/v2"
id: string // "@<owner>/<slug>"
version: string
name: string
type: string // key in the nearest TYPES.md
description?: string
owner: {
type: "guild" | "user" | "org"
id: string
slug: string
}
storage:
| { inline: StorageDefinition } // AIP-35 (required)
| { ref: string }
| { file: string }
sandbox?:
| { inline: SandboxDefinition } // AIP-36 (optional)
| { ref: string }
| { file: string }
code?:
| { inline: CodeDefinition } // AIP-26 (optional — workspace as repo)
| { ref: string }
| { file: string }
work?:
| { inline: WorkDefinition } // AIP-20 (optional — node status/board)
| { ref: string }
| { file: string }
identity?: // AIP-23 identity-ref
| IdentityRef
| IdentityRef[]
wall?: "shared" | "isolated" | "sealed" | "hard" // default "isolated"
includes?: { ref: string; mode?: "read" | "write" | "append" }[]
exports?: { path: string; to: string | string[] | "children"; mode?: "read" | "write" }[]
agents?: { file: string; share?: string[] }[]
routines?: { file: string }[]
secrets?: { file: string }
uses_secrets?: { from: string; slug: string; mode?: "bind" | "reveal" }[]
apps?: { id: string; version: string; expose?: ("agents"|"tools"|"ui"|"data")[]; attach?: string }[]
accepted_apps?: { from: string; app?: string }[]
policy?: PolicyBlock | PolicyBlock[]
defaults?: { readOnly?: boolean }
publish?: {
template?: boolean
registry?: string
visibility?: "private" | "unlisted" | "public"
}
tags?: string[]
createdAt?: string
lock?: string // default "agentproto.lock"
status?: "active" | "paused" | "archived" // default "active"
metadata?: Record<string, unknown>
}Conformance rules
-
One
WORKSPACE.mdper node. A node is a folder with exactly oneWORKSPACE.md. NestedWORKSPACE.mdfiles ARE nodes — every one under a tree root is read, none are "the only one that counts" — with the nearest ancestorWORKSPACE.mdas the implicit parent (a folder with no manifest of its own is simply part of its nearest ancestor's node). -
idis immutable. Once set, never changes. Renaming the workspace mutatesname, neverid. Moving the node to a different folder (ws mv) rewrites the path, never the id. Hosts that need to changeidMUST treat the result as a new workspace. -
owner.slugand the slug suffix ofidMUST match. A workspace at@acme-corp/marketing-opsMUST haveowner.slug = "acme-corp". Validators MUST reject mismatches. -
storage.inlineandstorage.refare mutually exclusive. Exactly one form per WORKSPACE.md (same forsandbox,code,work,presence). -
No I/O at parse time. Reading WORKSPACE.md MUST NOT trigger credential resolution, network calls, or storage instantiation. Hosts materialize storage lazily.
-
A node's
typeMUST resolve in the nearest ancestorTYPES.md, and that type'sparentsMUST include the resolved type of the node's own nearest-ancestor-with-a-WORKSPACE.md(or be a root type with no ancestor). Unresolvable or disallowed nesting is a hard error. -
wallMUST NOT be looser than the type'sdefault_wall. Orderedshared < isolated < sealed < hard; a node MAY only equal or exceed its floor. -
An
includesentry is inert without a matchingexportsentry on the target, and vice versa — see "Includes and exports". Doors are two-sided by construction; there is no single-sided override. -
Secrets are never inherited. A node's effective secret set is exactly its own
.secrets/SECRETS.mdplus whateveruses_secretsentries have a matching grant. Nothing else, regardless of wall level or ancestry. -
A child's resolved budget is bounded by its parent's. See "Budgets aggregate".
-
A declared
work:MUST resolve to a parseable AIP-20 WORK.md (schema: "work.workspace/v2").work:itself is optional — this rule only fires when it IS declared. -
An
apps[].attachpointed at a DIFFERENT node is inert without a matchingaccepted_appsentry on that target — same two-sided consent as includes/exports/secrets. See "Apps and consent". -
Paths MUST be tree-relative and confined.
exports[].path,includes[].reffragments,secrets/agents/routines/work/presence/codefile refs, andagentproto.lock'sdataDirMUST NOT escape the tree via..traversal, a leading/, or a symlink. See "Path confinement". -
A node's effective status is the most restrictive value along its ancestor chain (
archived>paused>active) — a child is never more active than an ancestor. Hosts MUST NOT start agents or fire routines at a node whose effective status ispausedorarchived. See "Node status: active / paused / archived". -
A declared
presence:MUST resolve to a parseableworkspace.presence/v1document, and its effective (merged) form MUST name apersona.presence:itself is optional; this rule only fires when it IS declared. Apresence.fileorextendspath that escapes the tree is a hard error (rule 13). -
Presence only narrows down an
extendschain. Forbidden terms are never removed,approvalis never weakened, an opengateis never cleared by a descendant, and the effective presence status is the most restrictive along the chain. A host MUST NOT take any external action (publish, comment, follow, send) for a node whose effective presence status isdraftorpaused, nor for a node whose effective node status (rule 14) is notactive. See "Presence block:presence:".
Stable identity
id + version together form the workspace's stable identity.
A breaking change to the manifest's OWN content (a storage provider
swap, an owner reassignment, dropping a field this manifest used to
carry) SHOULD bump version. This is independent of schema, which
never changes for an AIP-34 node short of a future AIP revision — see
"On version vs. schema" above.
The four wall levels
| Level | Name | What crosses | Mechanism |
|---|---|---|---|
| 0 | shared | This node's siblings — the other children of the same parent — read the whole node. | The PARENT behaves as though it had declared exports: [{ path: <this node's relative path>, to: "children", mode: "read" }] on itself. See "Includes and exports" for why the declaring node matters. |
| 1 | isolated (default) | Nothing, without an explicit include + matching export (or an apps/secrets grant). Ancestors still see everything (no restriction applies upward). | Host-side resolver filters every file/memory/app-tool call by the requesting session's node scope (see "Node scope of a session"). |
| 2 | sealed | Like isolated, and ancestors ALSO lose raw-file visibility: they read only this node's EXPORT.md. Inbound includes from elsewhere require host-side approval (AIP-7 approval_request). | Same process/daemon; the host filters every read by the requesting session's node scope, as for isolated; ancestors read only EXPORT.md. The caller id is a claim, not a credential: see "What sealed guarantees". |
| 3 | hard | Like sealed, and enforced by a separate process/identity: no shared daemon, no shared auth profile, no shared MCP surface. The only traffic in or out is a declared export, delivered as a message, never mounted. | Second daemon, or a dedicated OS user/sandbox. |
A node MAY raise its own wall (0→1→2→3) relative to what its parent or
its TYPES.md.default_wall would otherwise give it, but MUST NOT set
a level looser than that floor (conformance rule 7). agentproto workspace check flags a looser-than-floor wall as a hard error, not
a warning.
Node scope of a session
The walls above filter by "the requesting session's node scope". That scope is defined here, once.
- A session has at most one node scope: the nearest declared node
whose folder contains the session's AIP-46
ground. "Declared" means a folder with aWORKSPACE.md(rule 1); a folder without one belongs to its nearest declared ancestor. Thegroundis an AIP-54 ref and MAY carry a subtree body, written with slashes as inlocal-body:ws://workspaces/@acme/agentik/simone/docsis the subtreesimone/docsof workspace@acme/agentik. The node scope is the nearest declared node containing that folder, which issimoneif it declares aWORKSPACE.mdand@acme/agentikotherwise. No other syntax names a subtree. - The scope is read from the caller. A host MUST derive it from the
calling session's
ground: at spawn for the prompt it composes, and on every file, memory, app or tool call from the session that makes the call. It MUST NOT take it from the configuration of the server that executes the call (a tool server, an MCP server, a store), which serves many sessions. A call whose caller session cannot be identified MUST be refused, never served as unscoped. - Sessions are scoped, operators are not. A principal that has a
home node or seats in a node (an AIP-9 operator, an
AIP-42 agent) is not itself subject to a wall. Its
sessions are: the same principal running one session in
@acme/agentikand another in@jeremy/persois read as two scopes. The walls and the policy cascade of this AIP apply to a session's node scope only. - No declared node, no node scope. A session whose
groundlies in no declared node (a workspace with noWORKSPACE.md) has no node scope and the wall rules of this AIP do not apply to it. Declaring a tree is what turns them on.
Host duty. A host that serves memory, file, app or tool reads
MUST filter every one of them by the requesting session's node scope
(the duty stated in the isolated row above), before results are
paginated, ranked or excerpted.
What sealed guarantees. For a sealed node, the data of that
node never enters a prompt, a memory projection or a host tool answer
of a session whose node scope is outside it, apart from what the node
declares in its EXPORT.md and in matching exports. This is a
guarantee about what the host composes and returns, not an OS wall. A
harness with native shell or file tools, or a host command tool that is
not confined, runs as the same OS user and can read the node's files on
disk; a local process can claim another session's caller id. A host
that needs more than this declares the node hard, which moves the
boundary to a separate process or identity.
Includes and exports (two-sided consent)
A door exists only when BOTH sides declare it:
# consumer: agentik/chatcommerce/WORKSPACE.md
includes:
- { ref: "ws://workspaces/@jeremy/simone#docs/whatsapp-flows", mode: read }# provider: agentik/simone/WORKSPACE.md
exports:
- { path: docs/whatsapp-flows, to: "@jeremy/chatcommerce", mode: read }Resolution rule: an includes entry is honoured iff some exports
entry on the target node has to equal to the consumer's id, an array
containing it, OR the sentinel "children" with the consumer actually
nested in the declaring node's folder subtree (see next paragraph for
what "declaring node" means). The effective mode is the more
restrictive of the two sides ordered read < append < write; a
consumer asking for write against a read-only export gets read,
and the verifier reports the downgrade rather than silently granting
less than requested. A one-sided declaration (include with no matching
export, or an export nobody includes) is not an error by itself — it's
simply inert — but agentproto workspace check SHOULD surface unused
exports and unresolved includes so dangling doors get noticed.
One definition for to: "children", used both explicitly and
implicitly: it means every node nested, in the FOLDER tree, under
whichever workspace declares the export entry — direct or
transitive descendants, regardless of id. For an explicit exports:
entry, the declaring node is whoever wrote it (e.g. a node MAY export
part of itself to its own descendants). For the IMPLICIT grant
wall: shared synthesizes, the declaring node is the parent, not
the shared node itself — which is why wall: shared reaches a node's
SIBLINGS (the parent's other children), not merely its own
descendants: agentik/commun/ set to wall: shared is read by every
other project folder under agentik/, because agentik (the parent)
is the one implicitly exporting commun/ to: "children", and
agentik's children include commun/'s siblings. to: "children" is
folder-relative, not id-relative, by design: ids are flat and
immutable (rule 2), so there is no id pattern that would mean "my
siblings" or "my descendants" the way a path-relative sentinel does.
Apps and consent
apps[].attach defaults to "self" — the declaring node and its own
subtree, which needs no consent because a node can only ever restrict
itself that way. Pointing attach at a DIFFERENT workspace id crosses
that node's wall exactly like an includes entry would, and is
subject to the same two-sided rule: the TARGET node must declare a
matching accepted_apps entry.
# declaring node: agentik/seo-tooling/WORKSPACE.md
apps:
- { id: "@agentik/seo-crew", version: "^0.1.0", attach: "@jeremy/chatcommerce" }# target: agentik/chatcommerce/WORKSPACE.md
accepted_apps:
- { from: "@jeremy/seo-tooling", app: "@agentik/seo-crew" }accepted_apps[].app is optional — omitted, the grant covers any app
from attaches. Without a matching entry, the cross-node attach is
inert (conformance rule 12): agentproto workspace check reports it
as an unresolved, unconsented attach, the same posture as a one-sided
includes/exports pair.
Secrets never descend
A node's .secrets/SECRETS.md is scoped to that node ONLY — it is
never visible to children by inheritance, mirroring the opposite of
how defaults.* preferences behave (those flow DOWN and get
overridden; secrets don't flow at all without an explicit grant).
Sharing a specific secret with a specific node is a two-sided
declaration exactly like includes/exports:
# provider: agentik/.secrets/SECRETS.md (AIP-19, extended)
secrets:
- slug: stripe-api-key
name: Stripe (Agentik account)
description: Payments. Never visible from Simone.
access:
bind:
- workspace: "@jeremy/chatcommerce" # AIP-19 extension — see below# consumer: agentik/chatcommerce/WORKSPACE.md
uses_secrets:
- { from: "@jeremy/agentik", slug: stripe-api-key, mode: bind }This requires one small, additive extension to AIP-19
SECRETS.md: accessEntry grows a sixth alternative, workspace: <id>,
alongside the existing role / userId / cap / tool / workflow
(still oneOf — exactly one principal kind per grant entry). Existing
SECRETS.md manifests are unaffected; this is a new optional field, not
a shape change to any existing one.
Budgets aggregate
policy.limits[].kind: "budget-usd-per-month" (or -per-day) on a
node is a ceiling on spend attributed to that node AND everything
under it. Resolution walks the chain from root to the node and takes
the MINIMUM declared value at the same kind — the same
most-restrictive-wins rule AIP-38 already states for grants, applied
to numeric limits. A child declaring a HIGHER budget than its parent
is not a schema error (over-reservation across siblings is allowed —
their limits may sum to more than the parent's), but the effective
ceiling for that child is still the parent's lower number, and the
parent's own limit is consumed first when several children spend
concurrently. agentproto workspace check reports the effective
(resolved) ceiling per node, not just the locally-declared one.
Policy follows the node chain
A node's policy is not only the node's own. A session scoped to a
node (see "Node scope of a session") is evaluated under the
AIP-38 composition of the policy of every node on its
chain: the node itself and each ancestor up to the root of its tree. The
composition is AIP-38's, applied once over the whole chain: a matching
deny in any node wins, default: deny in any node prevails, and every
requirement applies. A node therefore cannot lift a deny, a default or a
requirement declared above it, the same direction as "Budgets aggregate"
takes for numeric limits.
The chain stops at the tree root. A door (includes/exports) never
makes the including node a child, so a node reached through a door adds
nothing to the chain, and the policy of a node outside the chain (a
sibling, a descendant, another tree) is never consulted. Walls hide
files and memory from ancestors; they do not hide a node from its
ancestors' policy. Because it is the session that is scoped, an
operator's own policy (AIP-9) is composed with the chain of
the node the session runs in, and the policy of the operator's home node
does not travel with it into another tree.
Node type registry: TYPES.md
Exactly one TYPES.md per tree, at the root, schema: "workspace.types/v1":
---
schema: workspace.types/v1
types:
root:
parents: []
max_per_tree: 1
perso:
parents: [root]
default_wall: hard
company:
parents: [root]
default_wall: isolated
requires_files: [COMPANY.md]
project:
parents: [company]
default_wall: isolated
starter:
agents: [{ template: "@pygmalion/staff/project-lead" }]
routines: [{ template: "@pygmalion/staff/heartbeat-26h" }]
initiative:
parents: [perso, company, project]
default_wall: isolated
client: # tree-local extension
extends: project
adds_fields: { contract_end: date }
---parents lists the type values this type MAY nest under (nearest
WORKSPACE.md ancestor). default_wall is the floor a node of this
type gets when its own wall is omitted. requires_files names
sibling files agentproto workspace check expects at a node of this
type. Each entry conceptually compiles to an AIP-40
EXTENSION.md; TYPES.md is the authoring surface for that compilation,
not a competing mechanism.
A type that declares extends: <other> inherits the fields of <other>
(itself resolved through its own extends) that it leaves unset:
parents, default_wall, requires_files and starter, and likewise
max_per_tree and adds_fields. A field the type sets replaces the
inherited one as a whole; nothing is merged. An omitted or empty
requires_files counts as unset. Inheritance is a property of the
registry, so rule 6 and rule 7 apply to the resolved entry: a client
type that extends project nests where project nests and cannot set
a wall looser than project's floor.
Example (informative): a user tree and a company tree. Each tree has
its own TYPES.md. The user tree redeclares perso with a sealed
floor, a deliberate downgrade from the hard floor in the registry
above, for a host where one daemon serves the personal staff; see "What
sealed guarantees" for what that does and does not give. The company
tree declares a guild type that adds nothing to project:
# user tree: jeremy/TYPES.md
---
schema: workspace.types/v1
types:
root:
parents: []
max_per_tree: 1
perso:
parents: [root]
default_wall: sealed
---# company tree: agentik/TYPES.md
---
schema: workspace.types/v1
types:
company:
parents: []
max_per_tree: 1
default_wall: isolated
requires_files: [COMPANY.md]
project:
parents: [company]
default_wall: isolated
starter:
agents: [{ template: "@pygmalion/staff/project-lead" }]
guild:
extends: project # inherits parents, default_wall, starter
---Node status: work:
project above does NOT declare requires_files for a status file.
A project's status is not a markdown file to require — it's the
work: field: an AIP-20 WORK.md reference, whose
items are AIP-18 ITEM.md records. agentproto workspace check
validates a declared work: resolves to a parseable WORK.md
(conformance rule 11) the same way it validates requires_files
resolve to existing files, but does not require work: to be present,
and does not (yet) check item-level freshness inside that board, nor
how that board relates to any host's own runtime task store —
deferred, open work.
Node status: active / paused / archived
Unrelated to the work: board status above — this is the node's own
status field (conformance rule 14 governs its inheritance).
active(default) — runs normally.paused— the node keeps its declarations and data but runs nothing: a host MUST NOT start agents nor fire routines declared at or below it, and it's excluded from budget/heartbeat checks, same asarchived. Unlikearchived, it stays writable and resumes by flippingstatusback toactive.archived— read-only, excluded from budget/heartbeat checks, and never runs anything.
A node's declared status is exactly what its own WORKSPACE.md says —
never rewritten by inheritance. What a host enforces is the node's
EFFECTIVE status: the most restrictive value along its ancestor chain
(archived > paused > active); a child is never more active than
an ancestor. agentproto workspace check reports each node's
effective status, and names the ancestor it's inherited from whenever
that differs from the node's own declared value:
@acme/root status: paused → effective: paused
@acme/root/billing status: active → effective: paused (inherited from @acme/root)
@acme/root/billing/invoices status: archived → effective: archivedPresence block: presence:
A node that speaks in public (posts, replies, comments) needs an editorial policy that machines can check and a human signs off: who the node talks to, about what, in which words, on which accounts, how often, and who approves each piece before it leaves. The existing blocks each cover a neighbouring part and none covers this one:
| Concern | Already covered by | Gap this block fills |
|---|---|---|
| Voice, tone, register, self-declared limits | AIP-25 PERSONA.md (voice, boundaries) | Words that may never appear belong to the project, not to a reusable persona |
| What the node works on | AIP-20 WORK.md (work:) | Nothing about what is said in public |
| Limits and budgets | AIP-38 POLICY.md (policy:) | No notion of a channel, a topic or a published piece |
| Approval requests and signatures | AIP-7 GOVERNANCE.md | No policy that names which pieces need approval and who approves |
| Account credentials | AIP-19 SECRETS.md | No link between a secret and a channel |
| Company-wide defaults | AIP-6 COMPANY.md (no brand or voice fields) | Company defaults travel as a parent workspace.presence/v1 document through extends |
presence: adds no voice, no work tracking and no policy engine. It adds
the one document that binds them for public speech, and it names the
persona instead of restating it.
File and reference
presence: is the same inline / ref / file union as work:. The
document is markdown with YAML frontmatter, conventionally PRESENCE.md
in a presence/ folder next to the node's WORKSPACE.md. The schema is
PRESENCE.schema.json (schema tag workspace.presence/v1) and a worked example is
PRESENCE.example.md, both under resources/aip-34/draft/. The body is
informational: hosts read only the frontmatter.
Frontmatter
| Field | Type | Description |
|---|---|---|
schema | const workspace.presence/v1 | Required. |
name, title, description, version | strings | Required. name is kebab-case, 2 to 64 chars. |
status | enum | Required. draft, active or paused. |
extends | path | Relative path to a parent workspace.presence/v1 document (for example company defaults). |
persona | path or ws ref | The AIP-25 PERSONA.md that carries the voice. Required in the effective document. |
audience | object | primary, pains[], notTargeted[]. |
topics | object | pillars[] (id, title, angle) and exclude[]. |
lexicon | object | forbidden[] (term, reason, instead) and required[] (phrase, context). |
channels | array | One entry per account: id, network, account (handle, kind, owner), connection (provider, credentials as a secret slug), locale, formats, cadence, actions, publish (provider per action), approval. |
watch | object | What to read before commenting: keywords, accounts, hashtags, communities, commentRules. |
approval | object | mode (always or policy:<ref>) and approver (a principal ref). |
gates | array | id, description, status (open or cleared), blocks (any of links, posts, comments, channel:<id>). |
examples | object | good[] and bad[] pieces (text, why, channel) used to calibrate drafts. |
review | object | cadence (weekly or monthly), day, kpis[]. |
metadata | object | Namespaced vendor extensions. |
Credentials are never inline: connection.credentials MUST be the slug of a secret in the node's own
SECRETS.md, or one granted through uses_secrets
(AIP-19); the schema rejects anything that is not a bare
slug. Reading a presence document performs no I/O (rule 5).
Merge under extends
A child document is merged over its parent, and the merge only narrows:
- Replace:
title,description,audience,persona, and individualreviewfields. A child persona SHOULD itself extend the parent's persona; hosts MAY warn when it does not. - Union, never removable:
lexicon.forbidden(byterm, compared case-insensitively),topics.exclude, and everywatch.*array. A child may add areasonorinsteadto an inherited term, never drop the term. - Union by key:
lexicon.required(byphrase),topics.pillarsandchannels(byid; the child overrides fields of the sameid),gates(byid),examples(child entries first). - Tighten only:
approval.mode(alwaysis the strictest, so a child of analwaysparent MUST bealways) and a channel'sactions(a child may turnpostorcommentfromtruetofalse, never the reverse). - Gates: a gate is cleared only in the document that declares it. A
descendant redeclaring an ancestor's gate cannot clear it: the
effective status is
openif either declaration isopen. - Status: the effective presence status is the most restrictive
along the
extendschain (pausedoverdraftoveractive).
Status semantics
draft: the node's agents MAY prepare pieces and submit them for review; nothing leaves the host.active: approved pieces may be sent, subject to approval, gates and the node status of rule 14.paused: nothing is prepared and nothing is sent.
Presence status and node status (rule 14) are independent and both must allow an action.
What a host does with it
- Draft against it. The agent that writes a piece reads the
effective document: persona for voice,
topicsfor subject,watchfor what to read before a comment,examplesfor calibration. - Check the lexicon. A piece containing a forbidden term
(case-insensitive, accent-folded, whole word) MUST NOT be submitted
for approval; it goes back to drafting with the term named. A host
SHOULD flag a piece that states something a
requiredphrase covers without using the phrase verbatim. - Honour gates. An open gate blocks the listed kinds of action:
linksforbids any URL in a piece,postsandcommentsforbid those actions on every channel,channel:<id>forbids everything on that channel. - Ask a human. With
approval.mode: always, every piece waits for theapprover(AIP-7). What is approved is what is sent: the text is byte-identical, and any edit after approval voids the approval. - Send through the declared provider. The provider named in
publish.<action>(or elseconnection.provider) performs the action. If that provider is not connected, the action stays pending; a host MUST NOT silently route it through another provider. - Report. The
reviewblock names the cadence, day and KPIs of the periodic review.
A host MAY run these steps with an AIP-53 agent app that
reads the node's WORKSPACE.md, its presence: document and the
persona it names. This AIP does not require any particular runtime.
Example
The node declares the document:
presence: { file: presence/PRESENCE.md }and the document, reduced to the fields that matter (the full version is
PRESENCE.example.md):
---
schema: workspace.presence/v1
name: shopbot-presence
title: ShopBot public presence
description: How ShopBot speaks on LinkedIn and X.
version: 0.1.0
status: draft
extends: ../../acme-brand/presence/PRESENCE.md
persona: ./PERSONA.md
lexicon:
forbidden:
- { term: guaranteed ranking, reason: Nobody can guarantee a position in an AI answer. }
gates:
- id: public-site-stale
description: The public landing page still shows claims the product no longer makes.
status: open
blocks: [links]
---Tree-wide lockfile: agentproto.lock
Plain YAML (no frontmatter, no body) at the tree root, lockfile: "workspace.lock/v1". Pins every AIP-53 app and
AIP-64 pack installed anywhere in the tree to an exact version, its
source, the sha256 of the fetched artifact, which node it's attached
to, and a per-attach data directory:
lockfile: workspace.lock/v1
generated: 2026-10-17T18:00:00Z
apps:
- id: "@agentik/seo-crew"
version: 0.1.0
source: "file:/path/to/seo-crew"
sha256: "…"
attach: "@jeremy/chatcommerce"
dataDir: agentik/chatcommerce/.apps/seo-crew
packs:
- name: "@pygmalion/staff"
version: 0.1.0
digest: "review.pack-digest/v1:…"
attach: "@jeremy/root"dataDir is keyed per attach point, not per installed app — the
same app id attached to two different nodes gets two separate data
directories, each behind its own node's wall. agentproto workspace check compares each node's apps[].version range against the
resolved version recorded here and flags drift. dataDir is subject
to path confinement (below) — hosts MUST reject a lock entry whose
dataDir escapes the tree.
Sealed/hard digest: EXPORT.md
The only file an ancestor of a sealed or hard node is allowed to
read from it. schema: "workspace.export/v1" frontmatter (from,
generated_at, optional generated_by, sections), free-form prose
body:
---
schema: workspace.export/v1
from: "@jeremy/perso"
generated_at: 2026-10-17T07:00:00Z
generated_by: coach
sections: [Santé, Emploi]
---
## Santé
Rien à signaler cette semaine.
## Emploi
Deux entretiens programmés ; détails hors de portée du cerveau.Path confinement
Every tree-relative path this AIP accepts — exports[].path,
includes[].ref's #<subpath> fragment, secrets.file,
agents[].file, routines[].file, work.file, presence.file,
code.file, and
agentproto.lock's dataDir — MUST resolve inside the tree. Three
distinct failure modes, all MUST be rejected as hard errors:
- Leading
/— an absolute path escapes relativity entirely. ..traversal — any path segment equal to.., anywhere in the string (not just at the start).- Symlink escape — a path that is syntactically safe (no
/, no..) but resolves, via a symlink somewhere along it, to a location outside the tree.
The JSON Schema enforces (1) and (2) with a pattern on every
affected string field — see $defs.safeRelativePath in
WORKSPACE.schema.json. (3) is NOT detectable from the string alone:
hosts and agentproto workspace check MUST ALSO realpath-resolve
every such path and verify the result is still a descendant of the
tree root before reading, writing, or reporting its contents.
Example (workspace/v2 tree)
---
schema: workspace/v2
id: "@jeremy/simone"
version: 1.0.0
name: Simone
type: project
status: active
owner: { type: org, id: agentik, slug: jeremy }
storage:
inline: { provider: local-fs, config: { mount_path: /Users/jeremy/agentproto/agentik/simone } }
code:
inline:
path: /path/to/monorepo/projects/simone
work:
file: WORK.md
presence:
file: presence/PRESENCE.md
includes:
- { ref: "ws://workspaces/@jeremy/agentik#commun", mode: read }
secrets: { file: .secrets/SECRETS.md }
policy:
limits: [{ kind: budget-usd-per-month, value: 80 }]
---
## Description
Simone's project node. Code lives in the monorepo; this manifest is
the organigramme entry, not a second copy of the repo.Address resolution
Hosts that support cross-host addressable workspaces MUST
implement an address resolver that takes @<owner-slug>/<slug>
and returns either a workspace handle or not-found:
resolveWorkspaceAddress(addr: string): Promise<WorkspaceHandle | null>Single-app hosts resolve trivially: look up <owner-slug> in
the appropriate owner table (guilds / users / orgs), then JOIN
the matching workspace table by <slug>. Multi-app hosts iterate
owner kinds.
The slug lives on the workspace row; the owner_slug lives on
the owner row. No denormalization is required.
Workspace as repo (codespace pattern)
A workspace is just a folder of files plus a manifest. When that folder happens to be a git repo (storage.provider = github) AND has a CODE.md attached, the workspace plays the role of a codespace — a runnable code project the agent (or the user) can iterate on.
There is no separate "CODESPACE.md" primitive. The pattern is:
# WORKSPACE.md at the root of acme/marketing-bot repo
schema: workspace/v2
id: "@acme/marketing-bot"
version: 1.0.0
name: "Marketing Bot"
type: project
owner: { type: org, id: "01HQ8VR...", slug: acme }
storage:
inline:
provider: github
config: { owner: acme, repo: marketing-bot, branch: main }
sync:
pull: { on: turn-start, ttl_seconds: 30 }
commit: { on: per-turn, message_template: "{{operator}}: {{summary}}" }
push: { on: per-conversation, branch_policy: per-conversation, pr_policy: auto }
sandbox:
inline:
provider: mastra-e2b
config: { template: "code-interpreter" }
mounts:
- source: workspace
at: /workspace
mode: read-write
code:
file: "./CODE.md" # the workspace IS this code module
identity:
- { ref: "operator://current" }
- { ref: "user://current", role: "co-author" }Mounting workspaces of this kind into other workspaces (via the
host's mount/composition mechanism — typically the host's analog of
Mastra's Workspace.mounts) gives the "codespace mounted at
/marketing-bot/" experience: the parent workspace's agent can
read/write the marketing-bot repo's files at a path prefix, with
all the sync semantics declared in this WORKSPACE.md flowing
through.
The "codespace" terminology is descriptive, not normative.
Implementations MAY surface UI affordances ("This workspace is a
code project") when code is present, but this AIP does not
mandate any specific behaviour beyond "the workspace declares a
CODE.md".
Backward compatibility
A workspace without a WORKSPACE.md is still a valid workspace. Hosts MUST fall back to defaults derived from their persistence layer. Adding a WORKSPACE.md is additive — it never changes the workspace's address (which the host derives from its row).
To migrate a host into the AIP-34 model:
- On workspace creation, write a default WORKSPACE.md derived from the host's row.
- On read, prefer the manifest body over the row fields it covers.
- On row mutation, re-emit the manifest to keep them in sync.
Since 2026-10-23 (AIP-70) the canonical schema ids are workspace.lock/v1, workspace.presence/v1, workspace.export/v1, and workspace.types/v1; documents that declare agentproto-lock/v1, presence/v1, workspace-export/v1, or workspace-types/v1 remain valid, and hosts MUST accept both.
Migrating from workspace/v1
An earlier draft of this AIP shipped workspace/v1 — identity only,
no type, no tree composition. It is superseded outright by this
document: there is no v1 parser, no v1 schema file, and no tree mixing
a v1 node under a v2 one. A schema: workspace/v1 manifest is simply
not a valid AIP-34 node.
Rewriting one is small — every v1 field keeps its v2 meaning unchanged:
| v1 field | v2 |
|---|---|
schema: workspace/v1 | schema: workspace/v2 |
id, version, name, owner, storage, sandbox, code, identity, defaults, publish, tags, created_at, metadata | unchanged, carry over as-is |
| (none — new, required) | add type: pick the node's kind from the tree's TYPES.md (or write a minimal TYPES.md first if this is the first AIP-34 v2 node in the tree) |
| (none — new, all optional, all default closed/empty) | wall (default isolated), includes/exports/apps/accepted_apps/uses_secrets/agents/routines (all default []), secrets, work, status (default active), lock (default agentproto.lock) — add only the ones this node actually needs |
The only step with a real decision in it is type — everything else
is a mechanical field copy plus the discriminator flip. There is
nothing to do for a tree with no existing WORKSPACE.md at all: just
author workspace/v2 from the start.
Security considerations
WORKSPACE.md is declarative: a malicious manifest can lie
about owner or id. Hosts MUST treat the manifest as untrusted
input and verify ownership against their persistence layer at
read time. The manifest's owner.id MUST match the host row's
owner FK; mismatches MUST be flagged.
storage.ref to a registry slug crosses a trust boundary. Hosts
SHOULD validate that the resolving registry policy is acceptable
under workspace-owner policy before instantiating the backing
storage.
publish.visibility: "public" does NOT auto-publish. The
declaration is input to a downstream registry; the host decides
whether and when to honour it.
An unconfined path (see "Path confinement") is a tree-escape primitive
disguised as a content reference: exports[].path, an includes
fragment, or a lock dataDir that traverses or follows a symlink out
of the tree could expose files the wall was supposed to hide, or write
app data outside any node's control. Hosts MUST treat path confinement
failures as security-relevant, not cosmetic, errors.
An unconsented apps[].attach (see "Apps and consent") is the same
class of problem applied to app surfaces instead of files: without
the two-sided accepted_apps check, a node could grant itself tool/UI
exposure on an arbitrary OTHER node purely by declaring it, which is
exactly the privilege-escalation shape includes/exports already
guard against for raw files.
A presence document is the one block in this AIP whose output leaves
the host and is attributed to a person. A host MUST therefore treat
approval, gates and the forbidden-term list as controls, not hints:
a document pulled in through extends or ref can only narrow them
(rule 16), and a pack that ships a PRESENCE.md MUST NOT ship it with
status: active. Account credentials live only behind AIP-19 secret
slugs; a document that carries a token inline is invalid.
Open questions
-
Mounting workspaces into other workspaces.Resolved byincludes/exports(two-sided consent doors, see "Includes and exports") rather than amounts:field on the consumer alone — a provider that hasn't exported has no mount, regardless of what the consumer declares. -
Mixed-schema trees.Resolved: not supported. A tree is homogeneouslyworkspace/v2; see "Migrating from workspace/v1". -
Workspace versioning across hosts. When a workspace declared at host A is published and forked at host B, what's the lineage record? Likely a separate
LINEAGE.mdAIP. -
Per-workspace policy bundles. Workspaces may want to declare default approval policies, default agent identity bindings, default compute budgets. Whether these live in WORKSPACE.md or sibling manifests is an open call.
See also
- AIP-3 — SKILL.md — sibling manifest the workspace hosts
- AIP-14 — TOOL.md — sibling manifest the workspace hosts
- AIP-15 — WORKFLOW.md — sibling manifest the workspace hosts
- AIP-7 - GOVERNANCE.md: approval requests and signatures behind a presence document's
approvalblock - AIP-9 - OPERATOR.md: an operator's home node and seats; its sessions, not the operator, carry a node scope
- AIP-18 — COLLECTION.md / ITEM.md — item storage for the collection(s) a
work:WORK.md declares - AIP-19 — SECRETS.md —
secrets:/uses_secrets:;workspace:access entries pair withuses_secrets - AIP-20 — WORK.md — referenced from
work:; a project node's status/board, not a flat status file - AIP-23 — IDENTITY.md (identity-ref) — referenced from
identity? - AIP-25 - PERSONA.md: named by
presence.persona; carries the voice that a presence document deliberately does not restate - AIP-26 — CODE.md — referenced from
code?(workspace-as-repo) - AIP-30 — DRIVER.md — sibling manifest the workspace hosts
- AIP-35 — STORAGE.md — filesystem policy block
- AIP-36 — SANDBOX.md — sandbox/compute policy block
- AIP-37 — LIFECYCLE.md — event vocabulary referenced by sub-block lifecycles
- AIP-38 — POLICY.md —
policy.limitsbudget kinds - AIP-40 — EXTENSION.md — compilation target of each TYPES.md entry
- AIP-41 — ROUTINE.md — sibling manifest declared under
routines: - AIP-42 — AGENT.md — sibling manifest declared under
agents: - AIP-46 - SESSION: the
groundthat gives a session its node scope - AIP-53 — APP.md — referenced from
apps:/accepted_apps:andagentproto.lock - AIP-54 — ws:// resource scheme — grammar for
includes[].ref
Resources
Supporting artifacts for AIP-34. Links open the file on GitHub — markdown and JSON render natively in GitHub's viewer. Browse the full resource tree →
- EXPORT.schema.jsonaip-34/draft/EXPORT.schema.json
- LOCK.schema.jsonaip-34/draft/LOCK.schema.json
- PRESENCE.example.mdaip-34/draft/PRESENCE.example.md
- PRESENCE.schema.jsonaip-34/draft/PRESENCE.schema.json
- TYPES.schema.jsonaip-34/draft/TYPES.schema.json
- WORKSPACE.schema.jsonaip-34/draft/WORKSPACE.schema.json
AIP-33: SDK (sdk/v1): in-process SDK driver specialisation
A markdown + frontmatter format for declaring an in-process SDK driver — an npm/pip/cargo/go package that exposes named functions implementing one or more abstract TOOL contracts directly in the host runtime, without subprocess spawn or network hop. Specialises AIP-30 DRIVER for the `kind: sdk` case.
AIP-35: STORAGE (storage/v1): storage policy block
A composable schema block defining the `storage` field — provider, config, sync semantics, auth ref, exclude rules — for any manifest that names a backing store. Reused by WORKSPACE.md (AIP-34) and any future manifest that names persistent state. Inline or ref, mirroring AIP-17 RUNNER and AIP-19 SECRETS.