name: peopleflow-hrms description: Onboard Codex to the PeopleFlow HRMS Laravel application and guide safe changes across its multi-tenant, role-gated modules. Use when working in this repo on routes, controllers, middleware, models, Blade views, policy management, tenant onboarding, self-service, analytics, documents, payroll, shifts, or any change that needs app-specific context about tenant scoping, RBAC, route registration, or validation and service patterns.

PeopleFlow HRMS

Overview

Use this skill to build working context quickly before changing the app. Read the repo map first, then load only the reference file that matches the feature area you are touching.

Quick Start

1. Read references/app-map.md to identify the relevant route file, controller namespace, and view area.
2. Read references/access-and-policies.md if the change touches authentication, tenant scoping, roles, permissions, invitations, onboarding, or policy CRUD and evaluation.
3. Inspect the concrete files named in those references before editing. Do not assume the older service-layer pattern applies everywhere.
4. Preserve tenant scoping and role checks when adding queries, routes, or actions.
5. Validate with the narrowest useful command after edits.

Follow the App's Real Patterns

• Treat the app as a mixed architecture. Core HR modules are documented with controllers, form requests, services, and Blade views; newer feature areas often use feature-specific controller folders with more logic in-controller.
• Start route discovery in app/Providers/RouteServiceProvider.php. The app loads routes/web.php, routes/auth.php, routes/notifications.php, routes/self-service.php, routes/documents.php, routes/performance.php, routes/analytics.php, routes/onboarding.php, and routes/extra_features.php.
• Expect most authenticated web features to run behind auth, tenant, and tenant.active. The main dashboard group in routes/web.php also includes must.change.password and tenant.setup.
• Expect API policy endpoints to live under routes/api.php with auth:sanctum, tenant, and role:admin,hr_manager.

Preserve Tenant and RBAC Guarantees

• Check app/Http/Kernel.php for middleware aliases before adding route guards.
• Check app/Http/Middleware/SetTenantContext.php and app/Models/Concerns/BelongsToTenant.php before changing tenant-aware queries. Many models rely on the global tenant scope and automatic tenant_id assignment.
• Check app/Models/User.php, app/Http/Middleware/CheckRole.php, app/Http/Middleware/CheckPermission.php, and the role-management controllers before changing roles or permissions.
• Keep platform-admin flows separate from tenant-admin flows. Tenant management routes use can:manage-tenants under /platform/tenants.

Choose the Right Validation

• Run php -l on touched PHP files for fast syntax checks.
• Run the smallest relevant Laravel test or feature-specific command available in the repo.
• If you change routes or middleware, re-read the route file and confirm the middleware chain still matches nearby patterns.
• If you change tenant-aware models or controllers, verify every write path still sets or inherits tenant_id.

Use the References

• Use references/app-map.md for module boundaries, route files, controller namespaces, and where to look first for common tasks.
• Use references/access-and-policies.md for tenant context, role and permission enforcement, invitation and onboarding flows, and the policy management surface.
• Use rg -n "tenant|role:|permission|PolicyDefinitions|TenantContext" across app and routes when a change spans multiple modules.