​

Artifact schemas

• the artifact type
• its parent requirement
• its lifecycle
• its payload shape
• its document semantics

​

Full example

artifact:
  id: work_item
  name: Work Item
  icon: list-todo
  phase: plan

parent: intent

lifecycle:
  initial: draft
  states:
    - id: draft
      label: Draft
      actor: system
    - id: in_review
      label: In review
      actor: human
      handoff: true
    - id: approved
      label: Approved
      actor: human
    - id: superseded
      label: Superseded
      actor: system
      terminal: true

schema:
  type: object
  properties:
    summary:
      type: string
      required: true
      description: Markdown summary of the work item and the intended user-visible outcome.
    problem_statement:
      type: string
      required: false
      description: Markdown description of the problem being solved and why it matters.
    delivery_notes:
      type: string
      required: false
      description: Markdown notes describing scope boundaries, constraints, and implementation direction.
    acceptance_criteria:
      type: array
      required: false
      items:
        type: string
      description: Concrete acceptance criteria used to judge whether the work item is complete.

document:
  sections:
    - id: summary
      title: Summary
      field: summary
      kind: markdown
    - id: problem
      title: Problem statement
      field: problem_statement
      kind: markdown
    - id: delivery
      title: Delivery notes
      field: delivery_notes
      kind: markdown
    - id: acceptance
      title: Acceptance criteria
      field: acceptance_criteria
      kind: markdown

​

artifact

artifact:
  id: walkthrough
  name: Walkthrough
  icon: file-text
  phase: build

• id, name, and phase are required.
• phase must reference a phase from workflow.yaml.
• id must match the key used in workflow.yaml -> artifacts.

​

parent

parent: run

• Omit parent for root artifacts.
• When present, Fabriqa derives child relationships automatically.
• Agents should create the artifact under a real parent instance of that type.

​

lifecycle

lifecycle:
  initial: draft
  states:
    - id: draft
      label: Draft
      actor: system
    - id: verified
      label: Verified
      actor: human
      handoff: true

• the lifecycle only belongs to this artifact file
• Fabriqa does not reference inline lifecycles independently
• repeating lifecycle labels adds verbosity without adding runtime value

• one artifact file contains its own state machine
• authors do not need to jump between schema files to understand lifecycle state
• built-in workflows intentionally repeat lifecycle blocks when several artifact types share the same states

​

schema

• field names
• types
• enums
• required fields
• nested structures
• field descriptions
• field-local requiredness

• use type: object at the root
• Fabriqa treats artifact payload objects as closed by default in V1, so define every supported field explicitly
• agents may only create or update fields that are declared in schema.properties plus built-in system fields such as tags, target_scope, target_workspace_project_ids, and touched_workspace_project_ids
• declare requiredness on the field itself with required: true or required: false
• use description aggressively
• keep field names stable

schema:
  type: object
  properties:
    summary:
      type: string
      required: true
      description: Markdown summary of the artifact.

​

document

document:
  sections:
    - id: summary
      title: Summary
      field: summary
      kind: markdown

• which fields form the main document body
• the order of the main reader experience

• markdown string fields
• enums and primitive values
• string arrays such as tags, project IDs, and touched files
• system fields such as status, created_at, and updated_at

​

document.sections

sections:
  - id: summary
    title: Summary
    field: summary
    kind: markdown

• Prefer field for almost every section.
• field should usually point to a string property rendered as markdown.
• Use kind: markdown for both string fields and array<string> fields. Arrays of strings should render as bullet lists in the document body.
• If one markdown section uses multiple fields, Fabriqa combines those values into one markdown block in reading order instead of rendering them as separate widgets.
• Use fields only when you need one structured section to display several primitive or list fields together.

​

System fields

• every artifact has tags as a system-managed string array
• agents can add or update tags when they decide they are useful
• workflows can surface tags automatically in artifact metadata, sidebar views, dashboard filters, and later UI features
• tags are metadata, not part of the main document body

​

Automatic metadata

• if a field is used by document.sections, it is part of the document body
• every other schema-defined field becomes metadata automatically
• built-in system fields such as status, tags, target_scope, target_workspace_project_ids, touched_workspace_project_ids, and timestamps also appear as metadata automatically

​

How artifact documents render

• markdown sections render with Fabriqa’s read-only markdown renderer
• markdown string arrays render as bullet lists
• non-section primitive fields and small arrays render as compact metadata under the title
• child artifacts do not render again in the document body because the hierarchy already appears in the artifact viewer tree
• relations, linked chats, and activity belong in the contextual rail, not the document body

• one clear title
• a small metadata row under the title
• markdown sections in natural reading order
• minimal chrome and restrained separators

• checklist widgets for narrative requirements
• repeating child artifacts inside both the tree and the body
• turning relations or chat links into main document content
• heavy card stacks that make the artifact feel like an admin panel

​

Document-first authoring guidance

• summary as markdown
• implementation_notes as markdown
• verification_summary as markdown
• verification_verdict left as metadata
• touched_workspace_project_ids left as metadata

• large arrays of nested objects used as the main body of a design document
• artifact viewers that feel like forms instead of documents

​

Scope and associations

​

Planning scope

• use target_scope: workspace when the artifact applies to the whole workspace
• use target_scope: workspace_project when the artifact targets one or more specific workspace projects
• require target_workspace_project_ids only when target_scope is workspace_project
• do not store project names as canonical artifact data; resolve names from workspace metadata using the IDs

• some planning artifacts intentionally span the whole workspace before decomposition narrows to individual projects
• cross-project migrations, shared platform work, release coordination, and standards or policy artifacts do not naturally belong to one project
• third-party workflows may operate above single-project scope as well

• intent may be workspace-scoped for multi-project planning
• unit, story, work_item, and bolt often become workspace_project scoped as planning gets more concrete

​

Execution tracking

​

Parent associations

• work_item under intent
• walkthrough under run
• test_report under bolt

​

Continue reading