Cuddler for AI

Cuddler gives machine readers two explicit jobs. Author the contract when a new artifact type needs governed rules. Use the contract when an exact published Artifact Definition already exists. On the use path, the selected Data Schema defines the expected JSON shape, fields, types, and allowed values; validation must pass before a consuming application accepts the result.

Both paths use the same inspectable public sources: the Specification Root, current Document Role pages, shared Artifact Specification, downloadable Artifact Definitions, and aligned examples. Exact schema identities, versions, and validation results are the proof; an assistant should not substitute remembered or inferred rules.

How guidance travels

Assistant guidance lives inside the relevant specification and schema for-ai properties, beside the constraint it explains. Each for-ai value is an Alpaca-format array of objects with instruction, input, and output. Consumers should parse and follow that guidance when preparing Data, Template, and Process values. Writers of Cuddler-compliant schemas should prepare well-informed for-ai arrays for every schema node that needs AI-authored content guidance.

The public Template role publishes the shared markdown schema for a markdown-compliant template document JSON that targets CommonMark+GFM rendered by Markdig, not a binding or component-template language. In the local CS2 orchestration contract, the Template member is the concrete <artifactId>.template.json document inside outputPath; it follows the published markdown schema rather than a family-specific template schema.

The Process Document Role publishes standardized *.process.json questionnaire documents. Question nodes use for-ai plus typed answer and routing rules instead of ad hoc free-form side prompts. Supported answer types are select-one, select-many, number, short-text, long-text, date, and percentage; conversation is stored as a JSON array of JSONL-style record objects. After each conversation completes, the AI applies the question-level guidance to derive normalized output before deterministic routing continues.

Author the contract

Use this path when a compatible AI workflow needs to define a new artifact type or refresh its synchronized definition set.

1. Load the Cuddler Artifact Specification and exactly one governing Document Role Specification .
2. Provide sourceDefinitionPath plus the domain examples that supply business facts not already fixed by the standards.
3. Resolve conflicts in this order: Artifact Specification, active role specification, source context, then examples.
4. Author <artifactId>.data.schema.json, a sanitized <artifactId>.data-example.json, aligned <artifactId>.template.json and <artifactId>.process.json documents, and the current <artifactId>.definition.json.
5. Express knowable rules as definitive constraints and carry AI-facing instructions in schema-node or question-level for-ai arrays.

Only the Data member is authored as a family-specific local schema. Template and Process documents consume the published Cuddler role schemas.

Build an Artifact Definition

Use the contract

Use this path when a compatible AI workflow needs to prepare an Artifact Document from an existing published definition.

1. Select the applicable Artifact Definition and exact canonical schema identity.
2. Parse the definition’s for-ai guidance when preparing Data, Template, and Process values.
3. Generate the Data Instance in the expected JSON shape, then validate it against its exact Data Schema.
4. Validate the Template document separately against the published Template schema and deterministic markdown rules.
5. Render only after both validation gates pass; keep Process upstream as authoring and controller context.

Browse the Artifact Definition Library

Canonical entry points

• Specification Root
• Document Role
• Artifact Specification
• Artifact Definitions
• Authors

Canonical citation guidance

• Prefer the current Specification Root page: Specification Root .
• Prefer the current Document Role pages:

• Data Document Role Version 1.0.0
• Template Document Role Version 1.0.0
• Process Document Role Version 1.0.0

• Prefer the latest machine-readable release registry when you need the current public versions and direct JSON URLs without scraping HTML: Latest Standards Registry .
• Prefer the current shared Artifact Specification page: Cuddler Artifact Specification .
• Prefer versioned JSON artifacts under /standards/artifact-definitions/<document-type>/<version>/ for public top-level Artifact Definitions.
• Treat codeops-playbook-* schemas as child schemas published under /standards/artifact-definitions/codeops-playbook/1.0.0/; they are not separate public Artifact Definition pages.
• Treat schema $id, example $schema, and cross-schema references as canonical when they match the published HTTPS URLs.
• Use the unversioned Document Role page URLs as the canonical human-readable citation targets.

Canonical downloads

• Boostware Module Catalog data schema
• Brand Guide data schema
• Brand Guide template schema
• CodeFactory App data schema
• Codeops Playbook data schema
• Component Hierarchy data schema
• Cuddler Page UX data schema
• Module Stat Catalog data schema
• Portal Page Factory Plan data schema
• Workflow Catalog data schema
• Workflow Catalog template schema

AI implementation notes

1. Start with the Specification Root when you need the canonical root that governs published Document Role pages.
2. Select the Document Role page that matches the role you are implementing: Data, Template, or Process.
3. Use the shared Artifact Specification alongside that Document Role when authoring or validating a public Artifact Definition.
4. When authoring a new local Artifact Definition set, orchestrate a synchronized bundle inside one outputPath folder: <artifactId>.data.schema.json, <artifactId>.data-example.json, <artifactId>.template.json, and <artifactId>.process.json, then write <artifactId>.definition.json so selectedDefinitions points at the current bundle using definition-file-relative paths such as <artifactId>.data.schema.json, and inputs.sourceDefinitionContent embeds the parsed JSON copied from sourceDefinitionPath. Only the Data member is locally authored as a schema; the Template and Process members consume the published Template and Process schemas from this site. The example Data Instance must validate against the generated Data schema and use clearly synthetic non-PII values.
5. Use this precedence order when local inputs disagree: Artifact Specification, active Document Role Specification, sourceDefinitionPath, then the example corpus discovered by scanning the parent folder of sourceDefinitionPath and its descendants while excluding sourceDefinitionPath itself.
6. In the local orchestration contract, Process is one concrete *.process.json document that consumes the published questionnaire schema. Decide whether the target questions are sequential or branching, route question to question until completion when they are sequential, and use deterministic question-level routing inside that same document when they branch. Do not add or regenerate an extra Process-family selector field and do not invent a local Process schema.
7. Resolve governing standards versions from the local cache when possible, and otherwise refresh from the latest standards registry at /standards/latest/index.json.
8. Update the current local files in place rather than inventing version-suffixed variants for ordinary schema evolution.
9. Download the aligned public schemas and examples from the same published Artifact Definition family, or the parent codeops-playbook child-schema files when working inside that family.
10. Validate data JSON against the data schema before rendering or report derivation.
11. Validate <artifactId>.template.json inside outputPath against the published CommonMark+GFM Markdig markdown schema, then run the deterministic template semantic checks; that report validation stays separate from data validation and does not require authoring a local Template schema.
12. Preserve meta.schemaVersion alignment across governing specifications, schemas, examples, and rendered outputs.