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/v2

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
apiVersion	Product line	Status
—	—	—
`processkit.projectious.work/v1`	v0.x	Current v0.x entity format
`processkit.projectious.work/v1beta1`	none	Reserved; not used
`processkit.projectious.work/v2`	v1.x	Current v1.x entity format

The processkit product version, entity API version, schema-source format, and per-kind schema versions are independent axes. In particular, processkit v1.x deliberately uses entity API v2.

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.

The alpha.5 installer can project managed Codex and Claude configuration. It owns only declared processkit keys and preserves unrelated harness settings during install, update, and uninstall. Restart the harness after installation so it reloads the projection.

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

v1 alpha

v1.0.0-alpha.5 is installed with the native Rust lifecycle CLI from an explicitly downloaded, signed release. The alpha does not yet have an online version resolver or one-command bootstrap installer.

Use the complete v1 alpha installation and first-project tutorial . It verifies the signed envelope, checks both artifact digests, previews the plan, installs a selected profile, verifies managed state, and connects the Python MCP gateway.

The current command shape is:

Issue #135 Implementation Review

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

This final review compares GitHub issue #135 with the v1.0.0-alpha.5 implementation and its published release evidence.

Summary

The corrected product boundary and trustworthy local lifecycle are implemented. The Rust executable verifies and transactionally applies an explicit release; Python remains the MCP runtime; release content stays visible; and interruption recovery is exercised with real processes.

Issue #135 is complete as the v1.x implementation umbrella. Three extracted engineering tracks are implemented in alpha.5. The four-platform publication track remains open until locally produced artifacts from every supported host have been collected and verified.

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)

Install and Use the v1 Alpha

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

This tutorial installs the exact v1.0.0-alpha.5 release into a new project. Linux and macOS on x86_64 and arm64 are supported.

1. Check prerequisites

uname -m
python3 --version
uv --version
git --version
jq --version

Python 3.10 or newer, uv, Git, curl, tar, a SHA-256 utility, openssl, and jq are required.

2. Download the exact release

mkdir -p "$PWD/.processkit-download/v1.0.0-alpha.5"
cd "$PWD/.processkit-download/v1.0.0-alpha.5"

release_url="https://github.com/projectious-work/processkit/releases/download/v1.0.0-alpha.5"
for asset in \
 processkit-v1.0.0-alpha.5.tar.gz \
 processkit-v1.0.0-alpha.5.tar.gz.sha256 \
 processkit-v1.0.0-alpha.5.release.json \
 processkit-v1.0.0-alpha.5.release.sig \
 processkit-v1.0.0-alpha.5-public.pem
do
 curl -fL "$release_url/$asset" -o "$asset"
done

The release is exact-pinned. Do not replace the tag with latest.

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.

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.

Your First Entity

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

Create the first WorkItem through processkit’s MCP tools. Do not hand-edit canonical entity files: the management tool validates the schema, applies the storage policy, and writes the audit event as one governed operation.

Prerequisites

Complete the v1 alpha tutorial .
Start a new harness session after the installer writes its managed MCP projection.
Confirm the processkit-gateway tools are visible.

Create a WorkItem

Ask your MCP-capable agent:

Create a medium-priority task WorkItem titled “Evaluate processkit v1 alpha” with acceptance criteria to verify installation, record one decision, and test an update plan.

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:

Claude Code

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

v1 alpha note: Install with --harness claude to create the managed projection. The installer preserves unrelated Claude configuration. The direct uv gateway remains the development and compatibility fallback.

This document captures how processkit surfaces itself inside the Claude Code harness: which payloads land at session start vs. each turn, which hooks fire, and which Claude Code settings we recommend for any processkit project.

WorkItem: BACK-20260509_1317-DaringRaven (issue #19). Companion file: settings.example.json .

What the per-turn hook injects

scripts/emit_compliance_contract.py runs as both a SessionStart and a UserPromptSubmit hook (wired in /workspace/.claude/settings.json under hooks.SessionStart and hooks.UserPromptSubmit). It now emits two different payloads:

CLI and automation interfaces

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

processkit has two deliberately separate command interfaces. Human lifecycle commands optimize for reviewable output and safe project operation. The machine interface uses a versioned JSON request and result contract for aibox and other automation.

Release and development status: v1.0.0-alpha.5 supports the local lifecycle commands below except doctor and mcp. The v1.x-dev line adds read-only native diagnosis and MCP supervision for the next prerelease. Commands in “Target human lifecycle” remain planned unless listed as current.

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.

Generated CLI Reference

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

Do not edit this page by hand. Regenerate it with uv run scripts/generate-v1-docs.py.

Native lifecycle CLI for processkit projects

Usage: processkit <COMMAND>

Commands:
 plan Produce a deterministic, non-mutating installation plan
 install Install a verified release into a new or empty target project
 recover Roll back or finalize incomplete installer transactions
 uninstall Remove unchanged files owned by a prior installation
 update Update unchanged managed files from a verified release
 verify-release Verify a signed local release against an explicit local trust store
 verify Verify installed provenance and report managed-path drift
 inspect-compatibility Inspect a legacy processkit tree without mutating it
 migrate-v0 Transition an exact v0 release into a fresh v1 target
 doctor Diagnose the installed project and Python MCP runtime without mutation
 mcp Verify or supervise the shipped Python MCP gateway
 execute Execute one versioned installer request and emit one result envelope
 help Print this message or the help of the given subcommand(s)

Options:
 -h, --help Print help
 -V, --version Print version

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:

Rust Library API

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

The processkit crate exposes the versioned request envelope used by processkit execute --request. The supported alpha surface is intentionally small:

API_VERSION identifies the machine protocol;
Operation enumerates supported lifecycle operations; and
InstallerRequest constructs and serializes typed request envelopes.

Build and test the API documentation with:

cargo test --doc --locked --manifest-path installer/Cargo.toml
cargo doc --locked --no-deps --manifest-path installer/Cargo.toml

Public items follow semantic versioning within the v1 release line. Modules and functions not reachable from the crate root are internal implementation details and may change between prereleases. Filesystem transactions, release verification, and lifecycle execution remain behind the executable boundary; the library does not offer an alternate mutation path.

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.

Installer Contract

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

Alpha.4 status: Implemented for explicit local distributions and signed local releases. Canonical online release acquisition is not implemented.

The standalone installer consumes only a release directory or verified archive explicitly supplied by its caller. It has no built-in release URL, package layout, MCP inventory, or harness policy.

The release-owned contract is under .processkit/installer/. Protocol processkit.projectious.work/installer/v1alpha1 supports deterministic planning plus transactional install, update, uninstall, and recovery. copy/v1 and preserve-user/v1 are the closed payload operations.

v1 Alpha Release Facts

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

Do not edit this page by hand. Its authoritative source is release/v1-release-facts.json.

Fact	Value
Release	`v1.0.0-alpha.5`
Status	exact-pin prerelease
Signature	`Ed25519`
Installer protocol	`processkit.projectious.work/installer/v1alpha1`
Entity API version	`processkit.projectious.work/v2`

Native Assets

processkit-v1.0.0-alpha.5-x86_64-unknown-linux-gnu
processkit-v1.0.0-alpha.5-aarch64-unknown-linux-gnu
processkit-v1.0.0-alpha.5-x86_64-apple-darwin
processkit-v1.0.0-alpha.5-aarch64-apple-darwin

Every published asset has a checksum sidecar and is bound into the signed release envelope. The public release is the authority for final checksums and host provenance.

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.

Python MCP runtime contract

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

Python is an intentional processkit runtime dependency. It implements the MCP servers; it is not required by the Model Context Protocol itself. The native Rust CLI owns installation and lifecycle safety. Native diagnostics and process supervision wrap that Python implementation; they do not reimplement MCP behavior.

Current alpha requirements

Python 3.10 or newer must be discoverable by uv.
uv must support PEP 723 script metadata.
The installed gateway script and processkit shared Python library must be readable from the selected project root.
The first preparation may require network access to populate the uv cache.
Direct uv run startup remains a supported compatibility and development interface.

Every shipped MCP entry point declares its Python constraint and dependencies in a PEP 723 block. The gateway currently declares:

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.

Release Production

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

The v1 release path is agent-first, human-operable, and entirely local. Maintainer-controlled machines invoke the same repository scripts and bind their native results to one tagged commit. No GitHub Actions or hosted build service participates.

One-time key setup

Keep the private key outside the repository. The public key may be copied to the local trust store of every machine that installs official releases.

scripts/processkit-keygen-local.sh \
 "$HOME/.config/processkit/keys/release.pem" \
 "$HOME/.config/processkit/trust.d/release.pub.pem"

Back up the private key securely. Losing it prevents producing a release under that identity. Disclosing it requires creating a new key identity and removing the compromised public key from local trust stores.

Evidence-bound Release Process

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

Issue #151 defines the aibox-style release ritual adopted by processkit.

Version-line authority

The requested semantic version determines the only branch permitted to tag:

Version	Required branch
stable v0	`v0.x-release`
v1 alpha, beta, or RC	`v1.x-pre-release`
stable v1	`v1.x-release`

Resolve the mapping without mutation:

scripts/maintain.sh release-branch v1.0.0-alpha.5

Promotion into protected branches happens through pull requests. Never force-push a release branch.

Candidate evidence

Evidence belongs to an exact candidate:

dist/release-evidence/<version>/<commit>/
├── binding.json
├── RELEASE-STATE.md
├── RELEASE-DOCTORS.md
├── logs/
└── <step>.passed

The binding records version, commit, clean tree, branch, Rust, Python, uv, and host target. A step marker is reused only within that binding.

Installer Threat Model

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

Alpha.4 status: Traversal, symlink, forged-journal, signature, digest, downgrade, same-version equivocation, and interruption paths have automated coverage. The “before beta” items below remain open hardening targets.

The installer treats an archive, descriptor, manifest, catalog, adapter, and target filesystem as untrusted until validated. It must reject absolute or parent-traversal paths, archive links and path escapes, duplicate normalized destinations, unsupported operations, unverified assets, and target symlink escapes. It must not execute release-supplied code.

v0 Compatibility

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

v1.x development status: Exact-release inspection and a guarded fresh-target transition are implemented. Native in-place migration and automatic legacy-entity transformation are not supported.

The v1 installer identifies legacy processkit evidence without consulting aibox, harness, devcontainer, or MCP configuration files.

processkit inspect-compatibility \
 --root /path/to/legacy-tree \
 --distribution /path/to/processkit-v1-release \
 --json

An exact-release result requires every immutable anchor in a shipped compatibility manifest to match. The beta manifests cover v0.27.1 and v0.28.4 release trees. A partial installed project may be classified only as legacy-project-candidate; its exact version is never guessed.

aibox Integration

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

Alpha.5 status: The opaque request/result protocol and direct-CLI/aibox installed-state parity contract are implemented. The v0 compatibility bridge remains available for gradual downstream adoption.

aibox should treat processkit as an opaque local executable. It creates a versioned JSON request, invokes processkit execute --request <path>, parses the single JSON result, and does not duplicate processkit ownership policy.

The producer integration checkpoint is the schema bundle under src/.processkit/installer/schemas/, the executable built from installer/, and these local gates:

Acceptance Gate

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

Alpha.4 review: Ontology, schema generation, local installer lifecycle, signed release, extracted-package MCP smoke, and first-ART evidence are implemented. Four-platform native distribution, bootstrap installation, online release resolution, native doctor/MCP supervision, full dogfood update recovery, and v0-to-v1 migration remain GA blockers. See the issue #135 implementation review .

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.

Alpha Release Testing

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

Alpha.5 documentation review: This page records design or historical planning. For shipped behavior and current gaps, use the issue #135 implementation review .

Release Policy

The current test release is the explicit prerelease v1.0.0-alpha.5. It is merged from v1.x-dev into v1.x-pre-release, validated there, and tagged there.

Prereleases never become the implicit latest version. latest remains the highest stable release, currently from the supported v0 line. Downstream installers must opt in to an exact prerelease.

Alpha Scope

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

Alpha.4 documentation review: This page records design or historical planning. For shipped behavior and current gaps, use the issue #135 implementation review .

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

The alpha product slice is frozen to these 14 high-value concepts:

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

Four prerequisite parent concepts are required to model that slice honestly: Actor for TeamMember, Container for Scope, and Command plus Event for Migration. The generated alpha contract therefore covers 18 of the ontology’s 89 concepts while preserving the 14-concept product scope.

Alpha.3 Closure Plan

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

Alpha.4 documentation review: This page records design or historical planning. For shipped behavior and current gaps, use the issue #135 implementation review .

v1.0.0-alpha.3 was the feature-complete pre-cutover target. This historical plan did not authorize a merge to main; v0.x remains the stable line until the owner accepts the final ontology, migration, CLI, and aibox evidence.

The machine-readable gate ledger is docs-site/data/v1_alpha3_gates.yaml. It tracks all 81 original v1 criteria and all 15 installer criteria from issue #118. A criterion may be met, partial, missing, owner-review, or deferred-post-cutover.

Architecture Specification

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

Alpha.5 status: The Rust lifecycle/Python MCP boundary below is accepted and implemented for local release verification, planning, install, update, recovery, verification, and uninstall. Online release resolution, native runtime diagnostics, and Rust-supervised MCP are planned.

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.

Beta Ontology Plan

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

Alpha.4 documentation review: This page records design or historical planning. For shipped behavior and current gaps, use the issue #135 implementation review .

Target

The beta target is 62 of the ontology’s 89 concepts, or 69.7%. This keeps the accepted goal inside the 60–70% range while leaving room to validate the model through real workflows before completing the long tail.

Coverage is counted by ontology category:

Category	Beta target
Terminology	19
Primitives	22
Discriminators	8
Compositions	13
Total	62

The alpha’s 18 generated contracts are the first dependency-complete slice of this target.

Branch Start Work Plan

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

Alpha.4 documentation review: This page records design or historical planning. For shipped behavior and current gaps, use the issue #135 implementation review .

This plan turns the v1.0 documentation set into branch-start execution work. Phase 0 and Phase 1 are intentionally concrete; later phases are rougher and should be refined as evidence arrives.

Phase 0 - Branch Foundation

Goal: make the v1.0 branch buildable, testable, and clearly separated from v0.x maintenance.

Backlog:

Concept Mapping Briefing Analysis

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

Alpha.4 documentation review: This page records design or historical planning. For shipped behavior and current gaps, use the issue #135 implementation review .

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.

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.

Landscape Note

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

Alpha.4 documentation review: This page records design or historical planning. For shipped behavior and current gaps, use the issue #135 implementation review .

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.

OKF Compatibility Analysis

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

Alpha.4 documentation review: This page records design or historical planning. For shipped behavior and current gaps, use the issue #135 implementation review .

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.

Ontology Reference

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

Alpha.4 documentation review: This page records design or historical planning. For shipped behavior and current gaps, use the issue #135 implementation review .

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.

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.

processkit v1.0 Base Context

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

Alpha.4 documentation review: This page records design or historical planning. For shipped behavior and current gaps, use the issue #135 implementation review .

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.

processkit v1.0 RFC Analysis

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

Alpha.4 documentation review: This page records design or historical planning. For shipped behavior and current gaps, use the issue #135 implementation review .

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.

processkit v1.0 Start Assessment

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

Alpha.4 documentation review: This page records design or historical planning. For shipped behavior and current gaps, use the issue #135 implementation review .

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.

Product Specification

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

Alpha.4 documentation review: This page records design or historical planning. For shipped behavior and current gaps, use the issue #135 implementation review .

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.

Test Strategy

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

Alpha.4 documentation review: This page records design or historical planning. For shipped behavior and current gaps, use the issue #135 implementation review .

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.

Tooling Architecture

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

Alpha.4 documentation review: This page records design or historical planning. For shipped behavior and current gaps, use the issue #135 implementation review .

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.

v0 Reconciliation

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

Alpha.4 documentation review: This page records design or historical planning. For shipped behavior and current gaps, use the issue #135 implementation review .

Baseline

The v1 line forked from v0.27.1. Reconciliation therefore compares the current v1 work against the latest supported v0 release, currently v0.28.3, rather than copying the v0 tree wholesale.

The rule is:

carry fixes that remain valid under the v1 ontology
adapt lifecycle and storage behavior to generated v1 contracts
regenerate catalogs, schemas, and manifests from v1 sources
defer unrelated v0 features with an explicit disposition
never overwrite v1 schema sources with flat v0 schemas

Current Matrix

v0 surface	v1 disposition	Alpha status
Refreshable GitHub token-file authentication	Carry unchanged security semantics	Implemented and tested
Migration drafting	Adapt to v1 Migration schema and automatic apply mode	Implemented and tested
Historical migration filename repair	Carry with append-only audit bridge	Implemented and tested
Scope lifecycle	Adapt storage to `Container(kind=scope)`	Implemented and tested
TeamMember role assignment	Adapt through the Actor interface	Implemented and tested
Immutable release-manifest preflight	Carry `--check`; builds must not mutate tags	Implemented
`git-branching` skill	Carry after v1 metadata review	Deferred after alpha
`project-reconciliation` skill	Carry after v1 entity-name review	Deferred after alpha
`repository-portfolio-review` skill	Carry after v1 entity-name review	Deferred after alpha
v0 doctor fixes	Re-evaluate per finding against v1 storage	Ongoing
v0 flat schemas and generated catalogs	Never copy; regenerate from v1 sources	Enforced

Verification

The server smoke suite exercises the v1-native replacements. The package smoke suite then extracts only the release tree and repeats the workflow so repository imports cannot conceal a missing carry-over.

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

Entity File Format

Canonical shape

The four top-level keys

metadata fields

ID formats

Harness Compatibility

ID Formats

Configuration

The four combinations

Prefix registry

Installing

v1 alpha

Issue #135 Implementation Review

Summary

minimal

Included skills

When to upgrade

Source

Process Skills

workitem-management

Skill Package Format

Directory layout

Required frontmatter fields

Optional fields

Categories

Install and Use the v1 Alpha

1. Check prerequisites

2. Download the exact release

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

Language Skills

python-best-practices

Privacy Tiers

The three tiers

Relationships

The rule

Cross-reference examples

software

Highlights

When to upgrade

Your First Entity

Prerequisites

Create a WorkItem

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

Claude Code

What the per-turn hook injects

CLI and automation interfaces

WorkItem

State machine

Fields