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".

FieldValue
AIP34
TitleWORKSPACE (workspace/v2): workspace tree node manifest
StatusReview
TypeSchema
Domainworkspace.sh
RequiresAIP-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:

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:

  1. 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.

  2. 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.

  3. No publishability. Workspaces can't be templates, exports, or registry citizens because they have no addressable id and no manifest to publish.

  4. 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 2 enumerates the substrate.

  5. 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

  1. One file per node. A workspace NODE is a folder containing exactly one WORKSPACE.md at 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 a WORKSPACE.md), never a separate parent: field that could drift from the filesystem.

  2. Identity is globally addressable and flat. id follows 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.

  3. 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.

  4. 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.

  5. 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.

  6. 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 polymorphic owner_type columns.

  7. Publish posture is opt-in. A workspace declares publish.template: true if it intends to be cloneable. The declaration is the input to a downstream registry; this AIP does not specify the registry itself.

  8. Visibility defaults closed, every crossing is two-sided. A node's wall defaults to isolated: 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

FieldTypeDescription
schemastringAlways workspace/v2.
idstringGlobally addressable, FLAT id: @<owner-slug>/<workspace-slug>. Lowercase, digits, dashes. Immutable — survives the node moving to a different folder.
versionsemver stringRevision of THIS manifest instance. See "On version vs. schema" above.
namestringHuman-readable display name. 1–80 chars.
typestringNode 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.
ownerobject{ type: "guild" | "user" | "org", id: string, slug: string }. The slug participates in the addressable id above and MUST match its slug suffix.
storageobjectFilesystem policy: { inline: <STORAGE.md frontmatter body> } or { ref: "<path or registry slug>" } or { file: "<path>" }. See AIP-35.

Optional fields

FieldTypeDefaultDescription
descriptionstring""One-paragraph purpose. ≤2000 chars.
statusenum"active""active" | "paused" | "archived". See "Node status: active / paused / archived" below.
sandboxobject(none)Sandbox policy: inline / ref / file. See AIP-36. Optional — when absent, command-execution tools MUST be unavailable.
codeobject(none)Code policy: inline / ref / file. See AIP-26. Optional — when present, the workspace IS a code-workspace / repo (see "Workspace as repo" below).
workobject(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.
presenceobject(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.
identityobject | 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.
wallenum"isolated"Visibility level: "shared" | "isolated" | "sealed" | "hard". See "The four wall levels" below.
includesarray[]{ 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".
exportsarray[]{ 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".
agentsarray[]{ 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).
routinesarray[]{ file } — AIP-41 ROUTINE.md manifests this node hosts.
secretsobject(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_secretsarray[]{ 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").
appsarray[]{ 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_appsarray[]{ from: <id>, app?: <id> }. Provider-side consent for an apps[].attach pointed at THIS node by another node. See "Apps and consent".
policyobject | 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".
defaultsobject{}{ read_only: bool } and other workspace-wide defaults.
publishobject{ template: false, visibility: "private" }Publish posture: { template: bool, registry?: string, visibility: "private" | "unlisted" | "public" }.
tagsstring[][]Free-form discovery tags.
created_atstring (ISO 8601)noneCreation timestamp.
lockstring"agentproto.lock"Tree-relative path to this node's apps/packs lockfile. Only meaningful on a node that attaches apps/packs directly.
metadataobject{}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

  1. One WORKSPACE.md per node. A node is a folder with exactly one WORKSPACE.md. Nested WORKSPACE.md files ARE nodes — every one under a tree root is read, none are "the only one that counts" — with the nearest ancestor WORKSPACE.md as the implicit parent (a folder with no manifest of its own is simply part of its nearest ancestor's node).

  2. id is immutable. Once set, never changes. Renaming the workspace mutates name, never id. Moving the node to a different folder (ws mv) rewrites the path, never the id. Hosts that need to change id MUST treat the result as a new workspace.

  3. owner.slug and the slug suffix of id MUST match. A workspace at @acme-corp/marketing-ops MUST have owner.slug = "acme-corp". Validators MUST reject mismatches.

  4. storage.inline and storage.ref are mutually exclusive. Exactly one form per WORKSPACE.md (same for sandbox, code, work, presence).

  5. No I/O at parse time. Reading WORKSPACE.md MUST NOT trigger credential resolution, network calls, or storage instantiation. Hosts materialize storage lazily.

  6. A node's type MUST resolve in the nearest ancestor TYPES.md, and that type's parents MUST 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.

  7. wall MUST NOT be looser than the type's default_wall. Ordered shared < isolated < sealed < hard; a node MAY only equal or exceed its floor.

  8. An includes entry is inert without a matching exports entry on the target, and vice versa — see "Includes and exports". Doors are two-sided by construction; there is no single-sided override.

  9. Secrets are never inherited. A node's effective secret set is exactly its own .secrets/SECRETS.md plus whatever uses_secrets entries have a matching grant. Nothing else, regardless of wall level or ancestry.

  10. A child's resolved budget is bounded by its parent's. See "Budgets aggregate".

  11. 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.

  12. An apps[].attach pointed at a DIFFERENT node is inert without a matching accepted_apps entry on that target — same two-sided consent as includes/exports/secrets. See "Apps and consent".

  13. Paths MUST be tree-relative and confined. exports[].path, includes[].ref fragments, secrets/agents/routines/work/ presence/code file refs, and agentproto.lock's dataDir MUST NOT escape the tree via .. traversal, a leading /, or a symlink. See "Path confinement".

  14. 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 is paused or archived. See "Node status: active / paused / archived".

  15. A declared presence: MUST resolve to a parseable workspace.presence/v1 document, and its effective (merged) form MUST name a persona. presence: itself is optional; this rule only fires when it IS declared. A presence.file or extends path that escapes the tree is a hard error (rule 13).

  16. Presence only narrows down an extends chain. Forbidden terms are never removed, approval is never weakened, an open gate is 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 is draft or paused, nor for a node whose effective node status (rule 14) is not active. 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

LevelNameWhat crossesMechanism
0sharedThis 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.
1isolated (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").
2sealedLike 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".
3hardLike 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 a WORKSPACE.md (rule 1); a folder without one belongs to its nearest declared ancestor. The ground is an AIP-54 ref and MAY carry a subtree body, written with slashes as in local-body: ws://workspaces/@acme/agentik/simone/docs is the subtree simone/docs of workspace @acme/agentik. The node scope is the nearest declared node containing that folder, which is simone if it declares a WORKSPACE.md and @acme/agentik otherwise. 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/agentik and another in @jeremy/perso is 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 ground lies in no declared node (a workspace with no WORKSPACE.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.

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[].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 as archived. Unlike archived, it stays writable and resumes by flipping status back to active.
  • 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: archived

Presence 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:

ConcernAlready covered byGap this block fills
Voice, tone, register, self-declared limitsAIP-25 PERSONA.md (voice, boundaries)Words that may never appear belong to the project, not to a reusable persona
What the node works onAIP-20 WORK.md (work:)Nothing about what is said in public
Limits and budgetsAIP-38 POLICY.md (policy:)No notion of a channel, a topic or a published piece
Approval requests and signaturesAIP-7 GOVERNANCE.mdNo policy that names which pieces need approval and who approves
Account credentialsAIP-19 SECRETS.mdNo link between a secret and a channel
Company-wide defaultsAIP-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

FieldTypeDescription
schemaconst workspace.presence/v1Required.
name, title, description, versionstringsRequired. name is kebab-case, 2 to 64 chars.
statusenumRequired. draft, active or paused.
extendspathRelative path to a parent workspace.presence/v1 document (for example company defaults).
personapath or ws refThe AIP-25 PERSONA.md that carries the voice. Required in the effective document.
audienceobjectprimary, pains[], notTargeted[].
topicsobjectpillars[] (id, title, angle) and exclude[].
lexiconobjectforbidden[] (term, reason, instead) and required[] (phrase, context).
channelsarrayOne 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.
watchobjectWhat to read before commenting: keywords, accounts, hashtags, communities, commentRules.
approvalobjectmode (always or policy:<ref>) and approver (a principal ref).
gatesarrayid, description, status (open or cleared), blocks (any of links, posts, comments, channel:<id>).
examplesobjectgood[] and bad[] pieces (text, why, channel) used to calibrate drafts.
reviewobjectcadence (weekly or monthly), day, kpis[].
metadataobjectNamespaced 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 individual review fields. A child persona SHOULD itself extend the parent's persona; hosts MAY warn when it does not.
  • Union, never removable: lexicon.forbidden (by term, compared case-insensitively), topics.exclude, and every watch.* array. A child may add a reason or instead to an inherited term, never drop the term.
  • Union by key: lexicon.required (by phrase), topics.pillars and channels (by id; the child overrides fields of the same id), gates (by id), examples (child entries first).
  • Tighten only: approval.mode (always is the strictest, so a child of an always parent MUST be always) and a channel's actions (a child may turn post or comment from true to false, 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 open if either declaration is open.
  • Status: the effective presence status is the most restrictive along the extends chain (paused over draft over active).

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

  1. Draft against it. The agent that writes a piece reads the effective document: persona for voice, topics for subject, watch for what to read before a comment, examples for calibration.
  2. 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 required phrase covers without using the phrase verbatim.
  3. Honour gates. An open gate blocks the listed kinds of action: links forbids any URL in a piece, posts and comments forbid those actions on every channel, channel:<id> forbids everything on that channel.
  4. Ask a human. With approval.mode: always, every piece waits for the approver (AIP-7). What is approved is what is sent: the text is byte-identical, and any edit after approval voids the approval.
  5. Send through the declared provider. The provider named in publish.<action> (or else connection.provider) performs the action. If that provider is not connected, the action stays pending; a host MUST NOT silently route it through another provider.
  6. Report. The review block 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:

  1. Leading / — an absolute path escapes relativity entirely.
  2. .. traversal — any path segment equal to .., anywhere in the string (not just at the start).
  3. 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:

  1. On workspace creation, write a default WORKSPACE.md derived from the host's row.
  2. On read, prefer the manifest body over the row fields it covers.
  3. 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 fieldv2
schema: workspace/v1schema: workspace/v2
id, version, name, owner, storage, sandbox, code, identity, defaults, publish, tags, created_at, metadataunchanged, 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

  1. Mounting workspaces into other workspaces. Resolved by includes/exports (two-sided consent doors, see "Includes and exports") rather than a mounts: field on the consumer alone — a provider that hasn't exported has no mount, regardless of what the consumer declares.

  2. Mixed-schema trees. Resolved: not supported. A tree is homogeneously workspace/v2; see "Migrating from workspace/v1".

  3. 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.md AIP.

  4. 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

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 →