Entity File Format

Every processkit primitive entity is stored as a Markdown file with a YAML frontmatter block. The format is inspired by Kubernetes objects — stable, versioned, and easy to parse.

Canonical shape

---
apiVersion: processkit.projectious.work/v1   # required — schema version
kind: WorkItem                                # required — primitive type
metadata:                                     # required
  id: BACK-calm-fox
  created: 2026-04-06T10:30:00Z
  updated: 2026-04-06T11:15:00Z
  labels:
    priority: high
spec:                                         # required — entity-specific
  title: "Add a release audit check"
  state: in-progress
  assignee: ACTOR-alice
---

# Body — freeform Markdown

Human-readable description, acceptance criteria, notes, history.

The four top-level keys

Key	Required	Purpose
`apiVersion`	yes	Schema version. Always `processkit.projectious.work/v1` at v0.x.
`kind`	yes	Primitive type. Determines which schema validates `spec`.
`metadata`	yes	Identity, timestamps, labels. Cross-cutting fields.
`spec`	yes	Entity-specific fields. Validated by primitive schema.

metadata fields

Field	Required	Type	Notes
`id`	yes	string	Unique identifier. Format configurable (see below).
`created`	yes	ISO 8601 datetime	UTC. Never edited after creation.
`updated`	no	ISO 8601 datetime	Set on modification.
`labels`	no	map[string]string	Arbitrary key-value tags. Used by queries and filters.

ID formats

Configurable per project through installer or processkit settings:

`id_format`	`id_slug`	Example
`word`	`false`	`BACK-calm-fox`
`word`	`true`	`BACK-calm-fox-add-lint`
`uuid`	`false`	`BACK-550e8400-e29b-41d4`
`uuid`	`true`	`BACK-550e8400-add-lint`

The prefix (BACK-, LOG-, DEC-, …) is determined by the primitive kind and is not configurable. See Reference → ID Formats for details.

apiVersion policy

apiVersion follows the Kubernetes convention: <group>/<version>, where the group is a reverse-DNS name anchored on the owning organization. For processkit the group is processkit.projectious.work, making processkit a subcomponent of the projectious.work organization. This prevents name collisions if other organizations fork or publish compatible primitives under their own domains.

See Reference → apiVersion Policy for the evolution rules.

Authoritative source

The authoritative specification is src/context/schemas/ in the processkit repo. This page is a condensed overview; the shipped schema files define the authoritative spec contracts for each kind.