Introduction

• 1: Development
• 1.1: v0 Prototype
• 1.2: v1.x Version
• 1.2.1: Issue #135 Implementation Review
• 1.2.2: Acceptance Gate
• 1.2.3: Alpha Release Testing
• 1.2.4: Alpha Scope
• 1.2.5: Alpha.3 Closure Plan
• 1.2.6: Analysis Archive
• 1.2.6.1: Concept Mapping Briefing Analysis
• 1.2.6.2: OKF Compatibility Analysis
• 1.2.6.3: processkit v1.0 Base Context
• 1.2.6.4: processkit v1.0 RFC Analysis
• 1.2.6.5: processkit v1.0 Start Assessment
• 1.2.7: Architecture Specification
• 1.2.8: Beta Ontology Plan
• 1.2.9: Branch Start Work Plan
• 1.2.10: Landscape Note
• 1.2.11: Ontology Reference
• 1.2.12: Product Specification
• 1.2.13: Test Strategy
• 1.2.14: Tooling Architecture
• 1.2.15: v0 Reconciliation
• 2: Getting Started
• 2.1: Installing
• 2.2: Install and Use the v1 Alpha
• 2.3: Your First Entity
• 3: Primitives
• 3.1: Entity File Format
• 3.2: State Machines
• 3.3: Relationships
• 3.4: WorkItem
• 3.5: LogEntry
• 3.6: DecisionRecord
• 3.7: Artifact
• 3.8: Note
• 3.9: Actor
• 3.10: Role
• 3.11: Binding
• 3.12: Scope
• 3.13: Discussion
• 3.14: Gate
• 3.15: Migration
• 3.16: Schedule
• 3.17: Constraint
• 3.18: Category
• 3.19: CrossReference
• 3.20: Context
• 3.21: Process
• 3.22: StateMachine
• 4: Skills
• 4.1: Skill Package Format
• 4.2: Skill Hierarchy
• 4.3: Catalog
• 4.3.1: Process Skills
• 4.3.2: Language Skills
• 4.3.3: Infrastructure Skills
• 4.3.4: Architecture Skills
• 4.3.5: Design & Visual Skills
• 4.3.6: Data & Analytics Skills
• 4.3.7: AI & ML Skills
• 4.3.8: API & Integration Skills
• 4.3.9: Security Skills
• 4.3.10: Observability Skills
• 4.3.11: Database Skills
• 4.3.12: Framework & SEO Skills
• 4.3.13: Performance Skills
• 5: Packages
• 5.1: minimal
• 5.2: managed
• 5.3: software
• 5.4: research
• 5.5: product
• 6: Processes
• 7: Installer and releases
• 7.1: CLI and automation interfaces
• 7.2: Generated CLI Reference
• 7.3: Rust Library API
• 7.4: Installer Contract
• 7.5: Python MCP runtime contract
• 7.6: Release Production
• 7.7: Evidence-bound Release Process
• 7.8: Installer Threat Model
• 7.9: v0 Compatibility
• 7.10: aibox Integration
• 8: MCP Servers
• 8.1: Harness Compatibility
• 8.2: Claude Code
• 9: Reference
• 9.1: apiVersion Policy
• 9.2: ID Formats
• 9.3: Version Migration
• 9.4: Privacy Tiers
• 9.5: v2 Contracts
• 9.6: v1 Alpha Release Facts

1 - Development

This section is the open planning area for processkit evolution. It separates the current v0 prototype from the planned processkit v1.0 rebuild so readers can distinguish shipped behavior from future design.

Design documents that affect the product, architecture, implementation scope, acceptance gates, or external positioning should be added here. Governance-relevant documents should also be recorded as processkit Artifacts or Decisions through the processkit gateway.

Sections

• v0 Prototype
• v1.0 Version

1.1 - v0 Prototype

The current project is the v0 prototype line of processkit. It is usable and dogfooded, but it is not the final v1.0 architecture. It proves the product shape: git-backed process memory, skills, state machines, MCP tools, package tiers, release machinery, and a Docusaurus docs site for human readers.

Current Status

As of the v1.0 branch start, main is at the v0.27.x line with additional development documentation. The prototype has:

• a shipped src/ deliverable boundary for consumers
• file-backed process entities with YAML frontmatter
• processkit API v2 entity schemas and state machines
• package tiers for selected skill and context bundles
• per-domain MCP management tools plus a processkit gateway mode
• pk-doctor health checks and release-audit style validation
• release tarball, provenance, and docs publishing scripts
• a manual GitHub Pages publish flow for docs-site
• aibox-assisted installation and synchronization in derived projects

The v0 line remains the maintenance and migration-source line while v1.0 is built on a parallel branch.

How We Got Here

The context index shows the prototype grew through dogfooding rather than from a single upfront platform rewrite:

• The product target was captured in ART-20260409_1854-KindCrane-processkit-product-requirements-document as provider-neutral process memory, skills, and MCP tools for agentic software projects.
• Early releases established the file-backed entity model, package tiers, skill catalog, and consumer-facing src/ mirror.
• Release automation was hardened after the v0.19.0/v0.19.1 learning that git push --tags is not the same thing as publishing a GitHub Release.
• The aibox integration became an installer/supervisor path, not the processkit source of truth. The v0.25 handover records the package and MCP-gateway handoff shape for downstream projects.
• The provider-neutral gateway decision DEC-20260502_0743-CoolFjord-adopt-provider-neutral-processkit-gateway-daemon kept processkit standalone while adding a lower-process-count runtime path for MCP-capable harnesses.
• Later v0 work added stricter doctor checks, release integrity checks, MCP config drift detection, TeamMember routing, and docs-site coverage.

Why v1.0 Is Needed

The v0 prototype proved the workflow but exposed model pressure:

• the current primitive set cannot cleanly express the full v1.0 ontology without overloading tags, kinds, and fields
• agents still need better query surfaces than concrete-kind guessing
• schema composition, generated runtime schemas, and validation modes need to become first-class
• migration and test evidence need to be automated rather than relying on manual aibox dogfood
• pk-doctor and MCP tooling need adversarial fixtures and stronger contract tests

v0 should therefore be treated as working evidence and migration source. v1.0 is the revised implementation line.

1.2 - v1.x Version

The v1 line is an active prerelease, not only a design proposal. v1.0.0-alpha.5 supplies a native Rust lifecycle CLI, a signed release contract, generated schemas, and the Python MCP runtime as visible project content.

The RFC and planning pages in this section remain useful design history. Statements written as future requirements are not evidence that a feature is implemented. Use the implementation review for the current truth.

Current Status

• Issue #135 Implementation Review
• Alpha.5 Release Facts
• Install and Use the v1 Alpha

The fixed architecture is:

• Rust owns release trust and project-content lifecycle.
• Python remains the authoritative MCP implementation.
• skills, schemas, processes, state machines, and entities remain files.
• context/ is dogfood consumer state; src/context/ is the release producer payload.
• the supported v0 line remains the default while v1 is exact-pin alpha.

Design and Evidence Documents

• Product Specification
• Architecture Specification
• Ontology Reference
• Tooling Architecture
• Test Strategy
• Alpha Scope
• Alpha Release Testing
• v0 Reconciliation
• Beta Ontology Plan
• Branch Start Work Plan
• Landscape Note
• Acceptance Gate
• Issue #135 Implementation Review

Supporting Analysis

• Base Context
• Concept Mapping Briefing Analysis
• processkit v1.0 RFC Analysis
• OKF Compatibility Analysis
• Start Assessment

Branch Contract

The v1 development line is isolated from v0 maintenance:

• schema source and generated schema machinery
• v1.0 ontology and migration adapters
• MCP gateway, helper, and index changes required by the RFC
• automated fixture suites and first-ART validation evidence
• docs and acceptance-gate updates for the v1 line

v1.x-dev merges to v1.x-pre-release for each prerelease. At general availability, create v1.x-release from the selected prerelease state, validate and tag there, then merge it into main. v0 follows the same development-to-release-to-main pattern. Security fixes and dependency bumps may flow between lines when needed; feature work does not automatically backport.

Historical-page convention

Every page below this section is reviewed against alpha.5, but several pages describe a target gate or the reasoning that preceded implementation. Treat the labels as follows:

• Implemented means executable code and release evidence exist.
• Partial means a safe subset exists and the remaining behavior is named.
• Planned means the page is a design contract, not a supported command.
• Historical means the page records an earlier alpha planning stage.

1.2.1 - Issue #135 Implementation Review

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.

Coverage Matrix

What Users Can Rely On

• exact local and immutable published release inputs;
• checksum and Ed25519 verification;
• a non-mutating deterministic plan;
• transactional install and update with persisted ownership;
• recovery after interrupted installer transactions;
• conservative uninstall that preserves changed or user-owned files;
• installed-provenance verification;
• Codex and Claude managed-key projections;
• Python MCP operation from the extracted package;
• versioned machine request/result envelopes for integrators;
• mixed-root v0 migration with replay-safe evidence; and
• reproducible, hash-locked Python runtime dependencies.

What Users Must Not Assume

• native semantic corpus migration, package, or harness commands;
• removal of Python or uv as runtime dependencies;
• in-place mutation of an existing v0 source tree; or
• GA stability of alpha contracts.

Extracted GA Follow-ups

1. #165: trusted four-platform release distribution
2. #167: v0 mixed-root baselines and CLI/aibox parity
3. #168: generated CLI, release, and Rust API documentation
4. #170: runtime dependency locking and host-health coverage

Alpha.5 completes the trustworthy native lifecycle around visible content and the Python MCP runtime. Issue #165 remains the publication gate; the other three follow-ups are complete.

1.2.2 - Acceptance Gate

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.

RFC Cutover Gate

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.

The local release-candidate proof is executable through uv run scripts/smoke-test-servers.py. Its final first-ART RC acceptance matrix binds the production-shaped scenario to planning, execution, evidence, and inspect-and-adapt outcomes. Package smoke runs the same matrix against the staged release tree.

Detailed RFC Criteria

The detailed list below expands the RFC gate into checkable criteria for planning and implementation. Criteria marked soft may be waived with a recorded rationale. All other criteria are strict.

P0 - Pre-conditions

O1 - Ontology Completeness

T2 - Tooling Parity

C3 - Corpus Migration

S4 - Skills And Agents

A5 - First-ART Validation

G6 - Cutover Decision Point

R7 - Post-cutover Stabilisation

Alpha Gate

Alpha is ready when:

• the alpha ontology subset is documented
• schemas are generated and committed
• MCP create/read/transition paths work for alpha entities
• query_by_interface works for at least one shared interface
• strict and tolerant validation modes are observable
• a small v0.x corpus migrates or maps into the alpha model
• processkit-native fixture tests pass without depending on aibox
• one real process cycle runs through the alpha
• OKF export produces a conformant bundle
• docs build locally

Beta Gate

Beta is ready when:

• the implemented beta inventory targets approximately 60-70% of the 89-concept ontology (roughly 54-62 concepts), with explicit exclusions; this directional coverage target complements rather than replaces the capability and evidence criteria below
• the ontology has expanded beyond the alpha subset with migration proof
• all migrated kinds validate strictly
• core MCP tools have stable signatures
• MCP Python signatures match draft-2020-12 JSON Schemas
• docs cover user workflows and architecture
• pk-doctor checks the important invariants
• pk-doctor passes a golden adversarial fixture
• each actionable finding names an installed tool with compatible arguments or a recognized policy, migration, archive, or external disposition
• runtime integration examples exist
• OKF import and export are both tested
• human review and approval workflows are represented

Release Candidate Gate

Release candidate is ready when:

• schema generation is deterministic
• migration tools are repeatable
• doctor remediations execute through the shipped gateway and recheck cleanly
• acceptance fixtures cover adversarial cases
• docs, examples, and publishing scripts are stable
• a real project has run a full planning and delivery cycle
• package smoke tests pass from release artifacts without aibox
• no known blocker remains for v1.0.0 cutover

Final Gate

v1.0.0 is ready when:

• the cutover decision is recorded
• the final ontology and migration plan are accepted
• docs are published
• release artifacts are reproducible
• downstream projects have a supported adoption path
• v0.x maintenance and v1.x development boundaries are documented

1.2.3 - Alpha Release Testing

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.

Pre-tag Gate

Run from a clean v1.x-pre-release worktree:

uv run scripts/generate-v1-schemas.py --check
uv run scripts/smoke-test-servers.py
uv run scripts/smoke-test-package.py
scripts/check-docs-local.sh
uv run scripts/generate-mcp-manifest.py --check
scripts/test-installer-local.sh

Also run pk-doctor and the release audit. The release build must validate the committed MCP manifest and must not rewrite tracked release metadata.

Standalone Pilot

Create a local signing key once, then build the complete release set:

scripts/processkit-keygen-local.sh release.pem release.pub.pem
scripts/release-local.sh \
  v1.0.0-alpha.5 release.pem release.pub.pem

The signed envelope binds the archive, native installer executable, target triple, version, and trusted key. Verify it independently:

scripts/verify-release-local.sh \
  dist/processkit-v1.0.0-alpha.5.release.json \
  dist/processkit-v1.0.0-alpha.5.release.sig \
  release.pub.pem

Run the native executable against a disposable project through its opaque request contract. The local installer suite covers install, verify, update, recovery, user-drift handling, and uninstall. It neither invokes aibox nor uses GitHub Actions or another hosted build service.

The suite includes two complementary recovery signals:

• the full shipped distribution completes install/update/uninstall lifecycle acceptance; and
• a compact signed-layout fixture sets PROCESSKIT_INSTALLER_FAIL_AFTER_ACTION=0, proves exit 75 and a durable journal, runs native recovery, verifies the exact old state and project-owned file, retries the update, and verifies the new provenance.

Run that focused acceptance independently with:

scripts/test-update-recovery-local.sh

An aibox pilot may consume the exact signed prerelease afterward. That is a downstream compatibility check and never blocks or defines processkit release correctness.

Promotion

Promote the next alpha only from a new merge into v1.x-pre-release. Alpha tags are immutable. The supported v0 line remains the default until the final CLI and migration path have passed joint processkit/aibox testing.

1.2.4 - Alpha Scope

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.

All 18 schemas are generated from the registry. Risk and Scope are discriminator overlays, while TeamMember and Migration are compositions of their prerequisite interfaces.

Required Capabilities

• Generate schemas for the alpha kinds.
• Create and transition entities through MCP tools.
• Query entities by ID, text, relation, and interface.
• Preserve structured LogEntries.
• Migrate a small v0.x corpus.
• Export a conformant OKF bundle.
• Publish the docs site locally and through GitHub Pages.
• Run automated fixture tests without requiring aibox.
• Run one real process cycle through the new model.

Out Of Scope

• Full 89-concept implementation.
• Complete migration of every historical entity.
• Runtime-specific orchestration.
• Vector database integration.
• Public package stability guarantees.

Alpha Proof

The alpha is successful when:

• a real work item moves from capture to completion
• at least one decision is recorded and linked
• artifacts and notes are attached as supporting evidence
• a gate or approval is represented
• event history is queryable
• an agent can retrieve the relevant context through MCP
• OKF export passes v0.1 conformance
• processkit-native tests pass without aibox
• a human can inspect the same state in files and docs

Promotion Gates

Alpha promotion additionally requires:

• deterministic regeneration produces no diff
• every generated schema is valid JSON Schema draft 2020-12
• the representative fixture validates and indexes all declared interfaces
• discriminator identity survives indexing
• source and packaged context trees remain in sync
• the docs site, server smoke suite, and release audit pass

1.2.5 - Alpha.3 Closure Plan

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.

Alpha.3 closes the pre-cutover implementation work:

1. complete the 89-concept ontology and 70 executable schema contracts;
2. provide operational MCP, index, transition, and event parity;
3. migrate representative manual-v0 and aibox-managed corpora;
4. execute the retained agent-scenario and first-ART suites;
5. finish installer planning, structured reconciliation, security, and Codex/Claude parity;
6. validate the exact release artifact in a bare aibox container; and
7. publish reproducible, signed, exact-pinnable release assets.

The G6 owner decision and every R7 criterion remain outside alpha.3 because they require an actual cutover and post-cutover observation.

1.2.6 - Analysis Archive

These documents preserve the reasoning that led to the current v1.0 planning set.

• Base Context
• Concept Mapping Briefing Analysis
• processkit v1.0 RFC Analysis
• OKF Compatibility Analysis
• Start Assessment

1.2.6.1 - Concept Mapping Briefing Analysis

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.

Executive Read

The document starts as a reconciliation exercise: preserve processkit’s closed primitive set and map missing concepts onto fields, sub-kinds, or Binding types. It does not stay there.

By the later rounds, the recommendation has shifted to a greenfield ontology for a new processkit version:

• keep the processkit target from the v0.x line
• replace the old “small closed primitive set plus many special cases” model with a richer orthogonal ontology
• promote several abstract parents to first-class atomic primitives
• model domain terms through discriminators and compositions
• support large agent-heavy organizations by making vocabulary explicit enough for agents to reason over

The most important sentence operationally is in Round 16: for a 10-human, many-agent company doing roughly 500-person work, the document recommends going full greenfield.

Relationship To Base Context

The briefing preserves these base-context invariants:

• processkit remains provider-neutral and harness-neutral
• project memory remains structured, versioned, and agent-readable
• repository-local process data remains the source of truth
• migrations remain explicit
• rich skills and MCP tooling remain part of the product
• old context/ dogfood history is evidence, not a payload to ship

It challenges these base-context assumptions:

• the current v0.x primitive set is no longer treated as the likely target
• current schemas are evidence, not constraints
• “no new primitives” is rejected by later rounds
• kind= discriminators alone are insufficient for the greenfield model
• composition support becomes load-bearing

The base context says “do not change the product target.” This briefing does not change the target. It changes the ontology and implementation strategy for reaching that target.

Evolution Inside The Document

The early section says:

• zero new primitives required
• keep the closed primitive set
• add fields, known_kinds, known_types, and Binding kinds
• use an editorial Content / Structure / Governance framing

The middle rounds add:

• a fourth level: Specification / Type / Meta
• a cross-cutting Relation stratum
• explicit Definition / Instance / Record thinking, then later simplify back to level-only organization
• a class column:
  • T: terminology only
  • P: primitive
  • D: discriminator on a parent primitive
  • C: composed schema

The late rounds settle on a greenfield-corrected cut:

• parent concepts such as Record, Specification, Container, Policy, Event, and Capability become atomic primitives
• children such as DecisionRecord and LogEntry become compositions under Record
• some grammar-level concepts are dropped as too low-level
• the greenfield model is judged sufficient for SAFe-style scaling

This means the final recommendation should be read from Rounds 13-17, not from the opening “zero new primitives” finding.

Final Ontology Shape

The final stable shape in the document has five levels:

• Specification / Type / Meta
• Content
• Structure
• Governance
• Relation

It classifies concepts by four implementation classes:

• T: concept only, no schema
• P: atomic primitive with its own YAML schema
• D: discriminator variant on a parent primitive
• C: composed schema assembled from primitive blocks

Round 14/15 reports:

• 35 foundational concepts
• 47 specifics
• 82 concepts total
• 21 primitives
• 19 discriminators
• 23 compositions
• 19 terminology concepts

The very last delta table also says Round 14 drops from 87 to 81 concepts after removing six grammar-leak concepts. This conflicts with the Round 14/15 total of 82 because Round 15 adds Uniqueness. For future work, treat the effective final count as 82 unless newer input clarifies otherwise.

The RFC is that newer input. The current processkit v1.0 target is 89 concepts: 19 T, 22 P, 24 D, and 24 C.

Candidate Atomic Primitives

The greenfield model’s important P candidates are:

Specification / Type / Meta:

• Specification

Content:

• Artifact
• Capability
• Command
• Discussion
• Message
• Note
• Proposition
• Queue
• Record
• Resource
• Token
• WorkItem

Structure:

• Actor
• Channel
• Container
• Role

Governance:

• Event
• Gate
• Policy

Relation:

• Binding

Some of these overlap with old processkit primitives. Others are new or promoted from concepts previously represented by fields, sub-kinds, or runtime behavior.

Major Reclassifications

The biggest conceptual shift is parent promotion:

• Record becomes primitive; DecisionRecord, LogEntry, Measurement, Outcome, and Archive become Record-derived forms.
• Container becomes primitive; Scope becomes a composition or specific container form.
• Specification becomes primitive; schema, process, role, gate, schedule, goal, service, channel, queue, and test specifications become composed specifications.
• Policy becomes primitive instead of being represented only through Artifact + Binding + Gate composition.
• Event becomes primitive and pairs with Command.
• Proposition becomes primitive and absorbs Belief, WorldFact, and Risk as discriminator variants.
• Capability becomes primitive and absorbs Skill, Authority, and Service as specific forms.
• Binding remains primitive, but Hierarchy, Position, Correlation, and Provenance become Binding variants.

These changes are incompatible with simply importing v0.27.1 schemas. They require a deliberate model redesign.

Load-Bearing Design Decisions

The document creates several decisions that should be confirmed before implementation:

1. Adopt full greenfield ontology rather than incremental v0.27.x evolution.
2. Treat Round 14/15 as the baseline cut, subject to newer inputs.
3. Use 5 levels: Specification / Content / Structure / Governance / Relation.
4. Use T/P/D/C classification to decide storage shape.
5. Promote Record, Specification, Container, Event, Policy, Capability, Proposition, Command, Message, Queue, Resource, Token, and Channel.
6. Demote old first-class children such as DecisionRecord and LogEntry to composed Record forms in the greenfield model.
7. Keep Binding as the relation primitive and express hierarchy, provenance, position, and correlation as Binding variants.
8. Use Proposition as the shared parent for belief, fact, and risk.
9. Demote Service to a Capability-specific composition, unless newer SOA-oriented input reverses that.
10. Keep spatial/location and BFO disposition out of the core model.

The RFC supersedes item 10: Location is now a primitive and Capability{kind=disposition} is explicitly included.

None of these should be silently encoded as implementation work without a current confirmation pass, because the briefing is dated.

Composition Strategy

The document rejects a false binary between duplicated flat schemas and runtime $ref.

Recommended path:

1. Start with Option 8: runtime-only composition. Schemas may duplicate initially, while tests and polymorphic query behavior enforce shared interfaces.
2. Evolve toward Option 3: build-time generation. Source uses composition; generated runtime schemas are flat YAML.
3. Keep Option 7 available: extends: annotation with a lightweight loader.

The RFC supersedes this staged path. processkit v1.0 should use build-time Jinja + YAML schema generation from the start, with committed _generated/*.yaml output.

Scaling Argument

The document tests the model against:

• 10 humans plus agents doing roughly 500-person work
• 100 humans plus agents doing roughly 5000-person work
• SAFe / ART / portfolio structures

Its conclusion:

• today’s model is too weak for this
• a reduced model improves agentic workflows but under-models cadence, channel, policy, and goal vocabulary
• the greenfield model reaches near-complete SAFe modelling capability
• further 10x scale does not require new concepts

The remaining scale problems are engineering and governance:

• composition tooling
• indexing and search
• federation
• throughput
• bulk operations
• interpretation drift
• agent training on canonical meanings

This strongly implies that processkit v1.0 should invest early in indexing, composition tests, and canonical ontology documentation.

Questions Resolved By The RFC

The document left these unresolved or only implicitly resolved. The RFC now settles them for processkit v1.0:

• Position is Binding{kind=role-slot} with nullable subject.
• Belief, WorldFact, Risk, and WSJF-estimate sit under Proposition.
• Service is S(Capability)/C, not a primitive.
• Hierarchy remains a named concept implemented as Binding{kind=parent-child}.
• Location is a primitive with five discriminator variants.
• Capability{kind=disposition} is included.
• The final concept count is 89, not 81 or 82.
• The RFC supersedes Round 14/15 where they conflict.

Implications For processkit v1.0 Build-Up

The new project should not start by copying the old src/context/ schemas wholesale. The better path is:

1. Preserve the product target and release discipline from the first version.
2. Treat old schemas, skills, and MCP servers as implementation evidence.
3. Define the greenfield ontology contract first.
4. Decide the first-phase primitive set and class assignment.
5. Create schema-generation or runtime-composition policy.
6. Build minimal tooling around the new primitives:
   • ID generation
   • schema validation
   • state transitions
   • entity index
   • relation queries
   • migrations
7. Port or rewrite skills after the new ontology is stable.
8. Use migration adapters to ingest old-processkit context where needed.

The first implementation milestone should be a thin vertical slice, not the whole ontology:

• one or two Specification forms
• Record
• WorkItem
• Binding
• Container or Scope
• Event / Command
• index and validation support

Then expand through compositions and discriminators.

Risks

• The document is internally inconsistent because it records an evolving discussion, not a single final spec.
• It references companion Notes and Decisions that are not present in this new repository.
• It was produced before later project learning, so its final recommendation may be superseded.
• Going full greenfield creates a migration burden from processkit v0.x.
• Composition tooling can become a project inside the project.
• Agents may benefit from rich vocabulary, but humans may find the ontology too abstract without good docs and examples.

What The RFC Resolves

The later RFC answers the briefing’s implementation questions:

• The intended baseline is the RFC’s 89-concept T/P/D/C ontology.
• v1.0 is a greenfield rebuild with migration/import bridges from v0.x.
• The composition mechanism is build-time Jinja + YAML generation.
• SAFe / many-agent scaling remains the main ontology pressure.
• The first deliverable is a phase-gated alpha built around ontology completeness and tooling parity.

Working Interpretation

Until newer input says otherwise, use this as the working direction:

processkit v1.0 should preserve processkit’s product promise but rebuild the core model around the RFC’s greenfield 89-concept ontology. The old project is evidence and migration source, not a schema constraint. Implementation should follow the RFC’s build-time schema generation, interface-aware indexing, and 81-criterion gate.

1.2.6.2 - OKF Compatibility Analysis

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.

What OKF Is

OKF v0.1 is a deliberately small knowledge-bundle format:

• a directory tree of UTF-8 markdown files
• YAML frontmatter at the top of every concept document
• type as the only required frontmatter key
• optional title, description, resource, tags, and timestamp
• file path, minus .md, as the concept ID
• normal markdown links as graph edges
• optional index.md files for progressive disclosure
• optional log.md files for chronological history
• permissive consumers that tolerate missing optional fields, unknown types, unknown keys, broken links, and missing indexes

The announcement frames OKF as a vendor-neutral, agent- and human-friendly standard for exchanging metadata, context, and curated knowledge. It explicitly says OKF is a format, not a platform or service.

Fit With processkit Goals

OKF strongly aligns with several processkit goals:

• plain files over service lock-in
• git-native review, diffs, history, and distribution
• human-readable and agent-readable knowledge
• provider-neutral consumption
• markdown plus YAML frontmatter
• progressive disclosure through indexes
• graph navigation through links

This means OKF is strategically relevant. It is close enough to processkit’s existing shape that ignoring it would create unnecessary interoperability debt.

Limits And Mismatches

OKF is intentionally less strict than processkit needs to be.

Key mismatches:

• OKF has no fixed taxonomy; processkit v1.0 is explicitly building a typed ontology with T/P/D/C classes.
• OKF treats type values as unregistered strings; processkit needs schema-backed kinds, discriminators, and interfaces.
• OKF concepts are identified by bundle-relative paths; processkit uses stable entity IDs and may move storage paths as an implementation detail.
• OKF links are untyped and their relationship meaning lives in prose; processkit needs typed Bindings, explicit relations, lifecycle transitions, and queryable graph semantics.
• OKF requires permissive consumption of broken links and unknown fields; processkit needs strict validation for migrated kinds and controlled tolerant validation during migration.
• OKF log.md is prose history; processkit LogEntry entities are structured, append-only process evidence.
• OKF reserves lowercase index.md and log.md; processkit has richer index, schema, migration, and event-log machinery that should not be collapsed into those two files.

There is also a reference-implementation/spec mismatch: the v0.1 spec says only type is required for conformance, while the checked-in reference agent’s OKFDocument.validate() currently requires type, title, description, and timestamp. For processkit, the spec should be treated as normative and the reference implementation as an example producer profile, not as the compatibility contract.

Compatibility Model

The right compatibility model is a projection layer:

processkit canonical entities
  -> OKF exporter
  -> conformant OKF bundle

OKF bundle
  -> OKF importer
  -> external-source Artifacts / Notes / indexed knowledge

The canonical v1.0 system should keep:

• generated schemas and validation modes
• entity IDs
• lifecycle state machines
• typed relations and Bindings
• interface-aware queries
• event logs
• MCP tools as the write path

The OKF layer should provide:

• read-only exports for external consumers
• lossy-but-useful imports of external OKF knowledge
• optional round-trip preservation of unknown OKF frontmatter
• generated index.md files for exported bundles
• generated log.md files only as human-facing summaries, not as the source of truth for process events

Proposed v1.0 Requirements

Add an “OKF compatibility” acceptance slice to the v1.0 plan:

1. Define a processkit OKF exporter profile.
2. Map each exported processkit kind to an OKF type.
3. Include title, description, timestamp, and tags wherever available, even though only type is required by OKF.
4. Preserve processkit IDs in an extension key such as processkit_id.
5. Preserve processkit kind/interface metadata in extension keys such as processkit_kind and processkit_interfaces.
6. Encode typed relations in extension frontmatter, while also emitting normal markdown links for generic OKF consumers.
7. Generate conformant index.md files for progressive disclosure.
8. Treat log.md as an optional generated changelog summary.
9. Provide an OKF validator mode that checks v0.1 conformance.
10. Provide an OKF importer that marks imported knowledge as external and does not pretend it has full processkit lifecycle semantics.

Decision Guidance

Adopt OKF compatibility if it remains a boundary format.

Do not adopt OKF as the internal canonical model unless the OKF specification evolves to cover typed relations, lifecycle semantics, stable non-path IDs, validation profiles, and structured event history. That would be a different standard from OKF v0.1.

The safest wording for the v1.0 roadmap is:

processkit v1.0 SHOULD be able to produce and consume OKF v0.1 bundles, while retaining processkit’s stricter canonical schema, lifecycle, relation, and MCP semantics internally.

1.2.6.3 - processkit v1.0 Base Context

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.

Current Guiding Briefing

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

Conflict rule:

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

Current Repository Status

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

• aibox.lock pins upstream processkit to v0.27.1.
• aibox.toml enables the processkit core/managed skill surface.
• The workspace currently has no src/, docs-site/, or implementation source tree.
• Indexed processkit entities for WorkItems, DecisionRecords, Discussions, and Artifacts are currently empty in this project.
• GitHub auth was available for repository status checks.

Session-start process checks were run before this document was created. The pending aibox.lock backfill migration MIG-LOCK-20260703T161218 was applied through migration-management. After that, active migrations were zero.

pk-doctor still reports setup drift that should be tracked separately:

• missing scripts/check-src-context-drift.sh
• missing TeamMember tier directories for cora and thrifty-otter
• missing Claude sub-agent export for cora
• stale MCP manifest / server-header / preauth metadata
• one applied migration that is now an archive candidate

These findings are not part of the base-context target itself, but they are important when this repository starts growing source and release machinery.

Stable Product Target

The first processkit version defines processkit as:

provider-neutral process memory, skills, and MCP tools for agentic software projects.

The stable target should not change:

1. processkit is a versioned content and runtime layer for AI-assisted projects.
2. It gives agents and humans structured project memory through repository files, schemas, skills, state machines, and MCP tools.
3. It is provider-neutral and harness-neutral. Claude, Codex, OpenCode, Hermes, Aider, and other harnesses are integration targets, not core dependencies.
4. It is a process layer, not a replacement for a harness, runtime manager, issue tracker, or model provider.
5. It must remain usable manually, through MCP-capable harnesses, or via an external installer such as aibox.
6. It must remain forkable. Organizations can maintain private forks and downstream projects can consume those forks without changing their own structure.

The original PRD states the primary goal clearly: make it easy for any team to add a structured, agent-readable process layer to any repository.

Shipped Deliverable Boundary

The old project made a hard distinction between the processkit repository’s dogfooding context and the content shipped to consumers. This distinction is foundational and should be preserved.

src/ in the original repository is a literal mirror of a fresh consumer project root:

• src/AGENTS.md becomes <project>/AGENTS.md.
• src/context/ becomes <project>/context/.
• src/.gitignore.example is the recommended ignore template.
• src/.processkit/ is catalog tooling and package metadata; it is not installed into consumers as live project context.

The repository-root context/ in the old project is dogfood project state. It contains processkit’s own WorkItems, Decisions, Artifacts, logs, migrations, team state, and release history. That content must not be blindly mirrored into src/context/.

The release boundary guard from the original project explicitly allows dogfood-only directories under root context/ while forbidding them from shipping under src/context/. In src/context/, shipped Artifacts are model specs and model profiles only; dogfood Decisions, WorkItems, Discussions, Notes, Logs, Migrations, and Templates do not ship.

Consumer Usage Model

Consumers can use processkit manually or through a manager.

Manual use:

1. Download a versioned processkit release tarball.
2. Copy the shipped context/, .processkit, and AGENTS.md into the consuming project.
3. Configure the harness to launch processkit-gateway, or launch individual per-skill MCP servers.

aibox-assisted use:

1. aibox.toml pins [processkit] source, version, and src_path.
2. aibox fetches the source release, installs selected package tiers, and records aibox.lock.
3. aibox may configure or supervise runtime files, but processkit remains the standalone source for schemas, skills, packages, and MCP runtime.

The old README names three MCP layouts:

• processkit-gateway: preferred provider-neutral entry point.
• Per-skill MCP servers: canonical granular compatibility surface.
• aggregate-mcp: legacy compatibility bridge.

The gateway is additive. It must not replace per-skill servers as the canonical validation and compatibility surface.

Package Tiers

The original package model has five tiers:

• minimal: foundation for solo developers and small side projects.
• managed: recommended default for small teams with backlog and process cadence.
• software: managed plus architecture, infrastructure, security, performance, database, and observability skills.
• research: managed plus data, ML, AI, and research-authoring skills.
• product: software plus design, framework, product, and broader end-to-end product-development skills.

Packages compose through spec.extends; consumers can add or remove specific skills through config overrides.

Entity and Contract Model

The stable entity model is Markdown files with YAML frontmatter:

• apiVersion
• kind
• metadata
• spec
• body content where appropriate

The v2 direction is intentionally breaking and explicit. The historical decisions rejected long-term v1/v2 compatibility shims. v1 contexts are migration sources; after migration, v2 schemas and index semantics are authoritative.

Important v2 contract points:

• Unknown kinds, stale primitive assumptions, and ad hoc event/type vocabulary should fail validation.
• Metric, Model, Process, Schedule, and StateMachine are legacy v1 migration-source kinds, not shipped v2 entity primitives.
• Process definitions are Artifacts plus process-instance WorkItems.
• Schedule semantics use Binding(type=time-window).
• Runtime state-machine YAML files are implementation contracts, not user-authored StateMachine entities.
• Hook inbox items are Notes with spec.inbox.
• Agent cards and security policies are Artifact-backed projections.
• Eval gates produce eval-spec Artifacts, paired Gates, policy/application Bindings, and calibration LogEntries.

MCP and Indexing Principles

The old project converged on these operational rules:

• Agents read entities through index-management, not raw filesystem scraping.
• Agents write entities through management MCP tools so schema validation, state-machine enforcement, index updates, and event logs happen consistently.
• index-management is the read-side foundation.
• id-management is the write-side ID foundation.
• Entity search uses SQLite FTS5, with optional sqlite-vec semantic search and hybrid search.
• Broad health checks and release checks should return structured JSON so agents can route findings instead of re-parsing prose.

The original release had 30 MCP server files under src/context/skills. Most are processkit management servers; one additional shipped server was devops/repo-management.

Provider and Model Neutrality

Provider neutrality is a core invariant, not a convenience.

The old decisions establish:

• processkit skills, commands, MCP tools, and doctor findings must not require or invoke aibox host commands from inside derived project containers.
• aibox and other managers may install, supervise, or provide runtime signals, but processkit remediation surfaces stay generic.
• Role and TeamMember model assignments bind to provider-neutral Artifact(kind=model-profile) artifacts by default.
• Concrete Artifact(kind=model-spec) artifacts may encode provider and model names because they describe real provider models.
• Runtime access gates expand profiles into concrete candidates.
• Direct Role/TeamMember bindings to concrete ModelSpec artifacts are explicit pins or compatibility cases.

This is the design line that lets a processkit project move between Codex, Claude Code, Gemini CLI, Aider, Cursor, Copilot, OpenCode, Hermes, and future harnesses without rewriting its process memory.

Team and Role Model

The old project introduced persistent TeamMembers, Roles, RoleSlots, and Bindings to support repeatable multi-agent collaboration:

• Roles define responsibilities.
• TeamMembers represent named humans or AI personas.
• Bindings connect actors, roles, model profiles, scopes, and other addressable surfaces.
• RoleSlots decouple identity and capacity planning from concrete people or model invocations.
• Sub-agent dispatch should route through route_task first and use the recommended TeamMember/model class when available.

The workspace had processkit TeamMember remnants from installation, but pk-doctor reported missing tier directories and one missing Claude sub-agent export. Treat that as setup hygiene, not as the future team model.

Release and Migration Model

The first processkit version treated releases as deliberate versioned content, not silent syncs.

Stable release expectations:

• src/PROVENANCE.toml maps shipped files to the tag where each last changed.
• scripts/processkit-diff.sh compares tagged versions and classifies added, removed, changed, and unchanged files.
• Installers write explicit Migration documents for upgrades.
• Users and agents review migrations before applying them.
• Migration flow is pending -> in-progress -> applied.
• Release tarballs are built reproducibly from src/.
• Release packaging runs a release-boundary guard, release audit, provenance freshness check, MCP preauth validation, and checksum generation.

The old release process guarded against a known failure mode: dogfood context had changed while src/context/ did not receive corresponding shippable changes. The new version should preserve a guard that makes that drift visible.

Documentation Surface

The first version had two user-facing documentation surfaces:

• root docs such as docs/harness-claude-code.md
• Docusaurus docs under docs-site/

The most important stable docs topics are:

• installation and harness setup
• package tiers and skill catalog
• API version policy
• migration model
• v2 contracts
• ID formats
• privacy tiers
• gateway and MCP layouts

At the time of capture, the workspace did not yet have the current Docusaurus development section. Treat that statement as historical.

Current Gap Summary

Compared with the original processkit repository, this project currently has:

• processkit runtime context installed under root context/
• aibox config and lock data
• devcontainer/runtime scaffolding
• this base-context document

It does not yet have:

• src/ deliverable tree
• src/context/ schemas, state machines, skills, model artifacts, roles, bindings, and TeamMember defaults
• package definitions under src/.processkit/packages
• release scripts and verification scripts
• docs-site user documentation
• changelog, contribution guide, or release packaging flow
• processkit v1.0-specific WorkItems, Decisions, or Artifacts describing the rebuild roadmap

Base-Context Readiness Audit

This first phase is complete enough for the next briefing document.

Open items are intentionally deferred until the incoming briefing is reviewed:

• creating processkit v1.0-specific WorkItems or DecisionRecords
• choosing which old skills or runtime code to import versus redesign
• rebuilding src/, docs-site/, release scripts, or MCP runtime code
• resolving unrelated installed-context hygiene findings from pk-doctor

Improvement Surface for Later Briefing

The next briefing can change how the new implementation is built, but it should do so against these preserved targets:

• keep processkit provider-neutral and host-orchestrator-neutral
• keep the shipped deliverable boundary explicit
• keep entity writes validated through MCP, not hand-edited context files
• keep migrations explicit and reviewable
• keep gateway additive rather than replacing per-skill canonical servers
• keep model routing provider-neutral through profiles
• keep docs and release checks first-class
• keep dogfood project context separate from consumer deliverables

Likely redesign areas for processkit v1.0:

• simplify the source layout without losing the consumer mirror invariant
• reduce prompt/runtime overhead of the skill and MCP surfaces
• make package selection and command projection easier to reason about
• strengthen release and migration tests from the start
• define processkit v1.0-specific WorkItems/Decisions after the incoming briefing document is reviewed
• decide whether to import, regenerate, or redesign each old skill family rather than copying the whole first-version catalog wholesale

Evidence Index

Primary evidence from the original repository:

• README.md: product promise, install model, MCP layouts, current status
• ART-20260409_1854-KindCrane-processkit-product-requirements-document: original approved PRD
• src/INDEX.md: shipped deliverable boundary and mirror invariant
• src/.processkit/packages/*.yaml: package tiers and composition
• docs/harness-claude-code.md: harness behavior and compliance payloads
• docs-site/content/en/docs/reference/apiversion-policy.md: apiVersion rules
• docs-site/content/en/docs/reference/migration.md: migration model
• docs-site/content/en/docs/reference/v2-contracts.md: v2 entity rules
• docs-site/content/en/docs/reference/id-formats.md: ID format policy
• docs-site/content/en/docs/reference/privacy.md: privacy tiers
• src/context/skills/processkit/processkit-gateway/SKILL.md: gateway architecture
• src/context/skills/processkit/index-management/SKILL.md: read-side index foundation
• scripts/check-src-context-drift.sh: release boundary guard
• scripts/build-release-tarball.sh: release packaging flow
• scripts/smoke-test-servers.py: MCP smoke workflow

High-signal historical decisions:

• DEC-20260430_1416-SmoothTiger-adopt-breaking-v2-implementation-plan-for
• DEC-20260501_1739-ProudCrane-adopt-smoothtiger-informed-split-track-v2
• DEC-20260502_0743-CoolFjord-adopt-provider-neutral-processkit-gateway-daemon
• DEC-20260503_1829-LoyalComet-route-roles-and-team-members-through
• DEC-20260515_1232-GentleLantern-keep-processkit-host-orchestrator-neutral

1.2.6.4 - processkit v1.0 RFC Analysis

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.

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

The RFC’s operational direction is:

• full greenfield ontology rebuild
• 89 concepts in T/P/D/C classes
• Jinja + YAML schema composition
• committed build-time _generated/ schemas
• new regenerate_schemas MCP endpoint
• interface-aware polymorphic queries
• strict/tolerant per-kind validation during migration
• 9-12 month rebuild on a v1.0 branch
• alpha, beta, rc, final pre-release progression
• 81-criterion cutover gate before v1.0.0

Authority And Evidence

The RFC cites:

• DEC-DeepTide: rebuild authorization
• DEC-BraveAtlas: 81-criterion cutover gate
• DISC-BriskWillow: 20-round ontology discussion
• upstream issues #74 and #75 as pk-doctor reliability evidence

Those DEC/DISC entities are not indexed in this new repository, so they were not locally verifiable through processkit MCP.

I also checked the private projectious-work/internal repository as an external evidence source:

• origin/main 44704b451d4baa53d04eb0e53c1bc01a41f6627e (2026-05-16T20:18:07+02:00)
• origin/policy-primitive-trigger-reeval-2026-06-29 8197000d5951ae5e5303e6f2ca868d9f7b4e9ad9 (2026-06-29T07:05:29Z)

That repository verifies DISC-BriskWillow at context/discussions/ DISC-20260515_1955-BriskWillow-is-hierarchy-a-primitive-are-higher.md. The discussion is active, supersedes the earlier DISC-OpenPanda record, and carries forward the hierarchy / abstraction-level question. It also says the proposed decision was leaning toward editorial three-level framing without new primitives or schema migration, with hierarchy remaining composable through existing parent / Scope / Role / Binding shapes.

The same internal repository did not contain DEC-DeepTide or DEC-BraveAtlas by filename, ID token, or all-history search on the available branches. The June branch only adds tmp/policy-primitive-trigger-reeval-2026-06-29.md, which corroborates that DISC-BriskWillow is a live non-Policy primitive-admission question but does not provide the missing RFC decision records.

Treat the RFC as the authority because the user explicitly selected it as the guiding document. Treat DEC-DeepTide and DEC-BraveAtlas as unresolved external provenance to be imported, recreated, or replaced by new local decision records before irreversible implementation cutover.

What Supersedes The Earlier Concept Mapping

The earlier analysis treated Round 14/15 as the likely baseline and noted open questions. The RFC closes or changes several of those points.

The RFC now says:

• final ontology count is 89 concepts, not 81/82
• Location is a new primitive
• Skill is a primitive, not a composition
• TeamMember is a composition, not Actor{kind=team-member}
• Service is S(Capability)/C, not a primitive
• Position is Binding{kind=role-slot} with nullable subject
• Location has five discriminator variants
• Capability{kind=disposition} settles the disposition question
• build-time Jinja + YAML composition is the preferred mechanism
• _generated/ output is committed
• processkit v1.0 should be built upstream on a v1.0 branch, not only in this derived repo

Any earlier note saying “confirm this later” should be read as resolved when the RFC makes a concrete settlement.

Ontology Direction

The current v0.x 13-primitive ontology is rejected as insufficient. The RFC says it cannot cleanly model AI-first SAFe execution at 100x5000 scale without both:

• missing first-class concepts, and
• grammar concepts leaking into the entity layer

The intended v1.0 ontology uses four concept classes:

• T: foundational terminology or meta-mechanic, no own lifecycle
• P: atomic primitive with schema, lifecycle, and persistence
• D: discriminator variant of a primitive
• C: composition of primitives and terminology fragments

Final RFC counts:

• T: 19
• P: 22
• D: 24
• C: 24
• total: 89

Key Primitive Settlements

The RFC explicitly calls out these settlements:

• Proposition is a new primitive. It is the parent for Belief, Risk, WorldFact, WSJF-estimate, and related epistemic content.
• Location is a new primitive, with discriminator variants for geographic region, site, coordinate, logical region, and timezone.
• Skill is a primitive with its own schema and lifecycle, distinct from Capability.
• Capability remains a primitive; Service is composed from Capability.
• TeamMember becomes a composition of Actor plus calendar, capabilities, persona, skill list, and journal.
• Position is a Binding variant with nullable subject.
• Hierarchy remains named for mental anchoring but is implemented as Binding{kind=parent-child}.

These are guiding decisions for processkit v1.0 unless later input supersedes the RFC.

Implementation Mechanics

The RFC rejects runtime $ref as the main solution and chooses build-time generation:

• schema sources live under schemas/src/
• Jinja templates render into flat _generated/*.yaml
• runtime tools consume _generated/
• _generated/ is committed to git
• composition uses extends: parent.yaml
• templates use {% include %} for T fragments
• merge behavior uses __merge: replace|concat|name-merge

This is more specific than the earlier “Option 8 first, Option 3 later” guidance. The RFC chooses the build-time path directly.

Required MCP endpoint:

regenerate_schemas(kinds: list | None) -> {rebuilt, unchanged, errors}

The same endpoint handles full and partial rebuilds. aibox apply triggers full rebuilds by default, with opt-out for fast iteration.

Validation And Indexing

Validation is phase-gated:

• migrated kinds: strict validation
• kinds still migrating: tolerant validation, warn but pass
• per-kind validation mode must be observable through MCP

Indexing extends the existing FTS5 surface rather than replacing it. Schemas declare interfaces:

interfaces: [Record, Versioned]

The required new query capability is:

query_by_interface(Record, ...)

This is load-bearing. The RFC identifies it as the fix for agent routing failures where agents have to choose between WorkItem, DecisionRecord, Artifact, LogEntry, and similar concrete kinds.

Branch And Release Model

The RFC proposes an upstream v1.0 feature branch:

• main continues v0.x.y maintenance
• v1.0 receives all greenfield rebuild work
• alpha, beta, rc, and final tags are cut from v1.0
• final cutover merges v1.0 into main and tags v1.0.0
• derived projects opt in by pinning aibox.toml to alpha/beta/rc tags

Backport policy:

• security fixes flow both ways
• dependency bumps flow at maintainer discretion
• feature work does not backport either way

This keeps the 9-12 month divergence bounded.

Cutover Gate

The RFC adopts an 81-criterion acceptance gate:

• 75 strict criteria
• 6 soft criteria
• 8 phases

Phases:

• P0: pre-conditions
• O1: ontology completeness
• T2: tooling parity
• C3: corpus migration
• S4: skills and agents
• A5: first-ART validation
• G6: cutover decision point
• R7: post-cutover stabilization

The most important proof phase is A5: model a real ART end to end and run one full PI cycle in the new ontology.

The RFC highlights these specific acceptance constraints:

• regenerate_schemas(kinds: list | None) MCP endpoint is required
• search must include FTS5 plus interface grouping
• canned query set must be signed off before rc
• all MCP tools need valid Python type signatures and matching draft-2020-12 JSON Schemas
• pk-doctor must pass a golden adversarial fixture

Upstream Asks

The RFC asks upstream maintainers for:

1. host the v1.0 feature branch upstream
2. endorse merge-to-main and v1.0.0 release model
3. accept the backport policy
4. name an upstream owner/contact
5. adopt DEC-BraveAtlas or counter-propose a release gate

It explicitly does not ask upstream for engineering capacity.

Timeline

Indicative timeline:

• months 1-2: composition tooling and first alpha
• months 3-4: parent promotion and migration scripts
• months 5-6: specification compositions plus Channel, Queue, Resource, Container; beta begins
• months 7-9: skills, MCP tools, doctor, indexer; beta to rc
• months 10-12: cutover and first ART on v1.0
• post-cutover: at least 14 days stabilization

The gate, not the calendar, decides release progress.

Risks

The RFC’s main risks:

• upstream rejects branch model
• single derived-project decider bottlenecks sign-off
• pk-doctor bugs hide failures
• corpus migration loses data
• agents drift into non-canonical interpretations
• long-lived main / v1.0 divergence becomes hard to merge

The RFC mitigates these through the RFC itself, DEC-BraveAtlas tracking, adversarial doctor fixtures, migration loss ceilings, agent scenario tests, and strict backport policy.

Implications For This Repository

For processkit v1.0, this RFC should become the primary planning baseline:

• do not build from the old v0.27.1 schema set
• do not follow the earlier 81/82-concept Round 14/15 interpretation
• use the RFC’s 89-concept shape as current guidance
• plan schema tooling before broad schema migration
• make interface-aware indexing a first-class requirement
• design validation modes before migrating live corpora
• treat pk-doctor rewrite/hardening as part of v1.0, not afterthought
• prepare for upstream-branch workflow or a fork fallback

The first concrete work products should be:

1. local copy of the RFC analysis and conflict rules
2. ontology inventory derived from the 89-concept RFC
3. phase-zero work plan for composition tooling
4. local representation of the 81-criterion gate
5. decision record for processkit v1.0 adopting this RFC as guidance

The fifth item should be recorded through processkit DecisionRecord MCP only after explicit acceptance, or when the user asks us to start planning work items.

Conflict Rule

If processkit-v1.0-rfc-draft.md conflicts with concept-mapping-2026-05-16.md, the RFC wins.

If the RFC conflicts with old processkit v0.27.1 implementation, the RFC wins for processkit v1.0 design, while v0.27.1 remains migration-source evidence.

If later user-provided input conflicts with the RFC, analyze that input explicitly and decide whether it supersedes this RFC.

1.2.6.5 - processkit v1.0 Start Assessment

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.

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

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

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

Why Start

The market is converging toward exactly the problems processkit is trying to solve:

• persistent agent context
• local and git-native knowledge
• markdown / frontmatter agent memory
• MCP tool interoperability
• durable work state
• human review and approval gates
• multi-agent role specialization
• observability, lineage, and auditability

The RFC’s core differentiators remain valid:

• schema-backed process entities
• lifecycle-aware WorkItems, Decisions, Discussions, Notes, Artifacts, Bindings, Gates, Skills, and Logs
• MCP write paths rather than ad hoc file edits
• typed relations instead of prose-only links
• provider-neutral model and role routing
• interface-aware search and query
• structured event history

No surveyed external project fully covers this combination.

Why Constrain The Start

The RFC’s 89-concept ontology is too large to treat as proven before implementation. It should be validated by usage.

The first alpha should answer:

• Does the new ontology reduce agent confusion in real work?
• Does query_by_interface improve routing and retrieval?
• Can existing v0.x history migrate without losing process evidence?
• Can agents create and transition entities reliably through MCP tools?
• Can humans still inspect and review the files directly?
• Can OKF export/import work without weakening internal semantics?

If those are not proven early, a larger rebuild will produce more schema surface without enough operational proof.

Concepts To Learn From

These external concepts should influence v1.0 without replacing processkit’s identity.

OKF: Boundary Format

Learn:

• minimal markdown + YAML interchange
• permissive consumers
• path-readable bundles
• generated index.md for progressive disclosure
• plain markdown links for generic graph consumers

Apply:

• OKF exporter and importer
• extension frontmatter preserving processkit IDs and kinds
• OKF validator mode
• generated OKF bundles for publication and exchange

Do not copy:

• path IDs as canonical IDs
• untyped relations as the only graph model
• prose log.md as authoritative event history

Basic Memory / LLM Wiki: Local-First Memory

Learn:

• agents work well with simple, readable markdown memory
• backlinks and lightweight entity extraction are useful
• user-owned files build trust
• MCP access to memory lowers integration friction

Apply:

• keep canonical files inspectable by humans
• improve indexes, backlinks, and local search ergonomics
• expose memory operations through MCP with clear tool metadata
• make agent write paths safe but still low-friction

Do not copy:

• free-form notes as the only data model
• weak lifecycle semantics

LangGraph / ADK / Microsoft Agent Framework: Runtime Boundaries

Learn:

• durable execution, pause/resume, and human-in-the-loop workflows are now table stakes
• agent runtimes increasingly support state, tools, telemetry, and multi-agent orchestration
• framework-specific orchestration changes quickly

Apply:

• make processkit easy for those runtimes to use
• define stable MCP tools for work, decisions, gates, and logs
• model approvals and interrupts as first-class process state
• provide runtime-neutral integration examples

Do not copy:

• agent loop orchestration
• provider-specific runtime assumptions

OpenAI Agents SDK: Handoffs, Guardrails, Tracing

Learn:

• handoffs need explicit target identity and task shape
• guardrails should be auditable process artifacts
• traces are valuable when debugging agent behavior

Apply:

• connect TeamMember / Role routing to handoff metadata
• model guardrails as Gates and policy Bindings
• map traces or summaries into structured LogEntries or Artifacts

Do not copy:

• SDK-specific session state as canonical project memory

Letta / Mem0: Memory Layering

Learn:

• long-term memory needs summarization, retrieval, and consolidation
• different memory layers serve different retrieval needs
• graph memory can improve multi-hop questions

Apply:

• separate fleeting notes, permanent artifacts, decisions, logs, and team-member memory
• add explicit promotion and consolidation workflows
• support graph-aware retrieval over typed entities and Bindings

Do not copy:

• opaque memory stores as the only source of truth
• personalization-first memory as the center of the project model

DataHub / OpenMetadata / Unity Catalog: Metadata Governance

Learn:

• catalogs win by combining metadata, lineage, ownership, search, quality, and governance
• typed metadata supports automation better than prose alone
• enterprise users expect lineage and ownership to be queryable

Apply:

• make ownership, source, provenance, and lifecycle queryable
• add lineage-style relations where process artifacts derive from one another
• expose health and quality checks through pk-doctor
• keep metadata extensible without losing validation

Do not copy:

• data-catalog scope as the core product
• centralized service dependency

OpenLineage: Faceted Extensibility

Learn:

• a small core model plus extension facets can scale across domains
• lineage events benefit from consistent naming and extensible metadata

Apply:

• consider facet-like schema extension points for v1.0 entities
• keep core fields stable while allowing typed extension payloads
• use event metadata to preserve provenance and causal relationships

Do not copy:

• run/job/dataset as processkit’s universal core model

OpenHands / SWE-agent / Copilot Agent / Aider: Coding-Agent Fit

Learn:

• coding agents need repository maps, task context, plans, tests, and review loops
• asynchronous agents need durable project state outside chat
• issue-to-PR agents benefit from clear acceptance criteria

Apply:

• make processkit the context substrate for coding agents
• export concise task briefs with related decisions and artifacts
• model acceptance criteria and verification as queryable fields
• preserve branch, PR, test, and review evidence in structured logs

Do not copy:

• code-editing agent behavior
• benchmark chasing as the project goal

Immediate Plan Improvements

Before full implementation, amend the v1.0 plan with these additions:

1. Add an OKF compatibility acceptance slice.
2. Add a one-project alpha proving a small ontology subset.
3. Define processkit’s runtime boundary explicitly.
4. Add a “not building” list: agent runtime, vector database, data catalog, OKF-only wiki.
5. Add provenance and lineage requirements.
6. Add handoff / approval / guardrail mapping to Roles, Gates, and Logs.
7. Add graph/backlink ergonomics for human and agent navigation.
8. Add migration proof for existing v0.x entities.
9. Add examples for LangGraph, ADK, OpenAI Agents SDK, and Microsoft Agent Framework as consumers.

Start Condition

Start once the first alpha slice is defined as a vertical proof:

• 10-15 highest-value concepts only
• generated schemas
• MCP create/read/transition path
• interface query
• OKF export
• migration of a small existing corpus
• one real process cycle driven through the new model

That is enough to learn quickly while preserving the RFC’s direction.

1.2.7 - Architecture Specification

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.

Product Boundary

The architecture is intentionally hybrid:

There is no planned wholesale rewrite of MCP servers in Rust. A future Rust mcp command may supervise the installed Python gateway, but Python remains authoritative.

The repository boundary is equally strict:

• context/ is processkit’s installed dogfood consumer state.
• src/context/ is the producer-curated release deliverable.

Dogfooding is acceptance evidence. It does not make the two trees redundant, and project-owned entities must never leak into the release payload.

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 RFC target is 89 concepts. Alpha.3 completed the planned ontology breadth; subsequent work is intentionally focused on lifecycle usability, trust, migration, runtime diagnostics, and proven user journeys rather than further default-ontology expansion. The detailed inventory is captured in Ontology Reference .

The product release version and entity API version are independent. The v1.0 release keeps apiVersion: processkit.projectious.work/v2; changing that value requires a separate, explicit migration.

Required Internal Semantics

The canonical model must preserve:

• stable processkit entity IDs
• schema-backed kinds and discriminators
• lifecycle state machines
• typed Bindings and queryable relations
• structured LogEntries
• validation modes per kind
• generated schemas
• MCP tools as the normal write path
• interface-aware queries such as query_by_interface

These semantics must not be collapsed into plain markdown links, free-form notes, or OKF’s permissive interchange model.

Schema Generation

The RFC’s build-time schema generation remains the preferred direction:

• source schemas ship under context/schemas/src/
• templates and fragments compose schemas
• generated flat schemas are committed
• runtime tools consume generated schemas
• a rebuild endpoint supports full or partial regeneration

The required endpoint shape remains:

regenerate_schemas(kinds: list | None) -> {rebuilt, unchanged, errors}

The generated schema architecture, MCP helper expectations, and index update flow are specified in Tooling Architecture .

Validation

Validation is phase-gated:

• migrated kinds use strict validation
• migrating kinds use tolerant validation with warnings
• validation mode must be visible through MCP
• release gates must fail on invalid strict entities

Indexing And Query

The index must support:

• full-text search
• entity lookup by ID
• relation traversal
• interface grouping
• query by interface
• backlinks or cited-by navigation

Interface-aware query is a core v1.0 feature because agents should be able to ask for records, decisions, artifacts, logs, or approvals without hard-coding every concrete kind.

The implementation should keep the index as a SQLite/FTS5 accelerator over canonical files. It must store declared schema interfaces, typed relations, event subjects, and enough metadata to support query_by_interface without replacing the git-backed entity files as the source of truth.

OKF Boundary

OKF is an import/export profile, not the internal canonical model.

Exports should:

• emit conformant OKF v0.1 bundles
• include OKF type
• preserve processkit_id, kind, and interfaces in extension frontmatter
• emit normal markdown links for generic OKF consumers
• preserve typed relation metadata for processkit-aware consumers

Imports should:

• mark content as external knowledge
• preserve unknown OKF frontmatter
• avoid pretending external OKF concepts have full processkit lifecycle semantics

Runtime Integration

processkit should provide examples and integration surfaces for:

• LangGraph
• Google ADK
• OpenAI Agents SDK
• Microsoft Agent Framework
• coding agents such as OpenHands, SWE-agent, Copilot Agent, and Aider

The stable contract should be MCP, files, schemas, and docs, not a framework-specific runtime dependency.

In alpha.5, harnesses launch the Python gateway directly through uv or an installer-managed projection. Native processkit doctor and processkit mcp commands are target interfaces, not current commands.

Testing Architecture

Manual dogfooding through a new aibox project is useful, but it is not the correctness strategy for v1.0. The core test suite must run against local fixture projects without requiring aibox and must cover schema generation, MCP contracts, state machines, index updates, migrations, and pk-doctor adversarial fixtures. aibox should be tested as an adapter after the processkit-native suite is green.

See Test Strategy .

1.2.8 - Beta Ontology Plan

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:

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

Implementation Status

The beta inventory is now frozen in src/context/schemas/src/registry.yaml and contains exactly 62 unique concepts:

• all 19 foundational terminology concepts
• all 22 atomic primitives
• the 8 selected discriminators
• the 13 selected compositions

The executable portion produces 43 generated schema contracts. The difference between 62 concepts and 43 schemas is intentional: terminology concepts are reusable schema and lifecycle mechanics rather than independently persisted entity kinds. A contract test enforces the four category counts, uniqueness, and presence of every generated output.

Selected Discriminators

The beta discriminator set is:

• Risk
• Belief
• WorldFact
• WSJFEstimate
• Assumption
• Scope
• Hierarchy
• Position

Selected Compositions

The beta composition set is:

• TeamMember
• DecisionRecord
• LogEntry
• Migration
• ProcessSpecification
• GoalSpecification
• RoleSpecification
• GateSpecification
• SchemaSpecification
• ScheduleSpecification
• TestSpecification
• ChannelSpecification
• QueueSpecification

Selection Rules

Concepts enter the beta set when they support a real processkit workflow, unlock another selected concept, or provide interoperability value. Parent concepts count independently because their contracts are generated and tested. Variants are represented as discriminators rather than false top-level kinds.

The 27 concepts outside the beta target remain valid ontology candidates; they are deferred, not rejected.

Promotion Gates

Beta promotion requires:

• a stable, dependency-closed list of exactly 62 implemented concepts
• generated schemas and state machines for every selected executable concept
• MCP create, transition, query, and relation coverage where the concept owns lifecycle behavior
• representative migration from a v0.x corpus
• OKF export and import conformance
• at least one end-to-end process cycle using the beta model
• deterministic generation, fixture, package, docs, and release-audit checks passing through the local release gate

1.2.9 - Branch Start Work Plan

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:

• Freeze the branch contract and backport policy in docs.
• Add a visible branch banner or README note explaining that v1.0 is the rebuild line.
• Decide the initial source layout for context/schemas/src/, _generated/, schema renderer tests, and fixture projects.
• Add a minimal fixture-project layout for empty-project, alpha-project, migration-v0-project, adversarial-project, and art-project.
• Define the command surface for schema rebuild, validation, MCP smoke, index rebuild, and docs build.
• Establish manual local release-audit commands that do not depend on aibox or GitHub Actions.
• Record any accepted deviations from the RFC before implementation starts.

Exit criteria:

• The branch builds docs.
• The planned source/test directories exist.
• The first schema-generation and fixture-test commands are documented.

Phase 1 - Ontology And Schema Generation

Goal: turn the documented 89-concept ontology into generated schema contracts and prove deterministic generation.

Backlog:

• Create the canonical ontology registry with class, name, description, parent, discriminator, interface, lifecycle, and migration note fields.
• Scaffold src/context/schemas/src/ with T fragments, primitive schemas, discriminator overlays, and composition templates.
• Implement the Jinja + YAML renderer.
• Implement merge strategies for replace, concat, and name-merge.
• Commit _generated/*.yaml output and golden render fixtures.
• Add strict/tolerant validation-mode metadata per kind.
• Add schema contract tests for valid and invalid fixtures.
• Add the regenerate_schemas(kinds: list | None) MCP shape or a local implementation shim if the MCP server is not ready yet.

Exit criteria:

• Full and partial schema regeneration are deterministic.
• The generated schema tree is committed.
• The alpha ontology subset has generated schemas and validation tests.

Phase 2 - Tooling Parity

Goal: make the generated schemas usable through MCP and local tools.

Backlog:

• Build shared MCP helpers for schema loading, validation, state-machine checks, atomic writes, event emission, and index upsert.
• Port alpha create/read/transition tools to generated schemas.
• Add Python signature to draft-2020-12 JSON Schema consistency tests.
• Expose validation mode through MCP.
• Add state-machine fixtures for valid transitions, invalid transitions, guard failures, and terminal states.
• Keep per-domain tool ownership while allowing gateway aggregation.
• Define a shared remediation descriptor schema for doctor findings.
• Validate every executable remediation against the installed gateway tool catalog and input schema.
• Add a structured policy-exception resolver with scope, fingerprint, decision, and review metadata.

Exit criteria:

• Alpha entity writes happen through MCP helpers.
• Tool signatures and JSON Schemas match.
• State-machine and validation-mode tests pass.
• Every actionable alpha finding has an executable or formally recognized disposition.

Phase 3 - Indexing And Corpus Migration

Goal: migrate representative v0 data and prove that read-side behavior matches the new ontology.

Backlog:

• Extend the SQLite/FTS5 index with schema-declared interfaces.
• Implement query_by_interface for at least Record and Versioned.
• Index typed Binding edges, provenance, ownership, hierarchy, and event subjects.
• Build v0-to-v1 migration adapters for the alpha corpus.
• Implement declarative migration drafting, planning, and execution with source-hash preconditions and recovery journals.
• Support bounded operations for path moves, field updates, entity renames, reference rewrites, and archival.
• Preserve predecessor/successor links, durable ID aliases, and unknown-field reports without silently rewriting append-only logs.
• Measure field loss and orphan rates.
• Add index drift detection and reindex recovery tests.

Exit criteria:

• A representative v0 fixture corpus migrates without manual aibox steps.
• Interface queries return mixed-kind results correctly.
• Migration reports are deterministic and actionable.
• Migration-backed doctor findings can be planned, executed, and rechecked cleanly through the shipped gateway.

Phase 4 - Skills, Agents, And Runtime Surfaces

Goal: make skills and agent-facing instructions use the v1.0 model.

Backlog:

• Update skill metadata and trigger guidance to v1.0 ontology language.
• Remove v0 primitive assumptions from write-side skill instructions.
• Add canned agent scenarios covering work, decisions, risks, gates, roles, skills, artifacts, and migrations.
• Update gateway, per-domain MCP, and harness compatibility docs.
• Add malformed-output measurements for scenario runs.
• Keep aibox as an adapter path, not a core test dependency.

Exit criteria:

• Canned scenarios pass with malformed output below the acceptance threshold.
• Skills use MCP write paths for canonical entities.
• Runtime docs describe gateway and per-domain modes consistently.

Phase 5 - First-ART Validation

Goal: prove the rebuild with a production-shaped ART cycle.

Backlog:

• Model Portfolio, ValueStream, ART, Team, Scope, RoleSlot, and TeamMember structures.
• Run PI planning with objectives, risks, dependencies, capacity, and committed WorkItems.
• Execute the cycle through MCP transitions and gates.
• Capture demo evidence, Measurements, Outcomes, Decisions, and inspect-and-adapt follow-up.
• Record friction, interpretation drift, missing concepts, and missing tool affordances.
• Review the first-ART evidence before rc promotion.

Exit criteria:

• The first-ART pilot completes planning, execution, demo, and inspect-and-adapt.
• pk-doctor reports no blocking errors on the pilot corpus.
• Human reviewers can inspect the same state through files and docs.

Phase 6 - Cutover Preparation

Goal: prepare v1.0.0 without calendar-driven release pressure.

Backlog:

• Verify all strict gate criteria through A5.
• Produce reproducible release artifacts from a clean checkout.
• Publish migration and downstream adoption guidance.
• Finalize v0.x maintenance and LTS policy.
• Record the cutover decision.
• Prepare merge strategy from v1.0 to main.

Exit criteria:

• No known blocker remains for final v1.0.0 cutover.
• The cutover decision is recorded.
• Docs and release artifacts are published and reproducible.

Phase 7 - Post-cutover Stabilisation

Goal: stabilize the v1 line after release.

Backlog:

• Observe the minimum 14-day stabilization window.
• Track and triage critical regressions.
• Exercise downstream migration support.
• Verify release integrity, provenance, docs publication, and package installation.
• Run index rebuild, drift recovery, MCP smoke, sensitive-data, and adversarial pk-doctor fixtures.
• Validate one v0.x LTS slow-adopter scenario if needed.

Exit criteria:

• Stabilization findings are closed, tracked, or accepted.
• Release integrity and adversarial fixture checks pass.
• v1.x becomes the normal development line after cutover.

1.2.10 - Landscape Note

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.

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

Local Markdown Memory

Projects such as Basic Memory and LLM wiki patterns show that agents and humans benefit from simple, local, readable markdown knowledge.

processkit should learn from their ergonomics: backlinks, readable files, simple search, and low-friction MCP access.

processkit should keep stronger lifecycle and relation semantics.

Agent Runtimes

LangGraph , Google ADK , OpenAI Agents SDK , and Microsoft Agent Framework provide orchestration, tools, handoffs, sessions, tracing, and human-in-the-loop behavior.

processkit should integrate with them through stable MCP tools and runtime-neutral examples. It should not own the agent loop.

Memory Layers

Letta and Mem0 show the importance of long-term memory, retrieval, summarization, and consolidation.

processkit should distinguish fleeting notes, permanent artifacts, decisions, logs, and team-member memory. Promotion and consolidation should be explicit process actions.

Metadata Governance

DataHub , OpenMetadata , Unity Catalog , and OpenLineage show the value of typed metadata, lineage, ownership, governance, and quality checks.

processkit should make ownership, provenance, lineage, and quality queryable without turning into a data catalog.

Coding Agents

OpenHands , SWE-agent , GitHub Copilot Agent , and Aider need durable task context, acceptance criteria, related decisions, test evidence, and review history.

processkit should make those inputs easy to retrieve and those outputs easy to record.

Concepts To Adopt

• boundary compatibility with OKF
• local-first markdown ergonomics
• explicit handoffs and approvals
• guardrails as auditable Gates
• traces and summaries as structured evidence
• memory promotion workflows
• typed provenance and lineage
• acceptance criteria as queryable fields
• runtime-neutral integration examples

Concepts To Avoid

• replacing agent runtimes
• replacing data catalogs
• treating vector memory as the source of truth
• reducing typed relations to prose links
• making path names the canonical identity model

1.2.11 - Ontology Reference

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.

Counts

The v1.0 target is 89 ontology concepts.

Full Working Inventory

This inventory makes the RFC’s count concrete for implementation planning. It preserves the RFC settlements: Location and Skill are primitives, Service and TeamMember are compositions, Position is a role-slot Binding discriminator, and Hierarchy is a named parent-child Binding discriminator.

T: Foundational Concepts

P: Atomic Primitives

D: Discriminator Variants

C: Compositions

1.2.12 - Product Specification

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.

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

1. Capture work as typed WorkItems with acceptance criteria.
2. Record decisions with context, alternatives, rationale, and consequences.
3. Attach artifacts and supporting analysis to work and decisions.
4. Route tasks to roles, team members, skills, and model classes.
5. Apply gates for approval, policy, evaluation, and release checks.
6. Query by interface rather than forcing agents to guess concrete entity kinds.
7. Preserve process evidence in structured LogEntries.
8. 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.

1.2.13 - Test Strategy

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.

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 and every actionable finding has an executable or formally recognized disposition
• docs and examples remain buildable
• downstream integrations can consume the published contracts without becoming release prerequisites

Automated Layers

Fixture Projects

Use local fixture projects under the test tree:

• empty-project: no context, used for first install and schema generation
• alpha-project: small valid corpus covering the alpha ontology slice
• migration-v0-project: representative v0.x corpus for migration adapters
• adversarial-project: invalid frontmatter, bad transitions, broken links, malformed bindings, and inconsistent index state
• remediation-project: actionable doctor findings with safe fixes, archives, migrations, policy exceptions, and external blockers
• art-project: a compact first-ART scenario that exercises planning, execution, demo, inspect-and-adapt, decisions, risks, and evidence

These fixtures run through plain local repository commands. aibox can consume the same fixtures in an adapter suite, but the fixtures must not require aibox or GitHub Actions to exist.

Alpha Proof

Alpha automation should pass before any alpha tag:

• full schema rebuild from shipped context/schemas/src/
• committed _generated tree matches the renderer output
• create/read/transition MCP paths work for the alpha slice
• query_by_interface works for at least Record
• strict and tolerant validation modes are observable
• the alpha fixture migrates from v0.x or maps explicitly
• actionable alpha findings close through the shipped gateway or resolve to a recognized non-executable disposition
• docs build locally

Manual dogfood remains useful after this automated baseline, not instead of it.

Final Release Proof

The final gate should include:

• all strict 81-gate criteria green
• first-ART validation completed with recorded evidence
• all MCP tools schema-checked
• pk-doctor adversarial and remediation fixtures green after executing their declared closure paths
• package smoke tests green from release artifact
• signed archive and native installer verify and install without network access or an external project manager
• no known index/schema/migration blocker

This keeps the RFC’s first-ART proof while removing the current hard dependency on manual downstream experimentation.

1.2.14 - Tooling Architecture

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.

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.

MCP Helper Library

Every MCP server should use shared helpers rather than reimplementing process rules. The helper layer should provide:

• ID allocation and collision checks
• generated schema loading
• draft-2020-12 JSON Schema validation
• state-machine loading and transition validation
• strict/tolerant validation-mode lookup
• frontmatter and body parsing/serialization
• atomic file writes under the canonical storage layout
• event-log emission for mutating actions
• index upsert/delete calls after successful writes
• typed error responses with actionable remediation
• Python type-signature to JSON Schema consistency checks
• golden fixture helpers for MCP contract tests

The RFC requires MCP tools to have valid Python type signatures and matching draft-2020-12 JSON Schemas before release candidate.

Doctor Remediation Contract

Every pk-doctor finding with action_required: true must have a typed disposition. Supported dispositions are:

• safe_fix: a bounded, idempotent repair
• migration_needed: a planned data or identity transformation
• archive_needed: a lifecycle-preserving archive operation
• policy_decision_needed: a structured, reviewable exception
• external_dependency: a named downstream or infrastructure blocker

Executable dispositions must name a gateway tool, provide schema-valid arguments, and declare whether confirmation, data-loss approval, preflight, or dry-run support is required. Release validation must introspect the gateway catalog and fail when a declared tool is absent or its input schema is incompatible with the finding.

Prose guidance alone is not an actionable remediation. When processkit cannot execute or formally recognize the required disposition, the finding must be informational and link to tracked implementation work instead of claiming that the derived project can resolve it.

Policy Exceptions

A policy exception is structured data, not an arbitrary DecisionRecord. It must identify the check and finding fingerprint, affected scope, rationale, approver or accepted decision, and an expiry or review condition. Doctor resolves exceptions through a shared policy service and reports stale, over-broad, or unmatched exceptions. The underlying DecisionRecord remains the durable rationale, while the exception supplies the machine-readable suppression contract.

Schema Generation

Shipped schema sources live under src/context/schemas/src/, which becomes context/schemas/src/ in an installed project. Runtime tools consume a committed context/schemas/_generated/*.yaml tree. Keeping both paths inside src/ ensures that derived projects can regenerate schemas without fetching repository-only build inputs.

Composition rules:

• extends: parent.yaml declares composition inheritance
• {% include %} includes T fragments into templates
• __merge: replace|concat|name-merge declares per-field merge strategy
• generated schemas declare interfaces such as Record or Versioned
• generated files are committed so agents and reviewers can diff runtime contracts directly

The required MCP endpoint is:

regenerate_schemas(kinds: list | None) -> {rebuilt, unchanged, errors}

kinds=None performs a full rebuild. A non-empty list rebuilds only the requested generated schemas and their dependencies. aibox apply may trigger full rebuilds by default, but schema generation must not depend on aibox; it must be runnable through processkit’s local test commands.

Validation Modes

Validation is phase-gated:

• migrated kinds validate strictly
• kinds still being migrated validate tolerantly and emit warnings
• validation mode is queryable through MCP per kind
• release gates fail on invalid strict entities

This lets alpha/beta users test incomplete migrations without allowing known-invalid final entities to pass unnoticed.

Indexing Database

The RFC keeps the existing SQLite/FTS5 direction and extends it with interface-level grouping. The index is an accelerator and query surface, not the source of truth. Git-backed entity files remain canonical.

The minimum index stores:

• entity identity, kind, discriminator, state, title, timestamps, and path
• declared interfaces from generated schemas
• frontmatter fields needed for common filters
• typed relation edges from Bindings and inline references
• event subjects and actors for timeline queries
• full-text rows for titles, bodies, specs, and selected metadata
• validation and generation metadata for drift checks

The required read patterns are:

• get_entity(id)
• search by text
• query by kind, state, owner, and container
• traverse relation edges
• backlinks or cited-by navigation
• query_by_interface(interface, filters...)

query_by_interface(Record, ...) is load-bearing because it lets agents retrieve DecisionRecords, LogEntries, measurements, approvals, and other record-like entities without guessing every concrete kind.

Index Update Flow

Writes should follow one transaction-like path:

1. MCP tool receives a typed request.
2. The tool loads the generated schema and current validation mode.
3. The helper validates input and transition guards.
4. The entity file is written atomically.
5. Required LogEntries or Events are emitted.
6. The changed entity, relations, and events are upserted into SQLite.
7. The response returns the entity ID, path, state, validation mode, and index update status.

If index update fails after a file write, the response must surface drift and pk-doctor must detect it. A separate reindex tool should rebuild SQLite from files for recovery, local fixtures, and release checks.

Declarative Migration Execution

Migration management must support a processkit-native lifecycle:

1. draft_migration records intent, source and target versions, operations, and expected source hashes.
2. plan_migration validates schemas, references, permissions, collisions, and append-only constraints without writing.
3. execute_migration applies the approved plan through the shared atomic write, event, and index-update path.
4. A failed execution aborts before commit or leaves a recovery journal that can be resumed or rolled back deterministically.

The initial declarative operation vocabulary should cover move_path, update_field, rename_entity, rewrite_reference, and archive_payload. Migration files must not embed arbitrary executable scripts. Each operation declares preconditions and expected hashes so a plan cannot silently apply to changed input.

Stable Identity And History

Identity changes should preserve historical truth without rewriting append-only LogEntries. The preferred model is a canonical replacement plus durable predecessor/successor relations and an ID alias index. Reads through an old ID resolve to the canonical entity while returning the alias path used for resolution.

History rewriting is exceptional. It requires an explicit migration policy, original-content hashes, archived source payloads, and an auditable event. A filename-style warning alone never justifies rewriting event history.

1.2.15 - v0 Reconciliation

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

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.

Before each prerelease:

1. compare the selected v0 release with v1.x-dev
2. update this matrix
3. run schema, server, package, docs, doctor, and release-audit checks
4. record any intentional deferral with an owner or milestone

2 - Getting Started

Choose the path that matches your release line:

• v1 alpha: use the native CLI and signed local-release envelope. Start with the v1 alpha tutorial .
• v0 stable: retain the supported v0 installer or managed aibox workflow. See Installing for the compatibility path.

What v1 installs

A v1 distribution contains visible, reviewable project content:

• context/skills/ and the Python MCP servers shipped with those skills;
• context/schemas/, generated contracts, and state machines;
• .processkit/ profiles, installer contracts, and release metadata;
• harness projections owned at individual managed keys; and
• AGENTS.md, the provider-neutral agent entry point.

The installer records managed ownership in .processkit/state.json. New project entities and local overrides remain owned by the consuming project.

Runtime requirements

• Linux ARM64 GNU for the published alpha.5 native executable.
• Python 3.10 or newer and uv for the Python MCP runtime.
• Git and an MCP-capable harness for the normal agent workflow.
• curl, tar, and sha256sum for the tutorial.

Linux x86_64 and macOS native assets, a bootstrap installer, online release resolution, and native processkit doctor/processkit mcp commands are future work.

Learning path

1. Complete the v1 alpha tutorial .
2. Create your first entity through MCP.
3. Review installer guarantees .
4. Choose a package profile .
5. Read the v1 implementation status .

2.1 - Installing

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:

processkit plan \
  --root /path/to/project \
  --distribution /path/to/processkit-v1.0.0-alpha.5 \
  --profile managed \
  --harness codex

processkit install \
  --root /path/to/project \
  --distribution /path/to/processkit-v1.0.0-alpha.5 \
  --profile managed \
  --harness codex \
  --yes

Do not copy the v1 payload by hand. The CLI supplies transaction, ownership, recovery, and conservative uninstall evidence that manual copying cannot.

Stable v0 and managed aibox projects

Existing v0 projects remain supported and should stay pinned to their current stable version until the v1 migration path is complete. aibox remains an optional downstream installer and integrator; it is not required to build, test, or run processkit.

See v0 compatibility and aibox integration before changing an existing project.

After installation

Python and uv remain runtime prerequisites for MCP:

uv run \
  context/skills/processkit/processkit-gateway/mcp/server.py \
  serve --transport stdio

Use MCP tools for entity writes. They validate schemas and transitions and produce the required audit events.

2.2 - Install and Use the v1 Alpha

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.

3. Verify checksums

sha256sum -c processkit-v1.0.0-alpha.5.tar.gz.sha256

The command must report OK.

4. Install the CLI locally

curl -fLO \
  https://raw.githubusercontent.com/projectious-work/processkit/v1.0.0-alpha.5/scripts/install-processkit.sh
chmod +x install-processkit.sh
./install-processkit.sh v1.0.0-alpha.5
export PATH="$HOME/.local/bin:$PATH"
processkit --version

No root access is required. Add $HOME/.local/bin to your shell PATH if it is not already present.

5. Verify the signed release

mkdir -p "$PWD/trust"
key_id="d35516ccd7be9efad6579c5f6c2ab8ba1a59f18d563f339e62e1cef9a5f9a1eb"
cp processkit-v1.0.0-alpha.5-public.pem \
  "$PWD/trust/v1.pub.pem"

jq -n --arg key_id "$key_id" '{
  apiVersion: "processkit.projectious.work/local-trust/v1alpha1",
  kind: "TrustStore",
  keys: [{
    keyId: $key_id,
    algorithm: "Ed25519",
    publicKeyFile: "v1.pub.pem",
    status: "active"
  }]
}' >"$PWD/trust/trust-store.json"

processkit verify-release \
  --envelope "$PWD/processkit-v1.0.0-alpha.5.release.json" \
  --signature "$PWD/processkit-v1.0.0-alpha.5.release.sig" \
  --trust-store "$PWD/trust/trust-store.json"

For organizational use, obtain the public key through an independently trusted channel. Publishing a key beside an artifact makes verification reproducible but does not by itself establish publisher identity.

6. Extract the distribution

tar -xzf processkit-v1.0.0-alpha.5.tar.gz
distribution="$PWD/processkit-v1.0.0-alpha.5"

The extracted directory is the required local --distribution input.

7. Create a project and review the plan

project_root="$PWD/../../../processkit-alpha-project"
mkdir -p "$project_root"
git -C "$project_root" init

processkit plan \
  --root "$project_root" \
  --distribution "$distribution" \
  --profile managed \
  --harness codex \
  --format human

plan is non-mutating. Review the selected profile, managed paths, and harness projection before proceeding. Replace codex with claude when that is your harness.

8. Install and verify

processkit install \
  --root "$project_root" \
  --distribution "$distribution" \
  --profile managed \
  --harness codex \
  --yes

processkit verify --root "$project_root"
git -C "$project_root" status --short

The installer owns only declared managed paths and harness keys. It records ownership in .processkit/state.json; unrelated harness configuration and project files are preserved.

9. Start using MCP

Restart the selected harness so it reads the installed projection. If you need a direct development fallback, run the Python gateway from the project:

cd "$project_root"
uv run \
  context/skills/processkit/processkit-gateway/mcp/server.py \
  serve --transport stdio

In the harness, ask:

Use processkit to create a medium-priority task WorkItem titled “Evaluate processkit v1 alpha”, then read it back.

Continue with Your First Entity for transitions, decisions, relationships, and queries.

10. Update, recover, or uninstall

Preview a new exact distribution before updating:

processkit plan \
  --root "$project_root" \
  --distribution /path/to/new/exact/distribution \
  --profile managed \
  --harness codex

processkit update \
  --root "$project_root" \
  --distribution /path/to/new/exact/distribution \
  --yes

After an interrupted mutation:

processkit recover --root "$project_root" --yes

To remove only unchanged, provably managed content:

processkit uninstall --root "$project_root" --yes

Changed and user-owned files are preserved and reported.

Alpha.4 limitations

• Only Linux ARM64 GNU has a published native executable.
• Release acquisition and trust-root distribution are manual.
• Human commands require a local distribution directory.
• Native doctor, migrate, package, harness, and mcp command groups are not implemented.
• Python and uv remain required for MCP.
• v0-to-v1 migration is evidence and compatibility inspection only; do not migrate an existing v0 project in place.

Track the exact status in the issue #135 implementation review .

2.3 - Your First Entity

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.

The agent should route the request and call create_workitem. A successful response includes an ID and canonical path, for example:

BACK-curious-quail
context/workitems/2026/07/BACK-curious-quail.md

Read and transition it

Ask:

Read BACK-curious-quail through processkit, then transition it from backlog to in-progress.

The transition tool checks the WorkItem state machine and records its event. An invalid transition is rejected rather than silently changing the file.

Record and query a decision

Ask:

Record the accepted decision that this project will evaluate v1.0.0-alpha.5 in an isolated branch, link it to BACK-curious-quail, and query both entities back.

This exercises the core v1 user journey: governed write, relationship, audit event, and indexed read over visible project files.

Inspect the result

The files remain readable in Git:

git status --short
processkit verify --root .

processkit verify checks installer-managed content. Domain MCP tools and pk-doctor check project entities; a native processkit doctor command is planned but is not part of alpha.5.

Next

• Review MCP server operation .
• Learn the entity model .
• Read the alpha.5 limitations .

3 - Primitives

processkit provides a compact set of process primitives as universal building blocks. The v2 direction keeps durable project facts in the entity layer and moves workflow definitions, schedules, runtime model data, and lifecycle implementation details to narrower surfaces.

In the v1 release line, apiVersion remains processkit.projectious.work/v2. The product release version and entity API version are independent. Create and transition canonical entities through MCP management tools rather than hand-editing them.

Shipped v2 entity schemas

Demoted legacy surfaces

Metric, Model, Process, Schedule, and StateMachine are not first-class shipped entity surfaces in the SmoothTiger/SmoothRiver v2 direction. Metric and policy definitions become artifact-backed specifications; readings and events are LogEntries or external time series. Model data belongs to model-recommender roster/configuration surfaces. Processes are represented by process-instance WorkItems with definition Artifacts. Schedules are represented by time-window Bindings. State machines remain validation machinery, not author-facing workflow records.

Layered relationships

Primitives depend on each other through the skill hierarchy:

Layer 0: index (infrastructure), id (infrastructure), LogEntry (event-log)
Layer 1: Actor (actor-profile), Role (role-management), TeamMember
Layer 2: WorkItem, DecisionRecord, Scope, Category, Binding, CrossReference
Layer 3: Gate, Constraint, Migration, workflow/projection skills
Layer 4: Discussion, metrics-management, Owner profile (owner-profiling), Context grooming

Lower layers never depend on higher layers. The management skill for a primitive follows the same layer (e.g. workitem-management is Layer 2 and depends on event-log at Layer 0 and actor-profile at Layer 1).

Cross-references vs Bindings

Rule: if a relationship has scope, time, or its own attributes → use a Binding entity. Otherwise → use a cross-reference field in frontmatter.

See Primitives → Relationships for details.

Schema coverage

The current schema tree includes these authoritative YAML schema files under src/context/schemas/ . The schemas define the spec fields, required vs optional, and enum constraints. MCP servers validate against the schema on every write call — schema errors surface as structured tool errors rather than silent bad data.

Installer or CI validation can check the same file contracts without starting a full agent session. MCP write tools perform the authoritative write-path validation.

Next

• Format — the apiVersion/kind/metadata/spec contract.
• State Machines — default machines and how to override.
• Relationships — cross-references and Bindings.

3.1 - Entity File Format

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

metadata fields

ID formats

Configurable per project through installer or processkit settings:

The prefix (BACK-, LOG-, DEC-, …) is determined by the primitive kind and is not configurable. See Reference → ID Formats for details.

apiVersion policy

apiVersion follows the Kubernetes convention: <group>/<version>, where the group is a reverse-DNS name anchored on the owning organization. For processkit the group is processkit.projectious.work, making processkit a subcomponent of the projectious.work organization. This prevents name collisions if other organizations fork or publish compatible primitives under their own domains.

See Reference → apiVersion Policy for the evolution rules.

Authoritative source

The authoritative specification is src/context/schemas/ in the processkit repo. This page is a condensed overview; the shipped schema files define the authoritative spec contracts for each kind.

3.2 - State Machines

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.

Overrides must:

• Keep the same initial state (or migrate existing data).
• Not remove states that existing entities are currently in.
• Add new transitions only from states that already exist.

See the state-machine-management skill for details.

Multiple machines for one kind

You can ship multiple state machines for the same primitive kind by using distinct names. Entities opt into a specific machine via spec.state_machine: <name>. Useful when the same kind has fundamentally different lifecycles (e.g. a WorkItem with bug-lifecycle vs story-lifecycle).

3.3 - Relationships

processkit expresses relationships between entities two ways:

1. Cross-references — lightweight fields in frontmatter
2. 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:

See the cross-reference-management skill for the full list and conventions.

Binding examples

---
apiVersion: processkit.projectious.work/v1
kind: Binding
metadata:
  id: BIND-bright-falcon
  created: 2026-04-06T00:00:00Z
spec:
  type: role-assignment
  subject: ACTOR-alice
  target: ROLE-tech-lead
  scope: SCOPE-project-x
  valid_from: 2026-01-01
  valid_until: 2026-12-31
---

Conventional binding types:

Legacy process-gate, process-scope, and schedule-scope Bindings are v1 migration inputs only. New v2 relationships should target the concrete WorkItem, Scope, Artifact, or Gate being governed.

See the binding-management skill for the full spec.

Why Binding was generalized from RoleBinding

DISC-002 §11 analyzes the decision to generalize the 18th primitive from RoleBinding to Binding. The short version: the indirection pattern applies to at least 7 relationship types across processkit, and one generalized primitive is cleaner than multiplying specific bindings. See DEC-023 in the aibox repo.

3.4 - WorkItem

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

State machine

backlog → in-progress → review → done
              ↕
           blocked

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

Fields

Required

Optional

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.

3.5 - LogEntry

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

Fields

Required

Optional

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.

Manual calls to log_event are for events that have no MCP server: deploying a build, running a meeting, making a phone call, completing a manual step in a process.

Event type conventions

Use dot-separated entity.verb naming:

Notes

• LogEntries are never updated or deleted. If an event was logged in error, log a corrective entry explaining the error.
• query_events and recent_events support filtering by subject, actor, event_type, and date range.
• Logs are date-sharded: context/logs/{year}/{month}/.

3.6 - DecisionRecord

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.

State machine

proposed → accepted → superseded
         ↘ rejected

accepted, rejected, and superseded are terminal.

Fields

Required

Optional

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.

3.7 - Artifact

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

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.

Fields

Required

Optional

Examples

Self-hosted (document body in the file)

---
apiVersion: processkit.projectious.work/v1
kind: Artifact
metadata:
  id: ART-20260411_0903-BrightVale-deploy-runbook
  created: '2026-04-11T09:03:00Z'
spec:
  name: Deploy Runbook — v0.12.0
  kind: document
  tags: [runbook, deploy, v0.12.0]
  produced_at: '2026-04-11T09:03:00Z'
---

## Steps

1. Run smoke tests: `uv run scripts/smoke-test-servers.py`
2. Stamp provenance: `bash scripts/stamp-provenance.sh vX.Y.Z`
...

Pointer (external file)

---
apiVersion: processkit.projectious.work/v1
kind: Artifact
metadata:
  id: ART-20260411_0904-NeatDawn-brand-design-system
  created: '2026-04-11T09:04:00Z'
spec:
  name: Brand Design System
  kind: design
  location: https://www.figma.com/file/abc123/brand-design-system
  format: figma
  owner: ACTOR-design-team
  tags: [brand, design-system]
---

Notes

• Artifact has no state machine — it is a catalogue record, not a work-tracking entity. Use WorkItem to track the work that produces it.
• query_artifacts supports filtering by kind, tags, and title substring.
• For long-lived reference documents that agents should read, prefer the context-management skill; for point-in-time deliverables, use Artifact.

3.8 - Note

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

State machine

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

insight, promoted, and archived are terminal.

Note types (Luhmann/Ahrens taxonomy)

Fields

Required

Optional

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.

Hook adapters may use the filesystem hand-off directories tasks/inbox/, tasks/claimed/, tasks/done/, and tasks/failed/. Use prepare_hook_inbox_dirs to create that layout, then capture_inbox_item, claim_inbox_item, complete_inbox_item, and fail_inbox_item to keep the canonical Note state in processkit.

Links — typed Zettelkasten edges

Each entry in links has:

Example

---
apiVersion: processkit.projectious.work/v1
kind: Note
metadata:
  id: NOTE-20260411_0905-ClearDawn-fts5-trigram
  created: '2026-04-11T09:05:00Z'
spec:
  title: FTS5 trigram tokeniser matches substrings without pre-tokenisation
  body: |
    SQLite's FTS5 with the trigram tokeniser splits text into overlapping
    3-character sequences. This lets you search for partial words
    (e.g. "Crow" matches "StoutCrow") without needing a dedicated
    tokenisation pass. Ideal for entity ID word-pair search.
  type: insight
  state: insight
  tags: [sqlite, fts5, search]
  links:
    - target: NOTE-20260411_0906-BrightWave-search-ux
      relation: supports
      context: >
        Trigram matching is what makes the search UX feel instant —
        users type partial word-pairs and get matches immediately.
---

Notes

• Title discipline matters: a good Note title is a self-contained claim or question — "FTS5 trigram tokeniser matches substrings" not "FTS5 notes". The title alone should convey the idea.
• Tags group notes by topic; links build arguments. Use both.
• A question note that remains unanswered after a week should become a Discussion or WorkItem spike.

3.9 - Actor

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

Fields

Required

Optional

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.

3.10 - Role

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

Fields

Required

Optional

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.

3.11 - Binding

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.

When to use a Binding vs a cross-reference

Fields

Required

Optional

Type conventions

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.

Example

---
apiVersion: processkit.projectious.work/v1
kind: Binding
metadata:
  id: BIND-20260411_0908-WarmOak-alice-techlead-q2
  created: '2026-04-11T09:08:00Z'
spec:
  type: role-assignment
  subject: ACTOR-20260411_0906-alice
  target: ROLE-20260411_0907-ClearOak-tech-lead
  scope: SCOPE-20260410_q2-2026
  valid_from: '2026-04-01'
  valid_until: '2026-06-30'
  description: Alice is tech lead on the processkit project for Q2 2026
---

Notes

• end_binding closes a binding by setting valid_until to the current datetime — use this rather than deleting the entity.
• resolve_bindings_for returns all active bindings for a given subject, useful for “who is currently assigned to what” queries.

3.12 - Scope

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

State machine

planned → active → completed
        ↘ cancelled

completed and cancelled are terminal.

Fields

Required

Optional

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.

3.13 - Discussion

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.

State machine

active → resolved
       ↘ closed (no outcome)

resolved and closed are terminal.

Fields

Required

Optional

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.

3.14 - Gate

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.

Fields

Required

Optional

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