# AGENTS.md — Sis Project Conventions

## Project Overview

Sis is a shared household chore/task tracker with a Haskell backend and
TypeScript/Mithril.js SPA frontend.

## Build & Tooling

- **Haskell container:** `./hs <cmd>` runs Haskell tools inside the
  flipstone/haskell-tools Docker image. Use for `stack build`, `stack test`,
  `hpack`, `fourmolu`, `hlint`.
- **Build script:** `./scripts/build` — formats (fourmolu), lints (hlint),
  builds with stack, copies binary to `build/`.
- **Test script:** `./scripts/test` — fourmolu check, hlint, `stack test`.
- **Run script:** `./scripts/run` — starts server in Docker via `stack exec`.
- **hpack:** `package.yaml` is the source of truth for dependencies. After
  editing it, run `./hs hpack` to regenerate `sis-server.cabal`. (If `hpack`
  is unavailable, edit `sis-server.cabal` manually in parallel.)

## Haskell Conventions

- **Style:** fourmolu-formatted. The `./scripts/test` script checks this.
  Run `./hs fourmolu --mode inplace app/ src/ test/` before committing.
- **Lint:** hlint clean required. Fix any hints before committing.
- **Warnings:** `-Wall -Werror` in `package.yaml`. All warnings are fatal.
- **Module qualifiers:** Use qualified imports with descriptive aliases
  (e.g., `import Data.Text qualified as T`).
- **JSON:** Aeson instances live in the same module as the types they
  serialize (`Sis.Types`).
- **Architecture:** The backend uses [Orb](https://github.com/flipstone/orb)
  for HTTP routing (`Sis.Server`), with WAI/Warp underneath. Route types
  (like `HealthCheck`) implement `Orb.HasHandler`.

## Frontend Conventions

- **SPA framework:** [Mithril.js](https://mithril.js.org/) v2 with TypeScript.
- **CSS:** [Neo Brutalism](https://unpkg.com/neobrutalismcss@latest) CDN.
- **Build:** `npm run build` (or `cd frontend && npx tsc` for dev).
- **API client:** Thin fetch wrapper in `frontend/src/api.ts`. Base path `/api`.
- **Dev server:** `npm run serve` serves the built frontend on port 5000.

## Project Structure

```
sis/
├── app/Main.hs            # Server entry point, CLI options, Warp setup
├── src/
│   ├── Sis.hs             # Top-level re-exports
│   ├── Sis/Server.hs      # Orb HTTP routes, WAI app, SPA serving
│   ├── Sis/Types.hs       # Core domain types (Task, User, etc.)
│   └── Sis/Database.hs    # SQLite connection management
├── test/Spec.hs           # Hspec test suite
├── frontend/
│   ├── src/
│   │   ├── index.ts       # Mithril mount point
│   │   ├── api.ts         # Backend API client
│   │   └── components/    # Mithril components
│   └── public/style.css
├── docs/
│   ├── specs/             # Design specs
│   └── plans/             # Implementation plans
├── scripts/               # build, test, run
├── package.yaml           # Haskell deps (hpack source of truth)
├── sis-server.cabal       # Generated by hpack
├── stack.yaml             # Stack resolver config
├── docker-compose.yml     # Deployment stack
├── Dockerfile             # Production image
└── FEATURES.org           # Feature roadmap
```

## Commit Style

- Conventional commits: `feat:`, `deps:`, `test:`, `chore:`, `docs:`.
- Each commit should be a self-contained logical change.
- Run `./scripts/test` before committing. Tests must pass.

## Agent Autonomy
- As changes are completed then verify functionality using Playwright 
- Once functionality is confirmed then commit and push changes