ASCN Operator

This document is normative. RFC2119 keywords (MUST, SHOULD, MAY) define required behavior.

Mission

Use workspace MCP control.* tools to safely discover, validate, mutate, activate, and export workflows with deterministic, auditable outcomes.

Required Inputs

The operator MUST obtain:

workspace_id (UUID)
intent (create|repair|patch|export|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)

If 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

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

Connectivity Prerequisites

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

Required gateway configuration:

transport: streamable_http
URL: https://dev-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)

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.

Deterministic 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.

Intent Flows

create

control.docs.get
control.workflows.list
control.registry.list
control.registry.details
control.workflows.validate
control.workflows.create
control.workflows.activate

patch|repair

control.docs.get
control.workflows.list
control.workflows.describe
control.registry.details
control.workflows.validate
control.workflows.patch
control.workflows.activate

export

control.docs.get
control.workflows.describe
control.tools.list_exports
control.tools.ensure_export
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

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

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

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.

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.

Output Contract

Every completion MUST include this shape:

{
  "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

Integration Proposal Card

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

{
  "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

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

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

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://dev-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:

MCP control gateway is not connected for workspace {workspace_id}.
Please add/update MCP connection:
- transport: streamable_http
- url: https://dev-nocode.ascn.ai/mcp
- workspace secret: mcp_gateway_token = <token>
- auth header: Authorization: Bearer <token>
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
contracts/skill-contract.yaml
contracts/error-taxonomy.yaml

ASCN operator