CONTRIBUTING.md

Contributing to processkit

Thank you for working on processkit. This file is the operating manual for everyone — humans and AI agents — who contributes content to this repo.

Repository orientation (read first)

• README.md — what processkit is, the bootstrap loop with aibox
• AGENTS.md — canonical agent entry point (provider-neutral), including the critical "two meanings of skills/processes" disambiguation. CLAUDE.md is a thin pointer to this file.
• context/HANDOVER.md — current state, recent changes, deep briefing
• context/PRD.md — product requirements derived from aibox DISC-002
• src/INDEX.md — the rule: everything under src/ is shipped content; src/ mirrors a fresh consumer project root
• src/.processkit/FORMAT.md — the entity file format spec
• src/context/skills/FORMAT.md — the skill package format spec
• docs-site/ — user-facing docs, published to GitHub Pages

The golden rule

Everything under src/ is shipped to consumers. Everything outside src/ is about THIS repo itself.

Do not put repo-internal stuff under src/. Do not put shipped content outside src/. The two halves never mix.

Style: line widths

Hard-wrap markdown prose, Python, and YAML at 80 columns.

Smart exemptions (enforced by author judgment, not by tooling):

• Tables: rows may be wide; wrap only between rows, never inside.
• Fenced code blocks: preserve as-is; the language decides.
• URLs and link references: do not break URLs; the line containing one may exceed 80.
• YAML frontmatter in markdown: exempt.
• TOML files (PROVENANCE.toml, aibox.toml): exempt; some are machine-generated.

The rule is encoded in .editorconfig at the repo root for editors that respect it. There is no automated enforcement yet — it is applied to new and edited content. The 85 migrated skills under src/skills/ and the docs-site catalog pages predate the rule and will be wrapped as part of BACK-001 / BACK-009.

Developing inside the dev container

# From the host
aibox start                  # opens the processkit dev container
# inside the container
cd /workspace
ls src/                      # AGENTS.md, context/, .processkit/, INDEX.md, PROVENANCE.toml

The dev container is generated by aibox 0.14.1 (pinned in aibox.toml). Do not upgrade the aibox version pin without coordinating with the aibox team — see the bootstrap loop discussion in README.md.

Smoke-testing the MCP servers

A standalone smoke test (no MCP transport, just direct function calls) lives at scripts/smoke-test-servers.py. It creates a temp project, exercises every server's tools end-to-end, and asserts results.

uv run scripts/smoke-test-servers.py

This is the fastest feedback loop while editing servers or the lib. For real MCP-protocol testing, use any MCP-capable client (Claude Code, the mcp CLI's dev command, etc.).

Adding a new skill

1. Decide the category (process, language, framework, ...) and layer (null for technical skills, 0–4 for process-primitive skills).
2. Create src/context/skills/<skill-name>/SKILL.md with the frontmatter from src/context/skills/FORMAT.md. Use the three-level structure:
   • Level 1 — 1–3 sentences
   • Level 2 — key workflows
   • Level 3 — full reference
3. Add templates/ for entity scaffolds and examples/ for example outputs.
4. If the skill ships an MCP server, add mcp/server.py, mcp/mcp-config.json, and mcp/README.md.
5. If the skill is a process-primitive skill that should appear in a package tier, add it to src/.processkit/packages/managed.yaml (or higher).
6. Update src/context/skills/INDEX.md if appropriate.
7. Add the skill to docs-site/sidebars.js under the right catalog page if it deserves a docs entry.

Adding a new primitive

1. Add src/context/schemas/<kind-lowercase>.yaml (a Schema entity with spec.spec_schema = JSON Schema for the primitive's spec).
2. Update src/.processkit/primitives-INDEX.md and src/.processkit/FORMAT.md kind registry table.
3. Update src/context/skills/_lib/processkit/__init__.py KIND_PREFIXES and DEFAULT_DIRS.
4. If the primitive has lifecycle, add a state machine at src/context/state-machines/<name>.yaml.
5. Add a management skill at src/skills/<kind>-management/ (Layer 1–4 depending on dependencies).
6. Optionally ship an MCP server (mcp/server.py).
7. Update docs-site/docs/primitives/overview.md.

Adding a new MCP server

1. Create src/context/skills/<skill>/mcp/server.py using the boilerplate from any existing server (e.g. event-log/mcp/server.py).
2. The first ~30 lines are the _find_lib() helper — copy verbatim.
3. Use from processkit import ... to access shared utilities.
4. Register tools with @server.tool() decorators.
5. Add mcp-config.json and README.md.
6. Extend scripts/smoke-test-servers.py to exercise the new tools.
7. Add a section to docs-site/docs/mcp-servers/overview.md.

Foundation dependencies

If your server creates new entities, declare both Layer 0 foundation skills in the SKILL.md frontmatter:

spec:
  uses: [event-log, ..., index-management, id-management]

In server code, the standard pattern is:

db = index.open_db()
try:
    existing = index.existing_ids(db, "WorkItem")
finally:
    db.close()

new_id = ids.generate_id(
    "WorkItem",
    format=cfg.id_format,
    slug_text=title if cfg.id_slug else None,
    existing=existing,
)
ent = entity.new("WorkItem", new_id, spec)
ent.write(target)

db = index.open_db()
try:
    index.upsert_entity(db, ent)
finally:
    db.close()

Servers call into processkit.ids and processkit.index directly via the lib, not via the id-management/index-management MCP tools — the lib is the implementation; the MCP tools are agent-facing wrappers around the same code.

Working with the shared library

src/context/skills/_lib/processkit/ is internal infrastructure. Public modules:

• entity — read/write entity files
• frontmatter — YAML frontmatter parsing
• ids — ID generation (word/uuid × slug)
• paths — find project root, resolve directories
• schema — load schemas, validate spec
• state_machine — load + validate state machines
• config — read aibox.toml
• index — SQLite indexer

Changes to the lib affect every MCP server. Run the smoke test after any non-trivial change.

Releasing

processkit releases via semver git tags. The current cadence:

Tag	Theme
v0.1.0	Foundation — format spec, 3 schemas, 2 state machines
v0.2.0	Skill migration — 101 skills, 5 packages, docs-site bootstrap
v0.3.0	MCP servers — 6 foundation servers, SQLite index, shared lib
v0.4.0	Current — Migration primitive, owner-profiling, context-grooming, PROVENANCE.toml, configurable upstream source, privacy tiers
v1.0.0	First stable release (not yet scheduled)

To release a new tag:

1. Update context/HANDOVER.md (preamble for the new version)
2. Update context/BACKLOG.md Done section
3. Update docs-site if user-visible changes shipped
4. Run uv run scripts/smoke-test-servers.py and confirm green
5. Run scripts/stamp-provenance.sh vX.Y.Z (regenerates src/PROVENANCE.toml)
6. git tag -a vX.Y.Z -m "..."
7. git push origin main && git push origin vX.Y.Z
8. Build and upload the release-asset tarball:

   scripts/build-release-tarball.sh vX.Y.Z
   gh release upload vX.Y.Z \
       dist/processkit-vX.Y.Z.tar.gz \
       dist/processkit-vX.Y.Z.tar.gz.sha256

   This is the preferred consumption path for aibox (DEC-025); aibox falls back to a git fetch if the asset is missing.
9. Publish the documentation site to GitHub Pages:

   scripts/publish-docs-gh-pages.sh vX.Y.Z

   The script builds docs-site/ locally and pushes the generated static site to the gh-pages branch. Do not add a GitHub Actions workflow for this; processkit publishes docs as an explicit local release step.

Backlog and tracked work

Known deferred items live in context/BACKLOG.md. When starting a new piece of work, add an entry there first; when finishing it, mark it done. Use the workitem-management MCP server for richer tracking once you have data to track.

Coordination with aibox

aibox and processkit are pinned to specific versions of each other:

• aibox.toml here pins aibox 0.14.1
• aibox (from the version that consumes processkit) pins a processkit tag

Upgrading the aibox pin in this repo requires coordination — the new aibox version must still work with the processkit version it tries to consume. See README.md for the bootstrap loop.

Improvements from derived projects

When a processkit consumer (any project using processkit via aibox or a manual install) finds a behavioral gap or content improvement in a processkit-installed file, they can contribute it back:

1. Fix locally first. Edit the file directly under context/ in the consumer project. The templates mirror at context/templates/processkit/<version>/ provides the diff baseline — three-way merge at next aibox sync will preserve the local edit.
2. Decide whether to file upstream. Is the improvement project-specific, or would it benefit every processkit consumer? If general, open a Discussion entity locally (kind: upstream-proposal) then file a GitHub issue at projectious-work/processkit.
3. What makes a good upstream issue. Include: the file changed, the specific failure mode it addresses, the proposed fix text, and whether the fix was validated in a real session. Issues with a concrete reproduction ("agent said X, then didn't do Y") are faster to act on than abstract suggestions.

Maintainers will review and, if accepted, merge the improvement into the appropriate src/ file so all consumers benefit at the next release.

Style notes

• Markdown: GitHub-flavored. Tables wherever they help. Code fences with language tags.
• YAML: 2-space indent, no tabs. Strings quoted only when necessary.
• Python: PEP 8, type hints in public APIs, from __future__ import annotations.
• Skill descriptions: one-sentence imperative. "Manage X." not "This skill manages X."
• No emojis in shipped content unless the user explicitly asks.