processkit v1.0 Base Context

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

Created: 2026-07-04

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

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

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

Current Guiding Briefing

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

Conflict rule:

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

Current Repository Status

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

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

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

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

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

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

Stable Product Target

The first processkit version defines processkit as:

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

The stable target should not change:

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

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

Shipped Deliverable Boundary

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

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

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

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

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

Consumer Usage Model

Consumers can use processkit manually or through a manager.

Manual use:

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

aibox-assisted use:

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

The old README names three MCP layouts:

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

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

Package Tiers

The original package model has five tiers:

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

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

Entity and Contract Model

The stable entity model is Markdown files with YAML frontmatter:

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

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

Important v2 contract points:

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

MCP and Indexing Principles

The old project converged on these operational rules:

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

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

Provider and Model Neutrality

Provider neutrality is a core invariant, not a convenience.

The old decisions establish:

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

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

Team and Role Model

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

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

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

Release and Migration Model

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

Stable release expectations:

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

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

Documentation Surface

The first version had two user-facing documentation surfaces:

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

The most important stable docs topics are:

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

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

Current Gap Summary

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

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

It does not yet have:

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

Base-Context Readiness Audit

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

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

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

Improvement Surface for Later Briefing

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

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

Likely redesign areas for processkit v1.0:

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

Evidence Index

Primary evidence from the original repository:

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

High-signal historical decisions:

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