Development on processkit

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.

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 .

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.

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.

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.