Skip to main content

Context System Overview

The aibox context system gives AI agents the structured, file-based information they need to work effectively on your project — backlog, decisions, standups, processes, primitives, and skills.

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 slim project skeleton (.aibox-version, .gitignore, an empty context/, and a thin CLAUDE.md pointer).
  • 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. 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.

A single root-level instructions file is not enough for non-trivial projects. It works well for instructions and preferences, but it does not provide a standard place for decisions, backlog, progress tracking, or team conventions.

How Context Files Work​

After aibox init and aibox apply (with a real [processkit].version pinned), your project looks something like this:

my-project/
├── AGENTS.md                       # Canonical agent entry — rendered from processkit scaffolding
├── CLAUDE.md                       # Thin pointer to AGENTS.md (provider entry file)
├── aibox.toml
├── .devcontainer/
└── context/
    ├── skills/                     # Editable skill copies
    ├── processes/                  # release, code-review, feature-development, bug-fix
    ├── schemas/                    # primitive schemas
    ├── state-machines/             # state machine definitions
    └── templates/
        └── processkit/
            └── v0.26.15/           # Immutable upstream snapshot, base of three-way diffs

AGENTS.md, CLAUDE.md, and provider files​

AGENTS.md at the project root is the canonical agent entry document. It is rendered from the processkit template (AGENTS.md at the processkit tarball root) during aibox init (write-if-missing — never overwrites). The agents.md ecosystem convention is to read this file from any AI harness.

When [ai.harness.claude] enabled = true, aibox also writes a thin CLAUDE.md at the project root that just points at AGENTS.md. Processkit command adapters are projected into the enabled harness surfaces, including .claude/skills/<name>/SKILL.md for Claude Code. Canonical skill content still lives under context/skills/; provider-specific files are generated shims.

OWNER.md — Developer Identity​

OWNER.md captures the developer's identity and preferences. It is created during aibox init (or by the owner-profile skill the first time the agent asks), with fields that help AI agents understand who they are working with:

  • Name — how the developer prefers to be addressed
  • Domain expertise — areas of knowledge and experience
  • Primary languages — programming languages used most often
  • Communication language — natural language for responses (e.g., English, German)
  • Timezone — for scheduling and availability context
  • Working hours — typical availability window
  • Current focus — what the developer is currently working on or learning
  • Communication preferences — style and conventions for AI interactions

Skills and Processes​

Skills and processes are owned by processkit. For full documentation on what's available, how skills are organised, and which packages to use, see:

Version Tracking​

Two pieces track the version:

[aibox]
version = "0.23.0"

[processkit.context]
schema_version = "1.0.0"

[processkit]
version = "v0.26.15"

When the schema evolves, aibox doctor flags version mismatches and aibox apply runs the relevant migrations. See Migration for details.

Relationship to aibox.toml​

The [processkit.context] section in aibox.toml declares context schema metadata. The [processkit] section pins which version of the content repository this project consumes:

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

Run aibox apply after editing [processkit].version to pull a new release.

Design Principles​

Convention over configuration. File names and locations are standardised so AI agents can find them without special instructions.

Human-readable first. All context files are Markdown. They are useful without any tooling.

Editable in place. Everything under context/skills/, context/processes/, context/schemas/, and context/state-machines/ is yours to edit. The immutable snapshot under context/templates/processkit/<version>/ exists only as the base of aibox apply's three-way diff.

No lock-in. Context files are plain Markdown and YAML in a context/ directory. Stop using aibox and the files remain useful.

Clean boundary between container and content. aibox owns the box; processkit owns what goes in it. Each ships on its own cadence.