Introduction

• 1: Development
• 1.1: Product Specification
• 1.2: Architecture Specification
• 1.3: Ontology Reference
• 1.4: Tooling Architecture
• 1.5: Test Strategy
• 1.6: Alpha Scope
• 1.7: Landscape Note
• 1.8: Acceptance Gate
• 1.9: Analysis Archive
• 1.9.1: processkit v1.0 Base Context
• 1.9.2: Concept Mapping Briefing Analysis
• 1.9.3: processkit v1.0 RFC Analysis
• 1.9.4: OKF Compatibility Analysis
• 1.9.5: processkit v1.0 Start Assessment
• 2: Getting Started
• 2.1: Installing
• 2.2: 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: MCP Servers
• 7.1: Harness Compatibility
• 8: Reference
• 8.1: apiVersion Policy
• 8.2: ID Formats
• 8.3: Version Migration
• 8.4: Privacy Tiers
• 8.5: v2 Contracts

1 - Development

This section is the open planning area for processkit v1.0.

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.

Core Documents

• Product Specification
• Architecture Specification
• Ontology Reference
• Tooling Architecture
• Test Strategy
• Alpha Scope
• Landscape Note
• Acceptance Gate

Supporting Analysis

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

1.1 - Product Specification

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

System Role

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

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

Canonical Model

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

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

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

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 live under a source tree
• 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.

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.3 - Ontology Reference

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.4 - Tooling Architecture

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.

Schema Generation

Schema sources live under schemas/src/. Runtime tools consume a flat, committed _generated/*.yaml tree.

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 in processkit tests and CI directly.

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, CI fixtures, and release checks.

1.5 - Test Strategy

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

Test Goals

The v1.0 test strategy must prove:

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

Automated Layers

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
• art-project: a compact first-ART scenario that exercises planning, execution, demo, inspect-and-adapt, decisions, risks, and evidence

These fixtures should run with plain repository commands in CI. aibox can consume the same fixtures in an adapter suite, but the fixtures must not require aibox to exist.

Alpha Proof

Alpha automation should pass before any alpha tag:

• full schema rebuild from 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
• 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 fixture green
• package smoke tests green from release artifact
• aibox adapter test green for a pinned v1.0.0-rc.*
• no known index/schema/migration blocker

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

1.6 - Alpha Scope

Purpose

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

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

Scope

Implement 10-15 high-value concepts covering:

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

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

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

1.7 - Landscape Note

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.8 - Acceptance Gate

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.

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 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
• 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
• 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.9 - 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.9.1 - processkit v1.0 Base Context

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/docs/reference/apiversion-policy.md: apiVersion rules
• docs-site/docs/reference/migration.md: version migration model
• docs-site/docs/reference/v2-contracts.md: v2 entity/projection rules
• docs-site/docs/reference/id-formats.md: ID prefix and format policy
• docs-site/docs/reference/privacy.md: privacy tiers and private dirs
• 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.9.2 - Concept Mapping Briefing Analysis

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.9.3 - processkit v1.0 RFC Analysis

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.9.4 - OKF Compatibility Analysis

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.9.5 - processkit v1.0 Start Assessment

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.

2 - Getting Started

processkit is consumed by agent harnesses and project tooling. You can install it manually from a release tarball, or let an installer such as aibox do the copying and harness wiring for you.

The minimal workflow is:

1. Install a processkit release into your project’s context/ tree.
2. Pick a package tier (minimal, managed, software, research, or product).
3. Register processkit-gateway with your MCP-capable harness.
4. Use MCP tools for entity reads and writes instead of editing project memory by hand.

See Installing for concrete commands.

What gets installed

A processkit release contains:

• context/skills/ — the shipped skill catalog and per-skill MCP servers.
• context/skills/_lib/processkit/ — shared Python runtime helpers used by the MCP servers and gateway.
• context/schemas/ — the 16 shipped v2 project-memory schemas.
• context/state-machines/ — implementation contracts used by entity management tools.
• .processkit/ — package tier metadata and release metadata.
• AGENTS.md — a provider-neutral agent entry point.

Your project then owns its local memory under directories such as context/workitems/, context/decisions/, context/artifacts/, context/notes/, and context/logs/.

Managed install path

Managed installers can add devcontainer lifecycle, harness config, and upgrade handling. aibox is the reference managed integration today: it can fetch a pinned processkit release, choose a package tier, write MCP config for the selected harness, and optionally supervise the gateway daemon.

That is convenience infrastructure. The same installed processkit files can also be used directly by Claude Code, Codex, OpenCode, Hermes, Aider integrations, or a custom MCP client when those tools are configured manually.

Requirements

• Python 3.10 or newer.
• uv, used to run the Python MCP server scripts and resolve their inline PEP 723 dependencies.
• An MCP-capable harness if you want tool access. You can still read the skills and schemas directly without MCP.
• Docker or OrbStack only if your chosen environment manager uses a devcontainer.

Learning path

1. Read Primitives → Overview to understand the durable entity model.
2. Read Primitives → Format to learn the entity file shape.
3. Read Skills → Overview to learn what skills do.
4. Pick a package (Packages → Overview ).
5. Create your first entity .

2.1 - Installing

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

Manual install

Download and unpack the release tarball:

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

Copy the shipped files into your project:

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

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

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

For a long-running local daemon:

uv run context/skills/processkit/processkit-gateway/mcp/server.py \
  serve --transport streamable-http --host 127.0.0.1 --port 8000 --path /mcp

For harnesses that only support stdio, connect to that daemon through the included proxy:

uv run context/skills/processkit/processkit-gateway/mcp/server.py \
  stdio-proxy --url http://127.0.0.1:8000/mcp

Per-skill MCP servers

You can also register individual MCP servers when you want a smaller tool surface or per-server permissions:

uv run context/skills/processkit/workitem-management/mcp/server.py
uv run context/skills/processkit/decision-record/mcp/server.py
uv run context/skills/processkit/index-management/mcp/server.py

Use the gateway for the normal one-process setup. Use per-skill servers when your harness or security model benefits from narrower registration.

Managed install

aibox can install and wire processkit automatically for managed devcontainer projects:

[processkit]
source = "https://github.com/projectious-work/processkit.git"
version = "v0.25.1"

[context]
packages = ["managed"]

In that mode aibox fetches the pinned processkit release, installs the selected package tier, writes harness MCP configuration, and records the resolved source in aibox.lock.

This path is optional. processkit remains usable anywhere the files can be installed and the MCP server command can be launched.

Package tiers

The shipped tiers are:

• minimal — smallest useful context for individual work.
• managed — default team context with backlog, decisions, scopes, handovers, release, and documentation workflows.
• software — engineering-heavy production software workflows.
• research — data, ML, and research-heavy workflows.
• product — product, design, frontend, and product-ops workflows.

See Packages for details.

Verify

Run the docs build and MCP smoke test from a processkit checkout:

./scripts/check-docs-local.sh
uv run scripts/smoke-test-servers.py

Inside a consuming project, use your installer’s validation command if one is available, and prefer processkit MCP tools for entity writes so schema validation and LogEntry side effects happen automatically.

2.2 - Your First Entity

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

Prerequisites

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

Creating a WorkItem by hand

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

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

## Acceptance criteria

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

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

Transitioning

When you start the task, update spec.state:

spec:
  state: in-progress
  started_at: 2026-04-06T10:15:00Z

and ideally write a LogEntry to context/logs/:

---
apiVersion: processkit.projectious.work/v1
kind: LogEntry
metadata:
  id: LOG-started-first-task
  created: 2026-04-06T10:15:00Z
spec:
  event_type: workitem.transitioned
  timestamp: 2026-04-06T10:15:00Z
  actor: ACTOR-you
  subject: BACK-first-task
  subject_kind: WorkItem
  summary: "Started work on BACK-first-task"
  details:
    from_state: backlog
    to_state: in-progress
---

When you finish the task, transition to done and write another LogEntry.

Doing this via an agent

If you use an MCP-capable agent, ask:

“Create a WorkItem for the task ‘Walk through the processkit onboarding’ and log its creation.”

The workitem-management skill tells the agent what shape to produce. The agent can call the workitem-management MCP server directly:

create_workitem(title="Walk through the processkit onboarding", type="task")
→ BACK-calm-fox

and the server validates the schema, writes the file, and logs the event automatically.

Next

• Explore the primitives to see the durable entity model.
• Browse the skill catalog to see what else the agent can do.

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.

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
    - Documentation build green
    - First public deploy complete
  parent: SCOPE-20260410_q2-2026
---

Notes

• Attach WorkItems to a Scope via a scope field on the WorkItem, or via a work-assignment Binding when richer tracking is needed.
• Scope hierarchy (quarter → sprint) is modelled via the parent field.
• transition_scope to active when work begins; to completed when the scope closes — this timestamps the lifecycle automatically.

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

Notes

• Gates define what to check; the evaluation happens externally (by an agent, CI, or human). Log the result with log_event using event_type: gate.passed, gate.failed, or gate.waived.
• evaluate_gate runs the validator_command (if set) and logs the result in one call.
• Advisory gates (blocking: false) surface warnings without halting the process.
• Attach gates to concrete v2 surfaces via workitem-gate or scope-gate Bindings. Legacy process-gate Bindings are migration-only.

3.15 - Migration

A pending, in-progress, or applied transition between two upstream processkit versions. Migrations are generated by aibox sync and represent the delta an agent must apply to bring the project’s context/ up to date.

State machine

pending → in-progress → applied
                      ↘ rejected

applied and rejected are terminal.

Fields

Required

Optional

The migration-management MCP server manages migration state transitions and provides migrate_context_to_v2(dry_run=true) for the breaking v2 API conversion path.

affected_files classification values

Example

---
apiVersion: processkit.projectious.work/v1
kind: Migration
metadata:
  id: MIG-20260411_0913-BrightHaven-v0-11-1-to-v0-12-0
  created: '2026-04-11T09:13:00Z'
spec:
  source: processkit
  from_version: v0.11.1
  to_version: v0.12.0
  state: applied
  summary: Add artifact-management skill and MCP server
  applied_at: '2026-04-11T06:40:00Z'
  applied_by: ACTOR-claude
---

Notes

• Migrations live under context/migrations/pending/ until applied, then move to context/migrations/applied/.
• aibox sync generates migrations automatically by diffing PROVENANCE.toml across versions.
• conflict files require human review — the agent drafts options in the plan field but should not apply them unilaterally.
• See Reference → Migration for the full migration model.

3.16 - Schedule

Legacy v1 time-based trigger or recurring cadence. In the SmoothTiger/SmoothRiver v2 direction, processkit no longer presents Schedule as a first-class shipped entity surface. Use Binding(type=time-window) with conditions.recurrence_rule for the durable contract; an external runner still performs execution.

v2 replacement

Use the binding-management server’s create_time_window path for time windows. pk-doctor’s v2_contracts check requires Binding(type=time-window) records to include conditions.recurrence_rule.

Fields

Required

Optional

Example

---
apiVersion: processkit.projectious.work/v1
kind: Schedule
metadata:
  id: SCHED-20260411_0915-CalmGlen-weekly-standup
  created: '2026-04-11T09:15:00Z'
spec:
  name: weekly-standup
  description: Fire the standup-context skill every Monday morning.
  cadence: weekly
  cron: "0 9 * * 1"
  timezone: Europe/London
  triggers:
    - kind: skill
      skill: standup-context
  active: true
---

Notes

• Legacy v1 Schedule records are documentation for migration only. In v2, an external runner reads Binding(type=time-window) records and fires the target at the right time.
• last_run and next_run are advisory fields set by the runner — not enforced by processkit on legacy records.
• Scope a recurring cadence by binding the governed WorkItem, Artifact, or Scope through type: time-window; do not create new schedule-scope Bindings.

3.17 - Constraint

An explicit rule or limit the project must respect — budget ceiling, latency SLO, regulatory requirement, team capacity cap. Violations are LogEntries; constraints themselves do not change when violated.

Fields

Required

Optional

Severity levels

Example

---
apiVersion: processkit.projectious.work/v1
kind: Constraint
metadata:
  id: CONST-20260411_0916-SteadyMoss-api-latency-slo
  created: '2026-04-11T09:16:00Z'
spec:
  name: api-latency-slo
  description: MCP tool round-trip p99 latency must stay below 200ms.
  kind: slo
  severity: hard
  target: "< 200ms p99"
  measurement: |
    Measured via the observability pipeline from tool-call dispatch to
    server response. Alert fires if exceeded for 5 minutes.
  source: Customer SLA — contract clause 4.2
  related_decisions:
    - DEC-20260409_latency-slo-accepted
---

Notes

• Constraint violations are logged via log_event with event_type: constraint.violated — the Constraint entity itself is not modified.
• A hard constraint violation should surface as a blocked WorkItem or an urgent Discussion.
• Bind a Constraint to a Scope via a constraint-scope Binding to make it scope-specific rather than project-wide.
• Set active: false when a constraint is no longer in effect (SLA renegotiated, regulatory exemption granted).

3.18 - Category

A classification axis with a closed set of allowed values — priority levels, bug severity tiers, product areas. Use Category when the valid values are defined and enforced; use freeform labels for open-ended tagging.