Opscotch Architect Skill

Design-focused guidance for engineers deciding whether and how to shape a solution in Opscotch terms.

This skill complements docs/docs/llm/opscotch-llm-skill.md. Use the operational skill for authoring details. Use this skill for fit assessment, boundary setting, topology decisions, and solution explanation.

Scope

Use this skill to:

• decide whether a problem fits Opscotch's runtime model
• translate business outcomes into workflows, steps, triggers, and boundaries
• decide what belongs in bootstrap versus workflow versus step structure
• shape data flow, authentication, persistence, packaging, trust, and licensing decisions
• explain architectural choices in Opscotch-native language

Do not use this file as the API catalog. For exact contracts, signatures, schemas, and validation, use:

• /llm/apireference-index.json
• /llm/apireference.json
• Opscotch Coder MCP context-discovery tools for authentication-context details

Primary provenance:

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

Canonical MCP Use

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

https://mcp.opscotch.ai/mcp

When MCP is available:

• call get_guidance(role=system) first
• call get_guidance(role=architect) before drafting architecture guidance
• call get_guidance(role=engineer) before implementation-sensitive examples or final config
• 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 processor
• use the most specific validation tool available before claiming a produced object is valid

Canonical schema resources exposed by the MCP server 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

Primary provenance:

• docs/docs/llm/opscotch-llm-skill.md -> https://docs.opscotch.co/docs/current/llm/opscotch-llm-skill
• Opscotch Coder MCP resources and guidance

Non-Negotiable Rules

• Do not invent APIs, runtime objects, or execution semantics.
• Do not assume Express-style request or response wrappers or undocumented ambient globals.
• Treat processor script as an inline JavaScript string, not a nested code object.
• Treat schema validity and runtime correctness as separate checks.
• Do not claim processor-context behavior as fact without source or MCP support.
• Prefer documented step-to-step orchestration and HTTP APIs over invented transport conventions.
• Narrow claims when the sources are incomplete instead of filling gaps with generic platform assumptions.

Primary provenance:

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

Core Architectural Lens

Think about Opscotch as a constrained workflow runtime for deployable automation products, not as a general application host.

• Bootstrap is the installed boundary of trust, permission, and operator intent.
• Workflow is the remotely updateable logic that uses those allowed capabilities.
• Steps are the architectural execution boundaries.
• Processors are responsibility slots inside a step.
• Resources are reusable implementation units, not the primary architecture.
• Packaging, signatures, keys, and licensing are architectural controls, not packaging afterthoughts.

Start architectural reasoning with these questions:

1. Can the business outcome be expressed through supported triggers, step flow, and bootstrap permissions?
2. Where is the correct boundary between operator-controlled installation concerns and updateable logic?
3. What is the smallest clear workflow shape that achieves the outcome without violating runtime constraints?

Primary provenance:

• docs/src/llm/processed/core-capabilities/runtime.md -> https://www.opscotch.co
• docs/src/llm/processed/docs/workflow.md -> https://docs.opscotch.co/docs/current/workflow
• docs/src/llm/processed/what-opscotch-does/what-productizing-automation-patterns.md -> https://www.opscotch.co
• docs/docs/llm/opscotch-llm-skill.md -> https://docs.opscotch.co/docs/current/llm/opscotch-llm-skill

Architectural Decision Loop

Use this loop before anyone writes config:

1. Reduce the business request to a trigger, input path, output path, and trust boundary.
2. Decide whether the outcome is installer-shaped, workflow-shaped, or deployment-topology-shaped.
3. Sketch the minimum step topology that keeps authentication, orchestration, transformation, and persistence responsibilities distinct.
4. Decide which data is static configuration, invocation payload, cross-step context, or durable state.
5. Choose the delivery and trust model early enough that packaging, signing, keys, and licensing are part of the design rather than retrofit work.

If the design still depends on invented ambient capabilities after this loop, it is not ready.

Primary provenance:

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

1. Recognize the Right Problem Class

Opscotch is strongest when the problem is operational automation with explicit boundaries, repeatable deployment, and reusable workflow logic.

Strong-fit shapes:

• scheduled collection, polling, and synchronization
• inbound event handling over HTTP, TCP, or file change
• multi-step integration across external systems
• transform, enrich, split, aggregate, and route workflows
• controlled distribution of the same logic across many environments
• solutions where trust, packaging, signing, encryption, or licensing matter

Weak-fit shapes:

• solutions that require arbitrary libraries or Node.js modules inside processors
• solutions that require async JavaScript, promises, or timer-driven code inside processors
• rich application hosting or UI-heavy products
• systems whose core value depends on long-lived complex in-memory state rather than explicit workflow boundaries
• solutions that need unconstrained outbound access without installer-defined bootstrap permissions

Suitability rule:

• judge fit against documented capability and constraints, not against whether marketing material named the exact use case

Primary provenance:

• docs/src/llm/processed/introduction/problem-to-plan.md -> https://docs.opscotch.co/docs/current/introduction/problem-to-plan
• docs/src/llm/processed/docs/workflow.md -> https://docs.opscotch.co/docs/current/workflow
• docs/src/llm/processed/core-capabilities/runtime.md -> https://www.opscotch.co
• docs/src/llm/processed/who-is-opscotch-for/automation-product-vendors.md -> https://www.opscotch.co
• docs/src/llm/processed/who-is-opscotch-for/managed-service-providers.md -> https://www.opscotch.co
• docs/src/llm/processed/who-is-opscotch-for/platform-infrastructure-teams.md -> https://www.opscotch.co

2. Frame the Problem in Opscotch Terms

Translate the requirement into five design questions:

1. What starts the work?
2. What data enters, from where, and under which permission boundary?
3. What sequence of decisions, calls, splits, enrichments, or reductions is required?
4. What state must survive across executions?
5. What leaves the system, and under which trust or commercial controls?

A good Opscotch design usually reads as:

• one business outcome
• one or more workflows representing reusable logic units
• a small number of clearly named steps with distinct responsibilities
• bootstrap permissions that are sufficient but not broader than necessary

Mirror the real operational sequence instead of collapsing it into one opaque processor. If the real-world flow is receive, authenticate, fetch, split, enrich, aggregate, and deliver, the workflow should usually expose those boundaries.

Primary provenance:

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

3. Draw the Bootstrap vs. Workflow Boundary

This is the most important architectural decision in Opscotch.

Put something in bootstrap when it is:

• installer-controlled
• environment-specific
• security-relevant
• required to define what the runtime is allowed to do
• expected to change only with operator intent or restart

Typical bootstrap responsibilities:

• workflow source and deployment registration
• allowed outbound hosts
• allowed file roots and file watcher scope
• allowed HTTP listeners
• allowed cross-deployment calls
• persistence root
• keys, package trust, and signer expectations
• licensing source and pool selection
• deployment-specific static data

Put something in workflow when it is:

• remotely updateable logic
• reusable business behavior
• step topology
• trigger wiring inside the installed boundary
• processor composition
• state transition logic
• workflow, step, or processor data that shapes behavior within the installed boundary

Use this rule:

• bootstrap answers "what may this deployment do?"
• workflow answers "how should this deployment use what it may do?"

Primary provenance:

• docs/src/llm/processed/docs/workflow.md -> https://docs.opscotch.co/docs/current/workflow
• docs/src/llm/processed/docs/patterns.md -> https://docs.opscotch.co/docs/current/patterns
• docs/docs/llm/opscotch-llm-skill.md -> https://docs.opscotch.co/docs/current/llm/opscotch-llm-skill
• docs/src/llm/processed/administrating/agent.md -> https://docs.opscotch.co/docs/current/administrating/agent

4. Shape Workflows, Steps, Processors, and Resources

Architect by responsibility, not by syntax.

Workflow

A workflow should represent a coherent operational outcome. Split workflows when trigger models, permissions, lifecycle cadence, or failure isolation differ materially.

Step

A step is the execution boundary. Create a new step when any of these changes:

• trigger responsibility
• authentication context
• failure-handling intent
• concurrency requirement
• persistence responsibility
• reuse value
• decision-making ownership

Useful step roles:

• entry or normalization
• controller
• worker
• authentication helper
• split or aggregate
• persistence reader or writer
• finalizer or response shaper

Processor

Think of processor hooks by purpose:

• urlGenerator: choose the target call shape
• payloadGenerator: form the outbound request content
• authenticationProcessor: apply request-local secret handling
• resultsProcessor: interpret output and decide the next move
• splitGenerator: fan out work items
• itemResultProcessor: handle per-item outcomes
• httpConnectFailedProcessor: shape network-failure behavior

Resource

Use resources for reusable behavior and parameterized logic. Do not use a resource to hide a step boundary that operators and architects need to reason about.

Primary provenance:

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

5. Choose Triggers Deliberately

Trigger choice is an architectural statement about event origin and ownership.

Use:

• http when an external actor pushes work to the runtime
• timer when the runtime must poll or evaluate on a schedule
• tcp when the input is socket-based
• fileWatcher when the real business event is local file mutation
• runOnce for startup-only initialization or seeding behavior
• deploymentAccess when another Opscotch deployment should remain the explicit caller

Selection heuristics:

• choose http when the external system already knows when work should begin
• choose timer when change must be discovered by checking
• choose fileWatcher only when bootstrap file permissions and locality are part of the intended design
• choose deploymentAccess when you want deployment boundaries and trust to stay explicit instead of exposing HTTP
• choose runOnce for support behavior, not recurring business flow

Avoid choosing a trigger just because it is technically possible. Choose the trigger that makes the event source and operational ownership obvious.

Decision rule:

• if the outside world knows when work should begin, prefer an inbound trigger
• if your deployment must discover change, prefer a polling or local-event trigger
• if the caller should remain another Opscotch deployment, preserve that fact with deploymentAccess instead of hiding it behind HTTP

Primary provenance:

• docs/src/llm/processed/introduction/problem-to-plan.md -> https://docs.opscotch.co/docs/current/introduction/problem-to-plan
• docs/src/llm/processed/docs/workflow.md -> https://docs.opscotch.co/docs/current/workflow
• docs/src/llm/processed/blog/2025-02-07-file-watcher.md -> https://docs.opscotch.co/blog/file-watcher
• docs/src/llm/processed/docs/patterns.md -> https://docs.opscotch.co/docs/current/patterns

6. Treat Authentication as a Boundary

Authentication in Opscotch is not just a header tweak. It is an isolated architectural concern.

Model authentication as one of three cases:

1. Static non-sensitive headers

• place them in bootstrap host headers

2. Request-local secret mutation

• use authenticationProcessor
• keep secrets in host data
• isolate credential use to the pending outbound call

3. Multi-step or stateful authentication flow

• call dedicated scripted-auth helper steps from the authentication flow

Architectural rules:

• normal business steps should not own secret-handling logic unless the request itself requires it
• authentication flows exist to establish or mutate auth state for the pending request
• authentication-only steps should not absorb unrelated business logic

If a design claim depends on what is available on the authentication context, verify it with MCP context tools before treating it as fact.

Primary provenance:

• docs/src/llm/processed/docs/workflow.md -> https://docs.opscotch.co/docs/current/workflow
• docs/src/llm/processed/docs/patterns.md -> https://docs.opscotch.co/docs/current/patterns
• docs/docs/workflow.md -> https://docs.opscotch.co/docs/current/workflow
• Opscotch Coder MCP context list

7. Design Data Flow and State Placement

Opscotch architecture is heavily shaped by where data lives.

Use:

• bootstrap data for deployment defaults and environment-specific values
• host data for host-specific configuration, especially auth-adjacent values
• workflow data for reusable logic defaults
• step data for role-local tuning
• processor data for fine-grained resource parameterization
• trigger input for invocation-specific payload
• step-to-step context for execution flow
• persistence for state that must survive across runs

Data merge guidance:

• broader to narrower merge order
• more specific values override less specific ones
• primitives overwrite
• objects and arrays merge additively

Architectural consequences:

• place stable defaults high in the hierarchy
• place local variation only where it is needed
• keep sensitive values in the most restricted layer that still supports the design
• treat persistence as step-scoped durable state, not as a general database

Useful persistent-state roles:

• cursors
• checkpoints
• last-seen markers
• counters
• queue coordination
• cache-like data with explicit ownership

Primary provenance:

• docs/src/llm/processed/introduction/problem-to-plan.md -> https://docs.opscotch.co/docs/current/introduction/problem-to-plan
• docs/src/llm/processed/docs/workflow.md -> https://docs.opscotch.co/docs/current/workflow
• docs/src/llm/processed/docs/patterns.md -> https://docs.opscotch.co/docs/current/patterns
• docs/src/llm/processed/blog/2025-02-07-queue.md -> https://docs.opscotch.co/blog/queue

8. Compose for Maintainability

Maintainable Opscotch design depends on explicit roles and visible boundaries.

Prefer:

• controller and worker separation when orchestration would otherwise dominate one step
• synthesized storage when state must survive across runs
• multiple triggers only when the shared logic is genuinely the same
• reusable resources parameterized by data
• default step properties when many steps share the same operational settings

Create multiple deployments when:

• trust boundaries differ
• permissions differ materially
• rollout cadence differs
• one failure domain should not impact another

Prefer small explicit steps over one large processor when:

• the flow crosses several external dependencies
• failure modes need different treatment
• authentication and business logic should remain separate
• future operators must be able to explain the path quickly

Do not split steps mechanically. Split when the boundary changes what an operator, reviewer, or downstream deployment needs to understand.

Primary provenance:

• docs/src/llm/processed/docs/patterns.md -> https://docs.opscotch.co/docs/current/patterns
• docs/src/llm/processed/docs/workflow.md -> https://docs.opscotch.co/docs/current/workflow
• Opscotch MCP patterns resource

9. Choose Raw Config vs. Packaged Delivery

This is an architectural operating-model choice, not just a file-format choice.

Prefer raw workflow JSON when:

• iteration speed matters more than artifact control
• configuration will be updated directly and frequently
• package trust controls add little value to the deployment model

Prefer packaged .oapp delivery when:

• the workflow is a productized artifact
• resources should be resolved and embedded at package time
• signer identity and package integrity matter
• distribution, trust, or commercial controls must travel with the artifact

Architectural tradeoff:

• raw config optimizes for fast change
• packaged delivery optimizes for repeatable distribution, trust, and artifact-level control

For packaged designs, decide early:

• package identity
• signer requirements
• encryption strategy
• resource ownership and resolution
• rollout and versioning expectations

Primary provenance:

• docs/src/llm/processed/administrating/packaging.md -> https://docs.opscotch.co/docs/current/administrating/packaging
• docs/src/llm/processed/blog/2026-03-24-packaging.md -> https://docs.opscotch.co/blog/packaging
• docs/src/llm/processed/core-capabilities/distribution.md -> https://www.opscotch.co
• docs/src/llm/processed/security/signed-packages.md -> https://www.opscotch.co

10. Design Trust, Keys, and Encryption as First-Class Concerns

Cryptography changes system shape in Opscotch. Choose key purpose based on responsibility:

• sign for artifact integrity and signer identity
• authenticated for sender-and-recipient asserted encryption
• anonymous for recipient-only secrecy
• symmetric for shared-secret encryption cases

Architectural implications:

• package trust requires the runtime to know which public identities it accepts
• authenticated package encryption requires sender and recipient identity placement across packager and bootstrap
• bootstrap encryption and string encryption affect install workflow and operator secret handling
• BYOK is an architectural separation of who creates, stores, rotates, and trusts keys
• local verification supports environments where online trust lookups are not acceptable or possible

Primary provenance:

• docs/src/llm/processed/administrating/cryptography.md -> https://docs.opscotch.co/docs/current/administrating/cryptography
• docs/src/llm/processed/administrating/packaging.md -> https://docs.opscotch.co/docs/current/administrating/packaging
• docs/src/llm/processed/core-capabilities/security-integrity.md -> https://www.opscotch.co
• docs/src/llm/processed/security/signed-packages.md -> https://www.opscotch.co

11. Design the Licensing Model, Not Just the License Field

Licensing affects topology, rollout, and operating ownership.

Prefer delegated or centralized licensing when:

• entitlements must change without rebuilding packages
• many runtimes should draw from a controlled platform-level source
• licensing is part of operating the product, not just shipping it once

Think through:

• where PLATFORM licenses live
• whether runtimes obtain licensing from a licensing app
• whether environments or organizations need separate entitlement boundaries
• what expiry and renewal mean operationally

Treat licensing as complementary to bootstrap policy:

• licensing governs entitlement to execute or consume the product
• bootstrap policy governs what the runtime may access while doing so

Architectural rule:

• if entitlements must change more often than artifacts are rebuilt, design around remote or delegated licensing rather than embedding the commercial model into package rollout

Primary provenance:

• docs/src/llm/processed/administrating/licensing.md -> https://docs.opscotch.co/docs/current/administrating/licensing
• docs/src/llm/processed/security/licensing.md -> https://www.opscotch.co
• docs/src/llm/processed/core-capabilities/commercial-control.md

12. Explain Decisions to Stakeholders in Opscotch Terms

Use this structure:

1. Why Opscotch fits

• The problem matches supported trigger shape, data-access shape, and workflow constraints.

2. Why the boundary is drawn this way

• Installer-controlled permissions, trust, and environment data are in bootstrap.
• Updateable business logic and orchestration are in workflow.

3. Why the step design looks this way

• Each step owns one responsibility boundary such as entry, auth, fetch, enrich, aggregate, persistence, or delivery.

4. Why the operating model looks this way

• The solution uses raw config or packaged delivery based on whether iteration speed or controlled distribution is the main priority.

5. Why the trust and commercial model looks this way

• Signing, encryption, and licensing choices reflect the deployment, ownership, and entitlement model.

Architect Checklist

Before implementation, confirm:

1. Fit

• Does the problem fit supported triggers, input paths, output paths, and processor constraints?

2. Boundary

• Which concerns are installer-controlled and belong in bootstrap?
• Which concerns are updateable logic and belong in workflow?

3. Topology

• How many deployments, workflows, and explicit step roles are needed?

4. Data

• What belongs in bootstrap data, host data, workflow data, step data, processor data, trigger input, or persistence?

5. Trust

• Is raw JSON enough, or is packaged delivery the correct artifact boundary?
• What signer and encryption model is required?

6. Commercial model

• Does the solution require centralized licensing, embedded entitlement, or no special licensing architecture?

7. Operability

• Can an operator explain what starts it, what it may access, what state it keeps, and how it is updated?

Provenance Map

Primary design sources used in this skill:

• docs/docs/llm/opscotch-llm-skill.md -> https://docs.opscotch.co/docs/current/llm/opscotch-llm-skill
• docs/src/llm/processed/introduction/problem-to-plan.md -> https://docs.opscotch.co/docs/current/introduction/problem-to-plan
• docs/src/llm/processed/docs/workflow.md -> https://docs.opscotch.co/docs/current/workflow
• docs/src/llm/processed/docs/patterns.md -> https://docs.opscotch.co/docs/current/patterns
• docs/src/llm/processed/administrating/packaging.md -> https://docs.opscotch.co/docs/current/administrating/packaging
• docs/src/llm/processed/blog/2026-03-24-packaging.md -> https://docs.opscotch.co/blog/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/core-capabilities/runtime.md -> https://www.opscotch.co
• docs/src/llm/processed/core-capabilities/distribution.md -> https://www.opscotch.co
• docs/src/llm/processed/core-capabilities/commercial-control.md
• docs/src/llm/processed/core-capabilities/security-integrity.md -> https://www.opscotch.co
• docs/src/llm/processed/who-is-opscotch-for/automation-product-vendors.md -> https://www.opscotch.co
• docs/src/llm/processed/who-is-opscotch-for/managed-service-providers.md -> https://www.opscotch.co
• docs/src/llm/processed/who-is-opscotch-for/platform-infrastructure-teams.md -> https://www.opscotch.co
• Opscotch Coder MCP guidance, pattern, resource, and context-discovery surfaces