Build Your First Artifact Definition

This tutorial shows the shortest useful path from document intent to a synchronized local Artifact Definition set, then from that set to validatable Artifact Documents. The goal is not to reinvent the standards; it is to preserve one explicit contract across both agent workflows.

The two-agent workflow

Agent 1: author the contract

1. Start with the relevant Document Role so you know which domain you are working in.
2. Load the shared Artifact Specification as the flagship authoring contract.
3. Prepare the orchestration payload with outputPath and sourceDefinitionPath; point sourceDefinitionPath at the source-side JSON context file you want embedded, and the Process side now resolves automatically to the single *.process.json contract.
4. Inspect the matching Artifact Definitions and any existing source definition file to see how published examples and current context are structured.
5. Draft the Process document, Data definition, and Template document together so the controller, model, and markdown-template view contracts stay aligned. Only the Data member is locally authored as a schema; the Template and Process members consume the published schemas from www.cuddler.dev.
6. Validate the synchronized bundle plus the definition file, then update the current files in place.

The expected current files inside outputPath are:

<artifactId>.data.schema.json
<artifactId>.data-example.json
<artifactId>.template.json
<artifactId>.process.json
<artifactId>.definition.json

Agent 2: use the contract

1. Read <artifactId>.definition.json to resolve the active synchronized files.
2. Bind the Data Instance to the exact "$id" of <artifactId>.data.schema.json.
3. Parse applicable schema-node and Process-question for-ai guidance instead of relying on a separate undocumented prompt.
4. Prepare the Data, Template, and Process values required by the selected definitions.
5. Validate the Data Instance against the Data Schema.
6. Validate the Template document against the published Template schema and deterministic markdown rules.
7. Render only after both validation gates pass; retain diagnostics when a value does not conform.

What to keep in view

• The Document Role tells you what the domain means.
• The Artifact Specification tells you how a public Artifact Definition must be authored.
• The latest standards registry at /standards/latest/index.json exposes the current public versions and direct JSON URLs when a local cache needs to refresh.
• <artifactId>.definition.json inside outputPath tells downstream tooling which synchronized bundle is current, including <artifactId>.data-example.json, and embeds the parsed JSON copied from sourceDefinitionPath.
• The example Artifact Documents tell you what a successful implementation looks like without overriding the standards.

Practical checkpoints

• Keep the synchronized bundle aligned on one artifact identity and business purpose.
• Keep the selectedDefinitions block in <artifactId>.definition.json inside outputPath pointed at the current bundle.
• Bind the instance "$schema" to the exact canonical schema identity.
• Keep the Process output as one *.process.json document that consumes the published questionnaire schema; if the target questions are sequential, route question to question until completion, and if they branch, keep that branching inside deterministic question-level routing in the same document.
• Treat validation failures as blockers, not warnings to work around.
• Keep the final rendered output readable without weakening sanitization defaults.

Next step

Once the definition-building side is clear, move to Create a Data Schema to refine the one family-specific schema that local orchestration authors. Then browse the Artifact Definition Library to experience the downstream document-building side of the contract.