Cloud Collaboration Domain Model

This document defines the cloud collaboration concepts shared by Wework and Wegent. The product exposes one Workspace, Project, Member, Agent, Issue, and Run model while continuing to reuse the existing Wegent Team, Bot, Ghost, Shell, Model, and Task execution facilities.

This is a target domain model. It does not replace the established sources of truth and execution wiring in Cloud Project Collaboration Architecture.

See Collaboration Workspace Storage Model for the concrete table mapping and relationship rules.

Core terminology

Product concept	Definition
`Workspace`	The long-lived tenant boundary for members, permissions, agents, devices, integrations, and shared resources
`Project`	A container inside a Workspace that organizes work around a product, business objective, or delivery
`Member`	A human or agent that can receive notifications, collaborate, or initiate execution
`Agent`	A machine member that can receive an Issue and produce a Run
`Issue`	A durable unit of work that can be discussed, advanced, reviewed, and accepted
`Run`	One bounded attempt by an Agent to execute an Issue
`Runtime`	An environment on a device that can execute a required Shell and capability set
`Deliverable`	A verifiable result submitted for an Issue by a human or Agent
`View`	A board, list, table, or other presentation of the same Issues in a Project

The product path is fixed:

Workspace
└── Project
    └── Issue
        ├── Assignments: Human | Agent
        └── Runs
            ├── Agent
            ├── Initiator
            ├── Runtime
            ├── Execution Workspace
            └── Deliverables

Workflow and Automation may create, assign, organize, or trigger Issues and Runs. They must not form an independent task and execution model.

Workspace and Project

Workspace owns shared people and capabilities:

members, roles, and permissions;
Agents, Teams, and capability definitions;
Devices, Runtimes, and execution access;
GitHub, GitLab, IM, and other integrations;
repository registries, workflow templates, and automation templates;
cross-Project search, analytics, quotas, and audit.

Project organizes a concrete body of work:

Issues, comments, attachments, and deliveries;
the Project member scope and enabled Agents;
statuses, fields, and Views;
Project resources, Workflows, and Automations;
Project-level execution-policy overrides.

The existing CloudProject directly implements Project and should no longer be presented as a collaboration Workspace. A real Workspace must be added above it. The current board is only the default Project View:

Workspace
└── Project (CloudProject)
    ├── View: Board
    ├── View: List
    ├── View: Table
    └── Issues (LoopItem)

Member, Assignment, and Execution

Member is the common collaboration actor:

Member
├── Human
└── Agent

Issues, Workflow nodes, and dispatchers use the same MemberRef:

type MemberRef = { type: "human"; id: string } | { type: "agent"; id: string };

Assignment means directed notification, attention, and a request for action. It does not grant exclusive execution rights and is not required to start work:

Issue
├── Assignments: 0..N MemberRef
└── Runs: 0..N

An Issue may be assigned to multiple Humans or Agents.
Assigning a Human adds the Issue to that person's notifications and work list.
Assigning an Agent may trigger a Run according to Project policy or may only notify it until an explicit start.
An unassigned Member with Project execution permission may still start work, comment, or submit Deliverables for the Issue.
Assignment neither grants Issue access nor blocks other Members from working.

A machine Run independently records who initiated it and which Agent executes it:

Run
├── initiated_by: Human | Agent | Automation
├── agent_id
├── runtime_id
└── trigger: manual | assignment | mention | workflow | automation

A Human may open an Issue in Wework and select a local workspace, but starting a Codex Run additionally requires Project execution permission. Issue accessibility alone does not authorize execution, while Assignment is not required. Fully manual work records activity and Deliverables without fabricating a machine Run.

Devices, Executors, and Runtimes are not Members. They do not have durable collaboration identities and cannot be Assignment targets or Agents.

Unified Agent model

Wework Agent and Wegent Agent must not become separate definitions. Product Agent uses the existing Wegent Team, Bot, Ghost, Shell, and Model structure:

Agent
└── Team
    └── Bot
        ├── Ghost
        │   ├── Prompt
        │   ├── Skills
        │   ├── MCP Servers
        │   └── Plugins
        ├── Shell
        └── Model

A single-agent Agent is a Team with one Bot.
A multi-agent Agent is a Team with multiple Bots and a collaboration mode.
The product always assigns an Agent and does not ask users to choose between Bot and Team.
A local Wework coding Agent is the same Agent running a Codex Shell with Wework Plugins through a Wework Executor, not another Agent type.

The existing ProjectChatAgent becomes a binding from a Project to a Workspace Agent:

ProjectAgentBinding
├── project_id
├── agent_id / team_id
├── project_role
├── instruction_override
├── runtime_policy_override
└── enabled

Agent identity, Team, capabilities, and default execution policy belong in kinds. A Workspace receives access to a Team through resource_members; a Project stores only enablement and Project-specific differences.

Authorization fields from the legacy model do not move into ProjectAgentBinding. Existing LoopItemExecution.executor_owner_user_id remains on the Run and is copied to replacement or resumed Runs. Claim, heartbeat, event-reporting, and completion endpoints authorize against that Run field, so replacing ProjectChatAgent with ProjectAgentBinding does not widen Run-owner execution access.

Workspace Agents and Project-private Agents

A Team remains the only Agent entity. Authorization edges and ProjectAgentBinding express its usage scope without adding another Workspace ownership field to Team:

Team
├── Workspace grant: available in a Workspace
└── ProjectAgentBinding: enabled in a Project

A Team granted to a Workspace may be bound to multiple Projects in it.
Creating an Agent inside a Project creates a Team, grants it to the current Workspace, and creates a ProjectAgentBinding.
A Team bound only to one Project behaves as a Project-private Agent.
Promoting it to Workspace-shared does not copy Team, Bot, or Ghost; it only allows other Projects to establish bindings.
Archiving a Project does not delete the Team. Historical Runs retain their immutable execution snapshots.

If the same Agent only needs different repository context, extra instructions, or Runtime preferences in different Projects, use ProjectAgentBinding overrides instead of creating a Project-private Agent. Use scope = project only when its role, capabilities, permissions, or lifecycle truly belong to that Project.

Ghost Plugin

Ghost adds plugins alongside skills and mcp_servers:

spec:
  prompt: ...
  skills:
    - ref: skill/code-review
  mcp_servers:
    - ref: mcp/project-space
  plugins:
    - ref: plugin/wework-browser
      version: 1.2.0
      required: true
      config: {}

The reference model should contain at least:

type GhostPluginRef = {
  ref: string;
  version?: string;
  required: boolean;
  config?: NonSecretPluginConfig;
  credential_refs?: PluginCredentialRef[];
  permissions?: string[];
};

type JsonValue =
  | string
  | number
  | boolean
  | null
  | JsonValue[]
  | { [key: string]: JsonValue };

type NonSecretPluginConfig = Record<string, JsonValue>;

type PluginCredentialRef = {
  name: string;
  ref: string;
};

A Plugin is a capability package that may expand into Skills, MCP servers, Hooks, Tools, and Runtime Requirements. Compiling a Ghost into an effective capability manifest must deduplicate entries and validate conflicts.

config is persisted execution intent and must conform to the non-secret configuration schema declared by the Plugin. Tokens, passwords, private keys, and other credentials must never be stored in config; they are represented only by credential_refs and resolved by the local or cloud compiler at materialization time.

Only Plugins that affect Agent execution belong to Ghost. UI-only Plugins that extend Wework menus, pages, or components remain Wework host extensions.

Shell, Runtime, Device, and Executor

Their responsibilities are fixed:

Concept	Responsibility
`Shell`	Defines how to execute, such as Codex, ClaudeCode, Agno, Dify, or Chat
`Runtime`	Represents an available Shell instance and capability set on a Device
`Device`	Provides the machine, filesystem, network, and local credentials
`Executor`	Claims Runs, prepares environments, starts Shells, reports events, and handles cancellation and recovery

The relationship is:

Agent requires capabilities
    ↓ scheduler match
Runtime provides capabilities
├── Device
├── Executor
└── Shell

An Agent does not own a Device. It stores a default Runtime policy and access rules. A Run records the Runtime and Device selected for that attempt. Local directories may require a pinned Device, while cloneable Git repositories should normally allow dynamic selection from a Runtime pool.

Issue and Run

LoopItem remains the cloud source of truth for Issue. loop_item_executions becomes the single product-level Run envelope for both Wework-local and Wegent execution:

Run
├── project_id
├── issue_id
├── agent_id
├── trigger
├── backend_type
├── backend_execution_id
├── runtime_id
├── execution_workspace_id
├── status
└── result

Backend mappings are:

Run backend = wework_local
└── LocalTask / Codex thread

Run backend = wegent
└── Task / Subtask / Team execution

LocalTask, Task, and Subtask are execution-backend entities, not product tasks alongside Issue. Common Run status, logs, cancellation, recovery, and delivery interfaces must be backend independent. Backend-specific states are diagnostic details only.

A successful Run means only that the attempt ended normally. It does not imply that the Issue has been accepted.

Existing facility mapping

Target concept	Existing facility	Evolution
Workspace	`Kind(kind=CollaborationWorkspace)`	Reuse Kind and generic authorization
Project	`CloudProject`	Reuse directly and unify product terminology
Issue	`LoopItem`	Reuse directly
Agent	`Kind(kind=Team)`	Use as the only Agent definition
Bot/Ghost/Shell/Model	Wegent CRDs	Keep as internal Agent definitions
Project Agent	`ProjectChatAgent`	Reduce to ProjectAgentBinding
Run	`LoopItemExecution`	Promote to the only product execution record
Wegent backend	`Task` / `Subtask`	Use as backend execution records for Run
Wework backend	`LocalTask` / runtime RPC	Use as the local execution backend for Run
Runtime	Device, Executor, and Shell capabilities	Add a unified Runtime projection and scheduling interface
View	Current board and filters	Make board the default View and add server-backed saved Views
Workflow	Issue Workflow	Restrict to organizing Issues and Runs
Automation	Project Automation and local schedules	Merge definitions and trigger protocols

Required domain invariants

Workspace is the only tenant boundary for members, permissions, and shared capabilities.
Every Project belongs to one Workspace.
Every Issue belongs to one Project and inherits its Workspace through the Project authorization edge.
A Member is either a Human or an Agent; Devices and Executors cannot be Assignment targets.
Team is the only cloud Agent definition; a single Bot is exposed through a single-Bot Team.
A Project-private Agent remains a Team and is restricted through Workspace authorization and Project Binding.
Assignment produces notification and a request for action, not execution permission or an exclusive lock.
Any Project Member with execution permission may start a Run without being assigned.
ProjectChatAgent must not duplicate Agent identity, capabilities, or complete runtime configuration.
Every machine execution creates a Run before creating a backend execution record.
A Run binds to one execution backend but may contain multiple backend turns or subtasks.
Run and Issue do not duplicate workspace_id; resolve it through the Project authorization edge when needed.
A Workflow Node cannot become a third task type independent of Issue and Run.
Plugin permissions, versions, and configuration must enter an immutable execution snapshot.
An Executor may run an Agent only when the Agent requirements match the Runtime capabilities.

Evolution order

Register CollaborationWorkspace Kind and grant existing CloudProjects to default Workspaces.
Standardize CloudProject as Project in product terminology and make the board its default View.
Extend Workspace Member into a common Human/Agent assignable actor.
Use Team as the only Agent definition and reduce ProjectChatAgent to a Project binding.
Add Plugin references and effective capability manifests to Ghost.
Converge LoopItemExecution into the only Run envelope.
Unify Runtime capability discovery and execution-backend protocols.
Migrate local Wework Codex execution afterward so it does not introduce a second Agent or Run model.

Core terminology​

Workspace and Project​

Member, Assignment, and Execution​

Unified Agent model​

Workspace Agents and Project-private Agents​

Ghost Plugin​

Shell, Runtime, Device, and Executor​

Issue and Run​

Existing facility mapping​

Required domain invariants​

Evolution order​