# Context Overview

LLMS index: [llms.txt](/aibox/v1.x/llms.txt)

---

# 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](https://github.com/projectious-work/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.

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

With the default `context.mode = "processkit"` and a real
`[processkit].version` pinned, your project looks something like this after
`aibox init` and `aibox apply`:

```
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.27.4/            # Immutable upstream snapshot, base of three-way diffs
```

With `context.mode = "harness-only"`, aibox writes only the container and
harness surfaces:

```
my-project/
├── AGENTS.md                       # Minimal project instructions generated by aibox
├── CLAUDE.md                       # Thin pointer to AGENTS.md when Claude is enabled
├── aibox.toml
├── .aibox-home/
└── .devcontainer/
```

Harness-only mode intentionally omits processkit content, processkit MCP
gateway config, processkit hooks/preauth, processkit command adapters, and
processkit Migration entities. Generated text surfaces contain no processkit
references.

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

`AGENTS.md` at the project root is the **canonical** agent entry document. It
is either rendered from the processkit template (`context.mode = "processkit"`)
or generated as a minimal aibox-owned file (`context.mode = "harness-only"`).
It is write-if-missing during `aibox init`; aibox does not overwrite local
edits. The [agents.md](https://agents.md/) ecosystem convention is to read
this file from any AI harness.

When Claude is enabled in `[ai].harnesses`, aibox also writes a thin
`CLAUDE.md` at the project root that points at `AGENTS.md`. In processkit mode,
command adapters are projected into 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. In
harness-only mode, only the pointer is written.

## 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 and are only installed when
`context.mode = "processkit"`. For full documentation on what's available, how
skills are organised, and which packages to use, see:

- [Skills](../skills/index.md) — how skills install and how to browse them
- [Process Packages](process-packages.md) — package tiers and selection
- [processkit on GitHub](https://github.com/projectious-work/processkit)

## Version Tracking

Resolved versions are split between desired and applied state:

```toml
[context]
mode = "processkit"
packages = ["product"]

[processkit]
version = "v0.27.4"

[processkit.context]
schema_version = "1.0.0"
```

`aibox.toml` declares the desired image and processkit versions. `aibox.lock`
records the CLI version and exact resolved processkit release, checksum, addon
selection, and managed runtime-home state last applied to the project.

When the schema evolves, `aibox doctor` flags version mismatches and `aibox apply`
runs the relevant migrations. See [Migration](migration.md) for details.

## Relationship to aibox.toml

The `[context]` section in `aibox.toml` selects the context mode. The
`[processkit]` section is used only in processkit mode and pins which version
of the content repository this project consumes:

```toml
[context]
mode = "processkit"
packages = ["product"]

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

Run `aibox apply` after editing `[processkit].version` to pull a new release.
For harness-only projects, set only:

```toml
[context]
mode = "harness-only"
```

## Design Principles

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

**Human-readable first.** Context files and root instructions 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, and harness-only instructions are plain root-level Markdown. 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.