agent-standup CLAUDE.md

CLAUDE.md — Agent Standup

A task tracker for AI coding agents. Next.js (front end and API in one bundle) · Prisma · Postgres. Image built in CI → pushed to GHCR → pulled on the server. Never built on the server, no bind mounts.

Plans live in docs/plans/: PLAN.md (how it works), SCHEMA.md (tables, config, endpoints), DECISIONS.md (why), MILESTONES.md (the work, as PR-sized pieces with prerequisites).

---

What a session can do end to end

An item minted through the product walks the full state machine on service calls alone — plan_review → executing → in_review → merged — because the artifacts each transition guard reads are writable through the service.

Two decisions in record_artifact are load-bearing and worth knowing before changing it. reviewRound defaults to the item's current round, which is what lets the merge gate — it takes max(reviewRound) across every kind — read a commit at the round its own review is on. createdByType is resolved from an explicit creator or a live assignment and is never guessed, because it decides whether a human authorised a merge on a needs_approval item.

request_review is a separate operation from recording a review, not an oversight: the two are opposite ends of the same exchange, made by different parties at different times, and the event points at no artifact row precisely because there is nothing yet to point at.

MCP tools are derived from the operation registry (src/lib/mcp/tools.ts over src/lib/service/registry.ts), so registering an operation is the whole of that adapter's work. Resist adding a second list of tools — there is nowhere to forget an operation.

The hook

A single script (src/bin/standup-hook.ts) serves PreToolUse, PostToolUse and Stop. It pings the server and does what it is told. It holds no rules, no matcher and no cache: it reports the event, renders the answer, and that is the whole of it. Every rule worth having is conditional on item state, claim state, review artifacts or budget, none of which a script can see.