Project Manifest Reference

Each project context pack is described by an aiw.project.json file at the root of the context pack.

The manifest defines project identity, storage paths, connectors, code locations, and AI client preferences. Paths are relative to the context pack unless explicitly absolute.

Minimal Manifest

{
  "schema": "aiworkspace.project.v1",
  "id": "my-project",
  "display_name": "My Project",
  "knowledge_dir": "knowledge",
  "inbox_dir": "inbox"
}

Full Example

{
  "schema": "aiworkspace.project.v1",
  "id": "client-mobile",
  "display_name": "Client Mobile",
  "description": "Project context pack for a mobile application team.",
  "knowledge_dir": "knowledge",
  "inbox_dir": "inbox",
  "connectors_dir": "connectors",
  "prompts_dir": "prompts",
  "agents_dir": "agents",
  "connectors": {
    "mattermost": {
      "enabled": true,
      "config": "connectors/mattermost.json"
    },
    "photos": {
      "enabled": true,
      "config": "connectors/photos.json"
    }
  },
  "code_locations": [
    {
      "name": "Development machine",
      "availability": "remote-machine"
    }
  ],
  "ai_clients": {
    "opencode": {
      "enabled": true
    },
    "copilot": {
      "enabled": true
    }
  }
}

Fields

Field	Required	Description
`schema`	yes	Manifest schema version. Current target: `aiworkspace.project.v1`.
`id`	yes	Stable lowercase project id used by CLI and MCP.
`display_name`	yes	Human-friendly project name.
`description`	no	Short project description.
`knowledge_dir`	yes	Canonical Markdown memory directory.
`inbox_dir`	yes	Raw evidence directory.
`connectors_dir`	no	Directory for connector configs. Defaults to `connectors`.
`prompts_dir`	no	Directory for project prompts. Defaults to `prompts`.
`agents_dir`	no	Directory for project agent config. Defaults to `agents`.
`connectors`	no	Connector registry for this project.
`code_locations`	no	Local or remote code locations associated with this project.
`ai_clients`	no	AI client integration preferences.

Code Locations

Code may be local, remote, or unavailable on the current machine.

{
  "name": "iOS App",
  "path": "/Users/dev/Developer/app-ios",
  "role": "consumer-app",
  "availability": "local"
}

Supported target availability values:

local
remote-machine
not-configured
unknown

Connector Configs

Connector definitions should describe source behavior without storing secrets.

Example connectors/mattermost.json:

{
  "schema": "aiworkspace.connector.mattermost.v1",
  "enabled": true,
  "context_channels": [
    "team-standup",
    "team-code-review"
  ],
  "secret_refs": {
    "session": "keychain:aiworkspace/mattermost/session"
  }
}

Validation Rules

A production-ready manifest validator should check:

required fields exist;
project id is stable and path-safe;
configured directories exist or can be created;
connector config files exist when enabled;
secrets are referenced, not embedded;
code locations are explicit about local vs remote availability.

3.1 KiB Raw Blame History