unity-workflow

Before calling any skill in this module: if you are about to call a skill with parameters guessed from its name or description, STOP — read this file (or fetch its schema via GET /skills/recommend?includeSchema=true) first. If you already have the parameter definitions from recommend/schema, you may proceed straight to dryRun.

Triggers

• Undoing a whole task or session
• Snapshotting before risky changes
• Planning/previewing batch operations
• Rolling back
• Undo an entire task or session, snapshot before high-risk changes, plan/preview batch operations, roll back

Workflow Skills

Persistent history and rollback system for AI operations ("Time Machine"). Allows tagging tasks, snapshotting objects before modification, and undoing specific tasks even after Editor restarts.

NEW: Session-level undo - Group all changes from a conversation and undo them together.

Operating Mode

• Approval: Most skills in this module are marked SkillMode.SemiAuto(pure read queries in the bookmark / history / task / session series + workflow_plan, the latter with ReadOnly=true only generates an aggregation plan), and can be executed directly. Skills with side effects (bookmark_set / bookmark_goto / workflow_snapshot_object / workflow_snapshot_created / batch_retry_failed) follow the default SkillMode.FullAuto, and require a grant.
• Auto / Bypass: FullAuto executes directly.
• Contains NeverInSemi high-risk skills：bookmark_delete / workflow_delete_task(marked Operation.Delete, deletes bookmark/task records),workflow_clear_history(Operation.Delete + RiskLevel=high, clears all history + redo stack + file storage, irreversible). Under Approval/Auto these return MODE_FORBIDDEN, and can only be invoked under Bypass or when matched by Allowlist.

Note:workflow_undo_task / workflow_session_undo are not Delete operations (they are marked Modify/Execute); they can directly undo recorded tasks under Approval/Auto.

Surface profile: workflow_undo_task / workflow_redo_task / workflow_revert_task / workflow_session_undo inspect every snapshot the target task(s) would restore. If any snapshot would author a category the active profile withdraws — a scene GameObject, or a .unity / .mat asset — the whole call is refused with SURFACE_EXCLUDED (surfaceProfile/category/operation/manualDoc/userControlled/hint at the top level, not nested under details) rather than partially applied. Snapshots of scripts, prefabs, textures, ScriptableObjects, and Editor/project settings are unaffected — those stay undoable under every profile.

DO NOT (common hallucinations):

• workflow_save does not exist → use workflow_task_end to end and save a task
• workflow_rollback does not exist → use workflow_undo_task (by taskId) or workflow_session_undo (by sessionId)
• workflow_create does not exist → use workflow_task_start
• workflow_revert_task is deprecated → use workflow_undo_task

Routing:

• For simple undo/redo (1 step) → editor_undo / editor_redo (editor module)
• For multi-step undo → history_undo with steps parameter (this module)
• For conversation-level undo → workflow_session_undo (this module)

Bookmark Skills

bookmark_set

Save current selection and scene view position as a bookmark.

Parameter	Type	Required	Default	Description
bookmarkName	string	Yes	-	Name for the bookmark
note	string	No	null	Optional note for the bookmark

Returns: { success, bookmark, selectedCount, hasSceneView, note }

bookmark_goto

Restore selection and scene view from a bookmark.

Parameter	Type	Required	Default	Description
bookmarkName	string	Yes	-	Name of the bookmark to restore

Returns: { success, bookmark, restoredSelection, note }

bookmark_list

List all saved bookmarks.

No parameters.

Returns: { success, count, bookmarks: [{ name, selectedCount, hasSceneView, note, createdAt }] }

bookmark_delete

Delete a bookmark.

Parameter	Type	Required	Default	Description
bookmarkName	string	Yes	-	Name of the bookmark to delete

Returns: { success, deleted }

History Skills

history_undo

Undo the last operation (or multiple steps).

Parameter	Type	Required	Default	Description
steps	int	No	1	Number of undo steps to perform

Returns: { success, undoneSteps }

history_redo

Redo the last undone operation (or multiple steps).

Parameter	Type	Required	Default	Description
steps	int	No	1	Number of redo steps to perform

Returns: { success, redoneSteps }

history_get_current

Get the name of the current undo group.

No parameters.

Returns: { success, currentGroup, groupIndex }

Planning And Batch Governance

workflow_plan

Generate a combined execution plan for multiple skills on the server side.

Parameter	Type	Required	Default	Description
skillsJson	string	Yes	-	JSON array of { "name": "...", "params": { ... } } entries

Returns: { totalSteps, totalRisk, steps, dependencies, warnings, mayDisconnect }

batch_query_assets

Query project assets with filters that are useful before batch cleanup or migration work.

Parameter	Type	Required	Default	Description
searchFilter	string	No	-	Extra AssetDatabase.FindAssets filter text
folder	string	No	Assets	Search root
typeFilter	string	No	-	Asset type filter such as t:Material or Prefab
namePattern	string	No	-	Regex applied to file name without extension
labelFilter	string	No	-	Asset label filter such as l:Addressable
maxResults	int	No	200	Max assets returned

Returns: { count, totalMatched, summary, assets }

batch_retry_failed

Retry only the failed items from an earlier batch execution report. This now reuses the original operation context stored in the report.

Parameter	Type	Required	Default	Description
reportId	string	Yes	-	Source report ID from batch_report_get / batch_report_list
runAsync	bool	No	true	Return a jobId immediately or wait for completion
chunkSize	int	No	100	Chunk size for retry execution

Returns: { status, jobId?, retryCount, originalReportId, reportId? }

Session Management (Conversation-Level Undo)

workflow_session_start

Start a new session (conversation-level). All changes will be tracked and can be undone together. Call this at the beginning of each conversation.

Parameter	Type	Required	Default	Description
tag	string	No	null	Label for the session

Returns: { success, sessionId, message }

workflow_session_end

End the current session and save all tracked changes. Call this at the end of each conversation.

No parameters.

Returns: { success, sessionId, message }

workflow_session_undo

Undo all changes made during a specific session (conversation-level undo).

Parameter	Type	Required	Default	Description
sessionId	string	No	null	The UUID of the session to undo. If not provided, undoes the most recent session

Returns: { success, sessionId, message }

workflow_session_list

List all recorded sessions (conversation-level history).

No parameters.

Returns: { success, count, currentSessionId, sessions: [{ sessionId, taskCount, totalChanges, startTime, endTime, tags }] }

workflow_session_status

Get the current session status.

No parameters.

Returns: { success, hasActiveSession, currentSessionId, isRecording, currentTaskId, currentTaskTag, currentTaskDescription, snapshotCount }

Task-Level Skills

workflow_task_start

Start a new persistent workflow task to track changes for undo. Call workflow_task_end when done.

Parameter	Type	Required	Default	Description
tag	string	Yes	-	Short label for the task (e.g., "Create NPC")
description	string	No	""	Detailed description or prompt

Returns: { success, taskId, message }

workflow_task_end

End the current workflow task and save it. Requires an active task (call workflow_task_start first).

No parameters.

Returns: { success, taskId, snapshotCount, message }

workflow_snapshot_object

Manually snapshot an object's state before modification. Requires an active task (call workflow_task_start first). Call this BEFORE component_set_property, gameobject_set_transform, etc.

Parameter	Type	Required	Default	Description
name	string	No	null	Name of the Game Object
instanceId	int	No	0	Instance ID of the object (preferred)

Returns: { success, objectName, type }

workflow_snapshot_created

Record a newly created object for undo tracking. Requires an active task (call workflow_task_start first). Note: component_add and gameobject_create automatically record created objects, so you typically don't need to call this manually.

Parameter	Type	Required	Default	Description
name	string	No	null	Name of the Game Object
instanceId	int	No	0	Instance ID of the object (preferred)

Returns: { success, objectName, type }

workflow_list

List persistent workflow history.

No parameters.

Returns: { success, count, history: [{ id, tag, description, time, changes }] }

workflow_undo_task

Undo changes from a specific task (restore to previous state). The undone task is saved and can be redone later.

Parameter	Type	Required	Default	Description
taskId	string	Yes	-	The UUID of the task to undo

Returns: { success, taskId }

workflow_redo_task

Redo a previously undone task (restore changes).

Parameter	Type	Required	Default	Description
taskId	string	No	null	The UUID of the task to redo. If not provided, redoes the most recently undone task

Returns: { success, taskId }

workflow_undone_list

List all undone tasks that can be redone.

No parameters.

Returns: { success, count, undoneStack: [{ id, tag, description, time, changes }] }

workflow_revert_task

(deprecated) Alias for workflow_undo_task. Use workflow_undo_task instead.

Parameter	Type	Required	Default	Description
taskId	string	Yes	-	The UUID of the task to undo

Returns: { success, taskId }

workflow_delete_task

Delete a task from history (does not revert changes, just removes the record).

Parameter	Type	Required	Default	Description
taskId	string	Yes	-	The UUID of the task to delete

Returns: { success, deletedId }

workflow_clear_history

Permanently clear ALL workflow history: every task, the redo (undone) stack, and every backed-up file blob in the content-addressed store. High-risk and irreversible. This ONLY deletes tracking history — it does NOT undo or revert any change already applied to your project assets, scenes, or settings. To roll changes back, use workflow_undo_task / workflow_session_undo before clearing.

Marked SkillOperation.Delete + RiskLevel="high", so it is NeverInSemi (returns MODE_FORBIDDEN in Approval/Auto; only Bypass or an Allowlist hit can call it).

Parameters: None

Returns: { success, before, after, message } where before/after each report { tasks, undoneStack, historyFileBytes, fileStoreBytes }.

Snapshot Mechanism

History is persisted to workflow_history.json (schemaVersion 5). Asset and .meta bytes are independently content-addressed in Library/UnitySkills/workflow_files/<sha1>; history keeps fileHash / metaFileHash references. Schema 2/3 histories are migrated atomically: legacy blobs are made durable before inline base64 is removed.

Snapshots are tiered by SnapshotType:

Type	Trigger	What is stored	Undo behavior
Created	New asset/folder	path + GUID only	Delete the created asset/folder
Moved	asset_move	old + new path only	Move back to the old path
Deleted	asset_delete etc.	file + .meta moved into the store	Full restore, including .cs scripts (old implementation could not restore .cs)
Modified	material / SO / scene / uss / uxml / shadergraph …	content-addressed backup + lightweight originalJson	Restore the backed-up bytes
Setting	editor / project settings	handled via WorkflowSettingRestorerRegistry	Registry restores the previous value

Undo/redo return per-snapshot detail (TaskUndoResult: total / succeeded / failed / details / error). Operations run in reverse order; on the first failure, failed and unprocessed snapshots stay on their source stack so they can be retried.

Auto-clean

WorkflowAutoCleanConfig (EditorPrefs keys UnitySkills.Workflow.*) trims history and the file store after EndTask and after LoadHistory. Defaults: MaxTasks=200, MaxHistoryMB=32, MaxTaskAgeDays=30, MaxStoreMB=512, StoreMaxAgeDays=7. Store age/size pruning never removes a blob referenced by retained history. A value of 0 disables that individual limit.

Settings are now truly revertible

Setting-class skills used to be one-way; they now register a restorer and can be rolled back: console_set_pause_on_error / console_set_collapse / console_set_clear_on_play, debug_set_defines, graphics_set_quality_level / graphics_set_default_render_pipeline / graphics_set_quality_render_pipeline / graphics_add_always_included_shader / graphics_remove_always_included_shader / graphics_set_shader_stripping, physics_set_gravity / physics_set_layer_collision, project_add_tag.

Cinemachine's 28 write skills now set TracksWorkflow=true (the snapshot code existed but never auto-triggered). scene_save / scene_create are now rollback-capable (scene_save over an existing scene backs up the old file as a Modified snapshot).

Known Limitations

• scene_save undo restores the on-disk .unity file; if the scene is currently open, you must Reload Scene for the restore to take effect.
• Objects created in a never-saved scene: their GlobalObjectId becomes invalid across an Editor restart, so undo will mark them as failed in the result detail.
• External side effects (Package Manager operations, etc.) cannot be rolled back.

Minimal Example

import unity_skills

# Session-level: wrap entire conversation for bulk undo
unity_skills.call_skill("workflow_session_start", tag="Build Player")
unity_skills.call_skill("gameobject_create", name="Player", primitiveType="Capsule")
unity_skills.call_skill("component_add", name="Player", componentType="Rigidbody")
unity_skills.call_skill("workflow_session_end")
# Later: undo entire session
sessions = unity_skills.call_skill("workflow_session_list")
unity_skills.call_skill("workflow_session_undo", sessionId=sessions["sessions"][0]["sessionId"])

Auto-Tracked Operations

The following operations are automatically tracked for undo when a session/task is active:

• gameobject_create / gameobject_create_batch
• gameobject_duplicate / gameobject_duplicate_batch
• component_add / component_add_batch
• ui_create_* (canvas, button, text, image, etc.)
• light_create
• prefab_instantiate / prefab_instantiate_batch
• material_create / material_duplicate
• terrain_create
• cinemachine_create_vcam

For modification operations, the system auto-snapshots target objects before changes when possible.

Exact Signatures

Exact names, parameters, defaults, and returns are defined by GET /skills/schema or unity_skills.get_skill_schema(), not by this file.