Darwinbox

Build a self-hosted internal HR record app for a small team. Not payroll, not compliance, just records and leave.

Stack, no substitutions:
- Next.js 15, App Router, TypeScript, Tailwind.
- SQLite via better-sqlite3, file at ./data/hr.db, schema created on first run.
- No auth provider, no cloud, no telemetry. Single shared password from HR_PASSWORD in .env, checked in middleware, plus an ADMIN_EMAILS list in .env that unlocks admin views.

In scope:
1. Employees table: name, work email, job title, department, manager (self-referencing), start date, employment type, location, status (active, on leave, exited), notes. Full CRUD for admins, read-only directory for everyone.
2. Org chart rendered from the manager field as nested lists, no graph library.
3. Leave: policies table (name, days per year, carry-over cap), balances computed per employee per calendar year, requests with start date, end date, half-day flag, reason, status (pending, approved, rejected).
4. Approval flow: a request goes to the employee's manager, manager sees a queue, approve or reject with a comment. Every state change writes an append-only audit row with actor, timestamp and old/new values.
5. Working-day math that skips weekends and a holidays table admins can edit. Store all dates as ISO strings, no timezone conversion.
6. Reports: leave taken per employee per year, headcount by department, and a CSV export of employees plus approved leave for whoever actually runs payroll.
7. Seed script with 12 fake employees, 2 policies and a few requests so the app is not empty on first load.

Out of scope, do not build: salary fields, payslips, tax logic, expenses, recruitment, performance reviews, mobile apps, email sending, any integration.

Deliverables: working app on npm run dev, npm run seed, a .env.example, and a README that states plainly that this is a record keeper and that payroll and statutory filing are handled by a human accountant outside this system.

# AGENTS.md — Build guide for Darwinbox

## Project scope
A self-hosted employee directory with leave balances, approval requests and a CSV export you hand to whoever actually runs payroll.

Catalogue verdict: no. This is not a tool you use alone, it is the system of record for every employee your company has. The parts that look buildable, a leave tracker and an org chart, are the cheap 10 percent. The expensive 90 percent is statutory payroll across multiple countries, tax filings, audit trails, role-based access that HR and legal will actually sign off on, and the fact that finance, IT and the auditors all already read from it. A personal replacement makes no sense because there is no personal version of a company's payroll compliance. If you are a founder with eight people, a spreadsheet plus your accountant beats both this and a DIY build.
Use the implementation prompt below to define the deliverable. Complete each phase's acceptance checks before extending the scope.

## Working agreement
- Inspect the repository and its existing instructions before choosing paths, dependencies or commands. Keep one coherent stack and explain changes to the proposed architecture.
- Plan a vertical slice that accepts a real input and produces the useful output described below. Persist only the state the prompt calls for; respect memory-only and upstream-managed workflows. Use fixtures only when they are clearly labelled.
- After scaffolding, document the actual install, development, check and build commands in README and keep them synchronized with the package or project manifest. Do not report commands as successful unless they ran.
- Work in small steps. At handoff, list implemented flows, checks actually performed, remaining blockers, and any credentials or provider setup the owner must supply.
- Do not publish, spend money, contact customers, delete source data or run irreversible migrations without the project owner's authorization.

## Prerequisites
- Node 20 and a machine to run it on
- Someone external doing actual payroll and tax filing

## Stack and architecture
- SQLite via better-sqlite3, file at ./data/hr.db, schema created on first run.
- Model employees, leave requests, approval decisions, policy versions, and audit events; keep stable source IDs and timestamps.
- Interface for this HRMS / HCM suite workflow: a focused HRMS / HCM suite input, review, and export interface.

## Security and data integrity
- If Someone external doing actual payroll and tax filing is unavailable, keep the source record and show a recoverable error instead of a fabricated result.
- Validate imported records and file paths; keep user data within the storage location named in the prompt.
- State the practical limit: Statutory payroll, tax and provident fund compliance across jurisdictions, which is the entire product.

## Agent implementation rules
- Project rule, data: Model employees, leave requests, approval decisions, policy versions, and audit events; keep stable source IDs and timestamps.
- Project rule, behavior: Employees table: name, work email, job title, department, manager (self-referencing), start date, employment type, location, status (active, on leave, exited), notes. Full CRUD for admins, read-only directory for everyone.
- Project rule, recovery: If Someone external doing actual payroll and tax filing is unavailable, keep the source record and show a recoverable error instead of a fabricated result.

## Optional agent skills and references
No installable skill is listed for this guide; use the project rules and the stack documentation.

Read the linked SKILL.md and its dependencies before adding a skill. Select only the skills matching this project's runtime and task; their documentation does not supply API access, credentials or approval to perform external actions. Pin the reviewed revision where the tool supports it. Follow the chosen agent's documented project-level installation mechanism.

## Distribution ideas
These are optional planning notes. Obtain the owner's approval before publishing or contacting anyone.
- Demonstrate this HRMS / HCM suite operation with sample or user-owned data: Employees table: name, work email, job title, department, manager (self-referencing), start date, employment type, location, status (active, on leave, exited), notes. Full CRUD for admins, read-only directory for everyone.
- Show a concrete result or export: Reports: leave taken per employee per year, headcount by department, and a CSV export of employees plus approved leave for whoever actually runs payroll.
- State the practical limit: Statutory payroll, tax and provident fund compliance across jurisdictions, which is the entire product.

## Engineering roadmap
1. Phase 1, architecture and data: SQLite via better-sqlite3, file at ./data/hr.db, schema created on first run. Model employees, leave requests, approval decisions, policy versions, and audit events; keep stable source IDs and timestamps.
2. Phase 2, implement: Employees table: name, work email, job title, department, manager (self-referencing), start date, employment type, location, status (active, on leave, exited), notes. Full CRUD for admins, read-only directory for everyone.
3. Phase 3, implement: Leave: policies table (name, days per year, carry-over cap), balances computed per employee per calendar year, requests with start date, end date, half-day flag, reason, status (pending, approved, rejected).
4. Phase 4, review and output: Approval flow: a request goes to the employee's manager, manager sees a queue, approve or reject with a comment. Every state change writes an append-only audit row with actor, timestamp and old/new values. Reports: leave taken per employee per year, headcount by department, and a CSV export of employees plus approved leave for whoever actually runs payroll.
5. Phase 5, recovery and acceptance: If Someone external doing actual payroll and tax filing is unavailable, keep the source record and show a recoverable error instead of a fabricated result. Verify this invariant with a saved fixture: A rejected or withdrawn request cannot change the approved balance; a policy edit must not rewrite past decisions. State the practical limit: Statutory payroll, tax and provident fund compliance across jurisdictions, which is the entire product.

## Paid-product capabilities outside this build
- Statutory payroll, tax and provident fund compliance across jurisdictions, which is the entire product
- Audit trails and access controls that survive an actual audit or an employment dispute
- Integrations with finance systems, background check vendors, job boards and identity providers
- Mobile apps that non-technical employees will use for attendance and expense claims
- Someone to blame, and to call, when a pay run goes wrong on the 30th

## Implementation prompt
Build a self-hosted internal HR record app for a small team. Not payroll, not compliance, just records and leave.

Stack, no substitutions:
- Next.js 15, App Router, TypeScript, Tailwind.
- SQLite via better-sqlite3, file at ./data/hr.db, schema created on first run.
- No auth provider, no cloud, no telemetry. Single shared password from HR_PASSWORD in .env, checked in middleware, plus an ADMIN_EMAILS list in .env that unlocks admin views.

In scope:
1. Employees table: name, work email, job title, department, manager (self-referencing), start date, employment type, location, status (active, on leave, exited), notes. Full CRUD for admins, read-only directory for everyone.
2. Org chart rendered from the manager field as nested lists, no graph library.
3. Leave: policies table (name, days per year, carry-over cap), balances computed per employee per calendar year, requests with start date, end date, half-day flag, reason, status (pending, approved, rejected).
4. Approval flow: a request goes to the employee's manager, manager sees a queue, approve or reject with a comment. Every state change writes an append-only audit row with actor, timestamp and old/new values.
5. Working-day math that skips weekends and a holidays table admins can edit. Store all dates as ISO strings, no timezone conversion.
6. Reports: leave taken per employee per year, headcount by department, and a CSV export of employees plus approved leave for whoever actually runs payroll.
7. Seed script with 12 fake employees, 2 policies and a few requests so the app is not empty on first load.

Out of scope, do not build: salary fields, payslips, tax logic, expenses, recruitment, performance reviews, mobile apps, email sending, any integration.

Deliverables: working app on npm run dev, npm run seed, a .env.example, and a README that states plainly that this is a record keeper and that payroll and statutory filing are handled by a human accountant outside this system.

## Completion evidence
Demonstrate the prompt's acceptance scenarios against the scoped workflow. Include setup from a clean checkout and failure recovery. Check persistence across restart and export/restore only for the state the prompt says to store; for memory-only tools, confirm that temporary content is discarded as specified. Record actual results and remaining limitations. A detailed plan alone does not establish a working replacement.