ASCN Operator

Use this guide as the source of truth for how the operator should work.

Mission

Use workspace MCP

control.*

tools to safely discover, validate, change, activate, and export workflows, plus submit plugin bundles with clear, auditable outcomes.

Required Inputs

The operator MUST obtain:

```
workspace_id
```
(UUID)

intent

(

create|repair|patch|export|publish_plugin|delete|explain

)

Optional but strongly recommended:

```
workflow_id
```
for patch/repair/export/delete intents
required integration list and secrets map
success criteria (expected workflow status/tool name)
for
```
publish_plugin
```
:
```
plugin_name
```
, canonical handler list, and plugin definition metadata

blueprint_preference

(

linear|fanout|conditional|retryable_http|tool_export

)

latency target (for example
```
latency_slo_ms
```
)
throughput target (for example
```
throughput_rps
```
)
idempotency requirement (
```
strict|best_effort
```
)

workspace_id

is missing, the operator MUST stop before any mutation.

Required Tool Surface

The target gateway MUST expose these tools:

```
control.docs.get
```
```
control.registry.list
```
```
control.registry.details
```
```
control.workflows.list
```
```
control.workflows.describe
```
```
control.workflows.validate
```
```
control.workflows.create
```
```
control.workflows.patch
```
```
control.workflows.activate
```
```
control.workflows.delete
```
```
control.tools.list_exports
```
```
control.tools.ensure_export
```
```
control.runs.list
```
```
control.runs.details
```
```
control.plugins.create_plugin
```
```
control.plugins.update_plugin
```
```
control.plugins.list
```

If required tools are unavailable, the operator MUST fail fast with a dependency error summary.

Companion Skill Delegation

If capability is insufficient, the operator MUST delegate integration design/implementation to:

```
skills/ascn-integrations/SKILL.md
```

The operator MUST resume lifecycle mutations only after missing capability becomes available.

Connectivity Prerequisites

Before lifecycle operations, the operator MUST verify MCP connectivity for the workspace gateway.

Required gateway configuration:

transport:
```
streamable_http
```
URL:
```
https://nocode.ascn.ai/mcp
```
tool dependency id:
```
workspace-mcp-gateway
```
workspace secret name:
```
mcp_gateway_token
```
auth header:
```
Authorization: Bearer <token>
```
(must match secret value)
MCP auth/token source:
```
https://ascn.ai/no-code/mcp-list
```

The operator MUST NOT attempt workflow mutations until this dependency is reachable.

Dependency Handshake

At task start, the operator MUST perform a dependency readiness check:

confirm
```
workspace_id
```
is present
confirm MCP gateway dependency exists in agent runtime
confirm control tool surface is discoverable

If any check fails, classify as dependency failure and return user-facing connection instructions.

Capability Gap Policy

After dependency checks, the operator MUST determine whether current capability is sufficient.

Required detection order:

inspect workflow/tool inventory (

control.workflows.list

control.workflows.describe

control.tools.list_exports

)

inspect handler/trigger inventory (

control.registry.list

control.registry.details

)

classify capability status:
- sufficient
- missing_handler
- missing_trigger
- missing_auth_capability
- schema_or_contract_gap

If status is not

sufficient

, the operator MUST NOT invent handler/trigger names.

Blueprint Selector Policy

For

create|patch|repair|export

, the operator MUST select one workflow blueprint before drafting config.

Supported blueprint types:

```
linear
```
: single ordered chain
```
fanout
```
: one producer, multiple parallel consumers
```
conditional
```
: explicit branch routing with conditions
```
retryable_http
```
: network call with explicit retry/error path
```
tool_export
```
:
```
Trigger.Tool
```
surfaced via MCP

The operator MUST:

declare selected blueprint in output (
```
selected_blueprint
```
)
keep graph topology consistent with selected blueprint
use
```
control.registry.details
```
examples/minimal params as activity-level examples

Execution Policy

Global Rules

The operator MUST call
```
control.docs.get
```
before intent-specific mutations.
The operator MUST validate before every create/patch mutation.
The operator MUST mutate by
```
workflow_id
```
, never inferred names.
The operator MUST not perform delete without explicit
```
confirm=true
```
.
The operator MUST run
```
control.workflows.activate
```
after successful create/patch/export.
For exported MCP tools, the operator MUST run smoke-test trace checks using
```
control.runs.list
```
.
The operator MUST use a minimal-valid first draft, then expand.
The operator MUST complete schema-lock and reference-safety checks before mutation.
The operator MUST use a consistent node naming convention.
The operator MUST prepare patch strategy from error class before retrying failed validation.

Authoring Pipeline (Required)

For

create|patch|repair|export

, operator MUST apply this order:

select blueprint type
schema-lock from
```
control.registry.details
```
:
- required params
- defaults
- secret-backed fields
build minimal valid draft:
- smallest runnable set of nodes
- explicit trigger entry edge(s)
run reference safety gate:
- each
```
$node[...]
```
  has reachable directed path
- no raw
```
$...
```
  dynamic directives without
```
={{ ... }}
```
- no secret literals
validate (
```
control.workflows.validate
```
)
mutate (
```
create
```
or
```
patch
```
)
activate
expand/iterate only if required by scope

Intent Flows

create

```
control.docs.get
```
```
control.workflows.list
```
```
control.registry.list
```
```
control.registry.details
```
select blueprint + schema-lock + minimal valid draft
```
control.workflows.validate
```
```
control.workflows.create
```
```
control.workflows.activate
```

patch|repair

```
control.docs.get
```
```
control.workflows.list
```
```
control.workflows.describe
```
```
control.registry.details
```
select blueprint + schema-lock + minimal patch draft
```
control.workflows.validate
```
```
control.workflows.patch
```
```
control.workflows.activate
```

export

```
control.docs.get
```
```
control.workflows.describe
```

control.tools.list_exports

with

expose_mcp_only=false

to inspect all exports

```
control.tools.ensure_export
```
with canonical
```
output_path
```
```
control.workflows.validate
```
```
control.workflows.activate
```
invoke exported tool with minimal valid payload
```
control.runs.list
```
for latest run verification
```
control.runs.details
```
for node outputs and timeline diagnostics

delete

```
control.workflows.describe
```
summarize destructive impact
```
control.workflows.delete
```
with
```
confirm=true
```

publish_plugin

```
control.docs.get
```
```
control.registry.details
```
for each selected handler
```
control.plugins.create_plugin
```
```
control.plugins.update_plugin
```
(only when edits are required)
verify the published plugin appears under
```
user
```
category in plugin UI (
```
control.plugins.list
```
)
enforce UX behavior:
- unwrapped exports stay visible as flat
```
User.<Handler>
```
  entries
- published bundles render as first-class plugin cards/forms
instruct user to test via plugin card/form flow (not raw handler list)

Capability-Gap Flow

When capability is insufficient, operator MUST run this branch:

produce
```
gap_summary
```
with classification and impact
propose reuse-first options in priority order:
- compose with existing handlers/triggers/tools
- reuse/patch existing exported tool
- connect external MCP tool
- implement new reusable integration (handler/trigger)
produce at least one Integration Proposal Card
ask user to choose path before continuing mutations
run the
```
ascn-integrations
```
skill flow for the selected option

The operator MUST pause lifecycle mutations until user selects a path.

Post-Export Testability and Traceability

After export and activation, operator MUST validate runtime behavior:

invoke exported MCP tool with minimal valid payload
query latest runs via
```
control.runs.list
```
confirm latest run status is expected (
```
COMPLETED
```
for happy-path smoke)
inspect full run payload via
```
control.runs.details
```
when run is failed or unexpected
if run fails, include
```
run_id
```
and
```
trace_id
```
in failure summary

Export Robustness Rules

When handling export intent, operator MUST:

list exports with
```
expose_mcp_only=false
```
before reconciliation
ensure export output uses canonical
```
output_path
```
verify
```
output_path
```
resolves to output-producing node
check canonical tool name conflicts before activation
smoke-test after activation and inspect runs on any failure

Idempotency and Retry

Mutation operations MUST use a deterministic operation key:

{workspace_id}:{intent}:{workflow_id|workflow_name}:{payload_hash}

Transient failures (
```
timeout
```
,
```
5xx
```
, gateway unavailable) MAY retry up to 3 attempts with exponential backoff.
Validation/context/export-conflict failures MUST NOT auto-retry; patch context/payload first.
Retry behavior MUST be recorded in the final output.

Authoring Standards

Activity IDs MUST be unique.
Every
```
edges[].to
```
MUST reference an existing activity.
Trigger entry edges SHOULD be explicit for deterministic starts.
```
$json
```
MUST be used only for current node input.
Upstream reads MUST use
```
$node['id'].json.field
```
with graph reachability.
Dynamic expressions and secrets MUST use
```
={{ ... }}
```
.
Credentials MUST NOT be hardcoded.
If required capability is missing, operator MUST propose reusable integration path instead of ad-hoc one-off node logic.

Naming Convention

For generated/updated workflow nodes, operator MUST use:

activity id pattern:
```
<verb>_<domain>_<seq>
```
(example:
```
fetch_orders_01
```
)
trigger id pattern:
```
<kind>_<seq>
```
(example:
```
tool_01
```
,
```
cron_01
```
)

workflow name pattern:

<domain>_<intent>_<variant>

(example:

orders_sync_tool

)

lowercase snake_case ids for stable
```
$node[...]
```
references

Node Reference Syntax (Required)

The operator MUST explicitly use and communicate these patterns when authoring workflow params:

Current node input:
- ```
={{ $json }}
```
- ```
={{ $json.field }}
```

Upstream node output:

```
={{ $node['build'].json }}
```
```
={{ $node['build'].json.message }}
```

Upstream array/object access:
- ```
={{ $node['fetch'].json.items[0].id }}
```
Secrets:
- ```
={{ $secrets.telegram_bot_token }}
```

The operator MUST NOT use raw

$node[...]

or raw

$json...

strings without

={{ ... }}

in dynamic fields. If a node reference is used, graph reachability MUST be validated (

A -> ... -> B

Error Handling Standard

The operator MUST map errors to

contracts/error-taxonomy.yaml

Mandatory handling classes:

```
validation
```
: patch payload and re-validate.
```
context
```
: correct workspace/workflow mismatch before proceeding.
```
export_conflict
```
: list exports and reconcile canonical name/output path.
```
transient
```
: bounded retries with backoff.
```
dependency
```
: stop execution and provide MCP connection runbook to user.
```
capability_gap
```
: propose reusable integration options and request user decision.

Failure Patch Strategy Templates

On failed validation or mutation, operator MUST choose patch strategy by class:

```
validation
```
: patch params/edges/references, then re-validate
```
context
```
: rebind workspace/workflow id, then retry once
```
export_conflict
```
: list exports, reconcile tool+handler+output_path
```
dependency
```
: stop and return connection runbook
```
transient
```
: bounded retry with backoff (max 3)
```
capability_gap
```
: return proposals and wait for user decision

Output Contract

Every completion MUST include this shape:

json

{
  "operations_executed": [
    {
      "step": 1,
      "tool": "control.docs.get",
      "result": "success",
      "duration_ms": 12
    }
  ],
  "final_state": {
    "workflow_id": "<uuid>",
    "version": 3,
    "status": "ACTIVE"
  },
  "validation_summary": {
    "valid": true,
    "issue_count": 0
  },
  "unresolved_risks": []
}

On failure, output MUST include:

```
failing_operation
```
```
error_code
```
(taxonomy-aligned)
```
error_message
```
```
next_action
```
```
connection_instructions
```
when error class is
```
dependency
```
```
integration_proposals
```
when class is
```
capability_gap
```
```
run_trace
```
(
```
run_id
```
,
```
trace_id
```
) when runtime execution started
```
patch_strategy
```
selected from Failure Patch Strategy Templates

For

publish_plugin

, output MUST additionally include:

```
definition_id
```
```
plugin_name
```
```
handlers
```

visibility_state

(

visible_in_user_category|not_visible

)

```
next_action
```
with user-facing test steps

For

create|patch|repair|export

, output SHOULD additionally include:

```
selected_blueprint
```
```
schema_lock_summary
```
(required/default/secret-backed fields)

edge_intents

map (

sequence|branch_true|branch_false|error_path

)

Integration Proposal Card

When capability gap is detected, proposal MUST follow this structure:

json

{
  "integration_name": "Acme Orders Connector",
  "kind": "activity",
  "proposed_handler_id": "AcmeOrders.CreateOrder",
  "why_reusable": "Can be reused for all order create flows across workspaces",
  "params_schema": {"type": "object"},
  "returns_schema": {"type": "object"},
  "required_secrets": ["acme_api_key"],
  "auth_model": "api_key_header",
  "retry_policy": {"max_attempts": 3, "backoff": "exponential"},
  "rate_limit_hint": "100 req/min",
  "acceptance_tests": [
    "creates order with valid payload",
    "returns typed error on 4xx/5xx",
    "schema validation passes in control.workflows.validate"
  ],
  "reusability_scope": "multi-workflow"
}

User Decision Gate

For capability gap, operator MUST ask user to pick one option:

Compose from existing handlers/tools
Connect external MCP tool
Build new reusable integration (handler/trigger)

Mutations resume only after explicit user choice.

User Decision Message Templates

For capability-gap responses, operator SHOULD use these standardized user-facing templates.

compose_existing_handlers_or_tools

text

I can complete this using existing capabilities without building a new integration.
Plan:
1) compose current handlers/tools,
2) validate graph and schema,
3) activate workflow.
Choose this if you want fastest delivery with current platform components.

connect_external_mcp_tool

text

I can connect an external MCP tool and reuse it in this workflow.
Plan:
1) connect MCP tool endpoint,
2) verify tool schema and auth,
3) wire tool into workflow and validate.
Choose this if the capability already exists in an external MCP server.

build_new_reusable_integration

text

Current capabilities are insufficient. I propose a reusable integration:
- handler: {proposed_handler_id}
- scope: {reusability_scope}
- required secrets: {required_secrets}
Plan:
1) define params/returns schema,
2) implement reusable handler/trigger,
3) validate with acceptance tests and reuse in this workflow.
Choose this for long-term reuse across automations.

User-Facing MCP Connection Playbook

When the skill is loaded but MCP is not connected, the operator MUST provide this actionable instruction set:

Verify the ASCN base URL is reachable.

Configure MCP gateway connection:

name:
```
workspace-mcp-gateway
```
transport:
```
streamable_http
```
url:
```
https://nocode.ascn.ai/mcp
```

Ensure workspace secret
```
mcp_gateway_token
```
exists and has the intended token value.
Add
```
Authorization: Bearer <token>
```
header using the same token value.
Reconnect MCP client/session.
Re-run and verify control tool availability (
```
control.docs.get
```
or tool list inspection).

Recommended user message template:

text

MCP control gateway is not connected for workspace {workspace_id}.
Please add/update MCP connection:
- transport: streamable_http
- url: https://nocode.ascn.ai/mcp
- workspace secret: mcp_gateway_token = <token>
- auth header: Authorization: Bearer <token>
- token source: https://ascn.ai/no-code/mcp-list
Then reconnect MCP and retry this request.

Observability and Audit Fields

The final summary MUST include:

```
workspace_id
```
```
intent
```
```
tool_sequence
```
```
total_duration_ms
```
```
retry_count
```
```
mutation_count
```

Mutation Safety

Before delete, operator MUST provide impact summary.
After every mutation, operator MUST report affected
```
workflow_id
```
,
```
version
```
,
```
status
```
.
If activation fails, operator MUST stop and provide concrete patch plan.

Consistency Requirements

```
SKILL.md
```
MUST remain consistent with
```
contracts/skill-contract.yaml
```
.
Scenario files in
```
contracts/scenarios/
```
SHOULD cover create, repair, and export flows.

Change Management

Contract/toolflow changes MUST update
```
VERSION
```
and
```
CHANGELOG.md
```
.
Breaking changes MUST increment major version.
Non-breaking behavior additions SHOULD increment minor version.

References

```
references/workflow-construction.md
```
```
references/troubleshooting.md
```
```
references/mcp-connection.md
```
```
references/integration-proposals.md
```
```
references/plugin-publishing.md
```
```
contracts/skill-contract.yaml
```
```
contracts/error-taxonomy.yaml
```

ascn-operator

NPX Install

Tags

SKILL.md Content

ASCN Operator

Mission

Required Inputs

Required Tool Surface

Companion Skill Delegation

Connectivity Prerequisites

Dependency Handshake

Capability Gap Policy

Blueprint Selector Policy

Execution Policy

Global Rules

Authoring Pipeline (Required)

Intent Flows

Capability-Gap Flow

Post-Export Testability and Traceability

Export Robustness Rules

Idempotency and Retry

Authoring Standards

Naming Convention

Node Reference Syntax (Required)

Error Handling Standard

Failure Patch Strategy Templates

Output Contract

Integration Proposal Card

User Decision Gate

User Decision Message Templates

User-Facing MCP Connection Playbook

Observability and Audit Fields

Mutation Safety

Consistency Requirements

Change Management

References