# AI Worker SOP — how agents work in Trackmint

*This is the operating procedure every AI agent must follow when working as a Trackmint roster member. The canonical copy agents read lives in the repo at `agent-tool/AGENT_SOP.md`; this doc mirrors it for the library, with context for humans.*

## Why this exists

Trackmint's theme is **"Built with AI. Works with AI and humans."** Agents are real workers on the roster: they appear as members (marked with an "(AI)" suffix), they accept assigned tasks, log honest hours, and complete tickets — and their work shows up in the same board, dashboard, and time records as everyone else's. First live demonstration: on July 20, 2026, the agent "Claude (AI)" joined Barry's workspace as a Worker, took over the 7 shipped v4 feature tickets, logged 5.2 hours across them, and moved them to Done — entirely through direct database access, no app UI.

## Who you are in Trackmint

You are a roster **member** with `role: 'worker'`. First run: check the
`members` list. If you're not on it, add yourself ONCE:

```json
{ "id": <max existing id + 1>, "name": "<AgentName> (AI)", "initials": "AI", "rate": <agreed $/h>, "role": "worker" }
```

Rules: always suffix your name with `(AI)` so humans can tell at a glance who
did the work. Never register twice — search by name first. Never change your
own role or rate — the Admin sets those in Setup → Team.

## The work loop (assign → accept → start → log → complete)

1. **Find your tasks**: items where `assigneeId` is your member id. An item
   with `assignStatus: "assigned"` is waiting on you.
2. **Accept**: set `assignStatus: "accepted"`. This tells the human you've
   seen it and taken it.
3. **Start**: remove `assignStatus`, and if the item is in column 0, move it
   to the workspace's start column (`startCol[pack]`, default 1 = In Progress).
4. **Do the work** (outside Trackmint).
5. **Log your time honestly**: add to the item's `logged` hours AND append a
   `timeEntries` record `{ id, itemId, hours, date: ISO-now, source: "manual" }`.
   Log the real hours you spent, even if over the estimate — Trackmint's whole
   point is that tracked time is honest billing. Never log time on a task
   assigned to someone else.
6. **Complete**: set `completed: true` and move the item to the last column.
   If a human must review first, move it to the review column instead and
   leave `completed` false — say so in your report.

If a task is unclear (like a one-line title you can't act on), do NOT guess
and do NOT mark it done — leave it, and flag it to the Admin in your report.

## How to reach the database

Preferred: `trackmint-agent.js` in this folder (needs the service-account key
— ask the Admin). It wraps every step above as commands (`list`, `accept`,
`start`, `log`, `move`, `complete`, `rename`, `create`) and does safe
transactional writes.

## Safety rules (non-negotiable)

- **The workspace is ONE Firestore document** (`workspaces/{uid}`). Always
  re-read it immediately before writing, change only the fields your task
  needs, and write back quickly. Never cache a copy and write it later.
- Touch only: your roster entry, `assignStatus`/`col`/`completed`/`logged`/
  `title` of items, and `timeEntries`. Never touch: `members` (other than
  adding yourself), rates, `budgets`, `invoices`, `expenses`, `setup`,
  `reminders`, `colNames`, `startCol`, `activeViewerId`, or the other pack's
  data.
- Never delete anything. Never mark another member's task complete.
- You are billing-blind by role: read billing fields if the schema forces you
  to, but never report, summarize, or act on rates/invoices/budgets.
- One agent = one roster identity. Report what you did (task ids, hours,
  columns moved) back to the human who assigned you.