Headroom - Foundation

openspec/changes/headroom-foundation/specs/capacity-planning/spec.md

@@ -0,0 +1,99 @@
+## ADDED Requirements
+
+### Requirement: Calculate individual capacity
+The system SHALL calculate individual team member capacity for a given month based on availability, holidays, PTO, and weekends.
+
+#### Scenario: Calculate capacity for full month
+- **WHEN** calculating capacity for a team member with full availability (1.0) for all working days in February 2026
+- **AND** February has 20 working days (28 days - 8 weekend days)
+- **AND** the team member has no PTO or holidays
+- **THEN** the system calculates individual capacity as 20 person-days
+
+#### Scenario: Calculate capacity with half-day availability
+- **WHEN** a team member has availability of 0.5 for 10 working days in a month
+- **THEN** the system calculates capacity as 5 person-days (10 days × 0.5)
+
+#### Scenario: Calculate capacity with PTO
+- **WHEN** a team member has PTO for 3 working days in a month
+- **AND** the month has 22 working days
+- **AND** the team member has full availability (1.0) for all other days
+- **THEN** the system calculates capacity as 19 person-days (22 - 3 days PTO)
+
+#### Scenario: Calculate capacity with holidays
+- **WHEN** a month has 2 company holidays
+- **AND** a team member has 22 working days after removing weekends
+- **AND** the team member has full availability (1.0)
+- **THEN** the system calculates capacity as 20 person-days (22 - 2 holidays)
+
+#### Scenario: Calculate capacity with mixed availability
+- **WHEN** a team member has 10 days at 1.0 availability, 5 days at 0.5 availability, and 3 days at 0 availability in a month
+- **THEN** the system calculates capacity as 12.5 person-days (10×1.0 + 5×0.5 + 3×0)
+
+### Requirement: Calculate team capacity
+The system SHALL calculate total team capacity by summing individual capacities for all active team members.
+
+#### Scenario: Calculate team capacity for month
+- **WHEN** Team Member A has 20 person-days capacity
+- **AND** Team Member B has 18 person-days capacity
+- **AND** Team Member C has 15 person-days capacity
+- **THEN** the system calculates team capacity as 53 person-days
+
+#### Scenario: Exclude inactive team members from team capacity
+- **WHEN** calculating team capacity
+- **AND** one team member has active status set to false
+- **THEN** the system excludes the inactive team member from the team capacity calculation
+
+### Requirement: Calculate possible revenue
+The system SHALL calculate possible revenue based on team capacity and hourly rates.
+
+#### Scenario: Calculate possible revenue for team
+- **WHEN** Team Member A has 160 hours capacity at $150/hour
+- **AND** Team Member B has 144 hours capacity at $125/hour
+- **AND** Team Member C has 120 hours capacity at $175/hour
+- **THEN** the system calculates possible revenue as $63,000 (160×$150 + 144×$125 + 120×$175)
+
+### Requirement: Track availability per day
+The system SHALL allow setting daily availability as 0 (unavailable), 0.5 (half day), or 1.0 (full day).
+
+#### Scenario: Set full day availability
+- **WHEN** setting availability for a specific date to 1.0
+- **THEN** the system records the team member as fully available for that day
+
+#### Scenario: Set half day availability
+- **WHEN** setting availability for a specific date to 0.5
+- **THEN** the system records the team member as half-day available for that day
+
+#### Scenario: Set unavailable
+- **WHEN** setting availability for a specific date to 0
+- **THEN** the system records the team member as unavailable for that day
+
+#### Scenario: Reject invalid availability values
+- **WHEN** attempting to set availability to a value other than 0, 0.5, or 1.0
+- **THEN** the system rejects the input with validation error "Availability must be 0, 0.5, or 1.0"
+
+### Requirement: Manage holidays
+The system SHALL allow defining company-wide holidays that reduce available working days for all team members.
+
+#### Scenario: Add company holiday
+- **WHEN** an admin defines December 25, 2026 as a company holiday "Christmas Day"
+- **THEN** the system marks that date as a non-working day for all team members
+
+#### Scenario: Holidays affect capacity calculation
+- **WHEN** calculating capacity for a month with 2 company holidays
+- **THEN** the system automatically excludes those days from all team members' capacity calculations
+
+### Requirement: Manage PTO requests
+The system SHALL allow team members to request PTO which reduces their individual capacity.
+
+#### Scenario: Submit PTO request
+- **WHEN** a team member submits PTO for February 10-12, 2026
+- **THEN** the system creates a PTO record with start date, end date, and status "pending"
+
+#### Scenario: Approve PTO request
+- **WHEN** a manager approves a PTO request
+- **THEN** the system updates the PTO status to "approved"
+- **AND** the system automatically reduces the team member's capacity for those dates to 0
+
+#### Scenario: PTO affects capacity calculation
+- **WHEN** calculating capacity for a team member with approved PTO for 3 days
+- **THEN** the system excludes those 3 days from the capacity calculation