Skip to main content
This page records the accepted adaptive-workspace contract for Fleet Pi. It defines the canonical durable state, the manifest and section boundaries, and the non-canonical projection layer that may accelerate queries but never replaces files. The contract is implemented in apps/web/src/lib/workspace/workspace-contract.ts and is currently at WORKSPACE_CONTRACT_VERSION = 1.

​
Canonical boundary

agent-workspace/ is the canonical durable adaptive state.
  • Durable memory, skills, plans, evals, and artifacts remain path-backed files.
  • Workspace-installed Pi resources and policy material follow the same rule: reviewable files win over caches, rows, or hidden runtime state.
  • scratch/ is non-canonical temporary space. It can hold disposable working files, but it is not durable adaptive memory.
  • agent-workspace/indexes/ stores non-canonical projection data. Projection rows may accelerate search, health, provenance, or query flows, but canonical files still decide what Fleet Pi knows.

​
Accepted workspace shape

agent-workspace/
├── manifest.json
├── instructions/
├── system/
├── memory/
│   ├── daily/
│   ├── project/
│   └── research/
├── plans/
│   ├── active/
│   ├── completed/
│   └── abandoned/
├── skills/
├── evals/
├── artifacts/
│   ├── reports/
│   ├── datasets/
│   ├── traces/
│   └── diagrams/
├── scratch/
│   └── tmp/
├── pi/
│   ├── skills/
│   ├── prompts/
│   ├── extensions/
│   │   ├── enabled/
│   │   └── staged/
│   └── packages/
└── indexes/
agent-workspace/manifest.json describes the workspace shape and the versioned policy of the adaptive layer. Bootstrap may seed missing artifacts later, but the names and semantics of the sections above are fixed.

​
Section families and kinds

Every top-level section has a kind that the workspace server enforces:
SectionKindPurpose
instructions/canonicalDurable orientation and operational guidance that survives sessions.
system/canonicalWorkspace policy and system-level instructions (e.g., workspace-policy.md).
memory/canonicalDurable project knowledge, daily notes, and research.
plans/canonicalExplicit execution plans and backlog state (active/, completed/, abandoned/).
skills/canonicalRepo-local agent skills and supporting examples/evals.
evals/canonicalChecklists, scorecards, and regression-oriented evaluation material.
artifacts/canonicalDurable reports, datasets, traces, and reusable outputs.
pi/canonicalWorkspace-installed Pi skills, prompts, extensions, and packages.
scratch/temporaryDisposable working files only — never durable memory.
indexes/projectionProjection / query state only — never canonical.
The canonical kinds are exported as WORKSPACE_SECTION_KINDS = ["canonical", "temporary", "projection"].

​
Workspace-installed Pi resources

The canonical home for chat-installed Pi resources is inside agent-workspace/pi/:
  • agent-workspace/pi/skills
  • agent-workspace/pi/prompts
  • agent-workspace/pi/extensions (with enabled/ and staged/ subdirectories)
  • agent-workspace/pi/packages
These directories stay canonical because the installed resource itself is a reviewable file or directory in the repository.

​
Workspace policy files

The contract seeds a small set of policy files when missing. The current default is system/workspace-policy.md, which states:
agent-workspace/ is Fleet Pi’s canonical durable adaptive state. Bootstrap should preserve user-authored files.
Bootstrap never overwrites user-authored content. It only fills in absent canonical paths and the manifest.

​
.pi/settings.json compatibility bridge

.pi/settings.json remains the compatibility bridge between the Pi runtime and workspace-native resources. It may point Pi at agent-workspace/pi/*, but it does not replace the workspace as the durable store. That means:
  • Committed .pi/ configuration can keep loading project-local built-ins.
  • Workspace-installed resources still live under agent-workspace/pi/.
  • Changing the bridge must not imply changing where the canonical resource content lives.

​
Non-regression rules

  • Never promote indexes/ rows above canonical files.
  • Never treat session state as durable memory.
  • Never write durable memory outside of the section families above.
  • Bootstrap, health, indexing, and query surfaces must remain projections — they read canonical files, they do not replace them.
  • Existing canonical files under agent-workspace/ remain authoritative until bootstrap and indexing milestones land.

Agent workspace

Human-facing tour of what lives in agent-workspace/.

Architecture

How the workspace, web app, and Pi runtime fit together.

Runtime SDK seams

Safe extension points for workspace bootstrap, indexing, and provenance.

Chat modes

workspace_write and resource_install in Harness mode.