Connecteam

Build me a narrow small-team workforce scheduler to replace only Connecteam's visible operations loop. Requirements:

- Use Node.js 22, Fastify, Nunjucks, htmx, and better-sqlite3. Run one
  process behind Caddy; do not add a SPA, ORM, or container platform.
- Give one admin a mobile-first two-week schedule editor for employees, roles,
  locations, open shifts, recurring shifts, and per-shift checklists.
- Employees sign in with expiring magic links sent through SMTP credentials in
  .env. No public signup; hash tokens and rate-limit every login endpoint.
- Each employee can set availability, request time off, claim an open shift,
  request a swap, see only their own schedule, and mark shift tasks complete.
- Add explicit clock-in/out buttons. Store server time and optional one-shot
  browser location only after consent; never track location in the background.
- Managers approve requests, publish changes, and see an append-only audit log.
  Export schedules, requests, and worked time as CSV; never calculate payroll.
- Store everything in SQLite, make nightly timestamped backups, and include a
  tested restore command. No telemetry or third-party tracking.
- Out of scope: native apps, push notifications, chat, GPS geofences, kiosk and
  NFC clocks, payroll integrations, training, HR documents, and legal compliance.
- Add focused tests for permissions, overlapping shifts, token expiry, and CSV
  export, plus one Playwright flow from invite through completed shift.
- Include a README for .env, HTTPS, backups, retention, and the employee-data
  risks. End by running tests and listing the exact commands and results.

# AGENTS.md — Build guide for Connecteam

## Project scope
Publish a two-week staff schedule, collect availability and time-off requests, approve shift claims or swaps, attach checklists, and record explicit clock-ins with an auditable CSV export.

Catalogue verdict: no. Not as a one-shot. A narrow scheduler, availability form, shift checklist, and explicit clock-in log are buildable, but Connecteam's real product is the maintained mobile system around them: multi-user permissions, push delivery, GPS and kiosk capture, payroll integrations, audit history, and HR and compliance workflows. That is operational software a team has to trust, not a personal CRUD app.
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
- private HTTPS deployment
- Node.js 22 and SQLite
- SMTP credentials for employee magic links
- documented access, backup, and retention policy

## Stack and architecture
- Use Node.js 22, Fastify, Nunjucks, htmx, and better-sqlite3. Run one process behind Caddy; do not add a SPA, ORM, or container platform.
- Store everything in SQLite, make nightly timestamped backups, and include a tested restore command. No telemetry or third-party tracking.
- Interface for this deskless workforce management workflow: a focused deskless workforce management input, review, and export interface.

## Security and data integrity
- Add focused tests for permissions, overlapping shifts, token expiry, and CSV export, plus one Playwright flow from invite through completed shift.
- Keep API keys and OAuth secrets in .env; redact them from logs, generated files, and error responses.
- State the practical limit: native iOS and Android apps, offline use, and reliable push notifications.

## Agent implementation rules
- Project rule, data: Store everything in SQLite, make nightly timestamped backups, and include a tested restore command. No telemetry or third-party tracking.
- Project rule, behavior: Add explicit clock-in/out buttons. Store server time and optional one-shot browser location only after consent; never track location in the background.
- Project rule, recovery: Add focused tests for permissions, overlapping shifts, token expiry, and CSV export, plus one Playwright flow from invite through completed shift.

## 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 deskless workforce management operation with sample or user-owned data: Add explicit clock-in/out buttons. Store server time and optional one-shot browser location only after consent; never track location in the background.
- Show a concrete result or export: Managers approve requests, publish changes, and see an append-only audit log. Export schedules, requests, and worked time as CSV; never calculate payroll.
- State the practical limit: native iOS and Android apps, offline use, and reliable push notifications.

## Engineering roadmap
1. Phase 1, architecture and data: Use Node.js 22, Fastify, Nunjucks, htmx, and better-sqlite3. Run one process behind Caddy; do not add a SPA, ORM, or container platform. Store everything in SQLite, make nightly timestamped backups, and include a tested restore command. No telemetry or third-party tracking.
2. Phase 2, implement: Add explicit clock-in/out buttons. Store server time and optional one-shot browser location only after consent; never track location in the background.
3. Phase 3, implement: Add focused tests for permissions, overlapping shifts, token expiry, and CSV export, plus one Playwright flow from invite through completed shift.
4. Phase 4, review and output: Publish a two-week staff schedule, collect availability and time-off requests, approve shift claims or swaps, attach checklists, and record explicit clock-ins with an auditable CSV export. Managers approve requests, publish changes, and see an append-only audit log. Export schedules, requests, and worked time as CSV; never calculate payroll.
5. Phase 5, recovery and acceptance: Add focused tests for permissions, overlapping shifts, token expiry, and CSV export, plus one Playwright flow from invite through completed shift. 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: native iOS and Android apps, offline use, and reliable push notifications.

## Paid-product capabilities outside this build
- native iOS and Android apps, offline use, and reliable push notifications
- GPS geofences, kiosk and NFC clocks, and background location workflows
- payroll integrations, overtime rules, and labor-law compliance support
- chat, training, HR documents, recognition, and the rest of the three-hub suite
- vendor support plus hardened permissions, audit history, and incident response

## Implementation prompt
Build me a narrow small-team workforce scheduler to replace only Connecteam's visible operations loop. Requirements:

- Use Node.js 22, Fastify, Nunjucks, htmx, and better-sqlite3. Run one
  process behind Caddy; do not add a SPA, ORM, or container platform.
- Give one admin a mobile-first two-week schedule editor for employees, roles,
  locations, open shifts, recurring shifts, and per-shift checklists.
- Employees sign in with expiring magic links sent through SMTP credentials in
  .env. No public signup; hash tokens and rate-limit every login endpoint.
- Each employee can set availability, request time off, claim an open shift,
  request a swap, see only their own schedule, and mark shift tasks complete.
- Add explicit clock-in/out buttons. Store server time and optional one-shot
  browser location only after consent; never track location in the background.
- Managers approve requests, publish changes, and see an append-only audit log.
  Export schedules, requests, and worked time as CSV; never calculate payroll.
- Store everything in SQLite, make nightly timestamped backups, and include a
  tested restore command. No telemetry or third-party tracking.
- Out of scope: native apps, push notifications, chat, GPS geofences, kiosk and
  NFC clocks, payroll integrations, training, HR documents, and legal compliance.
- Add focused tests for permissions, overlapping shifts, token expiry, and CSV
  export, plus one Playwright flow from invite through completed shift.
- Include a README for .env, HTTPS, backups, retention, and the employee-data
  risks. End by running tests and listing the exact commands and results.

## 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.