Primitives — Overview
processkit provides a compact set of process primitives as universal building blocks. The v2 direction keeps durable project facts in the entity layer and moves workflow definitions, schedules, runtime model data, and lifecycle implementation details to narrower surfaces.
Shipped v2 entity schemas
| Primitive | Purpose | Prefix |
|---|---|---|
| WorkItem | Unit of work (task, story, bug, epic, spike, chore) | BACK |
| LogEntry | Immutable record of something that happened | LOG |
| DecisionRecord | A choice with rationale (ADR pattern) | DEC |
| Migration | Pending/in-progress/applied transition between upstream versions | MIG |
| Artifact | Completed deliverable (document, dataset, build, URL) | ART |
| Note | Zettelkasten capture layer (fleeting, insight, reference) | NOTE |
| Actor | Person or agent (humans, AI, services) | ACTOR |
| Role | Named set of responsibilities | ROLE |
| Binding | Scoped/temporal relationship between two entities (generalized RoleBinding) | BIND |
| Scope | Bounded container (sprint, milestone, project, quarter, release) | SCOPE |
| Category | Classification axis with defined values | CAT |
| Gate | Validation checkpoint | GATE |
| Constraint | Rule or limit the project must respect | CONST |
| Context | Ambient knowledge and environment | CTX |
| Discussion | Multi-turn exploratory conversation | DISC |
| TeamMember | Persistent participant with persona, agent card, and memory tiers | TEAMMEMBER |
Demoted legacy surfaces
Metric, Model, Process, Schedule, and StateMachine are not
first-class shipped entity surfaces in the SmoothTiger/SmoothRiver v2
direction. Metric and policy definitions become artifact-backed
specifications; readings and events are LogEntries or external time
series. Model data belongs to model-recommender roster/configuration
surfaces. Processes are represented by process-instance WorkItems with
definition Artifacts. Schedules are represented by time-window Bindings.
State machines remain validation machinery, not author-facing workflow
records.
Layered relationships
Primitives depend on each other through the skill hierarchy:
Layer 0: index (infrastructure), id (infrastructure), LogEntry (event-log)
Layer 1: Actor (actor-profile), Role (role-management), TeamMember
Layer 2: WorkItem, DecisionRecord, Scope, Category, Binding, CrossReference
Layer 3: Gate, Constraint, Migration, workflow/projection skills
Layer 4: Discussion, metrics-management, Owner profile (owner-profiling), Context grooming
Lower layers never depend on higher layers. The management skill for a
primitive follows the same layer (e.g. workitem-management is Layer 2 and
depends on event-log at Layer 0 and actor-profile at Layer 1).
Cross-references vs Bindings
Rule: if a relationship has scope, time, or its own attributes → use a Binding entity. Otherwise → use a cross-reference field in frontmatter.
| Situation | Use |
|---|---|
| "A blocks B" | cross-ref |
| "Alice is a developer" (globally) | cross-ref |
| "Alice is tech lead on project X for 2026" | Binding |
| "Security gate applies to release process on main" | Binding |
See Primitives → Relationships for details.
Schema coverage
The current schema tree includes these authoritative YAML schema files under
src/context/schemas/.
The schemas define the spec fields, required vs optional, and enum
constraints. MCP servers validate against the schema on every write call —
schema errors surface as structured tool errors rather than silent bad data.
Installer or CI validation can check the same file contracts without starting a full agent session. MCP write tools perform the authoritative write-path validation.
Next
- Format — the
apiVersion/kind/metadata/speccontract. - State Machines — default machines and how to override.
- Relationships — cross-references and Bindings.