processkit

apiVersion Policy

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

processkit uses a Kubernetes-style apiVersion field on every entity:

apiVersion: processkit.projectious.work/v1

The group

The group processkit.projectious.work is a reverse-DNS name anchored on the owning organization (projectious.work) with processkit as a subcomponent. This prevents name collisions if other organizations fork or publish compatible primitives under their own domains.

The form <reverse-dns-group>/<version> is the Kubernetes-idiomatic shape — exactly one slash. Tools that split on / expect exactly two parts.

Evolution rules

apiVersion	Status	Meaning
`processkit.projectious.work/v1`	current v0.x entity format	Initial public entity version
`processkit.projectious.work/v1beta1`	not used	Reserved
`processkit.projectious.work/v2`	planned	Breaking contract with explicit migration required

Non-breaking changes (stay at v1)

Adding new optional fields to schemas
Adding new primitive kinds
Adding new states to a state machine
Adding new skills
Adding new packages

Breaking changes (require v2)

Removing or renaming existing fields
Changing the type or meaning of existing fields
Removing states from a state machine (stranding existing entities)
Removing primitive kinds
Changing the semantics of metadata.id, metadata.created, or other cross-cutting fields

Migration between versions

The SmoothTiger/SmoothRiver v2 direction is a no-shim contract: v2 schemas and index semantics become authoritative, and processkit does not add hidden dual-read or permissive validation paths for v1 data. Existing v1 contexts remain a migration source, not a long-term compatibility target.

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:

Harness Compatibility

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

processkit’s MCP servers are provider-neutral Python programs. They do not require aibox at runtime. aibox can install processkit, merge MCP configuration, pre-authorize processkit tools where a harness supports that, and supervise a managed devcontainer. Those are convenience and lifecycle features; they are not a processkit dependency.

For a direct install, point the harness at the desired server command inside the installed context/skills tree. The recommended one-process entry point is:

{
 "mcpServers": {
 "processkit-gateway": {
 "command": "uv",
 "args": [
 "run",
 "context/skills/processkit/processkit-gateway/mcp/server.py"
 ],
 "env": {
 "PROCESSKIT_MCP_MODE": "gateway"
 }
 }
 }
}

Current modes

Mode	Use when	Harness impact
Per-skill servers	You need fine-grained tool registration or the broadest compatibility.	The harness launches one stdio process per registered skill.
`aggregate-mcp`	You already use the legacy aggregate server.	One stdio process, compatibility name, no daemon behavior.
`processkit-gateway` stdio	You want the provider-neutral gateway surface now.	One stdio process, eager tool import, richer gateway metadata.
Daemon plus stdio proxy	You want a long-lived daemon with lightweight harness proxies.	One shared daemon plus one lightweight stdio proxy per harness.

The current gateway command is equivalent to:

ID Formats

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

Entity IDs in processkit have the shape <PREFIX>-<id-body>. The prefix is determined by the primitive kind and is not configurable. The id-body has two independent configuration axes: format and slug.

Configuration

In the consuming project’s aibox.toml:

[context]
id_format = "word" # word | uuid
id_slug = false # true | false

The four combinations

`id_format`	`id_slug`	Example	Notes
`word`	`false`	`BACK-calm-fox`	Default. Short, memorable, solo-friendly
`word`	`true`	`BACK-calm-fox-add-lint`	Memorable + descriptive for prose contexts
`uuid`	`false`	`BACK-550e8400-e29b-41d4`	Uniqueness guarantees for large teams
`uuid`	`true`	`BACK-550e8400-add-lint`	UUID + readable context

Prefix registry

Primitive	Prefix
WorkItem	`BACK`
LogEntry	`LOG`
DecisionRecord	`DEC`
Migration	`MIG`
Artifact	`ART`
Note	`NOTE`
Actor	`ACTOR`
Role	`ROLE`
Binding	`BIND`
Scope	`SCOPE`
Category	`CAT`
CrossReference	—
Gate	`GATE`
Schedule	`SCHED` (legacy v1)
Constraint	`CONST`
Context	`CTX`
Discussion	`DISC`
Process	`PROC` (legacy v1)
StateMachine	`SM` (legacy v1)

Metric, Model, Process, Schedule, and StateMachine do not reserve first-class primitive prefixes in the v2 contract. The legacy prefixes remain documented so existing v1 contexts can be migrated and read correctly.

Installing

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

processkit is distributed as versioned GitHub releases. Each release contains a tarball with the shipped context/, .processkit/, and agent entrypoint files. You can install those files manually or let a managed environment tool do it.

Manual install

Download and unpack the release tarball:

curl -L \
 https://github.com/projectious-work/processkit/releases/download/v0.25.1/processkit-v0.25.1.tar.gz \
 -o processkit-v0.25.1.tar.gz
tar -xzf processkit-v0.25.1.tar.gz

Copy the shipped files into your project:

cp -a processkit-v0.25.1/context ./context
cp -a processkit-v0.25.1/.processkit ./.processkit
cp processkit-v0.25.1/AGENTS.md ./AGENTS.md

Then register the gateway with your harness. For stdio MCP:

minimal

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

Intended for: solo developers and small side projects. Extends: — (the base tier)

The lightest footprint package. Just enough structure to track work and debug effectively — no roles, no scopes, no governance artifacts.

Included skills

event-log — foundation: probabilistic append-only event log
actor-profile — basic Actor entities
workitem-management — WorkItem creation and transitions
git-workflow — branch/commit/PR conventions
debugging — systematic debug workflow
testing-strategy — unit vs integration vs E2E guidance
error-handling — cross-language patterns

When to upgrade

You’re joining a team → managed
You need formal decision records, scopes, and process artifacts → managed
You’re building production software → software
You’re doing data/ML work → research
You need the kitchen sink → product

Source

src/packages/minimal.yaml

Process Skills

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

Skills for managing project workflows, team coordination, and operational processes. Most process-primitive skills have an accompanying MCP server that enforces schema validation and state-machine rules.

workitem-management

Creates, transitions, and queries WorkItems — the task-tracking primitive in processkit. Use when managing backlog items, updating work item state, or querying items by status, owner, or priority.

Triggers: When the user asks to create a ticket, update a work item, query the backlog, or track progress on a task. Tools: create_workitem, transition_workitem, query_workitems, get_workitem, link_workitems Layers: Layer 2 (depends on event-log, actor-profile)

Skill Package Format

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

This page summarizes the skill package format. The authoritative source is src/context/skills/FORMAT.md in the processkit repo.

Directory layout

src/context/skills/<category>/<skill-name>/
 SKILL.md ← required — three-level agent instructions
 INDEX.md ← optional — human-readable overview
 examples/ ← recommended — example outputs
 templates/ ← recommended — YAML frontmatter entity scaffolds
 references/ ← optional — deep-dive reference material
 mcp/ ← optional — Python MCP server
 server.py
 mcp-config.json
 README.md

Required frontmatter fields

Field	Purpose
`apiVersion`	Always `processkit.projectious.work/v1` at v0.x.
`kind`	Always `Skill`.
`metadata.id`	`SKILL-<skill-name>`
`metadata.name`	Kebab-case; matches directory name
`metadata.version`	Semver, independent of processkit release
`metadata.created`	ISO 8601 UTC
`spec.description`	One-sentence summary (shown in listings)
`spec.category`	One of the registered categories
`spec.layer`	Integer 0–4, or `null` for non-process skills

Optional fields

Field	Purpose
`spec.uses`	Skills this depends on (strictly lower layer for process skills)
`spec.provides`	What the agent gains: primitive kinds, MCP tools, templates
`spec.when_to_use`	Trigger description for routing
`spec.replaces`	ID of a skill this one overrides (for community forks)

managed

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

Intended for: small teams with a shared backlog and process cadences. Extends: minimal

The recommended default. Adds roles, decisions, scopes, and all lightweight process artifacts (standups, retros, session handovers) on top of minimal.

What managed adds on top of minimal

Process primitives and cross-cutting process skills: role-management, decision-record, scope-management, category-management, cross-reference-management, binding-management, process-management, state-machine-management, gate-management, schedule-management, constraint-management, discussion-management, metrics-management.

process-management, schedule-management, and state-machine-management are included for legacy v1 migration guidance. They are not first-class v2 primitive authoring surfaces.

Skill Hierarchy

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

Process-primitive skills form a strict layered DAG. A skill’s spec.uses field may only reference skills in lower layers. Cycles are validation errors.

The layers

Layer	Role	Skills
0	Foundation	`index-management`, `id-management`, `event-log`
1	Primitive management	`role-management`, `actor-profile`
2	Core entities	`workitem-management`, `decision-record`, `scope-management`, `category-management`, `cross-reference-management`, `binding-management`
3	Workflow policy	`gate-management`, `constraint-management`; legacy/migration guidance for `process-management`, `state-machine-management`, `schedule-management`
4	Cross-cutting	`discussion-management`, `metrics-management`

Layer 0 has three skills with one intra-layer edge. index-management and id-management are the absolute foundation — they depend on nothing. event-log is also Layer 0 but uses: [index-management, id-management], so it conceptually sits “atop” them. This is the only intra-layer edge in the entire hierarchy. The strict-downward rule applies to Layers 1+ unchanged.

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.

Version Migration

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

processkit is distributed as versioned releases. Upgrading pinned versions is deliberate: processkit does not silently rewrite a consuming project’s context. A version bump should produce a Migration document under context/migrations/pending/ that the user and agent work through together.

The model

processkit ships a generic diff script (scripts/processkit-diff.sh) that compares two tagged versions of any processkit-compatible source — upstream processkit, a company fork like processkit-acme, or any other downstream. The script reads src/PROVENANCE.toml at each tag (a single file mapping every shipped file to the tag in which it last changed) and emits a structured diff: added, removed, changed, unchanged.

Your First Entity

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

Create your first WorkItem and see how processkit’s entity format works.

Prerequisites

A project with processkit installed (see Installing ).
A package tier that includes workitem-management; minimal and higher tiers include it.

Creating a WorkItem by hand

Write a file at context/workitems/BACK-first-task.md:

---
apiVersion: processkit.projectious.work/v1
kind: WorkItem
metadata:
 id: BACK-first-task
 created: 2026-04-06T10:00:00Z
 labels:
 area: onboarding
spec:
 title: "Try out processkit"
 state: backlog
 type: task
 priority: medium
 description: "Walk through the processkit docs and create a few entities."
---

## Acceptance criteria

- [ ] Read the primitives overview
- [ ] Read the skills overview
- [ ] Create this first WorkItem
- [ ] Transition it to in-progress, then done

If your installer has a validation command, run it now. The file has the core apiVersion, kind, metadata.id, and spec fields expected by the WorkItem schema.

Language Skills

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

Language-specific conventions, patterns, and best practices.

python-best-practices

Python conventions and patterns – typing, testing, project layout, tooling. Use when writing or reviewing Python code.

Triggers: When the user is working with Python code and asks about conventions, project structure, typing, testing, or says “how should I structure this Python project?”. Tools: None References: None

Key capabilities:

Project layout: src/ layout with pyproject.toml, use uv for dependency management
Type hints on all public function signatures with from __future__ import annotations
Testing with pytest: fixtures, parametrize, test naming test_<function>_<scenario>_<expected>
Code style: ruff format and ruff check, prefer dataclasses/Pydantic over dicts, pathlib over os.path
Error handling: raise specific exceptions, custom exception classes, never bare except:

Example usage

User asks to set up a new Python project. The agent creates pyproject.toml with project metadata and dependencies, src/ layout, tests/ directory, ruff config, and basic __init__.py.

Privacy Tiers

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

processkit recognizes three privacy tiers for entities under context/. The tier is declared via an optional privacy: field in metadata and enforced by directory layout + a .gitignore rule.

The three tiers

Tier	Default?	Git status	Typical use
`public`	no	tracked	identity.md, README, public roadmap
`project-private`	yes (default if omitted)	tracked	workitems, decisions, logs, working-style.md
`user-private`	no	NOT tracked	team-and-relationships.md, personal scratch notes

Most entities omit the field entirely and inherit project-private.

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:

software

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

Intended for: software engineering teams building production systems. Extends: managed

The “serious software team” tier. Adds architecture, API, database, infrastructure, security, observability, and performance skills on top of managed.

Highlights

Architecture: software-architecture, system-design, domain-driven-design, event-driven-architecture, concurrency-patterns
API: api-design, graphql-patterns, grpc-protobuf, webhook-integration
Database: database-modeling, database-migration, sql-patterns, sql-style-guide, nosql-patterns, caching-strategies
Infrastructure: ci-cd-setup, container-orchestration, dockerfile-review, kubernetes-basics, terraform-basics, linux-administration, dns-networking, shell-scripting
Security: auth-patterns, secret-management, secure-coding, threat-modeling, dependency-audit
Observability: logging-strategy, metrics-monitoring, alerting-oncall, distributed-tracing
Performance: performance-profiling, load-testing

When to upgrade

Only if you also need design, mobile, frontend framework skills → product.

Infrastructure Skills

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

Skills for containers, orchestration, networking, system administration, and CI/CD.

dockerfile-review

Dockerfile best practices review – layer optimization, caching, security, image size. Use when writing or reviewing Dockerfiles.

Triggers: When the user asks to review a Dockerfile, optimize an image, or says “why is my image so big?”, “is this Dockerfile correct?”, or “help me with Docker”. Tools: None References: None

Key capabilities:

Layer optimization: combine related RUN commands, order from least to most frequently changing
Caching: copy dependency manifests first, install, then copy source
Security: don’t run as root, never COPY secrets, pin base images with digest, remove package caches
Size reduction: slim/alpine base images, multi-stage builds, --no-install-recommends
Correctness: use COPY over ADD, set WORKDIR instead of cd, exec form for CMD/ENTRYPOINT

Example usage

User says “Review my Dockerfile.” The agent reads it and identifies that dependency installation and source copy are in the same layer (cache-busting), apt lists aren’t cleaned up, and the container runs as root. Provides specific fixes for each issue.

research

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

Intended for: research teams, data science projects, ML engineering. Extends: managed

Managed plus data, ML, AI, and research-documentation skills.

Highlights

Data: data-science, data-pipeline, data-quality, data-visualization, feature-engineering, pandas-polars, database-modeling, sql-patterns
AI/ML: ai-fundamentals, ml-pipeline, prompt-engineering, llm-evaluation, embedding-vectordb, rag-engineering, code-generation
Research authoring: latex-authoring, documentation, infographics, excalidraw
Infrastructure bits research projects touch: shell-scripting, container-orchestration

Source

src/packages/research.yaml

v2 Contracts

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

SmoothTiger/SmoothRiver v2 keeps durable facts in existing entity primitives and uses projection skills for runtime files. The source of truth remains processkit context; generated files are checked against that source.

Metric, Model, Process, Schedule, and StateMachine are legacy v1 migration-source kinds, not shipped v2 entity primitives. Model selection uses model-recommender roster/configuration data. Process definitions are Artifacts plus process-instance WorkItems. Schedule semantics use Binding(type=time-window). Runtime state-machine YAML files remain implementation contracts, not user-authored StateMachine entities.

Architecture Skills

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

Skills for software architecture, design patterns, and system design.

software-architecture

Analyzes codebases for architectural patterns and quality. Use when designing systems, creating ADRs, reviewing structure, or generating architecture diagrams.

Triggers: Designing systems, creating ADRs, reviewing code structure, generating C4 diagrams, applying SOLID/DRY/KISS principles Tools: None References: patterns.md

Key capabilities:

Analyze existing architecture by mapping module organization, dependency directions, and identifying violations (circular deps, layer skipping, leaky abstractions)
Suggest architecture patterns matched to project type (layered, hexagonal, modular monolith, microservices, pipe-and-filter, event-driven)
Create Architecture Decision Records (ADRs) with context, decision, and consequences
Review code for architectural violations: god modules, tight coupling, missing boundaries
Generate C4 diagrams (System Context, Container, Component) using Mermaid syntax

Example usage

“Review this project’s architecture” – Maps the dependency graph, identifies that controllers directly import database models (layer violation), suggests introducing a service layer with repository traits, and provides a C4 Level 3 component diagram of the proposed structure.

product

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

Intended for: end-to-end product development teams. Extends: software

The most comprehensive tier. Software plus design, mobile, framework, and product-specific skills. Use when engineering, design, research, and operations all live in the same repository.

What product adds on top of software

Design: frontend-design, mobile-app-design, logo-design
Framework: fastapi-patterns, tailwind, typescript-patterns, flutter-development, reflex-python
Data subset: data-visualization, feature-engineering, ai-fundamentals, prompt-engineering, llm-evaluation
Language conventions: python-best-practices, rust-conventions, go-conventions, java-patterns
Documentation: latex-authoring, excalidraw, infographics
Product ops: seo-optimization, agent-management

When NOT to use product

If you don’t actually need design, mobile, or framework skills — stick with software. The product tier is large and expecting every team to manage it is false economy.

Design & Visual Skills

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

Skills for frontend development, visual design, and creative production.

excalidraw

Generates Excalidraw diagrams programmatically as JSON. Use when creating architecture diagrams, flowcharts, or hand-drawn-style visuals for documentation.

Triggers: Creating architecture diagrams, flowcharts, system diagrams, or hand-drawn-style visuals for documentation Tools: None References: json-schema.md

Key capabilities:

Generate Excalidraw JSON files with proper structure (elements, appState, version 2 format)
Create element types: rectangles, ellipses, diamonds, lines, arrows, text, with configurable styles
Bind text labels to shapes for labeled diagrams
Follow layout guidelines: grid alignment (multiples of 20), consistent spacing, readable font sizes
Apply a semantic color palette (primary, secondary, success, warning, danger, neutral)
Produce architecture diagrams, flowcharts, and sequence-style diagrams
Embed in documentation as .excalidraw, SVG, or PNG

Example usage

“Create an architecture diagram for a web app with React frontend, Node API, and PostgreSQL” – Generates Excalidraw JSON with three labeled rectangles arranged left-to-right, connected by arrows labeled “HTTP/REST” and “SQL”, using blue for frontend, green for API, yellow for database.

Data & Analytics Skills

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

Skills for data science, data engineering, and analytics workflows.

data-science

Data analysis workflow from import through modeling and communication. Covers tidy data, EDA, statistical reasoning, and visualization. Use when analyzing datasets, building statistical models, exploring data, or communicating findings.

Triggers: Analyzing datasets, exploring data, building statistical models, creating visualizations, cleaning messy data, communicating findings Tools: Bash(python:*) Bash(jupyter:*) Read Write References: tidy-data-principles.md, statistical-methods.md, visualization-guidelines.md

Key capabilities:

Import and clean data: inspect shape/dtypes/nulls, handle missing data explicitly, parse dates, validate assumptions
Reshape data to tidy form (one variable per column, one observation per row) using melt/pivot
Conduct exploratory data analysis: univariate distributions, bivariate relationships, outlier detection, groupby aggregations
Apply statistical reasoning: state the question first, check assumptions, report effect sizes alongside p-values, use confidence intervals
Perform feature selection: remove zero-variance features, handle multicollinearity, use domain knowledge then data-driven methods
Follow model selection workflow: start simple (baseline), add complexity only when justified, use cross-validation, document decisions
Visualize with best practices: titles, axis labels, colorblind-friendly palettes, annotations, publication-quality export
Communicate results: lead with findings, plain language, show uncertainty, include actionable “so what”

Example usage

“I have a CSV of customer transactions. Help me understand churn patterns.” – Loads the CSV, prints shape/dtypes/nulls, creates tidy time-series per customer, runs EDA with churn-rate distributions and cohort analysis, tests whether usage frequency differs between churned/retained groups (t-test with effect size), and produces annotated visualizations summarizing the key drivers.

AI & ML Skills

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

Skills for AI/ML development, RAG pipelines, prompt engineering, and model evaluation.

ai-fundamentals

Core ML/AI concepts including model types, training pipelines, evaluation metrics, and neural network architectures. Use when explaining AI concepts, choosing model approaches, designing ML solutions, or reviewing AI-related code.

Triggers: Explaining ML/AI concepts, choosing model architectures, designing training pipelines, selecting evaluation metrics, debugging model performance (overfitting, leakage, class imbalance) Tools: None References: ml-concepts.md, math-foundations.md

Key capabilities:

Classify problems by learning paradigm: supervised, unsupervised, reinforcement, self-supervised
Match model types to problems: linear models for baselines, tree-based (XGBoost/LightGBM) for tabular data, neural networks for unstructured data, probabilistic models for uncertainty
Design correct training pipelines: data prep, train/val/test split before preprocessing, feature engineering, training, hyperparameter tuning, regularization, final evaluation
Select evaluation metrics by task: F1/AUC-ROC for classification, RMSE/MAE for regression, NDCG/MAP for ranking, BLEU/ROUGE for generation
Understand neural network architectures: MLP, CNN, RNN/LSTM, Transformer, GAN, VAE, diffusion models
Explain modern LLM concepts: attention, tokenization, pre-training + fine-tuning, RLHF, prompting strategies, scaling laws
Identify common pitfalls: data leakage, overfitting, underfitting, class imbalance, distribution shift, metric mismatch

Example usage

“Choose an approach for tabular customer churn prediction” – With 50K labeled rows of structured data, recommends gradient-boosted trees (XGBoost/LightGBM) with stratified k-fold cross-validation for the imbalanced target. Reports F1 and AUC-ROC. Baselines with logistic regression first, only considers neural approaches if tree models plateau.

API & Integration Skills

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

Skills for API design, protocol patterns, and system integration.

api-design

REST API design including resource naming, HTTP methods, status codes, pagination, versioning, and OpenAPI specs. Use when designing APIs, reviewing API contracts, or writing OpenAPI/Swagger documentation.

Triggers: Designing a new REST API or extending an existing one, reviewing API contracts, writing OpenAPI/Swagger docs, choosing pagination or versioning strategies, defining error response formats. Tools: Bash Read Write References: rest-conventions.md, openapi-patterns.md

Key capabilities:

processkit v1.0 Base Context

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

Created: 2026-07-04

This historical base context was created for the processkit v1.0 redesign. It was built from the earlier projectious-work/processkit repository, cloned locally at:

Source URL: https://github.com/projectious-work/processkit
Analyzed commit: 6a9a175f95c42dd76e23488feca42e3d05526b98
Local clone: /tmp/processkit-original

The goal is to preserve the proven v0.x product target while creating a clean basis for processkit v1.0 improvement briefings.

Current Guiding Briefing

The current guiding briefing is processkit-v1.0-rfc-draft.md, analyzed in the processkit v1.0 RFC analysis .

Conflict rule:

preserve the stable product target captured in this base context
use the v1.0 RFC for ontology, branch, release, schema-composition, validation, indexing, and cutover-gate direction
treat concept-mapping-2026-05-16.md as historical input where it agrees with the RFC, not as current guidance where it conflicts

Current Repository Status

At the time of this analysis, the workspace was a fresh aibox/processkit-derived project scaffold, not yet a rebuilt processkit source tree.

Product Specification

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

Purpose

processkit v1.0 provides a durable process substrate for agentic software projects. It gives humans and AI agents a shared project memory with typed work, decisions, discussions, artifacts, roles, skills, gates, bindings, and event history.

The product is not an agent runtime. It is the process and memory layer that agent runtimes, coding agents, and human maintainers can use to coordinate work safely.

Primary Users

Project owners who want inspectable, durable AI-assisted project memory.
Maintainers who need decisions, work, artifacts, and migrations to be traceable.
AI coding agents that need reliable task context and write-safe MCP tools.
Agent runtime integrators that need a provider-neutral process layer.

Problems To Solve

Agent sessions lose project context across turns and tools.
Important decisions and rationale are buried in chat.
Work state, review state, and acceptance criteria are not consistently queryable.
Multi-agent teams need roles, skills, handoffs, gates, and logs.
Markdown knowledge is readable but often lacks lifecycle semantics.
Service-owned metadata systems are less portable than git-backed files.

Product Goals

Keep project memory file-backed, git-native, and human-inspectable.
Make process writes happen through validated MCP tools.
Support typed entities, state machines, and relation queries.
Implement the RFC’s 89-concept T/P/D/C ontology target.
Preserve auditability through structured event logs.
Support provider-neutral roles, team members, model routing, and skills.
Export and ingest OKF bundles without weakening canonical semantics.
Integrate with external agent runtimes instead of replacing them.

Non-Goals

Build a general agent runtime.
Build a vector database.
Build a general data catalog.
Make OKF the canonical internal model.
Replace GitHub, issue trackers, CI, or code review systems.
Optimize for synthetic coding-agent benchmarks as the product goal.

Core Workflows

Capture work as typed WorkItems with acceptance criteria.
Record decisions with context, alternatives, rationale, and consequences.
Attach artifacts and supporting analysis to work and decisions.
Route tasks to roles, team members, skills, and model classes.
Apply gates for approval, policy, evaluation, and release checks.
Query by interface rather than forcing agents to guess concrete entity kinds.
Preserve process evidence in structured LogEntries.
Export selected knowledge as OKF for open exchange.

Success Criteria

A maintainer can understand project state from files and docs without replaying chat history.
An agent can create, transition, and query process entities through MCP tools without hand-editing canonical context files.
A real project cycle can run through the v1.0 alpha model.
Automated fixture tests cover schema generation, MCP contracts, indexing, migrations, and pk-doctor before manual dogfood begins.
OKF export produces a conformant bundle for public consumption.
Existing v0.x evidence can migrate or be explicitly preserved.

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.

Security Skills

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

Skills for application security, authentication, and threat analysis.

dependency-audit

Audits project dependencies for vulnerabilities and outdated packages. Use when checking security posture or planning dependency updates.

Triggers: Checking dependencies, auditing security, updating packages, verifying dependency health before a release. Tools: None References: None

Key capabilities:

Multi-ecosystem audit tool selection (cargo audit, pip-audit, npm audit, govulncheck)
Severity-based triage: critical/high (fix immediately), medium (this sprint), low (when convenient)
Update strategy: one dependency at a time, full test suite after each, changelog review
Outdated package detection (cargo outdated, pip list –outdated, npm outdated)
Ongoing maintenance: monthly reviews, Dependabot/Renovate automation, pinned version documentation

Example usage

User asks “Are my dependencies secure?” The agent runs the appropriate audit tool for the project’s package manager, summarizes findings by severity, and recommends specific version bumps for vulnerable packages. Flags any dependencies with no maintained alternatives.

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.

Observability Skills

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

Skills for logging, monitoring, tracing, and alerting in production systems.

logging-strategy

Structured logging strategy including log levels, correlation IDs, context propagation, and PII avoidance. Use when designing logging, reviewing log statements, or setting up log aggregation.

Triggers: Designing a logging approach, reviewing existing log statements, setting up log aggregation (ELK, Loki, CloudWatch), adding correlation IDs, deciding what to log and what to avoid. Tools: Bash Read Write References: structured-logging.md

Key capabilities:

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.

Database Skills

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

Skills for SQL, data modeling, NoSQL patterns, and schema migrations.

sql-patterns

SQL query patterns, schema design, and optimization. Joins, CTEs, window functions, indexing, and anti-patterns. Use when writing SQL queries, designing schemas, optimizing database performance, or reviewing database code.

Triggers: Writing or optimizing SQL queries (joins, CTEs, window functions), designing or reviewing schemas, analyzing EXPLAIN plans, choosing indexing strategies, fixing slow queries, implementing pagination or analytical queries. Tools: Bash Read Write References: query-patterns.md, schema-design.md

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
 - Documentation 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.

Architecture Specification

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

System Role

processkit v1.0 is a provider-neutral process and memory substrate. It stores canonical project entities in git-backed files and exposes safe read/write behavior through MCP servers.

Agent runtimes are consumers. processkit provides context, process state, governance, and memory; it does not own the agent loop.

Canonical Model

The v1.0 ontology follows the RFC’s T/P/D/C framing:

T: terminology and shared fragments without their own lifecycle
P: persistent primitives with schema and lifecycle
D: discriminator variants of primitives
C: compositions of primitives and terminology fragments

The full RFC target is 89 concepts. The alpha should implement only a small proven subset before expanding. The detailed inventory is captured in Ontology Reference .

Concept Mapping Briefing Analysis

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

Source: concept-mapping-2026-05-16.md

Analyzed: 2026-07-04

Supersession note: processkit-v1.0-rfc-draft.md is now the guiding briefing for processkit v1.0. Where this analysis conflicts with the processkit v1.0 RFC analysis , the RFC analysis wins. Keep this file as historical interpretation of the earlier concept-mapping input, not as current implementation guidance.

The filename dates the briefing to 2026-05-16, but the document itself continues through Round 17 on 2026-05-20. Treat it as a mid-May design snapshot, roughly six to seven weeks old as of this analysis.

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).

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.

Ontology Reference

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

processkit-v1.0-rfc-draft.md is the leading document for the v1.0 ontology. When older analysis conflicts with this page, the RFC and this page win.

T/P/D/C Classes

The RFC names four implementation classes. If a note says TCDP, read it as the same four classes, with the RFC’s canonical order written as T/P/D/C.

Class	Meaning	Description
`T`	Terminology / foundational fragment	A concept, slot, or meta-mechanic that has no independent entity lifecycle. T concepts are reused in schemas, state machines, constraints, and generated fragments.
`P`	Primitive	An atomic persistent entity kind with its own schema, lifecycle, ID policy, validation contract, and storage path. P concepts can be composed into C concepts.
`D`	Discriminator	A typed variant of a parent primitive, usually represented by `kind:` or an equivalent closed enum. D concepts inherit the parent schema and lifecycle.
`C`	Composition	A named kind assembled from primitives plus T fragments. C concepts can have their own lifecycle, but their schema is built from composed parts.

Counts

The v1.0 target is 89 ontology concepts.

processkit v1.0 RFC Analysis

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

Source: processkit-v1.0-rfc-draft.md

Analyzed: 2026-07-04

Status for this project: guiding briefing. Where this RFC conflicts with concept-mapping-2026-05-16.md or concept-mapping-briefing-analysis.md , this RFC wins.

Executive Read

The RFC turns the earlier concept-mapping work into an implementation and release proposal. It is no longer just an ontology discussion. It asks upstream processkit maintainers to host a full v1.0 greenfield rebuild on a parallel v1.0 branch while main continues v0.x maintenance.

The product target from the base context remains intact: processkit is still provider-neutral process memory, skills, and MCP tooling for agentic software projects. The RFC changes the model and build plan used to reach that target.

OKF Compatibility Analysis

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

Source:

Google Cloud announcement, “Introducing the Open Knowledge Format”, published 2026-06-12
GoogleCloudPlatform/knowledge-catalog okf/SPEC.md, v0.1 draft, inspected at d44368c15e38e7c92481c5992e4f9b5b421a801d

Analyzed: 2026-07-04

Recommendation

processkit v1.0 should support OKF as an import/export and publication profile, but should not make OKF the canonical internal format.

In practical terms:

Yes: emit conformant OKF bundles from selected processkit knowledge.
Yes: ingest OKF bundles into processkit as external knowledge sources.
Yes: preserve OKF-compatible affordances in v1.0 schema design where they do not weaken processkit semantics.
No: do not require the whole repository or canonical context/ tree to be an OKF bundle.
No: do not replace processkit entity IDs, typed relations, lifecycle states, validation modes, event logs, or interface-aware queries with OKF’s permissive markdown conventions.

This gives us interoperability without losing the benefits that make processkit more than an LLM wiki.

Tooling Architecture

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

The v1.0 tooling architecture follows the RFC: schemas are generated from Jinja + YAML sources, writes flow through MCP tools, and indexes are extended rather than replaced.

MCP Server Shape

MCP is the stable runtime contract for agents and harnesses. Files remain human-inspectable, but canonical mutations happen through tools.

The v1.0 server surface should include:

a processkit gateway that exposes the common read/write surface
per-domain management tools for work, decisions, records, gates, discussions, roles, bindings, migrations, and skills
an index-management surface for reads, search, relation traversal, and interface queries
a schema-management surface with regenerate_schemas
a doctor/audit surface for validation, drift, and release readiness

The gateway can aggregate tools for harness convenience, but tool ownership should remain domain-specific so validation and lifecycle rules stay close to the schema they enforce.

processkit v1.0 Start Assessment

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

Analyzed: 2026-07-04

Sources considered:

processkit-v1.0-rfc-draft.md
processkit v1.0 RFC Analysis
Concept Mapping Briefing Analysis
OKF Compatibility Analysis
Google OKF announcement and v0.1 specification
External survey of adjacent agent, memory, metadata, and coding-agent projects

Judgement

The v1.0 plan is good enough to start, but not as an unconstrained 9-12 month greenfield rebuild.

Start a v1.0 branch now, but run it as a narrow alpha first:

prove a small vertical slice before implementing the full ontology
keep processkit’s canonical semantics stricter than OKF
position processkit as process memory and governance, not as another agent runtime
integrate with external runtimes instead of rebuilding them
add OKF import/export as a boundary compatibility feature

The plan’s direction is strong. Its main risk is scope, not concept.

Test Strategy

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

The current exploratory strategy is to install processkit into a new aibox project and try workflows manually. That remains useful as a human dogfood check, but it is not enough for v1.0. It is not automated, it makes aibox a hard dependency, and it cannot prove release-gate criteria repeatably.

Test Goals

The v1.0 test strategy must prove:

schema generation is deterministic
generated schemas validate real and adversarial fixtures correctly
MCP tools match their Python signatures and JSON Schemas
writes enforce state machines, guards, validation modes, and event logs
index reads match canonical files after creates, transitions, and migrations
query_by_interface returns complete mixed-kind results
migration tools preserve data within the RFC gate limits
pk-doctor catches deliberately invalid entities
docs and examples remain buildable
aibox integration works as an adapter, not as the only system test

Automated Layers

Layer	Purpose
Schema unit tests	Render Jinja + YAML fragments, compare `_generated` output to golden files, and verify merge strategies.
Schema contract tests	Validate generated draft-2020-12 schemas against valid and invalid entity fixtures.
MCP contract tests	Check every tool signature against its JSON Schema and run typed request/response fixtures.
State-machine tests	Exercise valid and invalid transitions, guard failures, terminal states, and emitted events.
Index tests	Create and mutate fixture entities, then assert search, relation traversal, backlinks, and interface grouping.
Migration tests	Run v0.x fixture corpora through migration adapters and assert field-loss, orphan, and hash-immutability gates.
pk-doctor adversarial tests	Feed deliberately invalid fixtures and require every expected finding with no blocking false positives.
Package smoke tests	Install processkit from the local tree or release tarball into a temporary fixture project without aibox.
Docs tests	Build the Hugo site and verify links to generated reference pages.
Adapter tests	Run a small aibox install/apply workflow to prove integration, but keep it outside the core correctness suite.

Fixture Projects

Use local fixture projects under the test tree:

Alpha Scope

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

Purpose

The alpha proves that the v1.0 model improves real agentic project work before the project implements the full 89-concept ontology.

The alpha is a vertical slice, not a miniature final release.

Scope

Implement 10-15 high-value concepts covering:

WorkItem
DecisionRecord
Artifact
Discussion
Note
LogEntry
Binding
Gate
Role
TeamMember
Skill
Capability
Proposition or Risk
Scope
Migration

The exact list may change if implementation evidence shows a better slice, but it must cover work, decisions, artifacts, relations, gates, roles, skills, and event history.

Landscape Note

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

Positioning

processkit v1.0 is not trying to replace agent runtimes, memory databases, coding agents, or data catalogs. It should be the process substrate those systems can use.

Its strongest position is:

provider-neutral process memory and governance for agentic software projects.

Adjacent Areas

OKF

OKF validates markdown plus YAML frontmatter as an agent-readable exchange format. processkit should support OKF import/export, generated indexes, and permissive boundary consumption.

processkit should not copy OKF’s path IDs, untyped links, or prose-only logs as canonical semantics.

Acceptance Gate

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

Purpose

The acceptance gate keeps the v1.0 rebuild measurable. The RFC’s 81-criterion gate is authoritative for final cutover; the staged lists below are working summaries for alpha-first execution.

RFC Cutover Gate

Phase	Criteria	Strict	Soft
P0 - Pre-conditions	5	5	0
O1 - Ontology completeness	11	9	2
T2 - Tooling parity	12	9	3
C3 - Corpus migration	10	10	0
S4 - Skills and agents	8	8	0
A5 - First-ART validation	18	18	0
G6 - Cutover decision point	8	8	0
R7 - Post-cutover stabilisation	9	8	1
Total	81	75	6

A5 is the proof phase: model a real ART end to end and run one full PI cycle through planning, execution, demo, and inspect-and-adapt.

Framework & SEO Skills

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

Skills for specific frameworks and search engine optimization.

reflex-python

Reflex Python web framework for building full-stack apps in pure Python. Components, state management, and deployment. Use when building Reflex apps, designing component hierarchies, or managing app state.

Triggers: When building web apps with Reflex, designing components, managing state, routing, or creating full-stack Python web applications. Tools: Bash(reflex:*) Bash(python:*) Read Write References: component-reference.md

Key capabilities:

App structure: initialization, entry points, page decorators, file-based routing, configuration
Component system: layout (box, flex, grid), display (text, heading, image), input (input, select, checkbox), feedback (alert, toast, spinner)
State management with rx.State classes, typed vars, event handlers, computed vars, and substates
Event handling: on_click, on_change, two-way binding, background tasks, event chaining
Styling with Radix UI design tokens, responsive props, light/dark themes
Routing with dynamic segments, programmatic navigation, on_load events, and 404 handling
Database integration via built-in SQLModel with automatic migrations
Deployment to Reflex Cloud or self-hosted via Docker

??? example “Example usage” Build a todo app: Defines a TodoState with a list of todos and input field, creates event handlers for add/delete/toggle, builds UI with rx.input, rx.button, and rx.foreach(TodoState.todos, render_todo) to render the list dynamically.

Performance Skills

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

Skills for performance analysis, optimization, and load testing.

performance-profiling

Performance analysis methodology and profiling techniques for CPU, memory, and I/O. Flame graphs, benchmarking, and regression detection. Use when optimizing performance, profiling bottlenecks, or reviewing performance-critical code.

Triggers: When identifying bottlenecks, profiling CPU/memory/I/O, interpreting flame graphs, setting up benchmarks, or optimizing slow code paths. Tools: Bash Read Write References: profiling-tools.md

Key capabilities:

Follow the full performance analysis cycle: Identify, Measure, Profile, Optimize, Verify
CPU profiling with sampling profilers and flame graph generation
Memory profiling to detect leaks, allocation pressure, and unbounded growth
I/O profiling for disk, network, and database bottlenecks (N+1 queries, connection pooling, slow queries)
Benchmarking with statistical significance and regression detection
Flame graph interpretation: reading X-axis (alphabetical, not time), Y-axis (stack depth), and differential flame graphs
Common optimization patterns: algorithmic improvements, batching, caching, pooling, lazy evaluation, data layout

??? example “Example usage” Slow API endpoint: Measures end-to-end latency, profiles the handler, discovers 80% of time spent in 47 sequential database queries (N+1 problem). Rewrites as a single JOIN query, reducing response time from 3 seconds to 120ms.

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`)

processkit

apiVersion Policy

The group

Evolution rules

Non-breaking changes (stay at v1)

Breaking changes (require v2)

Migration between versions

Entity File Format

Canonical shape

The four top-level keys

metadata fields

ID formats

Harness Compatibility

Current modes

ID Formats

Configuration

The four combinations

Prefix registry

Installing

Manual install

minimal

Included skills

When to upgrade

Source

Process Skills

workitem-management

Skill Package Format

Directory layout

Required frontmatter fields

Optional fields

Categories

managed

What managed adds on top of minimal

Skill Hierarchy

The layers

State Machines

WorkItem default

DecisionRecord default

Overriding a default

Version Migration

The model

Your First Entity

Prerequisites

Creating a WorkItem by hand

Language Skills

python-best-practices

Privacy Tiers

The three tiers

Relationships

The rule

Cross-reference examples

software

Highlights

When to upgrade

Infrastructure Skills

dockerfile-review

research

Highlights

Source

v2 Contracts

Architecture Skills

software-architecture

product

What product adds on top of software

When NOT to use product

Design & Visual Skills

excalidraw

Data & Analytics Skills

data-science

AI & ML Skills

ai-fundamentals

API & Integration Skills

api-design

processkit v1.0 Base Context

Current Guiding Briefing

Current Repository Status

Product Specification

Purpose

Primary Users

Problems To Solve