Documentation Index
Fetch the complete documentation index at: https://docs.encoreos.io/llms.txt
Use this file to discover all available pages before exploring further.
Version: 1.0.0
Status: π Planned
Created: 2026-03-21
Last Updated: 2026-03-21
Constitution Reference: Section 1.3 (Integration Patterns β Pattern 1: Platform Integration Layer, Pattern 2: Event-Based)
Overview
This document defines the integration contract between the HR (Human Resources) core and the FW (Forms & Workflow) core. HR uses FW for dynamic forms, approval workflows, event-driven automations, and business rules across multiple HR features.
Related Specifications:
- HR-02: Credentialing & Compliance
- HR-03: Onboarding & Offboarding
- HR-06: PTO & Leave Management
- HR-10: Performance Management & Reviews
- HR-11: Benefits Administration
- HR-14: Employee Relations
- HR-15: Compensation Management
FW Features Consumed:
- FW-01/FW-05: Forms (single-page and multi-page)
- FW-03: Automation Engine (event triggers, actions)
- FW-15: Form Field Lookups (employee/department dropdowns)
- FW-16: Event-Based Workflow Triggers
- FW-34: Approval Workflows (multi-level with delegation)
- FW-45: Decision Tables (routing rules)
Cross-cutting guide: See FW Cross-Core Integration Guide for shared patterns, platform layer imports, and testing requirements.
Integration Pattern
Primary Pattern: Pattern 1 β Platform Integration Layer
Secondary Pattern: Pattern 2 β Event-Based Integration
HR accesses FW capabilities through:
@/platform/forms β form rendering and submission
@/platform/approvals β approval chain submission and inbox
@/platform/events β publishing HR events for FW automation triggers
@/platform/data-lookup β HR data as form field lookup sources
@/platform/calendar β business day calculations for SLA deadlines
Event Contracts (HR β FW)
Events published by HR that trigger FW automations and workflows.
HR-03: Employee Lifecycle Events
Event: hr_employee_hired
Event: hr_employee_hired
Channel: hr_events
Publisher: HR (HR-03 Onboarding)
Subscribers: FW-03 (onboarding workflow trigger), PF-10 (notification)
Status: β
Implemented (registered in KnownEventName)
Purpose
Triggers the employee onboarding workflow when a new hire record is created.
Trigger Conditions
- Trigger: New employee record created with
status = 'active' or onboarding instance started
Payload Schema
interface HrEmployeeHiredPayload {
organization_id: string; // UUID - tenant isolation
employee_id: string; // UUID - hr_employees.id
department_id: string; // UUID - pf_departments.id
position_id: string; // UUID - hr_positions.id
site_id?: string; // UUID - pf_sites.id
manager_id?: string; // UUID - hr_employees.id (reporting manager)
start_date: string; // ISO date - employment start date
employment_type: string; // 'full_time' | 'part_time' | 'contractor'
timestamp: string; // ISO timestamp
}
Consumer Actions
| Consumer | Action | Status |
|---|
| FW-03 Automation | Trigger onboarding workflow (parallel tasks to HR, IT, Facilities) | π |
| PF-10 Notification | Notify HR admin and hiring manager | π |
Testing Requirements
Event: hr_employee_terminated
Event: hr_employee_terminated
Channel: hr_events
Publisher: HR (HR-03 Offboarding)
Subscribers: FW-03 (offboarding workflow trigger), PF-10 (notification)
Status: β
Implemented (registered in KnownEventName)
Purpose
Triggers the employee offboarding workflow when an employee is terminated or resigns.
Payload Schema
interface HrEmployeeTerminatedPayload {
organization_id: string;
employee_id: string;
department_id: string;
termination_type: string; // 'voluntary' | 'involuntary' | 'retirement'
last_working_date: string; // ISO date
timestamp: string;
}
Consumer Actions
| Consumer | Action | Status |
|---|
| FW-03 Automation | Trigger offboarding checklist (IT deprovisioning, asset return, exit interview) | π |
| PF-10 Notification | Notify HR admin, IT, facilities | π |
HR-02: Credential Management Events
Event: hr_credential_expired
Event: hr_credential_expired
Channel: hr_events
Publisher: HR (HR-02 Credentialing)
Subscribers: FW-03 (renewal reminder automation)
Status: β
Implemented (registered in KnownEventName)
Purpose
Triggers renewal reminder workflow when an employee credential expires or approaches expiry.
Payload Schema
interface HrCredentialExpiredPayload {
organization_id: string;
credential_id: string; // UUID - hr_credentials.id
employee_id: string; // UUID - hr_employees.id
credential_type: string; // e.g., 'license', 'certification', 'cpr'
expiration_date: string; // ISO date
days_until_expiry?: number; // Negative if already expired
timestamp: string;
}
Consumer Actions
| Consumer | Action | Status |
|---|
| FW-03 Automation | Trigger credential reminder workflow (email at 90/60/30/7 days) | π |
| FW-03 Automation | Create renewal task for HR compliance team | π |
| PF-10 Notification | Alert employee and compliance officer | π |
Event: hr_credential_verified
Event: hr_credential_verified
Channel: hr_events
Publisher: HR (HR-02 Credentialing)
Subscribers: FW-03 (compliance status update)
Status: β
Implemented (registered in KnownEventName)
Purpose
Updates compliance tracking when a credential is verified or renewed.
Payload Schema
interface HrCredentialVerifiedPayload {
organization_id: string;
credential_id: string;
employee_id: string;
credential_type: string;
new_expiration_date: string;
verified_by: string; // UUID - user who verified
timestamp: string;
}
HR-06: Leave Management Events
Event: hr_leave_request_submitted
Event: hr_leave_request_submitted
Channel: hr_events
Publisher: HR (HR-06 PTO & Leave Management)
Subscribers: FW-34 (approval workflow)
Status: β
Implemented (registered in KnownEventName)
Purpose
Triggers the leave request approval workflow when an employee submits a leave request.
Payload Schema
interface HrLeaveRequestSubmittedPayload {
organization_id: string;
leave_request_id: string; // UUID - hr_leave_requests.id
employee_id: string; // UUID
leave_type: string; // 'vacation' | 'sick' | 'personal' | 'fmla' | 'bereavement'
start_date: string; // ISO date
end_date: string; // ISO date
total_days: number;
department_id: string;
manager_id: string; // UUID - direct manager
timestamp: string;
}
Consumer Actions
| Consumer | Action | Status |
|---|
| FW-34 Approval | Route to approval chain based on leave type and duration | π |
| FW-45 Decision Table | Determine approval chain (leave type Γ days β chain) | π |
Event: hr_performance_review_due
Channel: hr_events
Publisher: HR (HR-10 Performance Management)
Subscribers: FW-03 (review cycle workflow)
Status: π Planned (not yet in KnownEventName)
Purpose
Triggers the performance review cycle workflow when reviews are due for employees.
Payload Schema
interface HrPerformanceReviewDuePayload {
organization_id: string;
review_cycle_id: string;
employee_id: string;
reviewer_id: string; // UUID - manager conducting review
review_type: string; // 'annual' | 'quarterly' | 'probationary' | 'project'
due_date: string;
timestamp: string;
}
Event: hr_pip_initiated
Event: hr_pip_initiated
Channel: hr_events
Publisher: HR (HR-10 Performance Management)
Subscribers: FW-03 (PIP tracking workflow)
Status: π Planned (not yet in KnownEventName; related hr_pip_terminated is registered)
Purpose
Triggers PIP tracking workflow with milestone reminders and escalation deadlines.
Payload Schema
interface HrPipInitiatedPayload {
organization_id: string;
pip_id: string;
employee_id: string;
manager_id: string;
start_date: string;
end_date: string; // PIP deadline
review_milestones: string[]; // ISO dates for check-in milestones
timestamp: string;
}
HR-11: Benefits Events
Event: hr_benefits_enrollment_approved
Event: hr_benefits_enrollment_approved
Channel: hr_events
Publisher: HR (HR-11 Benefits Administration)
Subscribers: FW-03 (enrollment processing automation)
Status: β
Implemented (registered in KnownEventName)
Purpose
Triggers post-approval processing when a benefits enrollment is approved.
Payload Schema
interface HrBenefitsEnrollmentApprovedPayload {
organization_id: string;
enrollment_id: string;
employee_id: string;
plan_type: string; // 'medical' | 'dental' | 'vision' | '401k'
effective_date: string;
timestamp: string;
}
HR-14: Employee Relations Events
Event: hr_disciplinary_action_termination
Event: hr_disciplinary_action_termination
Channel: hr_events
Publisher: HR (HR-14 Employee Relations)
Subscribers: FW-03 (termination workflow), HR-03 (offboarding trigger)
Status: β
Implemented (registered in KnownEventName)
Purpose
Triggers termination workflow when a disciplinary action results in termination.
Payload Schema
interface HrDisciplinaryTerminationPayload {
organization_id: string;
disciplinary_action_id: string;
employee_id: string;
action_type: string; // 'termination'
effective_date: string;
timestamp: string;
}
Event: hr_incident_reported
Event: hr_incident_reported
Channel: hr_events
Publisher: HR (HR-14 Employee Relations)
Subscribers: FW-03 (investigation workflow)
Status: β
Implemented (registered in KnownEventName)
Purpose
Triggers investigation workflow when an employee incident is reported.
Payload Schema
interface HrIncidentReportedPayload {
organization_id: string;
incident_id: string;
reporter_id: string; // UUID - employee who reported
incident_type: string; // 'harassment' | 'safety' | 'policy_violation' | 'other'
severity: string; // 'low' | 'medium' | 'high' | 'critical'
site_id?: string;
timestamp: string;
}
Approval Chain Configurations
Leave Request Approval
Chain ID: hr-leave-request-approval
Entity Type: hr_leave_requests
Based On: HR-06
| Step | Approver Type | Condition | Timeout | Escalation |
|---|
| 1 | submitter_manager | Always | 48h | department_head |
| 2 | role: hr_manager | Leave > 5 days OR FMLA | 72h | role: hr_director |
Decision Table for Routing:
| Leave Type | Days | β Chain Steps |
|---|
| Vacation | β€ 5 | Manager only |
| Vacation | > 5 | Manager β HR |
| Sick | Any | Manager only (auto-approve if balance sufficient) |
| FMLA | Any | Manager β HR β Compliance |
| Bereavement | Any | Manager only (auto-approve) |
Credential Renewal Approval
Chain ID: hr-credential-renewal-approval
Entity Type: hr_credentials
Based On: HR-02
| Step | Approver Type | Condition | Timeout | Escalation |
|---|
| 1 | role: compliance_officer | Always | 72h | role: hr_director |
| 2 | role: hr_director | Critical credentials only | 48h | β |
Chain ID: hr-performance-review-approval
Entity Type: hr_performance_reviews
Based On: HR-10
| Step | Approver Type | Condition | Timeout | Escalation |
|---|
| 1 | submitter_manager (reviewerβs manager) | Always | 5 business days | department_head |
| 2 | department_head | Rating: βexceeds expectationsβ or βunsatisfactoryβ | 3 business days | role: hr_director |
Compensation Change Approval
Chain ID: hr-compensation-change-approval
Entity Type: hr_compensation_changes
Based On: HR-15
| Step | Approver Type | Condition | Timeout | Escalation |
|---|
| 1 | submitter_manager | Always | 48h | department_head |
| 2 | role: hr_manager | Always | 72h | role: hr_director |
| 3 | role: finance_manager | Increase > 10% OR salary > threshold | 72h | role: cfo |
Decision Table for Routing:
| Increase % | Salary Level | β Approval Levels |
|---|
| β€ 5% | Any | Manager β HR |
| 5-10% | Any | Manager β HR β Finance |
| > 10% | Any | Manager β HR β Finance β CFO |
| Any | > $150K | Manager β HR β Finance β CFO |
HR uses these FW form templates (specs in specs/fw/templates/):
| Template ID | Type | Spec Location | Description |
|---|
hr-leave-request-form | Form | specs/fw/templates/forms/hr-leave-request-form.md | Leave request data capture |
hr-employee-w4-form | Form | specs/fw/templates/forms/hr-employee-w4-form.md | Federal W-4 tax withholding |
hr-employee-i9-form | Form | specs/fw/templates/forms/hr-employee-i9-form.md | Employment eligibility verification |
hr-leave-request-bundle | Bundle | specs/fw/templates/bundles/hr-leave-request-bundle.md | Form + approval workflow |
| Template ID | Type | Priority | Description |
|---|
hr-performance-review-form | Form | P1 | Performance review data capture |
hr-onboarding-checklist-form | Form | P1 | New hire checklist (multi-page) |
hr-exit-interview-form | Form | P2 | Employee exit interview survey |
hr-pip-tracking-form | Form | P2 | PIP progress documentation |
hr-direct-deposit-form | Form | P2 | Banking information capture |
hr-onboarding-acknowledgment-form | Form | P2 | Policy acknowledgment signatures |
Workflow Templates
| Template ID | Spec Location | Description |
|---|
hr-leave-request-approval | specs/fw/templates/workflows/hr-leave-request-approval.md | Leave request through approval chain |
hr-credential-reminder | specs/fw/templates/workflows/hr-credential-reminder.md | Credential expiry reminders at 90/60/30/7 days |
Planned Workflow Templates (From Recommended Templates)
| Template ID | Priority | Description |
|---|
hr-employee-onboarding | P0 | Multi-department parallel onboarding (HR, IT, Facilities, Manager) |
hr-employee-offboarding | P0 | Offboarding checklist with IT deprovisioning, asset return |
hr-pip-tracking | P1 | PIP milestone reminders and escalation |
hr-performance-review-cycle | P1 | Annual/quarterly review cycle with self-assessment β manager β calibration |
hr-benefits-enrollment | P2 | Open enrollment workflow with deadline reminders |
hr-compensation-approval | P2 | Multi-level compensation change approval |
HR exposes these data sources for FW form field lookups (FW-15):
| Lookup Source | Table | Value Column | Label Column | Filter | Used By |
|---|
| Employees | hr_employees | id | full_name | status = 'active' | Leave forms, review forms |
| Departments | pf_departments | id | name | organization_id | All HR forms |
| Positions | hr_positions | id | title | status = 'active' | Onboarding, compensation |
| Managers | hr_employees | id | full_name | is_manager = true | Review forms, leave forms |
| Leave Types | hr_leave_types | id | name | is_active = true | Leave request form |
| Credential Types | hr_credential_types | id | name | β | Credential forms |
Hooks HR Components Import
// Forms
import { useFormTemplate, FormRenderer } from '@/platform/forms';
// Approvals
import { useSubmitApprovalRequest, useMyApprovalRequests } from '@/platform/approvals';
// Events
import { publishEvent } from '@/platform/events';
import type { KnownEventName } from '@/platform/events';
// Data lookups for form fields
import { useLookupOptions } from '@/platform/data-lookup';
Testing Requirements
Unit Tests
Integration Tests
E2E Tests
RLS Tests
Implementation Status
| Integration | Status | Notes |
|---|
HR events in KnownEventName | β
Partial | 12 events registered; hr_performance_review_due, hr_pip_initiated pending |
| Leave request approval chain | π Planned | Chain config needed; form + workflow templates ready |
| Onboarding workflow | π Planned | Template recommended in FW-28; not yet implemented |
| Credential reminder automation | π Planned | Workflow template ready (hr-credential-reminder) |
| Performance review workflow | π Planned | Events and chain not yet registered |
| Compensation approval chain | π Planned | Decision table needed for amount-based routing |
| Form field lookups | π Planned | HR table lookup configs not yet registered |