Opscotch LLM Skill

Implementation-focused guidance for engineers authoring Opscotch bootstraps, workflows, processors, resources, tests, packaging, and runtime integrations.

Scope

Use this skill to:

• decide whether a requirement fits Opscotch's real execution model
• separate bootstrap responsibilities from workflow responsibilities
• structure workflows, steps, triggers, processors, and reusable resources
• choose the right JavaScript context, validation path, and testing path
• apply packaging, cryptography, licensing, persistence, and delivery rules without inventing runtime behavior

Do not use this file as a complete API catalog. For exact context functions, signatures, and examples, use:

• /llm/apireference-index.json
• /llm/apireference.json
• /llm/patterns.json

Primary provenance:

• docs/src/llm/processed/docs/workflow.md -> https://docs.opscotch.co/docs/current/workflow
• docs/src/llm/processed/docs/patterns.md
• docs/src/llm/processed/docs/resource-documentation-with-doc.md
• docs/src/llm/processed/introduction/getting-started-full.md -> https://docs.opscotch.co/docs/current/introduction/getting-started-full
• docs/src/llm/processed/administrating/testing.md -> https://docs.opscotch.co/docs/current/administrating/testing
• docs/src/llm/processed/administrating/packaging.md -> https://docs.opscotch.co/docs/current/administrating/packaging
• docs/src/llm/processed/administrating/licensing.md -> https://docs.opscotch.co/docs/current/administrating/licensing
• docs/src/llm/processed/administrating/cryptography.md -> https://docs.opscotch.co/docs/current/administrating/cryptography
• docs/docs/workflow.md -> https://docs.opscotch.co/docs/current/workflow

Canonical MCP Use

The canonical schema, context-discovery, and validation surface is the Opscotch Coder MCP endpoint:

https://mcp.opscotch.ai/mcp

When the MCP server is available:

• call get_guidance(role=system) first
• call get_guidance(role=architect) before drafting structure
• call get_guidance(role=engineer) before implementation details
• read the MCP resource list before making schema-derived claims
• use lookup when you do not know the exact schema, pattern, context, or function yet
• use list_context, get_context, and get_context_function before asserting JavaScript context behavior
• use resolve_operational_context whenever a claim depends on what context means in a specific processor
• use the most specific validator available before claiming a generated object is valid

Canonical schema resources include:

• opscotch://schemas/bootstrap
• opscotch://schemas/bootstrap-errorhandling
• opscotch://schemas/bootstrap-host
• opscotch://schemas/bootstrap-key
• opscotch://schemas/bootstrap-packaging
• opscotch://schemas/bootstrap-record
• opscotch://schemas/bootstrap-workflow
• opscotch://schemas/processor
• opscotch://schemas/trigger
• opscotch://schemas/workflow
• opscotch://schemas/workflow-step

Canonical discovery and validation tools include:

• get_guidance
• get_schema
• get_patterns
• lookup
• list_context
• get_context
• get_context_function
• get_context_function_signatures
• resolve_operational_context
• validate_processor
• validate_trigger
• validate_step
• validate_workflow
• validate_workflow_file
• validate_bootstrap_file
• validate_bootstrap_errorhandling
• validate_bootstrap_host
• validate_bootstrap_key
• validate_bootstrap_packaging
• validate_bootstrap_record
• validate_bootstrap_workflow

Primary provenance:

• Opscotch Coder MCP resources, guidance, and context-discovery tools

Non-Negotiable Rules

• Do not invent APIs, runtime objects, or execution semantics.
• Do not assume Express-style request or response wrappers such as context.request or context.response.
• Do not assume undocumented ambient globals such as data, request, response, or mutable shared step state.
• Treat processor hooks such as resultsProcessor, urlGenerator, payloadGenerator, authenticationProcessor, splitGenerator, and itemResultProcessor as Opscotch processor objects.
• Treat processor script as an inline JavaScript string, not an alternate nested code container.
• Treat schema validity and runtime correctness as separate checks.
• Prefer documented context APIs such as setUrl(...), setBody(...), setHttpMethod(...), setHttpMultipartType(...), and sendToStep(...) over invented conventions.
• Prefer cautious, source-bounded guidance whenever the corpus does not fully define a behavioral edge case.

Primary provenance:

• docs/src/llm/operations/context/prompt-imperatives.md
• docs/src/llm/operations/context/processing-rules.md
• docs/src/llm/processed/docs/workflow.md -> https://docs.opscotch.co/docs/current/workflow

Core Mental Model

Opscotch separates operator-controlled runtime permissioning from remotely updateable solution logic.

• Bootstrap defines what the runtime is allowed to do.
• Workflow defines how those allowed capabilities are used.
• A workflow contains steps.
• A step is the execution boundary.
• Processors are JavaScript hooks attached to a step lifecycle.
• Resources hold reusable processor code that can be packaged into an app.

Use bootstrap for:

• host access
• file access
• HTTP listener permission
• deployment access
• persistence root
• licensing
• packaging trust
• keys
• deployment-specific data

Use workflow for:

• trigger selection
• step flow
• processor composition
• data overrides
• persistence usage
• orchestration between steps

Primary provenance:

• docs/src/llm/processed/docs/workflow.md -> https://docs.opscotch.co/docs/current/workflow
• docs/src/llm/processed/introduction/getting-started-full.md -> https://docs.opscotch.co/docs/current/introduction/getting-started-full
• docs/src/llm/processed/docs/patterns.md

Feasibility First

Before authoring config, map the requirement onto Opscotch's supported runtime model.

Check:

• trigger path: http, timer, tcp, fileWatcher, runOnce, or deploymentAccess
• input path: trigger payload, bootstrap or host data, context.files(...), context.getStream(), queue access, or outbound HTTP
• output path: HTTP response, metrics, logs, OTEL trace data, file writes, queue writes, or outbound HTTP
• processor constraints: synchronous JavaScript only, no imports, no Node.js modules, no await, no Promise, no callback-based async

If the design depends on arbitrary libraries, arbitrary runtime mutation, unsupported triggers, or async JavaScript inside one processor, redesign around bootstrap permissions plus multi-step orchestration.

Primary provenance:

• docs/src/llm/processed/docs/workflow.md -> https://docs.opscotch.co/docs/current/workflow
• docs/src/llm/processed/introduction/problem-to-plan.md -> https://docs.opscotch.co/docs/current/introduction/problem-to-plan
• docs/docs/workflow.md -> https://docs.opscotch.co/docs/current/workflow

Bootstrap Authoring

The bootstrap root is an array of records. Each record requires:

• deploymentId
• remoteConfiguration

Important bootstrap rules:

• bootstrap configuration is immutable after startup
• bootstrap records are schema-closed to undeclared properties
• frequency: 0 means load once only
• when frequency > 0, remoteConfigurationTimeout must be less than frequency
• startupPriority controls activation order, with lower values starting first

Important permissioning areas:

• allowExternalHostAccess for outbound HTTP
• allowFileAccess for file reads, writes, packaging resources, and file watching scope
• allowHttpServerAccess for inbound HTTP listeners and packaged static serving
• allowDeploymentAccess for cross-deployment calls
• persistenceRoot for durable workflow state
• licensing, packaging, and keys for commercial and cryptographic controls

Authoring guidance:

• define the smallest set of permissions that makes the workflow feasible
• keep environment-specific values in bootstrap data
• treat bootstrap changes as operational changes that usually require restart
• preload cryptographic keys in bootstrap when the workflow must reference them by ID at runtime
• configure licensing.licenseHost and licensing.licenseHostPoolId when the runtime should obtain licenses from a licensing app instead of relying on embedded package licensing

Primary provenance:

• docs/src/llm/processed/docs/workflow.md -> https://docs.opscotch.co/docs/current/workflow
• docs/src/llm/processed/administrating/agent.md -> https://docs.opscotch.co/docs/current/administrating/agent
• docs/src/llm/processed/administrating/licensing.md -> https://docs.opscotch.co/docs/current/administrating/licensing
• docs/src/llm/processed/administrating/cryptography.md -> https://docs.opscotch.co/docs/current/administrating/cryptography
• docs/src/llm/processed/blog/2026-03-24-licensing.md -> https://docs.opscotch.co/blog/licensing
• docs/src/llm/processed/blog/2025-02-03-allow-file-access.md -> https://docs.opscotch.co/blog/allow-file-access
• docs/src/llm/processed/blog/2025-02-03-allow-http-server-access.md -> https://docs.opscotch.co/blog/allow-http-server-access
• docs/src/llm/processed/blog/2025-02-04-allow-external-host-access.md -> https://docs.opscotch.co/blog/allow-external-host-access

Workflow And Step Authoring

The workflow root requires workflows. Common root-level fields include:

• data
• messages
• defaultStepProperties
• comment
• testData

Each workflow requires:

• name
• steps

Each step requires:

• stepId

Common step fields include:

• type
• trigger
• data
• singleThreaded
• httpTimeout
• persistence or persistenceFile
• processor hooks such as urlGenerator, payloadGenerator, authenticationProcessor, splitGenerator, itemResultProcessor, resultsProcessor, httpConnectFailedProcessor, and httpStatusHandling

Use comment to capture intent and flow. Use defaultStepProperties to centralize shared step settings instead of duplicating them.

Pattern guidance:

• use controller steps to orchestrate and worker steps to perform focused work
• keep authentication in dedicated auth flows
• use explicit registration and activation steps in composite deployments
• use defaultStepProperties only when the shared settings are genuinely part of one design shape

Primary provenance:

• docs/src/llm/processed/docs/workflow.md -> https://docs.opscotch.co/docs/current/workflow
• docs/src/llm/processed/docs/patterns.md
• docs/src/llm/processed/introduction/getting-started-full.md -> https://docs.opscotch.co/docs/current/introduction/getting-started-full

Processor And Context Guidance

Processor forms:

• inline script
• resource
• composite processors

Guidance:

• prefer resources for reusable or non-trivial logic
• prefer inline script only for small local behavior
• do not mix processors with a single-source script or resource form
• if both resource and script are present, script overrides resource
• validate the standalone processor shape when the MCP validator is available

Operational-context guidance:

• normal workflow logic runs in JavascriptContext
• authenticationProcessor runs in AuthenticationJavascriptContext
• any processor on a scripted-auth step runs in AuthenticationJavascriptContext
• sendToStep(...) returns JavascriptStateContext, which is read-only and intended for inspection

Useful JavascriptContext capabilities confirmed through the API corpus and MCP include:

• HTTP shaping: setUrl(...), setBody(...), setHttpMethod(...), setHeader(...), setHttpMultipartType(...)
• step orchestration: sendToStep(...), sendToStepAndForget(...), end()
• persistence: setPersistedItem(...), getPersistedItem(...)
• error handling: addUserError(...), addSystemError(...), isErrored(), getUserErrors(), getSystemErrors()
• file access: files(...)
• bytes and streams: bytes(), getStream(), setStream(...), setStreamFromString(...)
• crypto and telemetry: crypto(), diagnostic(), sendMetric(...)
• queue access: queue()

Primary provenance:

• docs/src/llm/processed/docs/workflow.md -> https://docs.opscotch.co/docs/current/workflow
• docs/src/llm/processed/docs/patterns.md
• docs/src/llm/processed/apireference.md
• docs/src/llm/processed/blog/2025-11-08-send-to-step.md -> https://docs.opscotch.co/blog/send-to-step
• Opscotch Coder MCP list_context, get_context, and resolve_operational_context

Data, Persistence, Errors, And Step Flow

Resolved data guidance:

• merge order is broader to narrower: bootstrap, host, workflow, step, processor
• more specific values win
• primitives overwrite
• objects and arrays merge additively

Persistence guidance:

• persistence is step-scoped durable state, not free shared memory
• stored values should be treated as strings unless you serialize explicitly
• prefer bootstrap persistenceRoot when state must survive restart or redeploy

Error guidance:

• use addUserError(...) for caller or operator fixable problems
• use addSystemError(...) for code, configuration, or unexpected runtime failures
• inspect returned JavascriptStateContext before trusting downstream output
• fire-and-forget forwarding requires a separate observation path if downstream failure visibility matters

Step-flow guidance:

• use sendToStep(...) when the caller needs the downstream result
• use sendToStepAndForget(...) when the caller should continue immediately
• use context.end() for deliberate early termination, not return alone

Primary provenance:

• docs/src/llm/processed/docs/workflow.md -> https://docs.opscotch.co/docs/current/workflow
• docs/src/llm/processed/docs/patterns.md
• docs/src/llm/processed/blog/2025-11-08-send-to-step.md -> https://docs.opscotch.co/blog/send-to-step
• docs/src/llm/processed/blog/2025-11-08-context-errors.md -> https://docs.opscotch.co/blog/context-errors

HTTP, Streams, Bytes, And Telemetry

Inbound and outbound HTTP guidance:

• use trigger.http with explicit server, method, and path
• put outbound request construction in urlGenerator and payloadGenerator
• use authenticationProcessor immediately before outbound HTTP for secret-bearing request mutation
• clear inherited headers with removeAllHeaders() before building an HTTP response when the flow started from an inbound HTTP event

Multipart and binary guidance:

• enable multipart uploads with trigger.http.multiPartUploadByteLimit
• multipart requests use body for text and stream for binary content
• context.getBody() returns a string
• context.getStream() returns a ByteReader
• use ByteContext for low-level binary manipulation, encoding conversion, compression, and stream-adjacent operations

Telemetry guidance:

• enable OTEL with OPSCOTCH_OTEL_PROPERTIES
• enrich the active trace with context.diagnostic().setAttribute(...), .event(...), and .errored(...)
• use trigger-level noTrace only where the source or schema supports it; do not generalize beyond documented trigger shapes

Primary provenance:

• docs/src/llm/processed/docs/workflow.md -> https://docs.opscotch.co/docs/current/workflow
• docs/src/llm/processed/docs/patterns.md
• docs/src/llm/processed/blog/2025-11-08-multipart-http-uploads.md -> https://docs.opscotch.co/blog/multipart-http-uploads
• docs/src/llm/processed/blog/2025-11-08-byte-manipulation.md -> https://docs.opscotch.co/blog/byte-manipulation
• docs/src/llm/processed/blog/2025-11-08-otel.md -> https://docs.opscotch.co/blog/otel

Resource Contracts With doc

Use doc when a resource is reusable enough that another engineer, workflow, or AI system should understand its contract without reverse-engineering the JavaScript.

Recommended contract shape:

• description(...) for the resource role
• inSchema(...) for payload consumed from context.getBody() or context.getPassedMessageAsString()
• dataSchema(...) for configuration consumed from context.getData(...)
• outSchema(...) when the resource returns a stable output envelope
• asUserErrors() when validation failures should be treated as caller mistakes
• run(...) for the implementation

Rules:

• doc.run(...) must fully enclose the processor code
• doc methods belong at the JavaScript root
• input and data validation happen before the processor runs
• output validation happens after the processor runs
• schema problems are raised at workflow load time

Use doc less aggressively for tiny one-off scripts with no meaningful contract.

Primary provenance:

• docs/src/llm/processed/docs/resource-documentation-with-doc.md
• docs/src/llm/processed/blog/2025-11-10-doc.md -> https://docs.opscotch.co/blog/validation
• Opscotch Coder MCP list_context and get_context_function

Testing

Testing guidance:

• when authoring a workflow, also author a test case
• treat tests as executable documentation of the intended flow
• prefer mocked service interactions during development
• understand the target external interaction before building the workflow
• keep reusable processor logic in resource files so it can be unit tested separately

Choose the right test path:

• use the test harness or opscotch-testrunner-single for workflow integration tests
• use opscotch-resource-testkit for JavaScript resource unit tests
• for local harness runs, resolve resourceDirs and testDirs relative to the test runner working directory, not the executable path or config path

Primary provenance:

• docs/src/llm/processed/introduction/getting-started-full.md -> https://docs.opscotch.co/docs/current/introduction/getting-started-full
• docs/src/llm/processed/administrating/testing.md -> https://docs.opscotch.co/docs/current/administrating/testing

Packaging, Cryptography, And Licensing

Packaging guidance:

• package workflows as .oapp when you need immutable deployable artifacts
• packaging is an HTTP API workflow, not a documented CLI flow
• resource files are loaded into the packaged workflow during packaging, so packaged apps do not depend on those files at runtime
• packaged updates require rebuild and redeploy
• unpackaged JSON workflow files can reload from disk without agent restart
• use /workflow-compile when you need post-preprocessing JSON rather than a package artifact
• use /workflow-hash when you need a stable pre-deploy comparison point
• use /package-envelope when you need a new outer signature or encryption envelope without rebuilding the inner workflow package

Cryptography guidance:

• use CryptoContext with ByteContext
• register or preload keys for the correct purpose and type
• keep keys out of logs
• use signatures for authenticity, authenticated encryption for confidentiality plus sender identity, anonymous encryption for recipient-only secrecy, and symmetric encryption for shared-secret cases

Licensing guidance:

• the current model supports centrally managed hierarchical licensing instead of requiring embedded licenses in every package
• runtimes can obtain licensing from a licensing app through bootstrap licensing settings
• embedded package licensing still exists in the documented 3.1.1 material, but is described as a legacy path

Primary provenance:

• docs/src/llm/processed/administrating/packaging.md -> https://docs.opscotch.co/docs/current/administrating/packaging
• docs/src/llm/processed/administrating/cryptography.md -> https://docs.opscotch.co/docs/current/administrating/cryptography
• docs/src/llm/processed/administrating/licensing.md -> https://docs.opscotch.co/docs/current/administrating/licensing
• docs/src/llm/processed/blog/2026-03-24-packaging.md -> https://docs.opscotch.co/blog/packaging
• docs/src/llm/processed/blog/2026-03-24-licensing.md -> https://docs.opscotch.co/blog/licensing
• docs/src/llm/processed/blog/2025-11-08-crypto-context.md -> https://docs.opscotch.co/blog/crypto-context

Working Loop

Use this loop when building or modifying an Opscotch solution:

1. Check feasibility against supported triggers, inputs, outputs, and processor constraints.
2. Decide what belongs in bootstrap versus workflow.
3. Discover the exact context functions, patterns, and schemas before assuming behavior.
4. Build the smallest working slice first.
5. Validate the most specific object shape available.
6. Test behavior separately from schema validity.
7. Package, license, and deploy only after the workflow behavior is already grounded.

Primary provenance:

• docs/src/llm/processed/docs/workflow.md -> https://docs.opscotch.co/docs/current/workflow
• docs/src/llm/processed/introduction/getting-started-full.md -> https://docs.opscotch.co/docs/current/introduction/getting-started-full
• docs/src/llm/processed/administrating/testing.md -> https://docs.opscotch.co/docs/current/administrating/testing
• docs/src/llm/processed/administrating/packaging.md -> https://docs.opscotch.co/docs/current/administrating/packaging