AlexandrAI AGENTS.md
agents-md

Personal Work Agent CLI Tools Agent Guide

Project-specific AGENTS.md guidance for Personal Work Agent CLI entry points, launcher wizard, token commands, nk304 command domains, tool shims, and tests.

AGENTS.md

Guidance for coding agents working on Personal Work Agent CLI and tool command surfaces.

Project Overview

The project exposes the main w10w225 CLI and an nk304 tool CLI. The main CLI manages launcher flow, config wizard, daemon control, pairing, token management, scheduler, sync-once, foreground server, and status reporting. Tool commands expose platform search and write-proposal flows for chat, memo, ticket, calendar, file, notification, and user domains.

CLI changes must preserve clear terminal output, explicit write proposals, and credential-safe behavior.

Project Map

  • src/workagent/cli.py is the main w10w225 parser, launcher, wizard, token management, daemon control, sync, scheduler, and pairing entry point.
  • src/workagent/tools_cli.py registers direct connector tool subcommands for platform search and request execution.
  • src/workagent/cli_tools/nk304_cli.py registers nk304 command domains.
  • src/workagent/cli_tools/nk304_api_client.py handles authenticated nk304 API requests.
  • src/workagent/cli_tools/commands/ contains chat, memo, ticket, calendar, file, notification, and user command handlers.
  • src/workagent/services/tool_shims.py and request_router.py route tool behavior into services.
  • pyproject.toml declares w10w225 and nk304 console scripts.

Setup Commands

bashuv run pytest tests/test_cli_tokens.py tests/test_cli_foreground_serve.py tests/test_cli_skills.py -q
uv run pytest tests/test_nk304_cli_commands.py tests/test_nk304_api_client.py tests/test_tool_shims.py -q
uv run pytest tests/test_request_router.py tests/test_nk304_write_connectors.py -q
make lint

Change Rules For Agents

  • Keep parser changes covered by direct tests; CLI regressions are easy to miss manually.
  • Keep write operations as explicit proposals unless the command path is intentionally executable and tested.
  • Preserve localized launcher text behavior where the launcher supports multiple languages.
  • Keep token add/list/disable/revoke flows credential-safe and redacted.
  • Do not print access tokens, pairing secrets, raw authorization headers, or private base URLs.
  • Keep nk304 domain command dispatch separated by command module.
  • Treat terminal output as user interface; keep errors concise and actionable.

Verification

bashuv run pytest tests/test_cli_tokens.py tests/test_launcher.py tests/test_launcher_i18n.py -q
uv run pytest tests/test_nk304_cli_commands.py tests/test_nk304_write_connectors.py -q
make lint

For command formatting changes, add assertions on exact important lines rather than relying only on exit codes.

Security Notes

CLI tools handle local credentials and remote write intents. Keep commands explicit, redact tokens, and avoid logging raw request payloads containing secrets or private endpoints.

PR Checklist

  • Console script entry points still resolve.
  • Parser and command tests cover new flags or domains.
  • Write commands stay proposal-gated or have explicit execution tests.
  • Token output remains redacted.