cli

Domain Models

Complete reference for domain entities, value objects, and enums. All definitions are derived from the TypeSpec source of truth (tsp/). Generated TypeScript types live in packages/core/src/domain/generated/output.ts.

Base Entity

All domain entities extend BaseEntity, which provides identity and timestamp fields.

export type UUID = string;

export type BaseEntity = {
  id: UUID;
  createdAt: any;
  updatedAt: any;
};

export type SoftDeletableEntity = BaseEntity & {
  deletedAt?: any;
};

Entities

Feature

The central aggregate root representing a piece of work progressing through the SDLC lifecycle. Feature encapsulates all related entities (Messages, Plan, Artifacts) and serves as the boundary for transactional consistency.

export type Feature = BaseEntity & {
  name: string;
  userQuery: string;
  slug: string;
  description: string;
  repositoryPath: string;
  branch: string;
  lifecycle: SdlcLifecycle;
  messages: Message[];
  plan?: Plan;
  relatedArtifacts: Artifact[];
  agentRunId?: string;
  specPath?: string;
  repositoryId?: UUID;
  fast: boolean;
  push: boolean;
  openPr: boolean;
  approvalGates: ApprovalGates;
  worktreePath?: string;
  pr?: PullRequest;
  parentId?: UUID;
  attachments?: Attachment[];
};

Plan

Implementation plan for a feature containing tasks, artifacts, requirements, and optional scheduling data.

export type Plan = BaseEntity & {
  overview: string;
  requirements: Requirement[];
  artifacts: Artifact[];
  tasks: Task[];
  state: PlanState;
  workPlan?: GanttViewData;
};

Task

Discrete unit of work within a Plan.

export type Task = BaseEntity & {
  title?: string;
  description?: string;
  dependsOn: Task[];
  actionItems: ActionItem[];
  baseBranch: string;
  state: TaskState;
  branch: string;
};

ActionItem

Granular, atomic step within a Task.

export type ActionItem = BaseEntity & {
  name: string;
  description: string;
  branch: string;
  dependsOn: ActionItem[];
  acceptanceCriteria: AcceptanceCriteria[];
};

AcceptanceCriteria

export type AcceptanceCriteria = BaseEntity & {
  description: string;
  verified: boolean;
};

Artifact

Generated document or file attached to a Feature.

export type Artifact = BaseEntity & {
  name: string;
  type: string;
  category: ArtifactCategory;
  format: ArtifactFormat;
  summary: string;
  path: string;
  state: ArtifactState;
};

Requirement

export type Requirement = BaseEntity & {
  slug: string;
  userQuery: string;
  type: RequirementType;
  researches: Research[];
};

Research

export type Research = BaseEntity & {
  topic: string;
  state: ResearchState;
  summary: string;
  artifacts: Artifact[];
};

Message

export type Message = BaseEntity & {
  role: MessageRole;
  content: string;
  options?: string[];
  answer?: string;
  selectedOption?: number;
};

Settings

Global Shep platform settings stored as a singleton.

export type Settings = BaseEntity & {
  models: ModelConfiguration;
  user: UserProfile;
  environment: EnvironmentConfig;
  system: SystemConfig;
  agent: AgentConfig;
  notifications: NotificationPreferences;
  workflow: WorkflowConfig;
  featureFlags?: FeatureFlags;
  onboardingComplete: boolean;
};

Repository

export type Repository = SoftDeletableEntity & {
  name: string;
  path: string;
};

Value Objects

ModelConfiguration

export type ModelConfiguration = {
  default: string; // Default model identifier for all agents
};

UserProfile

export type UserProfile = {
  name?: string;
  email?: string;
  githubUsername?: string;
};

EnvironmentConfig

export type EnvironmentConfig = {
  defaultEditor: EditorType;
  shellPreference: string;
};

SystemConfig

export type SystemConfig = {
  autoUpdate: boolean;
  logLevel: string;
};

AgentConfig

export type AgentConfig = {
  type: AgentType;
  authMethod: AgentAuthMethod;
  token?: string;
};

ApprovalGates

export type ApprovalGates = {
  allowPrd: boolean;
  allowPlan: boolean;
  allowMerge: boolean;
};

PullRequest

export type PullRequest = {
  url: string;
  number: number;
  status: PrStatus;
  commitHash?: string;
  ciStatus?: CiStatus;
  ciFixAttempts?: number;
  ciFixHistory?: CiFixRecord[];
};

Attachment

export type Attachment = {
  id: UUID;
  name: string;
  size: bigint;
  mimeType: string;
  path: string;
  createdAt: any;
};

ApprovalGateDefaults

export type ApprovalGateDefaults = {
  allowPrd: boolean;
  allowPlan: boolean;
  allowMerge: boolean;
  pushOnImplementationComplete: boolean;
};

WorkflowConfig

export type WorkflowConfig = {
  openPrOnImplementationComplete: boolean;
  approvalGateDefaults: ApprovalGateDefaults;
  ciMaxFixAttempts?: number;
  ciWatchTimeoutMs?: number;
  ciLogMaxChars?: number;
};

NotificationPreferences

export type NotificationPreferences = {
  inApp: NotificationChannelConfig;
  browser: NotificationChannelConfig;
  desktop: NotificationChannelConfig;
  events: NotificationEventConfig;
};

FeatureFlags

export type FeatureFlags = {
  skills: boolean;
  envDeploy: boolean;
  debug: boolean;
};

GanttViewData

export type GanttViewData = {
  tasks: GanttTask[];
  startDate: any;
  endDate: any;
};

export type GanttTask = {
  id: UUID;
  name: string;
  start: any;
  end: any;
  dependencies: UUID[];
  progress: number;
};

Enums

SdlcLifecycle

enum SdlcLifecycle {
  Started = 'Started',
  Analyze = 'Analyze',
  Requirements = 'Requirements',
  Research = 'Research',
  Planning = 'Planning',
  Implementation = 'Implementation',
  Review = 'Review',
  Maintain = 'Maintain',
  Blocked = 'Blocked',
}

TaskState

enum TaskState {
  Todo = 'Todo',
  WIP = 'Work in Progress',
  Done = 'Done',
  Review = 'Review',
}

PlanState

enum PlanState {
  Requirements = 'Requirements',
  ClarificationRequired = 'ClarificationRequired',
  Ready = 'Ready',
}

ArtifactCategory

enum ArtifactCategory {
  PRD = 'PRD',
  API = 'API',
  Design = 'Design',
  Other = 'Other',
}

ArtifactFormat

enum ArtifactFormat {
  Markdown = 'md',
  Text = 'txt',
  Yaml = 'yaml',
  Other = 'Other',
}

ArtifactState

enum ArtifactState {
  Todo = 'Todo',
  Elaborating = 'Elaborating',
  Done = 'Done',
}

RequirementType

enum RequirementType {
  Functional = 'Functional',
  NonFunctional = 'NonFunctional',
}

ResearchState

enum ResearchState {
  NotStarted = 'NotStarted',
  Running = 'Running',
  Finished = 'Finished',
}

MessageRole

enum MessageRole {
  Assistant = 'assistant',
  User = 'user',
}

AgentType

enum AgentType {
  ClaudeCode = 'claude-code',
  GeminiCli = 'gemini-cli',
  Aider = 'aider',
  Continue = 'continue',
  Cursor = 'cursor',
  Dev = 'dev',
}

AgentAuthMethod

enum AgentAuthMethod {
  Session = 'session',
  Token = 'token',
}

EditorType

enum EditorType {
  VsCode = 'vscode',
  Cursor = 'cursor',
  Windsurf = 'windsurf',
  Zed = 'zed',
  Antigravity = 'antigravity',
}

PrStatus

enum PrStatus {
  Open = 'Open',
  Merged = 'Merged',
  Closed = 'Closed',
}

CiStatus

enum CiStatus {
  Pending = 'Pending',
  Success = 'Success',
  Failure = 'Failure',
}

NotificationEventType

enum NotificationEventType {
  AgentStarted = 'agent_started',
  PhaseCompleted = 'phase_completed',
  WaitingApproval = 'waiting_approval',
  AgentCompleted = 'agent_completed',
  AgentFailed = 'agent_failed',
  PrMerged = 'pr_merged',
  PrClosed = 'pr_closed',
  PrChecksPassed = 'pr_checks_passed',
  PrChecksFailed = 'pr_checks_failed',
}

---

Maintaining This Document

Update when:

• Entity properties change in TypeSpec definitions (tsp/)
• New entities are added
• Value objects change
• Enums are added or modified

Source of truth: TypeSpec files in tsp/ directory. Generated TypeScript types in packages/core/src/domain/generated/output.ts.

Related docs:

• repository-interfaces.md - Persistence
• ../concepts/ - Conceptual explanations
• ../architecture/clean-architecture.md - Layer context

This site is open source. Improve this page.