sis/AGENTS.md

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 for HTTP routing (Sis.Server), with WAI/Warp underneath. Route types (like HealthCheck) implement Orb.HasHandler.

Frontend Conventions

• SPA framework: Mithril.js v2 with TypeScript.
• CSS: Neo Brutalism 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