Primitives on processkit

Entity File Format

Mon, 01 Jan 0001 00:00:00 +0000

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:

State Machines

Mon, 01 Jan 0001 00:00:00 +0000

Primitives with lifecycle (WorkItem, DecisionRecord, Scope, Discussion) are governed by state machines. processkit ships default machines that projects can override.

WorkItem default

backlog → in-progress → review → done
 ↓ ↑
 blocked ↑
 ↓ ↑
 backlog ←
(any state) → cancelled (terminal)

Source: src/context/state-machines/workitem.yaml .

DecisionRecord default

proposed → accepted → superseded (terminal)
 ↓
 rejected (terminal)

Source: src/context/state-machines/decisionrecord.yaml .

Overriding a default

Projects override a default by placing a same-named file in their own context/state-machines/ directory. The index MCP server (v0.3.0) and any validator prefer the project file over the processkit default.

Relationships

Mon, 01 Jan 0001 00:00:00 +0000

processkit expresses relationships between entities two ways:

Cross-references — lightweight fields in frontmatter
Bindings — first-class entities with their own files

Pick the right one based on what the relationship needs.

The rule

If a relationship has scope, time, or its own attributes → Binding. Otherwise → cross-reference.

Cross-reference examples

# In a WorkItem
spec:
 blocks: [BACK-swift-oak]
 blocked_by: [BACK-calm-fox]
 related_decisions: [DEC-023]
 parent: BACK-epic-lint

Conventional field names:

WorkItem

Mon, 01 Jan 0001 00:00:00 +0000

A unit of work — task, story, bug, epic, spike, or chore. The primary work-tracking primitive in processkit.


ID prefix	`BACK`
State machine	`workitem`
MCP server	`workitem-management`
Skill	`workitem-management` (Layer 2)

State machine

backlog → in-progress → review → done
 ↕
 blocked

All states can transition to cancelled. done and cancelled are terminal.

Fields

Required

Field	Type	Description
`title`	string (1–200)	Short, actionable title
`state`	string	Current state

Optional

Field	Type	Description
`description`	string	Long-form description, acceptance criteria
`type`	enum	`task` · `story` · `bug` · `epic` · `spike` · `chore` (default: `task`)
`priority`	enum	`critical` · `high` · `medium` · `low`
`assignee`	`ACTOR-*`	Responsible actor
`parent`	`BACK-*`	Parent work item (for subtasks / epics)
`children`	`BACK-*[]`	Child work item IDs
`blocks`	`BACK-*[]`	Items this one blocks
`blocked_by`	`BACK-*[]`	Items blocking this one
`related_decisions`	`DEC-*[]`	Decisions that motivated or govern this item
`scope`	string	Scope ID (sprint, milestone, release)
`estimate`	object	Freeform effort estimate
`started_at`	datetime	Set automatically on first `in-progress` transition
`completed_at`	datetime	Set automatically on `done` or `cancelled`

Example

---
apiVersion: processkit.projectious.work/v1
kind: WorkItem
metadata:
 id: BACK-20260411_0900-BoldVale-fts5-full-text-search
 created: '2026-04-11T09:00:00Z'
spec:
 title: Add FTS5 full-text search to SQLite index
 state: backlog
 type: story
 priority: medium
 description: |
 Implement FTS5 trigram tokeniser in index.py so agents can search
 entity body text, not just frontmatter fields.
 related_decisions:
 - DEC-20260409_1200-SwiftPeak-sqlite-for-index
---

Notes

All state transitions are auto-logged via event-log — no manual log call needed.
Use parent / children to model epics and subtasks; keep the epic type epic and subtask types task or story.
scope is a free string; bind to a Scope entity via binding-management when you need richer scope tracking (dates, goals, state).
Query by state, type, priority, or assignee via query_workitems.

LogEntry

Mon, 01 Jan 0001 00:00:00 +0000

An immutable, append-only record of something that happened. The audit trail primitive — never updated or deleted after creation.


ID prefix	`LOG`
State machine	none (immutable)
MCP server	`event-log`
Skill	`event-log` (Layer 0)

Fields

Required

Field	Type	Description
`event_type`	string	Machine-readable event type (e.g. `workitem.created`, `gate.passed`)
`actor`	string	ID of actor who caused the event
`timestamp`	datetime	When the event occurred (ISO 8601 UTC)

Optional

Field	Type	Description
`subject`	string	ID of the entity the event concerns
`subject_kind`	string	Kind of subject entity (fast filtering)
`summary`	string	One-line human-readable summary
`details`	object	Event-specific structured payload
`correlation_id`	string	Links related events (e.g. a workflow run)

Example

---
apiVersion: processkit.projectious.work/v1
kind: LogEntry
metadata:
 id: LOG-20260411_0901-SteadyWren-workitem-transitioned
 created: '2026-04-11T09:01:00Z'
spec:
 event_type: workitem.transitioned
 actor: ACTOR-claude
 timestamp: '2026-04-11T09:01:00Z'
 subject: BACK-20260411_0900-BoldVale-fts5-full-text-search
 subject_kind: WorkItem
 summary: WorkItem transitioned from backlog to in-progress
 details:
 from_state: backlog
 to_state: in-progress
---

Auto-logging

Entity-mutating MCP servers (create_*, transition_*, link_*) append a LogEntry automatically — callers do not need to call log_event separately.

DecisionRecord

Mon, 01 Jan 0001 00:00:00 +0000

A significant choice — architectural, product, or process — recorded with its context, rationale, and alternatives. The ADR (Architecture Decision Record) pattern as a first-class entity.


ID prefix	`DEC`
State machine	`decisionrecord`
MCP server	`decision-record`
Skill	`decision-record` (Layer 2)

State machine

proposed → accepted → superseded
 ↘ rejected

accepted, rejected, and superseded are terminal.

Fields

Required

Field	Type	Description
`title`	string (1–200)	Short declarative title
`state`	string	Current state
`decision`	string	The chosen option, stated clearly

Optional

Field	Type	Description
`context`	string	Situation that prompted the decision
`rationale`	string	Why this option was chosen
`alternatives`	object[]	Each with `option` (required) and `rejected_because` (optional)
`consequences`	string	Known or expected downstream effects
`deciders`	`ACTOR-*[]`	People / agents who made the decision
`supersedes`	`DEC-*`	Prior decision this replaces
`superseded_by`	`DEC-*`	Later decision that replaces this one
`related_workitems`	`BACK-*[]`	Work items that motivated or implement this decision
`decided_at`	datetime	When the decision was finalised

Example

---
apiVersion: processkit.projectious.work/v1
kind: DecisionRecord
metadata:
 id: DEC-20260411_0902-SwiftPeak-sqlite-for-index
 created: '2026-04-11T09:02:00Z'
spec:
 title: Use SQLite as the entity index store
 state: accepted
 decision: Use SQLite with WAL mode as the backing store for the index.
 context: |
 We need a queryable index over all context/ entities that agents can
 use without doing filesystem walks.
 rationale: |
 SQLite is zero-config, ships as a Python built-in, and supports
 full-text search via FTS5. No external service needed.
 alternatives:
 - option: PostgreSQL
 rejected_because: Requires a running service; too heavy for local dev.
 - option: DuckDB
 rejected_because: No built-in full-text search; adds a dependency.
 decided_at: '2026-04-09T12:00:00Z'
---

Notes

Use supersede_decision to create a clean supersession chain when a decision changes — the old record stays as history, the new one links back via supersedes.
Link decisions to work items with link_decision_to_workitem to make the “why was this built?” trail queryable.
proposed is the right starting state for decisions that need stakeholder sign-off before being acted on.

Artifact

Mon, 01 Jan 0001 00:00:00 +0000

A completed deliverable — document, dataset, build, diagram, URL, runbook, slide deck, or any other produced output. A catalogue record, not a work-tracking entity.


ID prefix	`ART`
State machine	none
MCP server	`artifact-management`
Skill	`artifact-management` (Layer 2)

Two usage patterns

Self-hosted — the content lives in the entity file’s Markdown body. location is omitted or used as an optional secondary pointer.

Pointer — the content lives externally (Figma, Google Drive, S3, a git path). location is required; the body may be empty or contain a summary.

Note

Mon, 01 Jan 0001 00:00:00 +0000

A Zettelkasten capture layer for ideas, observations, and references. Notes exist on a spectrum from raw capture (fleeting) to permanent knowledge (insight).


ID prefix	`NOTE`
State machine	`note`
MCP server	`note-management`
Skill	`note-management` (Layer 2)

State machine

fleeting → insight
 ↘ promoted (promoted to another entity kind)
 ↘ archived

insight, promoted, and archived are terminal.

Note types (Luhmann/Ahrens taxonomy)

Type	Description
`fleeting`	Quick capture, not yet refined — review within a week
`insight`	Permanent note — self-contained conclusion, part of knowledge base
`reference`	Literature note — pointer to an external source with summary
`question`	Open question — may promote to WorkItem (spike) or Discussion

Fields

Required

Field	Type	Description
`title`	string (1–120)	Self-contained claim or question — not a topic label
`body`	string	The note content
`type`	enum	`fleeting` · `insight` · `reference` · `question`
`state`	string	Current state

Optional

Field	Type	Description
`tags`	string[]	Freeform tags for discoverability
`source`	string	For `reference` notes: URL, book title, or conversation
`promotes_to`	object	`{kind, id}` — target entity when promoted
`review_due`	date	When the note should be reviewed
`inbox`	object	Hook-inbox status and routing metadata
`links`	object[]	Typed edges to other Notes (see below)

Hook inbox

The note-management MCP server can capture external or agent-generated interrupts as Notes with spec.inbox. Inbox items move through captured, claimed, completed, or failed, with an injection_mode of interrupt, ambient, or next-cycle.

Actor

Mon, 01 Jan 0001 00:00:00 +0000

A participant in the project — human, AI agent, or automated service. Actors are assigned to WorkItems, named in DecisionRecords, and bound to Roles.


ID prefix	`ACTOR`
State machine	none
MCP server	`actor-profile`
Skill	`actor-profile` (Layer 1)

Fields

Required

Field	Type	Description
`type`	enum	`human` · `ai-agent` · `service`
`name`	string (1–200)	Display name (for AI agents: model name + version)

Optional

Field	Type	Description
`email`	email	Humans only
`handle`	string	GitHub handle, Slack user, etc.
`expertise`	string[]	Tags used by assignment-suggestion logic
`roles`	`ROLE-*[]`	Shortcut for unscoped role assignment
`preferences`	object	Freeform (commit style, timezone, review style, …)
`active`	boolean	`false` = actor has left, no new work assigned (default: `true`)
`joined_at`	datetime	When actor became part of the project
`left_at`	datetime	When actor stopped

Example

---
apiVersion: processkit.projectious.work/v1
kind: Actor
metadata:
 id: ACTOR-20260411_0906-SteadyWren-claude
 created: '2026-04-11T09:06:00Z'
spec:
 type: ai-agent
 name: Claude Sonnet 4.6
 handle: claude
 expertise: [python, typescript, processkit, documentation]
 active: true
 preferences:
 commit_style: conventional-commits
 timezone: UTC
---

Notes

Roles are descriptive, not restrictive — processkit does not enforce RBAC. Use roles for assignment-suggestion only.
Use deactivate_actor (not manual editing) to mark an actor as active: false; it keeps the index consistent.
For scoped or time-bounded role assignments, use a Binding instead of the roles shortcut field.

Role

Mon, 01 Jan 0001 00:00:00 +0000

A named set of responsibilities. Roles are descriptive — they document who is expected to do what, but do not enforce access control.


ID prefix	`ROLE`
State machine	none
MCP server	`role-management`
Skill	`role-management` (Layer 1)

Fields

Required

Field	Type	Description
`name`	string (1–100)	Kebab-case identifier matching the `metadata.id` suffix
`description`	string	One-sentence purpose statement

Optional

Field	Type	Description
`responsibilities`	string[]	Imperative bullet points — concrete, not vague
`skills_required`	string[]	Skill IDs or names (advisory, not enforced)
`default_scope`	enum	`project` · `sprint` · `permanent` — assumed scope when binding without an explicit one
`supersedes`	`ROLE-*`	Role ID this one replaces

Example

---
apiVersion: processkit.projectious.work/v1
kind: Role
metadata:
 id: ROLE-20260411_0907-ClearOak-tech-lead
 created: '2026-04-11T09:07:00Z'
spec:
 name: tech-lead
 description: Owns technical direction and architecture decisions.
 responsibilities:
 - Review and approve architectural decisions (DEC)
 - Unblock teammates on technical questions within 24 hours
 - Run weekly engineering sync
 skills_required: [software-architecture, code-review, decision-record]
 default_scope: project
---

Notes

Roles describe responsibilities, not permissions. processkit does not enforce RBAC.
A global, unscoped assignment can use the Actor’s roles field directly. For a scoped or time-bounded assignment (“Alice is tech lead on Project X for Q2”), create a Binding instead.
link_role_to_actor creates the shortcut entry on the Actor entity.

Binding

Mon, 01 Jan 0001 00:00:00 +0000

A scoped or time-bounded relationship between two entities — the junction-table pattern promoted to a first-class primitive. Use when a relationship has scope, time, or its own attributes; use a frontmatter cross-reference field otherwise.


ID prefix	`BIND`
State machine	none
MCP server	`binding-management`
Skill	`binding-management` (Layer 2)

When to use a Binding vs a cross-reference

Situation	Use
“A blocks B”	frontmatter `blocks: [BACK-...]`
“Alice is a developer” (globally)	Actor’s `roles: [ROLE-...]`
“Alice is tech lead on Project X for Q2 2026”	Binding
“Security gate applies to this release WorkItem on main”	Binding
“Sprint 7 scopes these work items for Apr 1-14”	Binding

Fields

Required

Field	Type	Description
`type`	string	Freeform binding type (see conventions below)
`subject`	string	Entity on the “from” side
`target`	string	Entity on the “to” side

Optional

Field	Type	Description
`subject_kind`	string	Primitive kind of subject
`target_kind`	string	Primitive kind of target
`scope`	`SCOPE-*`	Scope within which the binding applies
`valid_from`	string	When binding starts (date or ISO 8601 datetime)
`valid_until`	string	When binding stops
`conditions`	object	Freeform constraints attached to binding
`description`	string	One-line human-readable summary

Type conventions

Type	Meaning
`role-assignment`	Actor → Role (scoped)
`work-assignment`	Actor → WorkItem (assigned to sprint/scope)
`workitem-gate`	WorkItem → Gate (this gate guards this run or task)
`scope-gate`	Scope → Gate (this gate applies within this scope)
`time-window`	Entity → Artifact/Scope (time or recurrence contract)
`budget-application`	Artifact → WorkItem/Scope (cost policy applies here)
`constraint-scope`	Constraint → Scope (constraint applies in this scope)
`category-assignment`	Entity → Category value

Process and Schedule are not v2 Binding endpoints. Legacy process-gate, process-scope, and schedule-scope records should be migrated to concrete WorkItem, Scope, Artifact, Gate, or time-window relationships.

Scope

Mon, 01 Jan 0001 00:00:00 +0000

A bounded container for work — sprint, milestone, quarter, release, or project. Scopes give WorkItems, Processes, and Constraints a shared time and goal boundary.


ID prefix	`SCOPE`
State machine	`scope`
MCP server	`scope-management`
Skill	`scope-management` (Layer 2)

State machine

planned → active → completed
 ↘ cancelled

completed and cancelled are terminal.

Fields

Required

Field	Type	Description
`name`	string (1–200)	Human-readable name
`kind`	enum	`sprint` · `milestone` · `quarter` · `project` · `release` · `other`
`state`	string	Current state

Optional

Field	Type	Description
`starts_at`	date	Start date
`ends_at`	date	End date
`goals`	string[]	Concrete, testable outcomes
`description`	string	Longer context
`parent`	`SCOPE-*`	Parent scope (a quarter contains sprints)
`related_decisions`	`DEC-*[]`	Planning or retro decisions for this scope

Example

---
apiVersion: processkit.projectious.work/v1
kind: Scope
metadata:
 id: SCOPE-20260411_0909-BrightElm-sprint-7
 created: '2026-04-11T09:09:00Z'
spec:
 name: Sprint 7 — WildButter docs push
 kind: sprint
 state: active
 starts_at: '2026-04-11'
 ends_at: '2026-04-25'
 goals:
 - All primitive reference pages published
 - Hugo and Docsy local build green
 - First public deploy complete
 parent: SCOPE-20260410_q2-2026
---

Notes

Attach WorkItems to a Scope via a scope field on the WorkItem, or via a work-assignment Binding when richer tracking is needed.
Scope hierarchy (quarter → sprint) is modelled via the parent field.
transition_scope to active when work begins; to completed when the scope closes — this timestamps the lifecycle automatically.

Discussion

Mon, 01 Jan 0001 00:00:00 +0000

A structured, multi-turn conversation exploring an open question. Discussions capture the back-and-forth of deliberation and produce (or fail to produce) DecisionRecords as outcomes.


ID prefix	`DISC`
State machine	`discussion`
MCP server	`discussion-management`
Skill	`discussion-management` (Layer 4)

State machine

active → resolved
 ↘ closed (no outcome)

resolved and closed are terminal.

Fields

Required

Field	Type	Description
`question`	string	The driving question — one crisp sentence
`state`	string	Current state

Optional

Field	Type	Description
`participants`	`ACTOR-*[]`	Actors participating
`related`	`DISC-*[]`	Related discussion IDs
`outcomes`	`DEC-*[]`	DecisionRecord IDs produced by this discussion
`opened_at`	datetime	When the discussion started
`closed_at`	datetime	When it was marked resolved or closed

Example

---
apiVersion: processkit.projectious.work/v1
kind: Discussion
metadata:
 id: DISC-20260411_0910-ClearWave-primitive-page-format
 created: '2026-04-11T09:10:00Z'
spec:
 question: What format should per-primitive reference pages follow?
 state: resolved
 participants: [ACTOR-claude, ACTOR-20260411_0906-owner]
 outcomes: [DEC-20260411_0911-SwiftMeadow-primitive-page-format]
 opened_at: '2026-04-11T09:10:00Z'
 closed_at: '2026-04-11T09:30:00Z'
---

Notes

Use add_outcome to attach a DecisionRecord after it has been created with record_decision. Both tools auto-log.
Discussions are the audit trail behind decisions — if a decision was reached after deliberation, the Discussion captures the reasoning path.
Transition to resolved when a Decision was reached; to closed when the question was abandoned or became moot.
The Markdown body (below the YAML frontmatter) is the space for the discussion thread — arguments, evidence, proposals, objections.

Gate

Mon, 01 Jan 0001 00:00:00 +0000

A validation checkpoint in a process. Gates define what must be true before work can proceed. Evaluation results are LogEntries — gate.passed, gate.failed, or gate.waived.


ID prefix	`GATE`
State machine	none
MCP server	`gate-management`
Skill	`gate-management` (Layer 3)

Fields

Required

Field	Type	Description
`name`	string (1–100)	Short kebab-case identifier
`description`	string	What this gate checks (one sentence)
`kind`	enum	`manual` · `automated` · `hybrid`
`validator`	string	Prose description of the check (one–two sentences)

Optional

Field	Type	Description
`validator_command`	string	CLI command for automated/hybrid gates
`required_roles`	`ROLE-*[]`	Roles authorised to sign off
`blocking`	boolean	`true` = work cannot proceed without passing (default: `true`)
`evidence_required`	boolean	`true` = `gate.passed` log must include artifact reference (default: `false`)

Example

---
apiVersion: processkit.projectious.work/v1
kind: Gate
metadata:
 id: GATE-20260411_0912-SteadyArch-smoke-tests-green
 created: '2026-04-11T09:12:00Z'
spec:
 name: smoke-tests-green
 description: All MCP server smoke tests must pass before tagging a release.
 kind: automated
 validator: Run `uv run scripts/smoke-test-servers.py` — exit 0 required.
 validator_command: uv run scripts/smoke-test-servers.py
 blocking: true
 evidence_required: false
---

Notes

Gates define what to check; the evaluation happens externally (by an agent, CI, or human). Log the result with log_event using event_type: gate.passed, gate.failed, or gate.waived.
evaluate_gate runs the validator_command (if set) and logs the result in one call.
Advisory gates (blocking: false) surface warnings without halting the process.
Attach gates to concrete v2 surfaces via workitem-gate or scope-gate Bindings. Legacy process-gate Bindings are migration-only.

Migration

Mon, 01 Jan 0001 00:00:00 +0000

A pending, in-progress, or applied transition between two upstream processkit versions. Migrations are generated by aibox sync and represent the delta an agent must apply to bring the project’s context/ up to date.


ID prefix	`MIG`
State machine	`migration`
MCP server	`migration-management`
Skill	`migration-management` (Layer 3)

State machine

pending → in-progress → applied
 ↘ rejected

applied and rejected are terminal.

Fields

Required

Field	Type	Description
`source`	string	Upstream source identifier (`processkit`, `processkit-acme`, …)
`from_version`	string	Version migrating FROM (semver tag)
`to_version`	string	Version migrating TO (semver tag)
`state`	string	Current state

Optional

Field	Type	Description
`source_url`	string	Git URL of upstream (for re-fetch if needed)
`generated_by`	string	What generated this (`aibox sync`, `user`, …)
`generated_at`	datetime	When the migration document was written
`summary`	string	One-line summary for listings
`affected_files`	object[]	Files touched — each with `path`, `classification`, and optional `group`
`affected_groups`	string[]	Logical groups affected (unit of auto-update)
`plan`	string	Project-specific migration plan drafted by agent
`progress_notes`	object[]	Append-only notes: `{timestamp, note, actor}`
`applied_at`	datetime	When migration reached `applied`
`applied_by`	string	Actor ID that finalised the migration
`rejected_reason`	string	If rejected, why
`source_api_version`	string	API version before a v2 conversion
`target_api_version`	string	API version after a v2 conversion
`source_processkit_version`	string	processkit version before conversion
`target_processkit_version`	string	processkit version after conversion
`apply_mode`	string	Migration apply mode (`one-shot`, etc.)

The migration-management MCP server manages migration state transitions and provides migrate_context_to_v2(dry_run=true) for the breaking v2 API conversion path.

Schedule

Mon, 01 Jan 0001 00:00:00 +0000

Legacy v1 time-based trigger or recurring cadence. In the SmoothTiger/SmoothRiver v2 direction, processkit no longer presents Schedule as a first-class shipped entity surface. Use Binding(type=time-window) with conditions.recurrence_rule for the durable contract; an external runner still performs execution.


ID prefix	`SCHED` (legacy v1)
State machine	none
MCP server	none
Skill	`schedule-management` (legacy authoring guidance)

v2 replacement

Use the binding-management server’s create_time_window path for time windows. pk-doctor’s v2_contracts check requires Binding(type=time-window) records to include conditions.recurrence_rule.

Constraint

Mon, 01 Jan 0001 00:00:00 +0000

An explicit rule or limit the project must respect — budget ceiling, latency SLO, regulatory requirement, team capacity cap. Violations are LogEntries; constraints themselves do not change when violated.


ID prefix	`CONST`
State machine	none
MCP server	none
Skill	`constraint-management` (Layer 3)

Fields

Required

Field	Type	Description
`name`	string	Kebab-case identifier
`description`	string	One-sentence statement of the constraint
`kind`	enum	`budget` · `slo` · `regulatory` · `capacity` · `dependency` · `policy` · `other`
`severity`	enum	`hard` · `soft` · `advisory`

Optional

Field	Type	Description
`measurement`	string	How to determine if the constraint is met
`target`	string	Threshold or boundary value
`source`	string	Where the constraint comes from (contract, regulation, decision)
`active`	boolean	`false` = no longer in effect (default: `true`)
`related_decisions`	`DEC-*[]`	Decisions that established or relaxed the constraint

Severity levels

Level	Meaning
`hard`	Cannot violate — work stops until resolved
`soft`	Flagged and tracked; can be overridden with justification
`advisory`	Informational — violation noted but no process impact

Example

---
apiVersion: processkit.projectious.work/v1
kind: Constraint
metadata:
 id: CONST-20260411_0916-SteadyMoss-api-latency-slo
 created: '2026-04-11T09:16:00Z'
spec:
 name: api-latency-slo
 description: MCP tool round-trip p99 latency must stay below 200ms.
 kind: slo
 severity: hard
 target: "< 200ms p99"
 measurement: |
 Measured via the observability pipeline from tool-call dispatch to
 server response. Alert fires if exceeded for 5 minutes.
 source: Customer SLA — contract clause 4.2
 related_decisions:
 - DEC-20260409_latency-slo-accepted
---

Notes

Constraint violations are logged via log_event with event_type: constraint.violated — the Constraint entity itself is not modified.
A hard constraint violation should surface as a blocked WorkItem or an urgent Discussion.
Bind a Constraint to a Scope via a constraint-scope Binding to make it scope-specific rather than project-wide.
Set active: false when a constraint is no longer in effect (SLA renegotiated, regulatory exemption granted).


ID prefix	`CAT`
State machine	none
MCP server	none
Skill	`category-management` (Layer 2)

Field	Type	Description
`name`	string (1–100)	Category name (kebab-case)
`description`	string	What this axis classifies
`axis`	string	Label key used on entities (e.g. `priority`, `severity`)
`values`	object[]	Allowed values — each with `name` (required), `description`, `deprecated`, `children` (optional)

Field	Type	Description
`applies_to`	string[]	Primitive kinds this applies to; empty = applies anywhere
`default`	string	Default value when unspecified
`multi`	boolean	`true` = entity can carry multiple values (default: `false`)

CrossReference

Mon, 01 Jan 0001 00:00:00 +0000

A lightweight, frontmatter-embedded relationship between two entities. CrossReference is not a file — it is a convention for fields in the spec block of any entity.


ID prefix	— (not a file entity)
State machine	—
MCP server	`index-management` (for querying)
Skill	`cross-reference-management` (Layer 2)

When to use a CrossReference vs a Binding

Use a CrossReference when the relationship is:

Simple — no scope, no time bounds, no attributes of its own
Directional — one entity points at another

Use a Binding when the relationship has scope, time, or its own attributes.

Context

Mon, 01 Jan 0001 00:00:00 +0000

A structured narrative document for long-lived ambient knowledge — owner identity, working style, team relationships, grooming reports, situational briefings. The value lives in the Markdown body.


ID prefix	`CTX` (or custom, e.g. `OWNER`)
State machine	none
MCP server	none
Skill	`context-grooming` (Layer 4)

Fields

Required

Field	Type	Description
`description`	string	One-sentence summary of what this document holds

Optional

Field	Type	Description
`purpose`	string	Why the document exists — when an agent should read it
`scope`	string	Where the context applies (`project`, `owner`, `team`, `sprint`)
`tags`	string[]	Freeform tags for retrieval
`sensitive`	boolean	`true` = body contains sensitive information (default: `false`)

Example

---
apiVersion: processkit.projectious.work/v1
kind: Context
metadata:
 id: OWNER-identity
 created: '2026-04-09T00:00:00Z'
spec:
 description: Owner identity, working style, and preferences for AI agents.
 purpose: |
 Read at session start to calibrate communication style and technical
 depth. Load before any substantive work begins.
 scope: owner
 sensitive: false
---

## Identity

Name: ...
Role: ...
Timezone: ...

## Working style

...

Notes

Context entities use the Markdown body (below the YAML frontmatter) for their primary content. The spec block is metadata only.
Custom ID prefixes (e.g. OWNER-identity, CTX-team-norms) are idiomatic — the CTX- prefix is the default but not required.
Sensitive context (sensitive: true) should live under context/**/private/ to be excluded from git tracking and the docs-site build.
Context grooming (context-grooming skill) prunes stale Context documents periodically — documents that have not been read or updated for a long time are candidates for archiving.

Process

Mon, 01 Jan 0001 00:00:00 +0000

Legacy v1 declarative workflow definition. In the SmoothTiger/SmoothRiver v2 direction, processkit no longer presents Process as a first-class shipped entity surface. Use a process-instance WorkItem for a concrete run and an Artifact for the reusable process definition.


ID prefix	`PROC` (legacy v1)
State machine	none
MCP server	none
Skill	`process-management` (legacy authoring guidance)

v2 replacement

Use:

WorkItem with spec.type: process-instance for a workflow run.
Artifact with spec.kind describing the reusable process definition.
Gate and Binding records for policies that apply to the run.

pk-doctor’s v2_contracts check flags v2 process-instance WorkItems that do not point at a process definition.

StateMachine

Mon, 01 Jan 0001 00:00:00 +0000

Legacy v1 state/transition graph entity. In the SmoothTiger/SmoothRiver v2 direction, processkit no longer presents StateMachine as a first-class shipped entity surface. State machines still exist as validation machinery used by MCP servers, but users should not model new workflow records as StateMachine entities.


ID prefix	`SM` (legacy v1)
State machine	none (meta-primitive)
MCP server	none
Skill	`state-machine-management` (legacy authoring guidance)

v2 replacement

Use the owning MCP server for lifecycle transitions. It loads the appropriate implementation contract and returns structured errors for invalid transitions. Project workflows should be expressed with WorkItems, Artifacts, Gates, and Bindings rather than new StateMachine records.