AlexandrAI AGENTS.md
agents-md

Personal Work Agent Action Executor Agent Guide

Project-specific AGENTS.md guidance for Personal Work Agent action parsing, execution results, write draft kinds, review-gated commands, and tests.

AGENTS.md

Guidance for coding agents working on Personal Work Agent action parsing and execution.

Project Overview

The action execution boundary parses model output into structured proposals, routes approved actions, builds write drafts, and returns explicit execution results. It is the safety layer between generated suggestions and platform-affecting operations.

Use this boundary when changing action proposal formats, write draft kinds, command routing, execution result semantics, or review-gated action flows.

Project Map

  • src/workagent/services/action_parser.py defines ActionProposal and ActionParser.
  • src/workagent/services/action_executor.py defines ExecutionResult and ActionExecutor.
  • src/workagent/db/enums.py defines AgentExecutionDecisionType, AgentWriteDraftKind, and AgentWriteDraftStatus.
  • src/workagent/db/models.py defines AgentWriteDraft and related session state.
  • src/workagent/services/request_router.py routes requests to supported execution paths.
  • src/workagent/services/tool_shims.py adapts tool outputs into service behavior.
  • tests/test_action_parser.py, test_action_executor.py, test_request_router.py, and test_tool_shims.py cover this boundary.

Setup Commands

bashuv run pytest tests/test_action_parser.py tests/test_action_executor.py -q
uv run pytest tests/test_request_router.py tests/test_tool_shims.py tests/test_nk304_write_connectors.py -q
make lint

Change Rules For Agents

  • Keep parser output explicit; do not infer destructive actions from loose prose.
  • Keep write drafts reviewable unless a command path is explicitly designed and tested for execution.
  • Add new write draft kinds in enums, models, sync payloads, and tests together.
  • Preserve error results as data, not uncaught exceptions, when a recoverable action fails.
  • Do not pass raw credentials, tokens, or private URLs into action proposals.
  • Keep formatting helpers separate from execution side effects.
  • Prefer deterministic unit tests over live platform calls.

Verification

bashuv run pytest tests/test_action_parser.py tests/test_action_executor.py tests/test_nk304_write_connectors.py -q
make lint

For new action kinds, include rejection, draft creation, and success-path tests.

Security Notes

This boundary can turn generated text into operations. Keep execution gated, inspectable, and credential-free. Never auto-approve writes without an explicit tested path.

PR Checklist

  • Parser behavior is fixture-tested.
  • New write kinds are added across enum/model/sync layers.
  • Recoverable failures return explicit ExecutionResult values.
  • No live secrets are present in tests or fixtures.