Getting Started

• 1: Installing
• 2: Your First Entity

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