agora

Walk every doc surface (README, CLAUDE.md, docs/prd/, docs/adr/, docs/architecture.md, docs/runbook.md, docs/solution.md, docs/lessons.md) and surface drift against current code. Use after any sizeable change to src/agora/saga/, src/agora/api/, src/agora/agents/, src/agora/models/, src/agora/config.py, Makefile, alembic/versions/, or .github/workflows/ — or when the user asks "are the docs still accurate", "check for doc drift", "stale-check the PRDs", or before tagging a release. Outputs a punch list of file:line drift candidates rather than rewriting docs autonomously.

Add a new state or step to the Agora ILL lifecycle without breaking saga invariants. Use when the user asks to add a state (e.g. "Held", "Renewed", "Lost"), add a forward+compensator pair, or extend the state machine. Walks through every file that must change in lockstep and writes the skeletons.

Scaffold a new outbox target handler (NCIP, webhook, peer relay, etc.) following the commit-then-enqueue pattern from ADR-0011. Use when adding a new external system that saga steps need to dispatch to asynchronously, when the user asks to "wire up an outbox handler for X", or when extending the OutboxWorker registry. Walks the developer through the handler signature, idempotency-key contract, lifespan registration, and the test pattern.

Run a security audit pass over agora — Bandit on src/agora/, pip-audit on locked deps, detect-secrets sweep, plus agora-specific concerns (ReShare Basic auth, NCIP creds, OpenURL targets, saga-event payload sanitization). Use when reviewing security before a milestone, after touching auth/credentials, before opening agora to a real ReShare tenant, or when CLAUDE.md known-gaps lists an unverified surface that touches credentials.

Validate an ISO 18626 XML payload against the published XSD. Use when reviewing/generating peer-facing wire messages, before flipping `RESHARE_ENABLED=true`, or when a peer reports a schema rejection. Catches the common 2021-revision pitfalls (DeliveryMethod rename, namespace drift, missing required header fields).

Bootstrap a new Architecture Decision Record under `docs/adr/` with the project's standard template, the next sequential number, and consistent Status/Context/Decision/Consequences sections. Use when the user makes a non-trivial design decision worth locking in (anything that would be expensive to reverse later).

Add a new rule to `PolicyAgent` (CONTU-style copyright, patron eligibility, budget, ISO 18626 cost cap, etc.) with consistent code, tests, and rationale-string format. Use when extending `src/agora/agents/policy.py`.

Probe a running FOLIO/ReShare (mod-rs) instance to verify the actual endpoint paths, request/response shapes, and idempotency-header handling — then diff against `HttpReShareClient` in `src/agora/clients/reshare.py`. Use before flipping `reshare_enabled=true` against a real instance, or when an integration error suggests our endpoint guesses are wrong.

Pretty-print the event timeline for an Agora saga given a saga_id or a JSON dump of saga_event rows. Use when debugging a stuck or unexpectedly-terminal saga, when verifying a compensator actually ran, or when a user asks "what happened with saga X". Reads from the live DB if `DATABASE_URL` is set; otherwise expects a JSON file path.