From e16bffa8dbe06942786cd271a83e554c058c637f Mon Sep 17 00:00:00 2001
From: Onur Solmaz <onur@textcortex.com>
Date: Fri, 13 Mar 2026 09:51:10 +0100
Subject: [PATCH] docs(cli): define spawn language for workspaces

---
 cli/skills/spz/SKILL.md                       |  5 +-
 cli/test/skillflag.test.ts                    |  2 +
 ...-13-spawn-language-for-agent-workspaces.md | 95 +++++++++++++++++++
 3 files changed, 101 insertions(+), 1 deletion(-)
 create mode 100644 docs/2026-03-13-spawn-language-for-agent-workspaces.md

diff --git a/cli/skills/spz/SKILL.md b/cli/skills/spz/SKILL.md
index 593696b..3db2e9f 100644
--- a/cli/skills/spz/SKILL.md
+++ b/cli/skills/spz/SKILL.md
@@ -1,6 +1,6 @@
 ---
 name: spz
-description: Use the spz CLI to provision, inspect, and access Spritz workspaces, including service-principal create flows, preset-based provisioning, canonical access URLs, and ACP-ready workspace operations.
+description: Use the spz CLI to spawn, provision, inspect, and access Spritz workspaces, including service-principal create flows, preset-based provisioning, canonical access URLs, and ACP-ready workspace operations.
 ---
 
 # spz
@@ -11,6 +11,7 @@ Use this skill when you need to interact with a Spritz control plane through the
 
 Typical cases:
 
+- spawn a new agent workspace from a preset such as `openclaw` or `claude-code`
 - create a new workspace from a preset such as `openclaw` or `claude-code`
 - create a workspace on behalf of a user with a service-principal bearer token
 - suggest a DNS-safe random name for a workspace
@@ -22,6 +23,8 @@ Typical cases:
 
 Spritz is a control plane for agent workspaces.
 
+In user-facing agent language, `spawn` means `create a Spritz workspace for an agent`.
+
 Core model:
 
 - a workspace is a `Spritz` resource
diff --git a/cli/test/skillflag.test.ts b/cli/test/skillflag.test.ts
index 0aa64a4..7d06145 100644
--- a/cli/test/skillflag.test.ts
+++ b/cli/test/skillflag.test.ts
@@ -38,8 +38,10 @@ test('skillflag show returns the bundled spz skill body', async () => {
   const result = await runCli(['--skill', 'show', 'spz']);
   assert.equal(result.code, 0, result.stderr);
   assert.match(result.stdout, /# spz/);
+  assert.match(result.stdout, /Use the spz CLI to spawn, provision, inspect, and access Spritz workspaces/i);
   assert.match(result.stdout, /service-principal create flow/i);
   assert.match(result.stdout, /--owner-provider discord/i);
+  assert.match(result.stdout, /spawn a new agent workspace from a preset/i);
   assert.match(result.stdout, /never pass a Discord, Slack, or Teams user ID through `--owner-id`/i);
   assert.match(result.stdout, /connect their account/i);
   assert.match(result.stdout, /ask for\s+clarification instead of guessing/i);
diff --git a/docs/2026-03-13-spawn-language-for-agent-workspaces.md b/docs/2026-03-13-spawn-language-for-agent-workspaces.md
new file mode 100644
index 0000000..7fcddbc
--- /dev/null
+++ b/docs/2026-03-13-spawn-language-for-agent-workspaces.md
@@ -0,0 +1,95 @@
+---
+date: 2026-03-13
+author: Onur Solmaz <onur@textcortex.com>
+title: Spawn Language for Agent Workspaces
+tags: [spritz, wording, cli, agents]
+---
+
+## Overview
+
+This document defines `spawn` as the preferred user-facing verb for starting an
+agent in a Spritz-backed system.
+
+In plain language:
+
+- `spawn an agent` means `create a Spritz workspace for that agent`
+- the technical system action is still `create` / `provision`
+- the stored resource is still a `workspace`
+
+This is a vocabulary rule, not a data model change.
+
+## Definition
+
+Use `spawn` when the human intent is:
+
+- start a fresh agent workspace
+- make that agent reachable through its returned URLs or terminal access
+- create the workspace from a preset such as `openclaw` or `claude-code`
+
+Do not use `spawn` to mean:
+
+- start a local child process
+- fork an existing workspace
+- duplicate a conversation
+- create a new owner identity
+
+## Rules
+
+When an agent or operator says `spawn`, interpret it as:
+
+1. resolve who the workspace is for
+2. resolve what preset or workspace spec should be used
+3. call Spritz create
+4. report back with what was spawned and how to open it
+
+Keep the canonical technical language unchanged:
+
+- API actions stay `create`
+- provisioning remains `provisioning`
+- the resource remains a `workspace`
+- ownership remains the internal Spritz owner model
+
+## CLI and Skill Guidance
+
+The bundled `spz` skill should understand `spawn` as shorthand for creating a
+Spritz workspace.
+
+Expected behavior:
+
+- if a user asks to `spawn` an agent, use `spz create`
+- if the owner is an external platform user, use external owner flags rather
+  than treating the platform ID as `--owner-id`
+- if preset, provider, subject, or tenant is unclear, ask for clarification
+- after success, report the spawned workspace name and returned open URLs
+
+## Examples
+
+User-facing request:
+
+```text
+Spawn a claude-code agent for me.
+```
+
+Technical action:
+
+```bash
+spz create --preset claude-code ...
+```
+
+User-facing request:
+
+```text
+Spawn an openclaw agent for this Discord user.
+```
+
+Technical action:
+
+```bash
+spz create --preset openclaw --owner-provider discord --owner-subject 123456789012345678 ...
+```
+
+## Validation
+
+The bundled `spz` skill description and examples should include the word
+`spawn` so agents learn the intended vocabulary at the skill boundary.
+