nocobase-workflow-manage

What this skill does

# Goal

Use the `nb api workflow` command surface to orchestrate workflows end-to-end: design trigger logic, build node chains, manage versions, and inspect execution results.

CLI usage rules:

1. Use `nb api workflow` as the canonical command namespace for workflow operations.
2. If the CLI is available but not authenticated for the target app, stop and guide the user to authenticate the CLI before continuing.
3. Before using an `nb api workflow` subcommand you have not used yet in the current task, run its `-h` once and follow the generated help text for flags and examples.

# Scope

- Handle: inspect workflow definitions, nodes, version state, executions, and failed jobs.
- Handle: create new workflows for business targets, then configure triggers and nodes sequentially.
- Handle: update existing workflows by creating a new revision first when the current version is frozen.
- Handle: enable workflows, move/duplicate/delete nodes or branches, and execute workflows only after explicit high-risk confirmation.
- Handle: diagnose failed executions and identify the failed job, node, or configuration mismatch.
- Handle: approval initiator, approver, and task-card UI authoring through `flowSurfaces` when the UI is bound to workflow or approval-node config.

# Non-Goals

- Do not handle `nb` installation or login bootstrap in this skill.
- Do not design data models, collections, or field schemas from scratch. Hand off to `nocobase-data-modeling`.
- Do not handle ordinary Modern page, tab, popup, or route-backed surface authoring. Hand off to `nocobase-ui-builder`.
- Do not invent filter syntax, evaluator functions, node types, trigger types, collection names, field names, or node keys.
- Do not bypass workflow-specific CLI interfaces with generic CRUD or local source edits.
- Do not delete whole workflows in this skill. If a user explicitly wants workflow deletion, stop and request a separately reviewed path.
- Do not treat approval schema wiring as part of this skill's v1 approval UI flow.

# Execution Preconditions

## Environment and Tooling

1. `nb` CLI must be available and authenticated to perform workflow operations.
   - Stop and ask the user to fix auth when the CLI returns `401`, `403`, `Auth required`, or equivalent access errors.
2. Before using an `nb api workflow` command you have not used yet in the current task, run `nb api workflow workflows -h`, `nb api workflow flow-nodes -h`, or the matching `nb api workflow <topic> <subcommand> -h` once and follow the generated help text.
3. When configuring `expression` fields in Calculation, Condition, or Multi-condition nodes, consult `nocobase-utils` for the authoritative function list of each engine. **Never fabricate function names** — verify against [formula.js reference](../nocobase-utils/references/evaluators/formulajs.md) or [math.js reference](../nocobase-utils/references/evaluators/mathjs.md).
4. Related helper skills: `nocobase-data-modeling`, `nocobase-utils`.
   - Use [`nocobase-data-modeling`](../nocobase-data-modeling/SKILL.md) according to the [Collection Resolution Gate](./convertions/index.md#the-collection-field-in-trigger-and-node-configuration) whenever a workflow trigger or node configuration depends on `collection`.

## Clarification and Mutation Preconditions

- Max clarification rounds: `2`
- Max questions per round: `3`
- Default execution bias:
  - If the intended action path is at least `70%` confident and the remaining uncertainty is in fields that can be safely revised after creation, proceed without asking. For example, nodes in editable (or new) workflow could always be updated (or moved/deleted) later, so if the only uncertainty is about node config details, proceed with the best guess and verify after mutation. Even more, newly created workflow will be in `enabled: false` state by default, so trigger config can be updated and nodes can be added/edited/moved/deleted freely until the user explicitly enables it, which means most uncertainties in a new workflow can be safely resolved after creation without blocking on questions.
  - Ask the user only when the unresolved choice affects a create-time commitment or another field that should not be guessed, or when the action is destructive/high-risk.
- Mutation preconditions:
  - CLI is reachable and authenticated.
  - The requested action is confirmed.
  - The target workflow is uniquely resolved for non-create actions.
  - For `create`, the trigger type and initial node chain are confirmed.
  - For `update`, `delete-node`, and `delete-branch`, the exact target node or branch and intended end state are confirmed.
  - If the existing workflow version has `versionStats.executed > 0`, a new revision is created before any node or trigger mutation.
  - For approval UI edits, the exact owner (`workflowId`, `nodeId`, or existing root `uid`) and whether the task is first-time / replace or localized edit are confirmed.
- Do not guess fields that behave like immutable or hard-to-reverse create-time decisions. Examples include workflow (trigger) `type`, and collection-bound trigger `config.collection` such as data collection event triggers.
- If uncertainty is limited to later-editable details, proceed with the best-supported choice and verify after mutation.
- If a required create-time commitment, destructive target, or approval UI owner/edit mode is still unresolved, stop and report exactly what is missing instead of guessing.

## Collection Resolution Gate

When a requested workflow depends on `collection` and the correct existing collection is not explicit from the user request or current context:

1. Use [`nocobase-data-modeling`](../nocobase-data-modeling/SKILL.md) to inspect existing collections first and inspect fields when needed.
2. Apply this gate to collection triggers and collection-bound operation triggers such as `collection`, `action`, `request-interception`, `approval`, `custom-action` with a bound collection, and `schedule` in collection time-field mode, as well as nodes whose config requires `collection`.
3. If an existing collection matches the business requirement with at least `70%` confidence, continue with that collection instead of asking the user.
4. Only ask the user how to proceed when no existing collection reaches that confidence threshold or when the unresolved collection choice is a create-time commitment that should not be guessed. Offer concrete next steps such as letting the user specify the collection, create it manually, or hand off collection creation to `nocobase-data-modeling`.

# Final Command Surface

Use only this final workflow operation surface. Discover exact flags from `-h` instead of keeping large command-shape reminders in context:

- Inspect workflows: `nb api workflow workflows list`
- Inspect one workflow (with nodes and version stats): `nb api workflow workflows get`
- Create a workflow: `nb api workflow workflows create`
- Update a workflow: `nb api workflow workflows update`
- Delete workflows: `nb api workflow workflows destroy`
- Create a new revision: `nb api workflow workflows revision`
- Re-register triggers: `nb api workflow workflows sync`
- Execute a workflow manually: `nb api workflow workflows execute`
- Create a node under a workflow: `nb api workflow workflows nodes create`
- Inspect one node: `nb api workflow flow-nodes get`
- Update a node configuration: `nb api workflow flow-nodes update`
- Delete a node: `nb api workflow flow-nodes destroy`
- Delete a branch: `nb api workflow flow-nodes destroy-branch`
- Move a node: `nb api workflow flow-nodes move`
- Duplicate a node: `nb api workflow flow-nodes duplicate`
- Test a node: `nb api workflow flow-nodes test`
- List executions: `nb api workflow executions list`
- Inspect one execution (with jobs): `nb api workflow executions get`
- Inspect a node job: `nb api workflow jobs get`
- List node jobs: `nb api workflow jobs list`
- Resume a waiting job: `nb api workflow jobs resume`
- Inspect an approval surface: `flowS