Skip to content

Entity Manager Specifications

This directory contains detailed specifications for the major features of the Entity Manager system. Each specification document uses RFC 2119 keywords (MUST, SHOULD, MAY) to clearly define requirements.

Specification Documents

Backend Interface

Defines the abstract contract that all entity manager backends must implement. Covers CRUD operations, link management, graph traversal, and backend-specific requirements for Backlog, Beads, GitHub, Markdown, Notion, Redis, and SQLite backends.

Entity Management

Describes the core data model for entities, including fields (id, title, description, status, labels, assignee), entity lifecycle operations, filtering and querying, and integration with external systems.

Covers the directed graph relationship system between entities. Includes link types (blocked by, blocking, parent, children), link operations, graph traversal, cycle detection, and use cases for LLM collaboration.

Configuration Management

Specifies the hierarchical configuration system supporting both repository-local and user-global settings. Covers configuration storage, precedence rules, backend configuration, and security considerations.

CLI Interface

Defines the command-line interface for entity manager. Covers all commands (entity, link, config), argument parsing, output format, error handling, and LLM integration considerations.

RFC 2119 Keywords

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in these documents are to be interpreted as described in RFC 2119:

  • MUST / MUST NOT: Absolute requirements
  • SHOULD / SHOULD NOT: Recommended but not required
  • MAY: Optional truly

Purpose of These Specifications

These specifications serve several purposes:

  1. Implementation Guidance: Provide clear requirements for developers implementing features
  2. Testing: Define expected behavior for test cases
  3. Documentation: Capture system design and constraints
  4. LLM Integration: Enable LLMs to understand system capabilities and constraints
  5. Extensibility: Define contracts for adding new backends or features

Contributing

When adding new features or modifying existing ones, update the relevant specification document to reflect the changes. Ensure that:

  • All requirements use appropriate RFC 2119 keywords
  • Edge cases and error conditions are documented
  • Security and performance considerations are addressed
  • LLM use cases are considered where relevant