@boundless-oss/atlas/src/modules/agile-management/types.ts

Atlas - MCP Server for comprehensive startup project management

export interface Sprint {
  id: string;
  name: string;
  goal: string;
  status: 'active' | 'completed' | 'cancelled';
  startDate: Date;
  endDate: Date;
  duration: number; // days
  team: string[];
  storyIds: string[];
  epicIds?: string[]; // Associated epics
  capacity: number; // story points
  velocity: number; // actual velocity achieved
  burndownData: BurndownDataPoint[];
  
  // Cross-module references
  milestoneId?: string; // Reference to roadmap milestone
  releaseId?: string; // Reference to release planning
}

import { 
  AcceptanceCriterion, 
  TaskDependency, 
  TimeTracking, 
  Attachment, 
  Comment, 
  CustomField,
  Subtask 
} from '../shared/task-types.js';

export interface Story {
  id: string;
  title: string;
  description: string;
  status: 'backlog' | 'todo' | 'in_progress' | 'review' | 'testing' | 'done' | 'blocked' | 'cancelled';
  priority: 'low' | 'medium' | 'high' | 'critical';
  storyPoints: number;
  acceptanceCriteria: AcceptanceCriterion[]; // Changed from string[] to structured criteria
  assignee?: string;
  epic?: string;
  sprintId?: string;
  createdAt: Date;
  updatedAt: Date;
  hoursSpent: number;
  tags: string[];
  
  // New enhanced features
  dependencies: TaskDependency[];
  timeTracking: TimeTracking;
  attachments: Attachment[];
  comments: Comment[];
  customFields: CustomField[];
  subtasks: Subtask[];
  watchers: string[];
  
  // Additional metadata
  dueDate?: Date;
  startDate?: Date;
  completedAt?: Date;
  blockedReason?: string;
  groomedWithUserFeedback?: boolean; // Indicates if story has been groomed with user feedback
  // Keep backward compatibility
  acceptanceCriteriaLegacy?: string[]; // For migration purposes
  
  // Cross-module references
  relatedIssueIds?: string[]; // References to issue-tracking module
  requirementId?: string; // Reference to product-requirements module
  featureId?: string; // Reference to feature in product roadmap
  bugIds?: string[]; // References to bug tracking
  
  // Documentation references
  designDocumentUrl?: string; // URL to design document
  implementationDocumentUrl?: string; // URL to implementation/technical document
  documentationStatus?: 'pending' | 'in-progress' | 'approved' | 'outdated'; // Documentation approval status
  documentationLastReviewed?: Date; // Last time documents were reviewed
  documentationReviewers?: string[]; // Who reviewed/approved the documents
}

export interface Epic {
  id: string;
  title: string;
  description: string;
  status: 'planned' | 'active' | 'completed' | 'cancelled';
  priority: 'low' | 'medium' | 'high' | 'critical';
  goals: string[];
  owner?: string;
  createdAt: Date;
  updatedAt: Date;
  storyIds: string[];
  stories?: string[]; // Alias for compatibility
  progress: number; // percentage
  metadata?: {
    estimatedEffort?: string;
    hasDependencies?: boolean;
    dependencyDetails?: string;
    risks?: string;
    targetUsers?: string;
    businessValue?: string;
    createdVia?: string;
  };
  
  // Cross-module references
  roadmapItemId?: string; // Reference to product roadmap
  requirementIds?: string[]; // References to product requirements
  featureIds?: string[]; // References to features
}

export interface SprintPlanningSession {
  id: string;
  sprintId: string;
  date: Date;
  attendees: string[];
  capacity: number;
  commitments: string[]; // story IDs
  notes: string;
  outcome: 'ready' | 'needs_work' | 'blocked';
}

export interface SprintRetrospective {
  id: string;
  sprintId: string;
  date: Date;
  attendees: string[];
  whatWentWell: string[];
  whatCanImprove: string[];
  actionItems: string[];
  sprintRating?: number; // 1-10
}

export interface StandupReport {
  id: string;
  sprintId: string;
  attendee: string;
  date: Date;
  yesterday: string[];
  today: string[];
  blockers: string[];
}

export interface VelocityReport {
  teamName: string;
  sprintsAnalyzed: number;
  periodStart: Date;
  periodEnd: Date;
  averageVelocity: number;
  highestVelocity: number;
  lowestVelocity: number;
  trend: 'improving' | 'declining' | 'stable';
  sprintData: SprintVelocityData[];
  insights: string[];
  recommendations: string[];
}

export interface SprintVelocityData {
  sprintName: string;
  velocity: number;
  completionRate: number;
  startDate: Date;
  endDate: Date;
}

export interface BurndownChart {
  sprintId: string;
  totalStoryPoints: number;
  completedPoints: number;
  sprintDays: number;
  dailyData: BurndownDataPoint[];
  onTrack: boolean;
  daysRemaining: number;
  trend?: string;
}

export interface BurndownDataPoint {
  day: number;
  idealPoints: number;
  actualPoints: number;
  remainingPoints: number;
  completedPoints: number;
}

export interface SprintStatus {
  sprint: Sprint;
  stories: Story[]; // Full story objects
  epics: Epic[]; // Full epic objects related to the sprint
  totalStories: number;
  completedStories: number;
  inProgressStories: number;
  remainingStories: number;
  totalStoryPoints: number;
  completedStoryPoints: number;
  remainingStoryPoints: number;
  sprintHealth: string;
  blockers: string[];
  currentVelocity: number;
  metrics: {
    velocity: number;
    capacity: number;
    utilization: number;
    burndownData: BurndownChart;
    health: 'excellent' | 'good' | 'at-risk' | 'critical';
    daysElapsed: number;
    daysRemaining: number;
    sprintDuration: number;
  };
  team: {
    members: string[];
    availability: number;
    blockers: string[];
  };
}

export interface BacklogFilter {
  epic?: string;
  priority?: string;
  assignee?: string;
  status?: string;
  maxStoryPoints?: number;
}

// Input option interfaces for API calls

export interface CreateSprintOptions {
  name: string;
  goal: string;
  duration: number;
  startDate?: Date;
  team?: string[];
  initialStoryIds?: string[];
}

export interface CreateStoryOptions {
  title: string;
  description: string;
  storyPoints: number;
  priority: 'low' | 'medium' | 'high' | 'critical';
  acceptanceCriteria: string[] | AcceptanceCriterion[]; // Support both legacy and new format
  epic?: string;
  assignee?: string;
  sprintId?: string;
  tags?: string[];
  dependencies?: TaskDependency[];
  timeEstimate?: number;
  watchers?: string[];
  groomedWithUserFeedback?: boolean;
  designDocumentUrl?: string;
  implementationDocumentUrl?: string;
  documentationStatus?: 'pending' | 'in-progress' | 'approved' | 'outdated';
}

export interface CreateEpicOptions {
  title: string;
  description: string;
  goals: string[];
  priority: 'low' | 'medium' | 'high' | 'critical';
  owner?: string;
}

export interface SprintPlanningOptions {
  sprintId: string;
  attendees: string[];
  capacity?: number;
  commitments: string[];
}

export interface StandupOptions {
  sprintId: string;
  attendee: string;
  yesterday: string[];
  today: string[];
  blockers: string[];
}

export interface RetrospectiveOptions {
  sprintId: string;
  attendees: string[];
  whatWentWell: string[];
  whatCanImprove: string[];
  actionItems: string[];
}

export interface StoryUpdateOptions {
  status?: 'backlog' | 'todo' | 'in_progress' | 'review' | 'testing' | 'done' | 'blocked' | 'cancelled';
  hoursSpent?: number;
  notes?: string;
  title?: string;
  description?: string;
  priority?: 'low' | 'medium' | 'high' | 'critical';
  storyPoints?: number;
  assignee?: string;
  tags?: string[];
  acceptanceCriteria?: string[] | AcceptanceCriterion[];
  dependencies?: TaskDependency[];
  timeTracking?: TimeTracking;
  groomedWithUserFeedback?: boolean;
  epic?: string;
  designDocumentUrl?: string;
  implementationDocumentUrl?: string;
  documentationStatus?: 'pending' | 'in-progress' | 'approved' | 'outdated';
  documentationLastReviewed?: Date;
  documentationReviewers?: string[];
}

export interface VelocityOptions {
  teamName?: string;
  lastNSprints: number;
}

export interface EpicUpdateOptions {
  title?: string;
  description?: string;
  status?: 'planned' | 'active' | 'completed' | 'cancelled';
  priority?: 'low' | 'medium' | 'high' | 'critical';
  goals?: string[];
  owner?: string;
  metadata?: {
    estimatedEffort?: string;
    hasDependencies?: boolean;
    dependencyDetails?: string;
    risks?: string;
    targetUsers?: string;
    businessValue?: string;
  };
}

export interface SprintUpdateOptions {
  name?: string;
  goal?: string;
  status?: 'active' | 'completed' | 'cancelled';
  endDate?: Date;
  team?: string[];
  capacity?: number;
}

// Team and capacity planning interfaces

export interface TeamMember {
  name: string;
  role: string;
  capacity: number; // hours per sprint
  skills: string[];
  availability: number; // percentage
}

export interface SprintCapacity {
  totalHours: number;
  totalStoryPoints: number;
  teamMembers: TeamMemberCapacity[];
  workingDays: number;
}

export interface TeamMemberCapacity {
  name: string;
  allocatedHours: number;
  allocatedStoryPoints: number;
  assignments: string[]; // story IDs
}

// Agile metrics and analytics

export interface AgileMetrics {
  velocity: VelocityMetrics;
  quality: QualityMetrics;
  predictability: PredictabilityMetrics;
  team: TeamMetrics;
}

export interface VelocityMetrics {
  current: number;
  average: number;
  trend: 'up' | 'down' | 'stable';
  consistency: number; // 0-100%
}

export interface QualityMetrics {
  defectRate: number;
  reworkRate: number;
  testCoverage?: number;
  codeReviewCoverage?: number;
}

export interface PredictabilityMetrics {
  commitmentAccuracy: number; // percentage
  scopeCreep: number; // percentage
  deliveryConsistency: number; // percentage
}

export interface TeamMetrics {
  memberSatisfaction?: number;
  collaborationScore?: number;
  knowledgeSharing?: number;
  impedimentResolution: number; // average days
}

// Story estimation and sizing

export interface EstimationSession {
  id: string;
  storyIds: string[];
  participants: string[];
  method: 'planning_poker' | 'story_points' | 't_shirt_sizes';
  results: EstimationResult[];
  date: Date;
}

export interface EstimationResult {
  storyId: string;
  estimates: Record<string, number>; // participant -> estimate
  finalEstimate: number;
  confidence: number; // 0-100%
  notes?: string;
}

// Definition of Done and acceptance criteria

export interface DefinitionOfDone {
  id: string;
  title: string;
  criteria: DoDCriteria[];
  applicableFor: string[]; // story types, epics, etc.
  createdBy: string;
  createdAt: Date;
}

export interface DoDCriteria {
  description: string;
  required: boolean;
  category: 'development' | 'testing' | 'documentation' | 'deployment';
  verificationMethod?: string;
}

// Sprint goals and objectives

export interface SprintGoal {
  id: string;
  sprintId: string;
  title: string;
  description: string;
  success_criteria: string[];
  priority: 'primary' | 'secondary';
  progress: number; // 0-100%
  status: 'not_started' | 'in_progress' | 'achieved' | 'at_risk';
}

// Release planning

export interface Release {
  id: string;
  name: string;
  version: string;
  targetDate: Date;
  sprintIds: string[];
  epicIds: string[];
  goals: string[];
  status: 'in_progress' | 'released' | 'cancelled';
  releaseNotes?: string;
}

export interface ReleaseStatus {
  release: Release;
  completedEpics: number;
  totalEpics: number;
  completedStoryPoints: number;
  totalStoryPoints: number;
  onTrack: boolean;
  risks: string[];
  mitigations: string[];
}