Skip to main content
skill CX Codex

corezoid-state-diagram-edit — Claude Code skill

corezoid-state-diagram-edit — a skill for updating Corezoid state diagrams in .conv.json files. Adjusts states, transition paths, and transition side effects.

MIT ★ 74 updated 2026-10-29

Install into Claude Code · Plugin marketplace All methods and platforms ↓
/plugin marketplace add corezoid/corezoid-ai-plugin
/plugin install corezoid@corezoid
Open on GitHub

What corezoid-state-diagram-edit does

This skill modifies Corezoid state diagram files (conv_type: "state") using the corezoid MCP server. It begins by resolving the target file path, diagram name, or numeric ID from your input. When a file contains conv_type: "process", it hands execution over to /corezoid-edit instead.

Edits adhere to strict diagram rules: each state node must have obj_type: 0, begin with an api_callback logic, and conclude with a self-referencing fallback transition. Brand new nodes receive generated 24-character hex identifiers. External call logics such as api or db_call cannot exist inside a state diagram, requiring side effects to live in helper nodes or separate driver processes.

What it helps with

  • Insert a new state node containing api_callback logic and a self-loop fallback
  • Reroute inbound transitions after removing an obsolete state node
  • Place helper nodes such as set_param or api_copy between states for transition side effects
  • Reorganise transition conditions so earlier go_if_const branches take priority

Example prompts for the agent

  • Update the state diagram in 1863140_User_Status.conv.json to add a pending review state.
  • Remove the suspended state from this state machine and fix all dangling transitions.
  • Adjust the go_if_const conditions in my state diagram to evaluate a new status flag.

How to install corezoid-state-diagram-edit

1Plugin marketplace

/plugin marketplace add corezoid/corezoid-ai-plugin
/plugin install corezoid@corezoid

This installs the whole corezoid plugin with all its skills

2Skills CLI (Vercel)

npx skills add corezoid/corezoid-ai-plugin --skill corezoid-state-diagram-edit -a claude-code

3Manually: put the files in place

~/.claude/skills/corezoid-state-diagram-edit/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/corezoid-state-diagram-edit/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about corezoid-state-diagram-edit

How to install corezoid-state-diagram-edit in Claude Code?

Run both marketplace commands in order: /plugin marketplace add corezoid/corezoid-ai-plugin and then /plugin install corezoid@corezoid.

What does corezoid-state-diagram-edit do?

It modifies Corezoid state machines, adjusting node connections, maintaining api_callback rules, and generating compliant node IDs.

Can corezoid-state-diagram-edit edit standard Corezoid processes?

No, it targets only files with conv_type: "state". Regular processes must be handled with /corezoid-edit.

Source text

SKILL.md · MIT
---
name: corezoid-state-diagram-edit
description: >
  Corezoid state diagram editing specialist. Use when the user wants to modify,
  update, or fix an existing Corezoid state diagram — add or remove a state, change
  a transition, add a side effect on transition, fix the wiring of an api_callback
  state node, or rework transitions. Activate when the user says "edit a state
  diagram", "add a state", "remove a state", "change transitions", "fix state
  diagram", "update state machine", "поправить state diagram", "изменить состояния",
  or refers to modifying a .conv.json with conv_type "state".
---

# Edit an Existing Corezoid State Diagram

You are a specialist in modifying Corezoid **state diagrams** (`conv_type: "state"`) using the `corezoid` MCP server.

A state diagram is a long-lived data store; modifying it means changing the set of states, the data conditions that drive transitions between them, or the side effects performed on transition. The driver processes that read / write the diagram are usually edited separately via `/corezoid-edit`.

Read `${CLAUDE_PLUGIN_ROOT}/docs/state-diagrams/state-diagram-overview.md` for a refresher on the model before editing.

---

## Identify the State Diagram (MANDATORY FIRST STEP)

**Before doing anything else**, resolve `PROCESS_PATH`:

1. Check whether the user already provided an identifier — a file path, state diagram name, or numeric id — in the current message or conversation history.
2. If no identifier is provided, ask:
   > "Please specify the state diagram — a file path (e.g. `1863140_User_Status.conv.json`), a name, or a state diagram id."
   Do **not** call any MCP tools until the user provides one.
3. If the user gives a **name or id**, search the local working directory for the matching `.conv.json` using `find` / `grep`.
4. Open the file and **confirm `"conv_type": "state"`** at the root. If `conv_type` is `"process"`, this is a regular process — hand off to `/corezoid-edit` instead.
5. Once `PROCESS_PATH` is confirmed, analyze the file before changing anything.

---

## Step 1: Analyze the State Diagram

Read the file and map out:

- The list of state nodes (every node with `obj_type: 0` whose first logic is `api_callback`). Note each state's `id`, `title`, and outbound `go_if_const` transitions.
- The Start node and which state it routes to (the initial state).
- Any helper nodes between states (Set Parameters, Code, Modify Task, Copy Task, Delay, Queue).
- Terminal nodes (`obj_type: 2`).

> 🔍 If you see `obj_type: 3` state nodes, you are looking at the legacy state-node format. The current Corezoid format uses `obj_type: 0` with `api_callback` as the first logic. Convert old nodes to the new format only if the user explicitly asks — otherwise leave them as-is and edit in place.

Make sure you also locate any **driver processes** that reference this state diagram (search the project for `conv[<sd_id>]`, `conv[@<alias>]`, and `api_copy` nodes with `conv_id: <sd_id>`). When editing, you may need to update those drivers too.

---

## Step 2: Plan the Edit

Categorise the change before touching JSON:

| Change type | What to touch |
|---|---|
| Add a new state | Insert a new `obj_type: 0` state node with `api_callback` + transitions + self-loop. Wire at least one inbound transition from an existing state's `go_if_const`. |
| Remove a state | Delete the node and re-route every inbound transition that pointed to it. Search the file for `to_node_id: "<deleted_id>"`. |
| Change a transition condition | Edit the `conditions` array of the relevant `go_if_const` in the source state. |
| Re-target a transition | Change `to_node_id` of the relevant `go_if_const`. |
| Add a side effect on transition | Insert a Modify Task / Copy Task / Set Parameters node between the source state and the target state. Update the source state's `go_if_const.to_node_id` to point at the new helper, and have the helper `go` to the original target. |
| Rename a state | Change `title` only — the `id` must stay the same to preserve drivers that reference it. |
| Add an alias | Hand off to `/corezoid-alias-manager`. |

---

## Step 3: Apply Changes

Edit `PROCESS_PATH` directly.

### Core rules

- Connect nodes only through `go` / `go_if_const` `to_node_id` fields.
- Every node that has `err_node_id` (Code, Set Parameters, Copy Task, Modify Task, Queue) must point at a real End: Error node — never to a state node.
- Node ids are 24-character hex: `^[0-9a-f]{24}$`. For new nodes, generate fresh ids; **never reuse** an old id, even if its node was deleted.
- Use descriptive `title` values — they are the state names visible on the canvas and dashboards.
- Layout: keep states roughly on the same `y` lane (≈ 400); increment `x` by ≈ 320–400 between adjacent states. Start at `y = 100`. End nodes at the bottom.

### State node invariants (do not break these)

For every state node:

- `obj_type: 0`
- First logic is exactly `{ "type": "api_callback" }` (no extra fields)
- Every outbound transition is a `go_if_const` between the `api_callback` and the trailing `go`
- The final logic is `{ "type": "go", "to_node_id": "<self_id>" }` — the "stay here" fallback
- `extra` contains `"icon":"state"`
- No `err_node_id` on `api_callback`

If you add or modify transitions, the order matters — **first matching `go_if_const` wins**. Put more specific conditions first.

### Allowed logics

Only these logics may appear inside a state diagram. Adding anything else will fail validation on push.

| Allowed | Type |
|---|---|
| Start | `go` (`obj_type: 1`) |
| State | `api_callback` + `go_if_const`s + self-`go` |
| Condition | `go_if_const` |
| Code | `api_code` |
| Set Parameters | `set_param` |
| Copy Task (fan-out) | `api_copy` with `mode: "create"` |
| Modify Task (by ref) | `api_copy` with `mode: "modify"` |
| Delay | semaphor-only |
| Queue | `api_queue` |
| End | (`obj_type: 2`) |

**Forbidden:** `api`, `api_rpc`, `api_rpc_reply`, `db_call`, `git_call`, `api_sum`, `api_form`. If the user asks to add one of these, push back: move the side effect into the driver process and explain why.

### Common pitfalls

- Adding a state but forgetting to wire any inbound transition → unreachable state.
- Deleting a state but leaving a `go_if_const` somewhere with `to_node_id` pointing to the deleted id → push will fail with "unknown node".
- Reordering transitions accidentally: the **first matching `go_if_const` wins**, so order is semantically meaningful.
- Using `api_copy mode: "modify"` from inside the state diagram targeting its own ref — that re-triggers `api_callback` and can loop. Use `set_param` to update the current task in place instead.
- Forgetting to update the driver process when you rename a state and the driver compares against its name (e.g. `{{conv[…].ref[…].status}} == "Active"`). The state name is `title`; the driver compares against a stored **value**, not the title — confirm with the user which they're checking.

---

## Step 4: Deploy the Changes

**MANDATORY: Always push after any change — even if work is in-flight. Without push, the changes exist only on disk.**

Call MCP tool **`push-process`** with `process_path: "<PROCESS_PATH>"`.

If push fails:
- Re-read the file and confirm `"conv_type": "state"` is still at the root (a stray editor save or auto-format may have flipped it).
- Lint with **`lint-process`** to localise the issue.
- Confirm every state node still ends in `go → self_id`.
- Confirm no forbidden logic types were introduced.

After a successful push, notify the user:

> "State diagram updated. Refresh the Corezoid page to see the new states / transitions. Any tasks already parked in renamed states keep their `id` references intact, but tasks parked in **deleted** states are now stranded — check the workspace before deleting a populated state."

> ⚠️ **Live data warning:** Unlike regular processes, a state diagram usually has **live tasks parked in its states**. Deleting or restructuring a state can strand those tasks. Before deleting a state, ask the user whether they want to migrate parked tasks first (e.g. by modifying their `ref` so they transition out of the doomed state).

---

## Step 5 (optional): Update Driver Processes

If your edit changed the **observable interface** of the state diagram — added a new field that drivers should now read, renamed a field drivers compare against, or removed a state drivers used to detect — hand off to `/corezoid-edit` for each driver process that needs updating.

To find driver processes affected by the edit, search the project:

```
grep -rn "conv\[<sd_id>\]" .
grep -rn "conv_id\": <sd_id>" .
grep -rn "conv\[@<alias>\]" .
```

---

## Reference Documents

| Path | When to read |
|---|---|
| `${CLAUDE_PLUGIN_ROOT}/docs/state-diagrams/state-diagram-overview.md` | Concepts, allowed nodes, root structure |
| `${CLAUDE_PLUGIN_ROOT}/docs/state-diagrams/state-diagram-node-structures.md` | Canonical JSON for every allowed node type |
| `${CLAUDE_PLUGIN_ROOT}/docs/state-diagrams/state-diagram-process-interaction.md` | How driver processes read / create / modify state tasks |
| `${CLAUDE_PLUGIN_ROOT}/docs/nodes/set-state-node.md` | Background and the `{{conv[...]}}` template |
| `${CLAUDE_PLUGIN_ROOT}/docs/nodes/copy-task-node.md` | Error catalogue for `api_copy` |
| `${CLAUDE_PLUGIN_ROOT}/docs/nodes/condition-node.md` | `go_if_const` reference |
| `${CLAUDE_PLUGIN_ROOT}/docs/variables-guide.md` | Variables (`{{env_var[@…]}}`) |

## Example Files

| Path | Description |
|---|---|
| `${CLAUDE_PLUGIN_ROOT}/samples/state-diagrams/user-status-state-diagram.conv.json` | Minimal two-state diagram (`Active` ⇄ `Inactive`) |
| `${CLAUDE_PLUGIN_ROOT}/samples/state-diagrams/user-status-driver-process.conv.json` | Companion driver process |

© Corezoid · MIT · corezoid/corezoid-ai-plugin

Similar skills

All skills for Automation and no-code: n8n, Zapier, Make →

From the same set30

The whole set →
corezoid-retro corezoid-retro — a skill that analyzes a completed Corezoid work session, extracts actionable insights, and stores them as workspace CLAUDE.md updates, team feedback, and permission rules. Every session teaches the next one. CX Codex +1 ★ 74repo stars corezoid-dashboard-manager corezoid-dashboard-manager is a Claude Code skill that builds Corezoid dashboards via cz-dashboards, mapping process node task counters to charts and setting grid layouts. CX Codex +1 ★ 74repo stars corezoid-git-context The corezoid-git-context skill records meaningful Corezoid session changes in stage documentation and syncs the git mirror. Use it after real process work. CX Codex +1 ★ 74repo stars plan-to-issues plan-to-issues converts a plan discussed in the chat into structured GitHub issues: an epic plus child tasks grouped by milestone and labeled by type. Triggers on command or keywords like "split plan into tasks" or "make issues from this". CX Codex +1 ★ 74repo stars corezoid-node-layout corezoid-node-layout arranges Corezoid process nodes into a readable top-to-bottom flow and moves error handling to the right. Use it before pushing a new process or after a layout request. CX Codex +1 ★ 74repo stars corezoid-access corezoid-access — a skill for managing access to processes, folders and projects in Corezoid. Share objects with users and groups, create API keys, invite external users, and audit who has access. CX Codex +1 ★ 74repo stars corezoid-project-review corezoid-project-review audits entire Corezoid projects or folders, finding circular calls, duplicate code logic, and shared hardcoded secrets. CX Codex +1 ★ 74repo stars corezoid-init corezoid-init connects a working directory to Corezoid, handles sign-in, and pulls a selected stage. Use it when starting a Corezoid project. CX Codex +1 ★ 74repo stars

Project sponsors

Companies that keep this analytics open