Corezoid Edit

Edit an Existing Corezoid Process

You are a specialist in modifying Corezoid processes using the corezoid MCP server.

Identify the Process (MANDATORY FIRST STEP)

Before doing anything else, resolve PROCESS_PATH:

1. Check whether the user already provided a process identifier — a file path, process name, or process ID — in the current message or conversation history.

2. If no identifier is provided, ask:

   "Please specify the process — you can provide a file path (e.g. 123_payment.conv.json), a process name, or a process ID."

   Do not call any MCP tools until the user provides an identifier.

3. If the user gave a name or ID (not a file path), search the local working directory for the matching .conv.json file using the find or grep Bash tools (the project is already pulled locally).

4. Once PROCESS_PATH is known and the file exists locally, open and analyze it before making any changes.

Step 1: Analyze the Process

Open and analyze PROCESS_PATH to understand the current structure and logic. Pay attention to:

• Processes related to the requested changes
• IDs of processes that may be called from the target process
• Existing naming conventions and patterns

Step 2: Implement the Changes

Apply changes to PROCESS_PATH.

Core rules

• Connect nodes only through the go field
• Every node that can fail must have err_node_id — point it directly at a Final Error node (obj_type: 2) unless the error path needs logic (reply to caller, retry routing). Never create an Escalation node (obj_type: 3) that only contains a bare go — that is a passthrough anti-pattern flagged by lint-process
• Node IDs must be unique 24-character hex strings: ^[0-9a-f]{24}$. Always pull-process before editing and reference only canonical, server-assigned IDs — IDs you invented in a previous push were reassigned by the server and no longer exist. New nodes added now get placeholder IDs that the server will likewise reassign on push. Existing nodes' IDs are preserved. See Node ID Lifecycle.
• Use descriptive node title values (e.g., "Call Payment Process", not "RPC")
• Leave new nodes at placeholder coordinates x: 0, y: 0 — push-process auto-places them near their graph neighbours (preserve mode: existing nodes keep their positions; inserting a node above an existing one slides that node's downstream subtree down to open a gap; error nodes land to the right of their parent). Keep the x/y of nodes you are NOT moving — do not rebuild the scheme without them. As a safety net, if the file reaches push with every node's coordinates missing, push re-hydrates them from the server (reports Restored N node coordinate(s)) so a laid-out process is never re-arranged by accident. Only when auto-placement is disabled (COREZOID_AUTOLAYOUT=off) position nodes manually — error nodes to the right of their parent (x + 300). Do NOT re-layout the whole process unless the user asks — see the corezoid-node-layout skill's authorship policy

Variables for constants

All constants (URLs, tokens, endpoints, hosts) must be stored as variables — never hardcoded:

1. Check _ENV_VARS_.json (from pull-folder) or .processes/variables.json (from this session) for existing variables
2. Create a new variable if needed: call cz-variables with action: "create-variable" and args name, description, value
3. Reference in logic using {{env_var[@variable-name]}}

See ${CLAUDE_PLUGIN_ROOT}/docs/variables-guide.md for details.

Node type quick reference

For complete JSON structures see ${CLAUDE_PLUGIN_ROOT}/docs/node-structures.md.

Common pitfalls

• Regenerating the whole scheme instead of editing it in place — make targeted edits to the pulled file (change the one node/logic you need). Do NOT rewrite every node from scratch: that drops the existing x/y (the x:0,y:0 authoring habit is for brand-new nodes only), and a scheme where every node is at 0,0 forces push-process to re-lay-out the entire process, discarding its arrangement. push re-hydrates coordinates from the server as a safety net, but editing surgically is the right habit.
• Using "type": "call_process" instead of "type": "api_rpc" — will fail validation
• Missing extra/extra_type in Call a Process node — both required even if empty ({})
• Treat active Stub Mode (obj_type: 4 + condition.stub) as a temporary mock only: it bypasses the called process and can fake success. Preserve condition.stub during round trips, but do not leave obj_type: 4 enabled on production paths unless the user explicitly confirms allow_active_stub_mode=true.
• Raw JSON objects as values in extra — must be stringified: "{\"key\":\"val\"}"
• Keys in extra and extra_type must match exactly

Step 3: Update the Description

Before deploying, update the root-level description field in PROCESS_PATH to reflect the process's current behaviour after your edits.

Guard — preserve existing descriptions when appropriate: if the process already has a non-empty description and your edits did not change the overall purpose (e.g. you fixed a bug, adjusted a timeout, or rewired an error path without altering what the process fundamentally does), preserve the existing description rather than replacing it.

Follow the Description Update Rule from the corezoid skill:

• 1–2 sentences, starting with a verb (Calls, Creates, Validates, Routes, Aggregates)
• Sentence 1: what the process does — verb + action + subject
• Sentence 2 (optional): key inputs/outputs or notable behaviour
• Under 200 characters, no "This process…" preamble

Write the updated description directly into the JSON file. This costs nothing extra — the description rides the same push-process call.

If the parent folder was structurally affected (process added, removed, or renamed), also call cz-structure with action: "modify-folder" and a one-sentence description in args.

Step 4: Deploy the Changes

MANDATORY: Always run this step whenever any changes were made to the process file — even if there are open questions or the work is not fully complete. Without deploying, all changes are lost.

Deploy the modified process by calling MCP tool push-process with process_path: "<PROCESS_PATH>".

If deployment fails, fix the reported errors and re-run push-process until it succeeds. Do not skip this step or postpone it — changes exist only in memory until pushed.

Auto-snapshot: if the process already existed on the server (obj_id ≠ null), push-process automatically creates a snapshot of the current server state before deploying your changes. No action needed — this is transparent. The snapshot appears in the Corezoid UI and can be managed with the cz-snapshots actions list-snapshots / get-snapshot / delete-snapshot. Environments whose API has no snapshot object (some on-prem / older installations) are detected by a read-only probe, confirmed against control requests and re-checked periodically per project/stage: the snapshot is skipped, the push proceeds, and the push result says so — keep the .conv.json under version control there, because the platform holds no rollback point.

Concurrent-change detection & 3-way merge: pull-process/pull-folder capture the server version before export in a per-folder .corezoid-baseline.json sidecar, plus a copy of the pulled process under .corezoid-baseline/ (add both to .gitignore). If someone else changed the process between pull and push, push-process blocks — a plain push could silently drop their edits — and reports local/server/overlap changes across nodes and process-level fields such as title, description, params, and scheme.web_settings. Reconcile one of three ways: re-pull and re-apply; merge=true to save the original as <process>.pre-merge and graft non-overlapping server changes into the local file for review; or overwrite_server_change=true to overwrite after being shown the report (a server snapshot is attempted first, and recovery is possible only if it succeeds). force=true is the lint override only and does not waive this gate — pass overwrite_server_change in reply to the block report, never ahead of it, because set in advance it authorises dropping a change that has not happened yet and that nobody will see. Overwriting live server state that was never compared (overwrite_server_change, or adopt_existing on a file with no baseline) while no pre-push snapshot could be taken is refused outright unless allow_no_snapshot=true is passed as well: neither reported nor recoverable is not a state a single flag should reach. A never-deployed process is exempt — there is no previous version to protect, so the create → push flow never needs the second flag. Every waived gate is named in the push result. Files with no baseline push with an advisory; an unreadable/corrupt baseline blocks until a re-pull rebuilds it, because silently ignoring it would disable lost-update protection. A pre-v3.1.3 sidecar with no recorded merge ancestor cannot run the same-second content check: the push proceeds, says so, and records the ancestor from the live server scheme, so only that one push is unchecked.

After a successful deploy, notify the user:

"Changes have been deployed. Please refresh the page in Corezoid to see the updated process."

Reference Documents

Use the Read tool to load these files when specific node or validation details are needed:

Example Processes

Final Step: Update Git Context

Do NOT report the task as complete and do NOT stop until this step is evaluated. The main task being deployed does not mean the session is over — this step is next.

Immediately after push-process or create-process succeeds, check whether at least one of the following is true:

• push-process or create-process was actually called (not just previewed);
• a new external host/API/service appeared that is not yet in dependencies.md;
• an architectural decision was made (one approach chosen over another);
• an issue was found or closed during this session.

If yes → activate corezoid-git-context skill right now. Do not wait for the user to ask. Do not skip because the main task "looks done".

If none of the above → skip and tell the user the session is complete.

The skill handles everything autonomously: reads current _ext/docs/, proposes a unified diff, asks confirmation, writes files, and pushes — one invocation.