Canonical standard text

The section below is the full normative publication rendered directly from the canonical repository source. Use it for exact wording, implementation details, and citation.

Version 1.0.0

1. Abstract

This document defines the Automation Document Role v1.0.0 as the governing Document Role for the Workflow domain. Artifact Definitions classified into this domain MUST conform to both this Document Role and the shared Artifact Specification.

The v1 automation model remains intentionally small:

1. a catalog owns one or more workflows,
2. a workflow defines one ordered sequence of steps,
3. a step is defined by canonical prompt instructions and an optional supporting script asset.

This release is a hardening patch over v1.0.0. It corrects support-artifact schema handling, sharpens conformance language, makes the feed derivation rules more deterministic, aligns diagnostics with RFC 6901 JSON Pointer semantics, and expands the conformance fixture set so every public rule identifier is exercised by at least one published fixture.

2. Status, Scope, and Publication Framing

This document is a stable public normative publication for the v1 automation contract published at https://www.cuddler.dev/standards/document-role/automation/.

This versioned Document Role is intentionally self-contained. It includes the full normative contract for release 1.0.0, and no linked schema, manifest, example, or support file is required in order to understand the required behavior defined here.

The primary normative contribution is the core automation contract made of:

1. catalog.manifest.json
2. workflow.manifest.json
3. prompt.json

The rest of the release is organized as supporting material around that core:

1. Publication profile: feed.json
2. Adjunct package profiles: plugin.manifest.json, skill.manifest.json, exec.workflow.json
3. Conformance and support artifacts: diagnostics schema, registries, tests manifest, implementation-report template, and example bundle manifest

This Document Role defines:

1. the core automation model,
2. the domain-level rules for JSON Artifact Definitions used in this domain, alongside the shared Artifact Specification that governs Artifact Definition authoring globally,
3. the authoring rules for valid automation data files,
4. the semantic validation rules that run after per-file schema validation,
5. deterministic diagnostics and conformance expectations,
6. publication derivation rules for feed.json,
7. governance, migration, reuse, security, and privacy expectations for the public standard.

This Document Role does not standardize:

1. a workflow runtime,
2. plugin transport protocols,
3. desktop UX,
4. agent-memory or state-persistence internals,
5. permission prompts or approval UIs,
6. package signature infrastructure,
7. telemetry formats,
8. structured step I/O contracts.

3. Conformance and Requirement Language

3.1 BCP 14 Language

The key words MUST, MUST NOT, REQUIRED, SHALL, SHALL NOT, SHOULD, SHOULD NOT, RECOMMENDED, MAY, and OPTIONAL in this document are to be interpreted as described in BCP 14 (RFC 2119 and RFC 8174) when, and only when, they appear in all capitals.

3.2 Formal conformance classes

This specification defines the following formal conformance classes:

1. Artifact Definition authoring implementation: produces or maintains the published JSON Artifact Definitions and support-artifact schemas defined by this release.
2. Validator: resolves schemas, validates source artifacts, runs semantic validation, and emits deterministic diagnostics.
3. Publisher: derives publication artifacts such as feed.json from valid source artifacts.

These are the only formal conformance classes for v1.0.0.

3.3 Informative implementation profiles

This release also publishes informative profiles that are useful but are not themselves formal conformance classes:

1. AI executor read-only v1 profile: consumes the public contract, locates the relevant artifacts, and understands the catalog -> workflow -> step model without claiming standardized execution semantics.
2. Adjunct-aware profile: additionally understands one or more optional adjunct surfaces such as plugin.manifest.json, skill.manifest.json, or exec.workflow.json.

Those profiles are published for tooling guidance and fixture discovery. They are not substitutes for the formal conformance classes above.

3.4 Conforming automation Artifact Definition

A conforming Cuddler automation Artifact Definition MUST:

1. use JSON Schema Draft 2020-12,
2. match the authoring profile defined by this Document Role,
3. include meaningful description text for every instance-visible property, either directly or through a reused definition,
4. constrain identifiers, versions, and paths consistently with this document,
5. remain aligned with the core automation model in Section 7,
6. be listed in specification.index.json,
7. preserve stable canonical $id values for the release.

3.5 Conforming automation data file

A conforming automation data file MUST:

1. declare the correct $schema value for its artifact type,
2. pass JSON Schema validation against that schema,
3. satisfy the relevant authoring profile in this document,
4. pass the semantic validation rules defined in Section 13 when cross-file relationships apply.

3.6 Conforming validator

A conforming validator MUST:

1. resolve the declared schema according to Section 12,
2. fail on schema-validation errors,
3. run semantic validation after schema success,
4. fail on semantic-validation errors,
5. emit diagnostics that conform to diagnostics.schema.json,
6. emit stable ruleId values for every public failure condition,
7. identify the failing artifact and location deterministically,
8. preserve authored ordering when reporting failures discovered in ordered arrays or repeated semantic checks.

3.7 Conforming publisher

A conforming publisher MUST:

1. begin from valid source artifacts,
2. refuse to publish source content that fails schema validation or semantic validation,
3. derive publication artifacts from valid source content rather than treating them as standalone authored truth,
4. preserve the catalog -> workflow -> step model when emitting publication outputs,
5. generate publishedOnUtc values in UTC with a trailing Z when the publisher is the system generating those values,
6. derive feed.json according to Section 14.

4. Normative References

The following references are normative for this specification:

1. RFC 2119, Key words for use in RFCs to Indicate Requirement Levels
2. RFC 8174, Ambiguity of Uppercase vs Lowercase in RFC 2119 Key Words
3. JSON Schema Draft 2020-12 Core
4. JSON Schema Draft 2020-12 Validation
5. JSON Schema Draft 2020-12 Recommended Output
6. RFC 3986, Uniform Resource Identifier (URI): Generic Syntax
7. RFC 6570, URI Template
8. RFC 6901, JavaScript Object Notation (JSON) Pointer
9. RFC 7763, The text/markdown Media Type
10. Semantic Versioning 2.0.0, https://semver.org/
11. RFC 3339, Date and Time on the Internet: Timestamps
12. RFC 3552, Guidelines for Writing RFC Text on Security Considerations

Where this specification restricts a referenced standard to a narrower authoring profile, the narrower Cuddler rule governs within this contract.

5. Design Goals and Non-goals

5.1 Design goals

The design goals of v1 are:

1. minimal authoring core,
2. transport and runtime neutrality at the source-contract level,
3. machine-validatable JSON artifacts,
4. human-authorable source files,
5. public documentation that humans and AI assistants can consume directly,
6. explicit separation of schema validation and semantic validation.

5.2 Non-goals

The non-goals of v1 are:

1. full workflow-engine standardization,
2. standardized step I/O contracts,
3. universal runtime capability negotiation,
4. agent-memory serialization,
5. package-signing infrastructure,
6. telemetry or execution-log standardization.

6. Terminology and Identity

This Document Role uses Automation Document Role as the public contract name.

The legacy https://www.cuddler.dev/standards/document-role/automation/v1.0.0/... namespace remains the canonical identifier namespace only for the published instance-validation schemas retained for compatibility in the v1 line:

1. catalog.manifest.schema.json
2. workflow.manifest.schema.json
3. prompt.document.schema.json
4. plugin.manifest.schema.json
5. skill.manifest.schema.json
6. exec.workflow.schema.json
7. feed.schema.json

Support-artifact schemas published for v1.0.0 use Cuddler-hosted schema identifiers under https://www.cuddler.dev/standards/document-role/automation/.

Public prose, release pages, and examples MUST use Cuddler naming. The retained legacy namespace MUST NOT be interpreted as a competing product identity.

7. Core Automation Model

The v1 core automation contract consists of three required data-file types:

1. catalog.manifest.json
2. workflow.manifest.json
3. prompt.json

Their relationship is fixed:

1. a catalog manifest declares one automation family,
2. the catalog references one or more workflow manifests,
3. each workflow manifest declares one ordered sequence of steps,
4. each step references one prompt document,
5. a step MAY also reference one supporting script asset.

The core contract does not require:

1. a plugin runtime,
2. a desktop package,
3. a transport mechanism,
4. a publication feed entry,
5. a machine-readable execution-state model.

This conceptual core MUST remain stable throughout the v1 line.

8. Artifact Taxonomy and Canonical Source Layout

8.1 Core contract

The minimum authored source surface for a valid automation family is:

1. catalog.manifest.json
2. workflow.manifest.json
3. prompt.json

8.2 Companion publication and adjunct profiles

The following surfaces are companion profiles rather than part of the minimum authored source surface:

1. feed.json as the publication profile
2. plugin.manifest.json as an adjunct package profile
3. skill.manifest.json as an adjunct package profile
4. exec.workflow.json as an adjunct package profile

Those artifacts are optional for core source validity and do not add normative requirements beyond the ones stated in this document.

8.3 Canonical source layout

The canonical source layout for one catalog is:

catalogs/<catalog-id>/
  catalog.manifest.json
  plugin.manifest.json                # optional adjunct
  skill.manifest.json                 # optional adjunct
  exec.workflow.json                  # optional adjunct
  <workflow-id>/
    workflow.manifest.json
    <step-id>/
      prompt.json
      script.ps1                      # optional

All manifest path references in v1.0.0 MUST use the catalog-root-relative reference frame.

That means every referenced path is resolved relative to the directory that contains catalog.manifest.json.

9. Artifact Registry

The machine-readable artifact registry for this release is published as specification.index.json.

The normative instance-validation artifact mapping is:

Support-artifact schemas and manifests are also normative release artifacts and are listed in specification.index.json.

specification.index.json is a machine-readable registry for the release package. It supports tooling and publication workflows, but the normative contract remains fully stated in this document.

10. Path, Identifier, Version, and Format Rules

10.1 Identifier rules

Catalog ids, workflow ids, step ids, prompt ids, and publication asset ids MUST:

1. be case-sensitive,
2. use lowercase kebab-case,
3. match ^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$,
4. remain stable once published unless all affected references are intentionally updated in the same change.

promptId MUST equal the owning step id.

10.2 Version rules

The canonical authoring form for automation manifest version fields is a release-version string in MAJOR.MINOR.PATCH form such as 2.3.0.

For compatibility, the catalog, workflow, and exec-workflow schemas MAY still accept a positive integer version in the v1 line.

When both forms are technically accepted:

1. authors SHOULD emit a release-version string,
2. validators MUST accept either the canonical release-version string or a positive integer where the schema allows it,
3. examples in this Document Role MUST use release-version strings,
4. integer compatibility is deprecated for a future major revision.

10.3 JSON Schema format handling

Implementations MUST support JSON Schema Draft 2020-12.

Within this Document Role, the following format-bearing constraints MUST be treated as assertions by a conforming validator:

1. date
2. date-time
3. uri
4. uri-reference

Validators MUST NOT silently downgrade those checks to annotation-only behavior for conformance decisions.

10.4 Path resolution algorithm

A conforming validator or publisher MUST resolve catalog-root-relative paths with the following algorithm:

1. take the directory containing catalog.manifest.json as the catalog root,
2. read the authored path exactly as written,
3. reject the path if it is empty,
4. reject the path if it begins with /,
5. reject the path if it contains \,
6. reject the path if it contains a Windows drive prefix such as C:,
7. split on /,
8. reject any empty segment, . segment, or .. segment,
9. join the remaining segments using / for logical resolution,
10. resolve the logical path beneath the catalog root,
11. reject the path if filesystem canonicalization escapes the catalog root,
12. reject the path if the target does not exist when the rule being evaluated requires an existing artifact.

The path language of v1.0.0 is intentionally the ASCII-like language enforced by the published path regexes. This release does not define additional Unicode normalization behavior.

11. Schema Resolution Rules

11.1 Core and companion instance artifacts

Within Cuddler core, adjunct, and publication instance documents, $schema is an application-level schema locator that identifies the canonical validation schema for the instance document.

11.2 Support artifacts

Within support manifests and registries such as specification.index.json, semantic-rules.json, conformance.manifest.json, tests/manifest.json, implementation-report.template.json, and examples.manifest.json, $schema identifies the Cuddler-published instance schema for that support artifact type.

11.3 Resolution algorithm

A conforming validator MUST resolve schemas as follows:

1. read the $schema string from the instance document,
2. compare it to the canonical identifiers listed in specification.index.json,
3. if an exact canonical identifier match exists in a local pinned mapping, use that local resource,
4. otherwise, if an exact match exists in a release-local artifact registry bundled with the validator, use that resource,
5. otherwise, an implementation MAY fetch the schema over the network if its security policy allows network schema resolution,
6. if network schema resolution is disabled or fails, emit AUT-SCHEMA-001,
7. if the validator has a pinned release artifact for that schema identifier, it MUST compare the resolved schema bytes to the SHA-256 digest published in specification.index.json,
8. if the resolved bytes do not match the published pinned digest, the validator MUST fail closed and emit AUT-SCHEMA-002.

For public Cuddler release validation, offline pinned release-local schemas are RECOMMENDED over live network fetches.

Validators MUST NOT prefer an arbitrary same-filename local file over the canonical schema-identifier mapping when the two disagree.

12. Semantic Validation, Diagnostics, and Rule Identifiers

12.1 Semantic validation model

Schema validation checks one document at a time.

Semantic validation checks cross-file relationships and release-specific invariants that cannot be expressed adequately in one schema alone.

The machine-readable semantic rule registry for this release is semantic-rules.json.

12.2 Required public rule identifiers

At minimum, a conforming validator MUST implement these public rule identifiers:

1. AUT-SCHEMA-001: schema could not be resolved
2. AUT-SCHEMA-002: resolved schema bytes did not match the pinned release schema digest
3. AUT-SCHEMA-003: JSON Schema validation failed
4. AUT-SEM-001: each catalog.manifest.json.workflows[].id MUST equal the id inside the referenced workflow.manifest.json
5. AUT-SEM-002: each declared workflow path MUST resolve to an existing workflow.manifest.json within the catalog root
6. AUT-SEM-003: each workflow step id MUST be unique within its owning workflow
7. AUT-SEM-004: each declared promptPath MUST resolve to an existing prompt.json
8. AUT-SEM-005: each declared scriptPath MUST resolve to an existing script asset
9. AUT-SEM-006: each prompt.json.promptId MUST match the owning step id
10. AUT-SEM-007: each referenced adjunct manifest path MUST resolve to the declared adjunct artifact type
11. AUT-SEM-008: duplicated feed-item summary fields MUST equal their embedded manifest counterparts when both are present
12. AUT-SEM-009: duplicate workflow reference ids within a catalog MUST be rejected
13. AUT-SEM-010: duplicate publication package identity tuples (catalogId, version) within one feed MUST be rejected

12.3 Diagnostics model

A conforming validator MUST emit a JSON object matching diagnostics.schema.json.

Each diagnostic entry MUST include:

1. message
2. severity
3. artifactPath
4. ruleId

When available, a diagnostic SHOULD also include:

1. code
2. instancePath
3. schemaPath
4. expected
5. actual
6. relatedArtifactPath

instancePath MUST be an RFC 6901 JSON Pointer.

schemaPath MUST be an RFC 6901 JSON Pointer into the resolved schema document.

Errors fail conformance. Warnings and info entries do not.

12.4 Metadata equality and intentional non-equality

The following equality rules are normative:

1. promptId MUST equal the owning step id,
2. catalog.workflows[].id MUST equal the referenced workflow id,
3. whenever root feedItem summary fields are present for displayName, description, author, organization, categories, or tags, they MUST equal the corresponding fields inside manifest.

The following fields are intentionally allowed to differ:

1. workflow.steps[].title and prompt.json.title,
2. workflow.steps[].summary and prompt.json.summary.

12.5 Example diagnostics

Schema failure example:

{
  "specVersion": "1.0.0",
  "valid": false,
  "diagnostics": [
    {
      "message": "Required property \"workflows\" is missing.",
      "severity": "error",
      "artifactPath": "catalogs/customer-success-playbooks/catalog.manifest.json",
      "instancePath": "",
      "schemaPath": "/required",
      "ruleId": "AUT-SCHEMA-003",
      "expected": [
        "$schema",
        "id",
        "version",
        "name",
        "description",
        "workflows"
      ]
    }
  ]
}

Semantic failure example:

{
  "specVersion": "1.0.0",
  "valid": false,
  "diagnostics": [
    {
      "message": "workflow reference id \"lead-intake\" does not match the referenced workflow id \"lead-intake-v2\".",
      "severity": "error",
      "artifactPath": "catalogs/customer-success-playbooks/catalog.manifest.json",
      "instancePath": "/workflows/0/id",
      "ruleId": "AUT-SEM-001",
      "relatedArtifactPath": "catalogs/customer-success-playbooks/lead-intake/workflow.manifest.json",
      "expected": "lead-intake-v2",
      "actual": "lead-intake"
    }
  ]
}

13. Publication Derivation Rules

feed.json is the publication profile for published automation packages.

It is derived output. It MUST NOT be treated as independently authored truth for the source contract.

13.1 Deterministic field mappings

When a conforming publisher derives one feedItem from one valid source catalog and no separate publication profile supplies overriding metadata:

1. root catalogId and manifest.catalogId MUST be derived from catalog.manifest.json.id,
2. root version and manifest.version MUST be derived from the published package version,
3. manifest.contractVersion MUST be set to 1.0.0,
4. manifest.displayName MUST be derived from catalog.manifest.json.name,
5. manifest.description MUST be derived from catalog.manifest.json.description,
6. root displayName and root description, when present, MUST equal the manifest values,
7. manifest.workflows[] MUST be emitted in the same order as the source catalog workflow references,
8. each manifest.workflows[].workflowId MUST be derived from the referenced workflow manifest id,
9. each manifest.workflows[].title MUST be derived from the referenced workflow manifest name,
10. each manifest.workflows[].relativePath MUST default to the catalog workflow reference path,
11. manifest.supportAssets[] MUST be derived from every declared scriptPath in workflow order, then step order,
12. each derived support-asset assetId MUST be <workflow-id>-<step-id>-script,
13. each derived support-asset relativePath MUST default to the source scriptPath,
14. each derived support-asset description MUST be Supporting script for step "<step title>" in workflow "<workflow name>".,
15. packageSha256 MUST be computed over the exact bytes of the published zip artifact,
16. publishedOnUtc at both the root and manifest levels MUST be UTC timestamps with a trailing Z.

13.2 Optional publication-only metadata

The following feed fields are publication-only metadata and are OPTIONAL in v1.0.0 unless a separate publication profile or publisher policy supplies them:

1. author
2. organization
3. categories
4. tags
5. installationSummary

When duplicated at both the root feed-item level and the embedded manifest level, they MUST remain equal.

13.3 Ordering and uniqueness

A conforming publisher MUST:

1. reject duplicate (catalogId, version) tuples within one generated feed,
2. serialize the top-level feed array in ascending order by catalogId, then by Semantic Version precedence of version,
3. preserve authored order for workflow-derived entries,
4. preserve derived workflow/step order for support assets unless a separate publication profile defines another deterministic order.

For v1.0.0, downloadUrl remains the historical field name even though the value is package-relative rather than an absolute URL.

14. Artifact Authoring Profiles

14.1 catalog.manifest.json

A conforming source catalog.manifest.json MUST define:

1. $schema
2. id
3. version
4. name
5. description
6. workflows

It MAY define:

1. sourceRepository
2. exportedAt
3. sourcePlugin
4. pluginManifestPath
5. skillManifestPath
6. workflowBundlePath

14.2 workflow.manifest.json

A conforming source workflow.manifest.json MUST define:

1. $schema
2. id
3. version
4. name
5. description
6. steps

Workflow steps[] MUST preserve execution order exactly as authored.

Each step MUST define:

1. id
2. title
3. promptPath

Each step MAY define:

1. summary
2. scriptPath

In v1.0.0, scriptPath remains a PowerShell-shaped adjunct path ending in script.ps1. That is an explicit v1 scope constraint, not a claim of cross-runtime execution neutrality for script assets.

14.3 prompt.json

A conforming prompt.json MUST define:

1. $schema
2. promptId
3. title
4. instructions

It MAY define:

1. summary
2. format

instructions is the canonical prompt content field and is authored as Markdown text embedded inside the JSON document.

In v1.0.0, omitted format values are treated as markdown. The field remains in the schema for explicitness and machine-readability even though only markdown is currently allowed.

14.4 Companion adjunct profiles

plugin.manifest.json, skill.manifest.json, and exec.workflow.json remain optional companion adjunct profiles in v1.0.0.

They MUST NOT replace the source authority of:

1. catalog.manifest.json
2. workflow.manifest.json
3. prompt.json

15. Security Considerations

This section is normative.

Implementations and authors MUST account for at least the following risks:

1. path traversal through crafted relative paths,
2. symlink or junction escape outside the catalog root,
3. schema poisoning through untrusted remote schema resolution,
4. untrusted prompt content that may instruct unsafe actions,
5. untrusted supporting scripts,
6. malicious package substitution or hash mismatch,
7. publication drift between derived artifacts and their source catalog,
8. denial of service through extremely large files, deeply nested JSON, or pathological schemas,
9. tool/runtime permission overreach by execution-oriented implementations.

Conforming validators and publishers MUST:

1. validate path references according to Section 10.4,
2. reject references that escape the catalog root after canonicalization,
3. fail closed when schema resolution is ambiguous or digest validation fails,
4. avoid treating prompt text or scripts as trusted merely because they pass schema validation,
5. treat packageSha256 as an integrity field over exact artifact bytes,
6. avoid granting network, filesystem, credential, or host-execution permissions solely because an artifact references them.

16. Privacy Considerations

This section is normative.

The core contract defined here does not itself authorize access to private data sources.

Implementations MUST assume that prompt content, summaries, publication descriptions, provenance fields, and example datasets may contain sensitive information.

Implementations SHOULD:

1. apply least-privilege access to any data consulted during authoring or execution,
2. avoid leaking private repository paths or unpublished metadata into derived public artifacts,
3. ensure that publication bundles and examples do not expose secrets, credentials, or internal-only source metadata,
4. treat telemetry and execution logs as out of scope unless separately standardized and governed.

17. Versioning, Governance, and Reuse

17.1 Status states

This Document Role family recognizes the following status states:

1. draft
2. stable
3. deprecated
4. obsolete

v1.0.0 is stable.

17.2 Patch releases

Non-breaking clarifications and hardening changes MAY be released as patch versions.

Patch releases MUST preserve:

1. the core catalog -> workflow -> step model,
2. canonical instance-validation schema $id values for the v1 line,
3. existing conforming source artifact shapes unless a change is explicitly declared breaking.

17.3 Breaking changes

Breaking changes MUST use a new major version.

Examples include:

1. renaming canonical fields,
2. removing integer-version compatibility,
3. replacing the top-level feed.json array shape,
4. changing the script model from the current PowerShell-shaped v1 constraint,
5. eliminating duplicated identity fields such as catalog.workflows[].id or promptId.

17.4 Reuse and redistribution

For this public Document Role family:

1. published JSON Artifact Definitions MAY be mirrored and redistributed when attribution is preserved and the original public URL is referenced,
2. published example artifacts MAY be reused and redistributed when attribution is preserved and the original public URL is referenced,
3. published conformance test artifacts MAY be mirrored and incorporated into independent validator or publisher test suites with attribution,
4. short quotations from the specification for implementation or review purposes are permitted with attribution,
5. altered redistributions SHOULD clearly indicate that they are modified copies and MUST NOT be presented as the canonical Cuddler publication.

18. Informative Appendices

18.1 Example bundle

The machine-readable example bundle for this release is published as examples.manifest.json.

The examples intentionally use source/package version 2.3.0 and feed contractVersion 1.0.0 so readers can distinguish artifact/package versioning from Document Role versioning.

18.2 Conformance fixtures

The conformance test bundle for this release is published under tests/ with a machine-readable index at tests/manifest.json.

Every public rule identifier in Section 12.2 is exercised by at least one published fixture.

18.3 AI implementation notes

The v1.0.0 public surface is intentionally sufficient for:

1. schema discovery,
2. artifact discovery,
3. core source authoring,
4. validation,
5. publication derivation,
6. machine-readable fixture discovery.

The following execution-oriented surfaces remain intentionally out of scope for v1.0.0 and are candidates for a future additive release:

1. structured step inputs and outputs,
2. cross-step state handoff semantics,
3. capability and permission declarations,
4. retry, timeout, and idempotence semantics,
5. machine-readable execution-state persistence.