AlexandrAI AGENTS.md
agents-md

Personal Work Agent Database and Config Agent Guide

Project-specific AGENTS.md guidance for Personal Work Agent SQLite models, async sessions, Alembic migrations, AppConfig models, config store, installation identity, and tests.

AGENTS.md

Guidance for coding agents working on Personal Work Agent database, migration, and configuration storage.

Project Overview

The persistence boundary uses async SQLAlchemy over SQLite, Alembic migrations, Pydantic config models, TOML config files, generated installation identity, agent secret files, and local directory resolution. This layer carries durable cases, events, runs, credentials metadata, scheduler jobs, review commands, agent sessions, pending items, write drafts, onboarding items, connected accounts, sync cursors, audit events, settings, and project agent definitions.

Use this guide when changing data models, enum values, migrations, config schemas, installation identity, or app path resolution.

Project Map

  • src/workagent/db/models.py defines SQLAlchemy ORM models.
  • src/workagent/db/enums.py defines durable enum values used across services and sync payloads.
  • src/workagent/db/session.py builds database URLs, engines, async session factories, and initializes metadata.
  • alembic/env.py and alembic/versions/ hold migration logic.
  • src/workagent/config/models.py defines AppConfig, connector config, engine settings, watch profiles, and local settings.
  • src/workagent/config/store.py reads and writes TOML config through ConfigStore.
  • src/workagent/config/env.py and paths.py resolve environment overrides and app directories.
  • src/workagent/config/installation.py manages generated installation ID and agent secret material.

Setup Commands

bashuv run pytest tests/test_db.py tests/test_alembic_smoke.py tests/test_config_store.py -q
uv run pytest tests/test_config_env.py tests/test_installation_id.py tests/test_credential_metadata.py -q
uv run alembic upgrade head
make lint

Change Rules For Agents

  • Add migrations for durable schema changes; do not rely only on metadata create_all.
  • Keep enum additions coordinated with sync models, server-side counterparts, and tests.
  • Use async sessions through the configured session factory.
  • Keep config defaults in Pydantic models and path resolution helpers, not scattered through services.
  • Do not store raw secrets in config files when a secret store path exists.
  • Preserve legacy compatibility when migrations intentionally drop or transform old data.
  • Use symbolic or repo-relative paths in docs and tests; do not publish machine-specific roots.

Verification

bashuv run pytest tests/test_db.py tests/test_alembic_smoke.py tests/test_config_store.py tests/test_config_env.py -q
make lint

For enum or model changes, add targeted tests in the service that consumes the new field.

Security Notes

This boundary touches credential metadata, installation identity, local paths, and durable work records. Do not log secrets, publish local directories, or serialize private token values into config examples.

PR Checklist

  • Migration and model changes are in the same patch.
  • Async DB access still uses session factories.
  • Config schema changes have tests and docs examples updated.
  • Secret values remain outside public config output.