Project Context

• 1: Context Overview
• 2: Skill Selection
• 3: Migration

1 - Context Overview

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.

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 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 — how skills install and how to browse them
• Process Packages — package tiers and selection
• processkit on GitHub

Version Tracking

Resolved versions are split between desired and applied state:

[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 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:

[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:

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

2 - Skill Selection

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.

Where the Content Lands

After aibox init and aibox apply with [context].mode = "processkit" and [processkit].version pinned:

context/
├── skills/                              # Editable copies of installed skills
├── processes/                           # release, code-review, feature-development, bug-fix
├── schemas/                             # primitive schemas
├── state-machines/                      # state machine definitions
└── templates/
    └── processkit/
        └── v0.25.7/
            ├── context/
            │   ├── skills/
            │   └── schemas/
            ├── .processkit/
            │   └── packages/            # The package YAMLs themselves
            └── AGENTS.md

The version path (v0.25.7 above) is whatever [processkit].version is pinned to in aibox.toml.

Harness-only projects do not install this content and do not create context/templates/processkit/.

Upstream Source

The skills are owned by processkit:

• Repository: https://github.com/projectious-work/processkit
• Releases: https://github.com/projectious-work/processkit/releases
• Local copy in your project: context/templates/processkit/<version>/.processkit/packages/

To consume a fork or a private mirror, point [processkit].source at it (see [processkit] configuration).

3 - Migration

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.

How Version Tracking Works

Two pieces track the version:

1. aibox.toml contains the target context schema version. Current canonical processkit-mode configs render this under [processkit.context]; [context].schema_version is still accepted for compatibility:

   [processkit.context]
   schema_version = "1.0.0"
   

2. aibox.lock records the aibox CLI/runtime state last applied to the project. Legacy .aibox-version files from older projects are absorbed into aibox.lock and removed by the migration path.

When aibox doctor detects a schema mismatch, it flags the project as needing migration and writes schema review artifacts.

Running Doctor

aibox doctor

Doctor performs the following checks:

• Validates aibox.toml syntax and field values
• Detects the container runtime (podman or docker)
• Checks for .aibox-home/ and .devcontainer/ directories
• Compares the current embedded context schema against the configured target schema version
• Validates expected context/processkit files for the chosen context mode

Example output when migration is needed:

==> Running diagnostics...
 ✓ Config version: 0.1.0
 ✓ Image: python
 ✓ Process: product
 ✓ Container name: my-app
 ✓ Container runtime: podman
 ✓ .aibox-home/ directory exists at .aibox-home
 ✓ .devcontainer/ directory exists
 ! Context schema: current 1.0.0, target 2.0.0 (migration needed)
 ✓ Diagnostics complete

Migration Artifacts

When a schema mismatch is detected, doctor generates review artifacts in .aibox/migration/:

.aibox/
└── migration/
    ├── schema-current.md
    ├── schema-target.md
    ├── diff.md
    └── migration-prompt.md

When processkit content, runtime-home drift, model/provider changes, or similar processkit-mode updates need human review, aibox emits Migration entities in context/migrations/:

context/
└── migrations/
    ├── pending/       # Migrations queued but not yet started
    ├── in-progress/   # Migration currently being applied
    └── applied/       # Completed migrations (archived for reference)

Each processkit Migration is identified by a MIG-ID and lives as a versioned document in the appropriate subdirectory. These Migration entities are managed through the normal resource grammar:

aibox get migration                       # show pending/in-progress migrations
aibox set migration <id> in-progress      # begin a pending migration
aibox apply migration <id>                # mark a migration as applied
aibox delete migration <id> --reason "…"  # reject and archive without applying

Applying a Migration

Strict Schema And Storage Policy

Migrations are the durable fix for schema, vocabulary, filename, ID, and directory-layout drift. A clean project should satisfy the current schemas and storage policy directly, not by carrying project-local compatibility allowlists.

Do not resolve doctor findings by adding legacy_known_* schema entries, doctor suppressions, mixed-layout exceptions, or local notes that accept legacy event names, IDs, filenames, or directory shapes as the steady state. If a schema genuinely needs a new value or layout, introduce that as an explicit schema migration and then migrate existing entities and references to the new standard.

Compatibility shims are acceptable only as short-lived migration aids. Before a migration is marked applied, the repository should contain canonical values, canonical filenames, canonical directory placement, and updated references.

With an AI agent (recommended)

1. Run aibox doctor to identify gaps and queue migration artifacts
2. Run aibox set migration <id> in-progress to begin the next pending migration
3. Open the migration document from context/migrations/in-progress/
4. Paste its contents into a Claude Code session (or let the agent find it via AGENTS.md)
5. Review the changes the agent makes
6. Run aibox apply migration <id> to mark the migration complete

Manually

1. Run aibox doctor to generate migration artifacts
2. Run aibox set migration <id> in-progress to move the migration to context/migrations/in-progress/
3. Follow the migration document’s checklist
4. Run aibox apply migration <id> to archive the migration to context/migrations/applied/

Best Practices

Never auto-migrate content. Structural changes (new files, renames) can be automated. Content changes (rewriting sections, reformatting entries) should always be reviewed by a human or guided AI session.

Migrate forward, do not grandfather. Fix schema and storage drift by moving entities to the current vocabulary, filenames, IDs, and directory layout. Project-local allowlists and doctor suppressions are not acceptable terminal states.

Commit before migrating. Always commit your current state before applying migration changes. This gives you a clean rollback point.

Run doctor after migrating. After applying changes, run aibox doctor again to confirm everything is clean.

Keep aibox.lock in version control. It records the resolved CLI, processkit, addon, and managed runtime state shared by the project. A legacy .aibox-version file is migration input only and is removed by aibox apply.

Schema Document Format

Schema documents in the schemas/ directory define the expected structure for each version. They specify:

• Which files each process flavor should contain
• Required sections within each file
• File naming conventions
• Directory structure requirements

These schemas are used by doctor to validate the project and by migration tooling to compute diffs between versions.