AlexandrAI AGENTS.md
agents-md

Personal Work Agent Review Workflow Agent Guide

Project-specific AGENTS.md guidance for Personal Work Agent review command processing, review sync, push-ready cases, receipts, redaction, and tests.

AGENTS.md

Guidance for coding agents working on Personal Work Agent review workflow.

Project Overview

The review boundary receives remote review commands, syncs command receipts, pushes ready cases, flattens thread context and bot identity, records processing outcomes, and redacts sensitive detail before pushing results. It sits between local case state and remote review surfaces.

Use this boundary when changing review command models, command processing, push-ready behavior, receipt handling, redaction, or review runtime wiring.

Project Map

  • src/workagent/services/review_commands.py processes review command decisions.
  • src/workagent/services/review_sync.py pulls commands, stores receipts, posts acknowledgements, and flattens context metadata.
  • src/workagent/services/review_push.py pushes ready cases and redacts sensitive detail.
  • src/workagent/services/review_runtime_factory.py composes review runtimes.
  • src/workagent/sync/models.py defines ReviewCommand, ReviewCommandAckPayload, and ReviewCommandResultPayload.
  • src/workagent/db/models.py defines ReviewCommand and ReviewCommandReceipt.
  • tests/test_review_commands.py, test_review_sync.py, test_review_push.py, test_review_runtime_factory.py, and test_review_sync_runtime.py cover behavior.

Setup Commands

bashuv run pytest tests/test_review_commands.py tests/test_review_sync.py tests/test_review_push.py -q
uv run pytest tests/test_review_runtime_factory.py tests/test_review_sync_runtime.py tests/test_review_runtime_e2e.py -q
make lint

Change Rules For Agents

  • Keep command receipt handling idempotent; duplicate remote commands should not duplicate side effects.
  • Preserve redaction in review_push before sending detail outside the local process.
  • Keep review command status transitions explicit and tested.
  • Keep thread context and bot identity flattening metadata-only.
  • Do not mix review push with outbound message sending; they have different queues and failure semantics.
  • Treat remote command payloads as untrusted data.
  • Keep local case status transitions validated by the case state machine.

Verification

bashuv run pytest tests/test_review_commands.py tests/test_review_sync.py tests/test_review_push.py -q
make lint

Broaden to sync runtime tests for command polling or acknowledgement changes.

Security Notes

Review workflows can expose local case context. Redact secrets, private paths, tokens, and credential-like details before pushing or logging. Keep participant identity metadata minimal.

PR Checklist

  • Duplicate command handling is tested.
  • Redaction coverage remains in place.
  • Review status and receipt changes are migrated together.
  • Remote payloads are treated as data, not instructions.