Skip to main content
Spruce

Spruce

Docs

Discord

Reference

Artifact and Template Schema

Every artifact and template in Spruce is a markdown file with YAML frontmatter. This page documents the exact schema used by the file format.

Artifact file

yaml

---
id: SPR-abc123          # unique, auto-generated
type: feature           # matches a template name
title: My feature       # required
status: In Progress     # template-defined
priority: High          # template-defined
size: M                 # template-defined
assignee: alice         # user id from users/
tasks:                  # relationship field
  - SPR-def456
  - SPR-ghi789
created: '2026-04-24T12:00:00Z'
modified: '2026-04-24T14:00:00Z'
---

# My feature

Markdown body. Freeform.

Required fields

  • id: auto-generated, never manually set.
  • type: must match a template name in templates/.
  • title: required, also drives the H1 in the body.

Common optional fields (template-dependent)

  • status, priority, size, assignee: most built-in templates define these.

Timestamps

  • created / modified: ISO-8601 UTC. Spruce maintains these; don't edit by hand.

Relationship fields

Relationship fields hold an array of target artifact IDs. Example:

yaml

tasks: [SPR-def456, SPR-ghi789]

Template file

A template lives at templates/<name>.md. It has a display block and a schema block in frontmatter:

yaml

---
display:
  color: '#06b6d4'
  icon: star-filled

schema:
  status:
    type: text
    label: Status
    required: true
    defaultValue: Backlog
    hints: [pinned]
    options:
      - { value: Backlog, label: Backlog, display: { color: '#64748b', icon: circle-dashed } }
      - { value: Todo, label: Todo, display: { color: '#f97316', icon: circle-dot } }
      # ...

  tasks:
    type: relationship
    template: task
    label: Tasks
    multiple: true
    required: false
---

A planned piece of work that delivers user-facing value.

The body below the frontmatter is the template's description, shown in the type picker and in Settings.

Field keys

  • type: text | number | date | boolean | relationship | user.
  • label: display name.
  • description: helper text.
  • required: boolean.
  • defaultValue: initial value for new artifacts.
  • hints[]: pinned etc.
  • multiple: for relationship and constrained text.
  • options[]: for constrained text.
  • template: for relationship (target type name).

Reference

Keyboard Shortcuts

Reference

MCP Tool Reference