skills

2026-06-02 04:18:55 +07:00
parent 4e28c8db5d
commit e6bb5d6514
8 changed files with 373 additions and 0 deletions
@@ -0,0 +1,72 @@
+# Draft Workspaces Reference
+
+Use draft workspaces for iterative workflow authoring. They are mutable and
+revisioned; artifacts are immutable and versioned.
+
+## Draft Shape
+
+A draft has:
+
+- `name`
+- `input_schema`
+- `state_schema`
+- `output_schema`
+- `start`
+- `steps`
+- `routes`
+- optional top-level `output`
+
+`steps` are keyed by stable ids. `routes` map outcomes to another step id or
+`__end__`.
+
+## Mapping Rules
+
+Step input bindings read graph values into node-local input:
+
+```json
+{
+  "target": { "root": "local", "parts": ["text"] },
+  "path": { "root": "input", "parts": ["text"] }
+}
+```
+
+Step output bindings write node-local output into workflow state:
+
+```json
+{
+  "source": { "root": "local", "parts": ["echoed"] },
+  "target": { "root": "state", "parts": ["echoed"] }
+}
+```
+
+Top-level workflow output uses `path` / `target`, not step-level
+`source` / `target`:
+
+```json
+{
+  "path": { "root": "state", "parts": ["echoed"] },
+  "target": { "root": "local", "parts": ["echoed"] }
+}
+```
+
+## Workspace Flow
+
+1. Create workspace from capability.
+2. Get workspace with `include_draft=true` before patching.
+3. Patch with current `revision`.
+4. Validate workspace.
+5. Save artifact or wrapper from workspace.
+
+If a patch returns `revision_conflict`, fetch the workspace again and retry
+against the latest revision.
+
+## Focused Helpers
+
+Prefer focused helpers over JSON Patch for common edits:
+
+- `set_draft_name`
+- `set_draft_route`
+- `set_step_input_map`
+- `set_step_output_map`
+
+Use JSON Patch for structural edits the helpers do not cover.