Project Context on aibox

Context Overview

Mon, 01 Jan 0001 00:00:00 +0000

Context System Overview

The aibox context system controls what project-level instructions and structured working memory are available to AI harnesses. It has two modes: processkit, which installs the full structured context layer, and harness-only, which keeps only the generated container and harness setup.

As of v0.16.0, the system is split across two cleanly separated projects:

aibox owns the container — devcontainers, addons, the CLI, the install/apply/migrate machinery, and the project skeleton (aibox.lock, .gitignore, provider pointer files, and, in harness-only mode, a minimal AGENTS.md).
processkit owns the content — every skill, every primitive schema, every state machine, the canonical AGENTS.md template, the processes, and the package YAMLs that compose them.
The user-side context/ directory is shared territory in processkit mode. aibox creates it, processkit fills it, and the user edits in place. An immutable upstream snapshot is kept under context/templates/processkit/<version>/ for the three-way diff that aibox apply uses to detect upstream changes versus local edits.

The Problem

AI coding agents like Claude operate best when they understand not just the code, but the project’s goals, decisions, and current state. Without structure, this information ends up scattered across chat histories, stale comments, and the developer’s memory.

Skill Selection

Mon, 01 Jan 0001 00:00:00 +0000

Skill Selection

New aibox projects list the standard processkit operating skills explicitly in [skills].include. This makes skill selection a direct comment/uncomment workflow in aibox.toml without relying on legacy package tiers.

Use [skills].include for explicit additions and [skills].exclude for explicit removals:

[skills]
include = [
 "pk-doctor",
 "status-briefing",
]
exclude = [
 # "skill-to-omit",
]

Legacy package tiers (minimal, managed, software, research, product) are still accepted for compatibility under [context].packages when [context].mode = "processkit", but explicit [skills] selection is the preferred control surface.

Migration

Mon, 01 Jan 0001 00:00:00 +0000

Migration

When the aibox context schema evolves between versions, existing projects may need to update their context files. The aibox doctor command helps identify schema gaps and produces review artifacts under .aibox/migration/.

Separate processkit content and generated-runtime changes are surfaced as Migration entities under context/migrations/ in processkit mode.

v0.16.0 — `context/AIBOX.md` is gone

Pre-v0.16 releases generated a context/AIBOX.md “universal baseline” file on every aibox apply. That file has been removed as part of the aibox⇄processkit split. The canonical agent entry document is now AGENTS.md at the project root. In processkit mode it is rendered from processkit scaffolding; in harness-only mode it is a minimal aibox-owned file. In both modes aibox init writes it only when missing.