AlexandrAI AGENTS.md
agents-md

Personal Work Agent Case Pipeline Agent Guide

Project-specific AGENTS.md guidance for Personal Work Agent case service, status transitions, queued prompt builder, scheduled launcher, and case processing tests.

AGENTS.md

Guidance for coding agents working on Personal Work Agent case creation and processing.

Project Overview

The case pipeline creates work cases from platform events or scheduled jobs, records case events, validates status transitions, builds queued prompts, invokes local processing, and moves cases through draft and review states. It is the core durable workflow between ingestion and execution.

Use this boundary when changing case status semantics, queued prompt content, case events, scheduled case creation, or terminal state behavior.

Project Map

  • src/workagent/services/cases.py owns CaseService and ScheduledCaseLauncher.
  • src/workagent/domain/case_state.py defines allowed CaseStatus transitions and terminal state checks.
  • src/workagent/services/case_processing.py defines QueuedPromptBundle, QueuedCasePromptBuilder, and QueuedCaseProcessor.
  • src/workagent/services/prompting.py provides source-specific system prompts.
  • src/workagent/db/enums.py defines CaseStatus and CaseSource.
  • src/workagent/db/models.py defines Case, CaseEvent, and ExecutionRun.
  • tests/test_case_services.py, test_case_processing.py, test_case_state.py, and test_scheduled_case_launcher.py cover behavior.

Setup Commands

bashuv run pytest tests/test_case_services.py tests/test_case_processing.py tests/test_case_state.py -q
uv run pytest tests/test_scheduled_case_launcher.py tests/test_worker_runtime.py -q
make lint

Change Rules For Agents

  • Validate status transitions through domain/case_state.py; do not bypass the state machine in services.
  • Record case events when changing meaningful state.
  • Keep queued prompts source-aware and free of raw credentials or hidden local paths.
  • Preserve terminal states so completed, sent, rejected, and expired cases do not re-enter active queues accidentally.
  • For new sources, add CaseSource enum, prompt behavior, ingestion mapping, and tests.
  • Keep scheduled case creation separate from platform ingestion.
  • Use async DB sessions consistently.

Verification

bashuv run pytest tests/test_case_state.py tests/test_case_services.py tests/test_case_processing.py -q
make lint

Broaden to worker and runtime tests when queue status behavior changes.

Security Notes

Case data may contain platform content and user requests. Do not include tokens, private platform URLs, or local runtime paths in prompts, events, or generated public docs.

PR Checklist

  • New statuses have transition tests.
  • Case events document durable state changes.
  • Queued prompt changes are covered by focused assertions.
  • Ingestion and scheduled creation remain separate paths.