Skip to content

Entity Management Specification

Overview

The Entity Management feature provides the core data model and operations for managing structured entities in the entity manager system. Entities represent any tracked item (requirements, tasks, issues) and support attributes, labels, assignment, and status tracking.

Purpose

Entities are the fundamental unit of work in the entity manager system. They enable: - Representation of requirements, tasks, or issues from external systems - Assignment to specific agents/owners - Status tracking for workflow management - Flexible metadata via labels - Link-based relationships with other entities

Requirements

Entity Data Model

Core Entity Fields

  • An entity MUST have a unique id field (string).
  • An entity MUST have a title field (string) that provides a human-readable name.
  • An entity MUST have a description field (string) for detailed information.
  • An entity MUST have a status field (string) indicating its current state.
  • An entity MUST have a labels field (dictionary) for key-value metadata.
  • An entity MUST have an assignee field (string or None) for the assigned agent/user.
  • An entity MAY have a metadata field (dictionary) for backend-specific data.

Entity Identification

  • Entity IDs MUST be unique within a backend.
  • Entity IDs SHOULD be strings to support different ID formats (numeric, UUID, beads hash).
  • Entity IDs MUST be stable (they MUST NOT change over the lifetime of an entity).
  • Entity IDs MAY be assigned by the backend (e.g., GitHub issue numbers) or generated by the system.

Entity Status

  • The status field MUST support at minimum the values: "open" and "closed".
  • The status field MAY support additional values (e.g., "in-progress", "blocked").
  • Status values SHOULD be lowercase for consistency.
  • The default status for new entities MUST be "open".

Entity Labels

  • Labels MUST be stored as key-value pairs in a dictionary.
  • Label keys MUST be strings.
  • Label values MUST be strings.
  • Label values MAY be empty strings for simple tags (key-only labels).
  • Labels SHOULD support structured data (e.g., "priority:high", "type:bug").
  • Labels MAY be used for filtering and querying entities.

Entity Assignment

  • The assignee field MUST be a string representing a user/agent identifier or None.
  • The assignee field MAY be None if no one is assigned.
  • The assignee field SHOULD be consistent with the backend's user identifier format (e.g., GitHub username, Notion user ID).
  • Multiple assignees per entity are NOT supported in the core model (backends MAY extend this).

Entity Metadata

  • The metadata field MAY contain any backend-specific information.
  • Common metadata fields include: url (link to the entity in the external system), created_at (timestamp), and updated_at (timestamp).
  • Applications MUST NOT depend on specific metadata fields being present across all backends.

Entity Operations

Entity Creation

  • When creating an entity, the title field MUST be provided.
  • When creating an entity, the description field defaults to an empty string if not provided.
  • When creating an entity, the labels field defaults to an empty dictionary if not provided.
  • When creating an entity, the assignee field defaults to None if not provided.
  • When creating an entity, the status field defaults to "open" if not provided.
  • Entity creation MUST assign a unique ID to the entity.
  • Entity creation MUST persist the entity to the backend storage.

Entity Reading

  • Reading an entity by ID MUST return all entity fields including id, title, description, status, labels, assignee, and metadata.
  • Reading a non-existent entity MUST raise an error.
  • Reading an entity SHOULD return the most current data from the backend.

Entity Updating

  • Entity updates MUST only modify fields that are explicitly provided.
  • Entity updates MAY support partial updates (e.g., updating only the title).
  • Updating the status field MUST change the entity's state.
  • Updating the labels field MUST replace the entire label set (not merge).
  • Updating the assignee field to None MUST clear the assignment.
  • Updating a non-existent entity MUST raise an error.
  • Entity updates MUST persist changes to the backend storage.

Entity Deletion

  • Entity deletion MUST remove the entity from the backend storage.
  • Entity deletion MAY be implemented as "soft delete" (e.g., closing an issue) depending on backend capabilities.
  • Deleting a non-existent entity SHOULD succeed silently (idempotent operation).
  • Entity deletion MAY remove associated links or leave them orphaned (backend-dependent).

Entity Listing

  • Listing entities MUST return a list of Entity objects.
  • Listing entities SHOULD support filtering by attributes (e.g., status, labels).
  • Listing entities SHOULD support sorting by any entity field.
  • Listing entities MUST support a limit parameter to restrict the number of results.
  • Listing entities with a limit of 0 SHOULD return an empty list.
  • Listing entities without filters SHOULD return all accessible entities.
  • Listing entities results SHOULD be returned in a consistent order when sorting is not specified.

Entity Filtering and Querying

Filter Syntax

  • Entity filters MUST be specified as key-value pairs.
  • Filter keys MUST correspond to entity fields or label keys.
  • Filter values MUST be strings for exact matching.
  • Filtering by status MUST match the entity's status field exactly.
  • Filtering by labels MUST check for label existence with matching value.

Supported Filter Fields

  • Filtering by status MUST be supported.
  • Filtering by label keys MUST be supported.
  • Filtering by assignee MAY be supported.
  • Filtering by title or description MAY be supported (backend-dependent).

Entity Lifecycle

Entity States

  • An entity in "open" status represents an active, incomplete item.
  • An entity in "closed" status represents a completed, resolved, or cancelled item.
  • An entity MAY transition from "open" to "closed".
  • An entity MAY transition from "closed" to "open" (reopening).
  • Entity state transitions SHOULD be logged or tracked where possible.

Entity Validation

  • Entity titles MUST NOT be empty or None.
  • Entity descriptions MAY be empty or None.
  • Entity status MUST be a valid status value for the backend.
  • Entity labels keys MUST NOT be empty or None.
  • Backend-specific validation MAY apply (e.g., GitHub title length limits).

Entity Serialization

  • Entities MUST be serializable to and from the backend storage format.
  • Entity data MUST be preserved accurately during round-trip serialization.
  • Entity IDs MUST remain stable across serialization operations.
  • Entity metadata MAY include additional backend-specific information not present in the core Entity model.

Integration with External Systems

GitHub Integration

  • GitHub issues MUST be mapped to entities.
  • GitHub issue number MUST be used as the entity ID.
  • GitHub issue state (open/closed) MUST be mapped to entity status.
  • GitHub issue labels MUST be parsed into entity labels (supporting "key:value" format).
  • GitHub issue assignee login MUST be used as the entity assignee.
  • GitHub issue HTML URL MUST be stored in entity metadata.

Notion Integration

  • Notion database pages MUST be mapped to entities.
  • Notion page ID MUST be used as the entity ID.
  • Notion Status property MUST be mapped to entity status.
  • Notion multi-select properties MUST be mapped to entity labels.
  • Notion People properties MUST be mapped to entity assignee.
  • Notion page URL MUST be stored in entity metadata.

Beads Integration

  • Beads items MUST be mapped to entities.
  • Beads hash MUST be used as the entity ID.
  • Beads state MUST be mapped to entity status.
  • Beads metadata MUST be mapped to entity labels.

Error Handling

  • Entity operations MUST raise descriptive errors for invalid operations.
  • Error messages MUST include relevant context (entity ID, field name, etc.).
  • Errors due to external system failures MUST be propagated to the caller.
  • Validation errors MUST be raised before attempting backend operations.

Performance Considerations

  • Entity reading SHOULD use cached data when available and freshness is not critical.
  • Entity listing SHOULD use backend-provided filtering for efficiency.
  • Entity updates SHOULD only transmit changed fields to the backend.
  • Bulk operations (create, update, delete) MAY be optimized by backends.

Use Cases for LLM Collaboration

Task Assignment

  • Entities MUST support assignment to specific agents/LLMs.
  • Multiple agents SHOULD be able to query which entities are assigned to them.
  • Agents SHOULD be able to claim unassigned entities by setting themselves as the assignee.

Dependency Tracking

  • Entity status SHOULD reflect whether the entity is blocked by dependencies.
  • Entities with dependencies that are not closed MAY be considered "blocked" status.

Progress Visibility

  • Entity status MUST be queryable to determine overall project progress.
  • Agents SHOULD be able to filter entities by status to find work.
  • Entities with "in-progress" status indicate active work that should NOT be claimed by other agents.